Package art.cutils.value

Class Try<T>

java.lang.Object

art.cutils.value.Try<T>

Type Parameters:

T - type

All Implemented Interfaces:

Serializable

public abstract class Try<T>
extends Object
implements Serializable

The Try class offers the ability write safe code without focusing on try-catch blocks in the presence of exceptions.

There are 3 states that determines the functionality of Try from the try operation performed.

• Successful Operation with result.
• Successful Operation without result.
• Failed Operation.

Requesting for a result on a successful operation which returns no result or failed operation which has not resulted will throw an IllegalStateException, using the map(ThrowingFunction) will vary depending on the state of the operation ... and so on. Review the method description for more information.

Furthermore, fatal exceptions aren't handle by Try:

• InterruptedException
• LinkageError
• ThreadDeath
• VirtualMachineError (i.e. OutOfMemoryError or StackOverflowError)

Since:

v1

Author:

Bobai Kato

See Also:

Serialized Form

Method Summary

Modifier and Type	Method	Description
abstract Try<T>	filter(Predicate<? super T> predicate)	If a result is present, and the result matches the given predicate, returns a Try describing the result, otherwise returns an empty Try
abstract T	get()	Use this method to retrieve the try operation result.
abstract Throwable	getCause()	Retrieve the Cause of try operation failure.
abstract Optional<T>	getOptional()	Use this method to retrieve the try operation Optional result.
abstract boolean	isEmpty()	Try is Empty if operation is Failed or Filter condition is not met.
abstract boolean	isFailure()	Use to check the state of the try operation.
boolean	isNotEmpty()	Try is Not Empty if operation is Successful or filter condition is met.
abstract boolean	isResult()	Use to check the state of a successful try operation whether or not it has a result.
abstract boolean	isSuccess()	Use to check the stage of the try operation.
abstract <M> Try<M>	map(ThrowingFunction<? super T,? extends M> mapper)	If a try operation return a result, apply the provided mapping function to it, and return and instance of Try with the applied result.
static <T> @NotNull Try<T>	of(Dealer<? extends T> operation)	Accepts a Dealer type function which is expected to return a result if operation was successful.
static <T> @NotNull Try<T>	of(Executable operation)	Accepts a Executable type function with no result expected if operation is successful.
abstract Try<T>	onEmpty(Runnable run)	If try filter condition is not met, invoke the specified Runnable.
Try<T>	onFailure(Runnable run)	If try operations fails, invoke the specified Runnable.
Try<T>	onFailure(Consumer<? super Throwable> cause)	If try operations fails, invoke the specified consumer with the exception thrown during the execution, otherwise do nothing.
Try<T>	onSuccess(Runnable runnable)	If isSuccess() and isNotEmpty(), invoke the specified Runnable.
Try<T>	onSuccess(Consumer<? super T> result)	If isSuccess(), isResult() and isNotEmpty() ()} invoke the specified consumer with the operation result, otherwise do nothing.
abstract T	orElseGet(Supplier<? extends T> other)	Return the result if available after the try operation, otherwise invoke supply other result
abstract T	orElseGet(T other)	Return the result if try operation is successful and has a result, otherwise return other value.
abstract T	orElseThrow(Throwable throwable)	Return try result if operation was successful, otherwise throw the exception supplied.
abstract <X extends Throwable> T	orElseThrow(Supplier<? extends X> exceptionSupplier)	Return try result if operation was successful, otherwise throw the exception supplied.
abstract Try<T>	peek(Accepter<? super T> acceptor)	Safely, performing an action on the current try result if present.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

of

@Contract("_ -> new")
@NotNull
public static <T> @NotNull Try<T> of(Dealer<? extends T> operation)

Accepts a Dealer type function which is expected to return a result if operation was successful.

Type Parameters:

T - variable type

Parameters:

operation - the operation that will be tried, a variable of Dealer type.

Returns:

instance of Try either with a Try.Success or Try.Failure state.

Since:

v1

of

@Contract("_ -> new")
@NotNull
public static <T> @NotNull Try<T> of(Executable operation)

Accepts a Executable type function with no result expected if operation is successful.

Type Parameters:

T - variable type

Parameters:

operation - the operation that will be tried, a variable of Executable type.

Returns:

instance of Try either with a Try.Success or Try.Failure state.

Since:

v1

onSuccess

public Try<T> onSuccess(Consumer<? super T> result)

If isSuccess(), isResult() and isNotEmpty() ()} invoke the specified consumer with the operation result, otherwise do nothing.

Parameters:

result - block of operation to be executed.

Returns:

existing instance of Try

Since:

v1

See Also:

Try.Success.get(), isSuccess(), isResult(), isNotEmpty()

isSuccess

public abstract boolean isSuccess()

Use to check the stage of the try operation.

Returns:

a Boolean depending on the state: true if try was successful else false if operation fails.

isEmpty

public abstract boolean isEmpty()

Try is Empty if operation is Failed or Filter condition is not met.

Returns:

a Boolean depending on the state: true if try is empty else false

Since:

v2.4

See Also:

filter(Predicate), isFailure(), isSuccess(), isNotEmpty()

onEmpty

public abstract Try<T> onEmpty(Runnable run)

If try filter condition is not met, invoke the specified Runnable.

Parameters:

run - the operation to be executed if filter condition is not met.

Returns:

existing instance of Try

Since:

v2.4.5

See Also:

onFailure(Runnable), filter(Predicate)

isNotEmpty

public boolean isNotEmpty()

Try is Not Empty if operation is Successful or filter condition is met.

Returns:

a Boolean depending on the state: true if try is not empty else false

Since:

v2.4

See Also:

filter(Predicate), isFailure(), isSuccess(), isEmpty()

get

public abstract T get()

Use this method to retrieve the try operation result.

Returns:

the try operation result

Throws:

IllegalStateException - Try state is Try.Success without an available result.

UnsupportedOperationException - Try state is Try.Failure when a try operation fails

Since:

v1

filter

public abstract Try<T> filter(Predicate<? super T> predicate)

If a result is present, and the result matches the given predicate, returns a Try describing the result, otherwise returns an empty Try

Parameters:

predicate - the predicate to apply to a result, if present

Returns:

an Try describing the value of this Try, if a result is present and the result matches the given predicate, otherwise an empty Try

Throws:

NullPointerException - if the predicate is null

Since:

v2.4

peek

public abstract Try<T> peek(Accepter<? super T> acceptor)

Safely, performing an action on the current try result if present. Unlike map(ThrowingFunction) this method will not affect the current Try results.

The same result will be returned with the Try instance.

Parameters:

acceptor - the action to be performed on the result if present.

Returns:

a Try consisting of the Result, if a result is present, otherwise an empty

getOptional

public abstract Optional<T> getOptional()

Use this method to retrieve the try operation Optional result.

Returns:

try operation Optional result.

Throws:

IllegalStateException - Try state is Try.Success without an available result.

UnsupportedOperationException - Try state is Try.Failure when a try operation fails

Since:

v1

onSuccess

public Try<T> onSuccess(Runnable runnable)

If isSuccess() and isNotEmpty(), invoke the specified Runnable.

Parameters:

runnable - the Runnable to be executed

Returns:

existing instance of Try

Since:

v1

See Also:

isNotEmpty(), isSuccess()

onFailure

public Try<T> onFailure(Consumer<? super Throwable> cause)

If try operations fails, invoke the specified consumer with the exception thrown during the execution, otherwise do nothing.

Parameters:

cause - the consumer to accept the cause and executed if an exception was thrown

Since:

v1

See Also:

Try.Failure.getCause()

isFailure

public abstract boolean isFailure()

Use to check the state of the try operation.

Returns:

a Boolean depending on the state: true if try operation fails else false if operation was successful..

getCause

public abstract Throwable getCause()

Retrieve the Cause of try operation failure.

Returns:

exception thrown during try operation.

Throws:

UnsupportedOperationException - if try operation is successful

Since:

v1

onFailure

public Try<T> onFailure(Runnable run)

If try operations fails, invoke the specified Runnable.

Parameters:

run - the Runnable to be executed

Returns:

existing instance of Try

Since:

v2

map

public abstract <M> Try<M> map(ThrowingFunction<? super T,? extends M> mapper)

If a try operation return a result, apply the provided mapping function to it, and return and instance of Try with the applied result.

Type Parameters:

M - The type of the result of the mapping function

Parameters:

mapper - a mapping function to apply to the result is available.

Returns:

an instance of Try describing the result of applying a mapping function to the result.

Throws:

NullPointerException - if the mapping function is null

IllegalStateException - if a try operation state is Try.Success but without a result.

UnsupportedOperationException - if a try operation state is Try.Failure.

orElseGet

public abstract T orElseGet(T other)

Return the result if try operation is successful and has a result, otherwise return other value.

Parameters:

other - the value to be returned if there is no result available, it could also be a null.

Returns:

the result, if present, otherwise other

Throws:

IllegalStateException - if a try was successful but returns no result.

orElseGet

public abstract T orElseGet(Supplier<? extends T> other)

Return the result if available after the try operation, otherwise invoke supply other result

Parameters:

other - a Supplier block whose result is returned if try fails

Returns:

the try result if available otherwise the result of other.get()

Throws:

NullPointerException - if value is not present and other is null

IllegalStateException - if a try was successful but returns no result.

orElseThrow

public abstract <X extends Throwable> T orElseThrow(Supplier<? extends X> exceptionSupplier)
                                             throws X extends Throwable

Return try result if operation was successful, otherwise throw the exception supplied.

Type Parameters:

X - Type of the exception to be thrown

Parameters:

exceptionSupplier - The supplier which will return the exception to be thrown

Returns:

the present value

Throws:

X - if there is no value present

IllegalStateException - if a try was successful but returns no result.

X extends Throwable

orElseThrow

public abstract T orElseThrow(Throwable throwable)

Return try result if operation was successful, otherwise throw the exception supplied. * @param throwable The Throwable which will to be thrown

Returns:

the present value

Throws:

IllegalStateException - if a try was successful but returns no result.

isResult

public abstract boolean isResult()

Use to check the state of a successful try operation whether or not it has a result.

Returns:

a Boolean depending on the state: true if try operation was successful and has a result or false if operation fails or successful but without a result.