io.atlassian.fugue.extensions.step

Class Steps

java.lang.Object

io.atlassian.fugue.extensions.step.Steps

public final class Steps
extends Object

This provides an entry point for a "for-comprehension" styled syntax shortcut of fugue Option, Either, Try and Java 8 Optional.

The intention of this comprehension is to provide access to flatMap, map and filter of these monad types in a way that is easier to read and reason about.

A short explanation is:

• Each step must preserve the shape of the original monad. For example if you begin with an Option then each step must return an Option with the final yield producing an Option result.
• Each step retains access to the previously defined/success values
• On the first empty/failure step result, no further steps will be evaluated
• Filter provides a convenience method to break out of further evaluation

Simple example usage of Steps to produce an Option by chaining functions that all have access to the previous values.

Option<Integer> result = Steps.begin(some(2)) .then(number -> some(number + 3)) .then((number1, number2) -> some(number1 * number2)) .yield((number1, number2, number3) -> number3 * 4);

This yield will produce a Option.some(A) containing the final value of 40.

This is calculated by:

1. The initial defined state of the option is 2
2. This value of 2 is given parameter name of number for the first step, and is added to 3, producing 5
3. The next step accepts both parameters (2 and 5) and multiplies them together, and returns this value of 10
4. The final yield accepts all 3 parameters (2, 5, 10) but only cares about the 3rd parameter (10) and multiplies this by 4 to produce 40
5. The result option is now a some of 40

An example of a Steps causing it to break out early, and do no further evaluation is:

Option<Integer> result = Steps.begin(some(2)) .then(number -> none(Integer.class)) .then((number1, number2) -> some(number1 * number2)) .yield((number1, number2, number3) -> number3 * 4);

In this example, the result will be none and the functions after the empty state is returned will not be evaluated.

While each step provides access to the previous values, if these are not required, then it is possible to evaluate a new value using a Supplier at each step. For example, the following is possible:

Option<Integer> result = Steps.begin(some(2)) .then(() -> some(5)) .then((number1, number2) -> some(number1 * number2)) .yield((number1, number2, number3) -> number3 * 4);

In this case we have decided that the first step will evaluate its result without requiring the previous state, and just return 5. This final result will still be a some of 40.

Filter is another method to break out of further evaulations and return the empty result. The following example, illustrates this:

Option<Integer> result = Steps.begin(some(2)) .then(number -> some(number + 3)) .filter((number1, number2) -> number2 == 0) .then((number1, number2) -> some(number1 * number2)) .yield((number1, number2, number3) -> number3 * 4);

In this contrived example, the filter predicate will return false as number2 will always be 5, and never 0. This will result in that steps result being changed to the empty value, and prevent any further step evaluation.

NB: It is possible to chain together up to 6 steps

Since:

4.7.0

See Also:

Option, Either, Try, Optional

Method Summary

Modifier and Type	Method and Description
static <A,LEFT> EitherStep1<A,LEFT>	begin(Either<LEFT,A> either) Begin a new Steps expresison, using the Either type.
static <A> OptionStep1<A>	begin(Option<A> option) Begin a new Steps expresison, using the Option type.
static <A> OptionalStep1<A>	begin(Optional<A> optional) Begin a new Steps expresison, using the Optional type.
static <A> TryStep1<A>	begin(Try<A> aTry) Begin a new Steps expresison, using the Try type.

Methods inherited from class java.lang.Object

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

Method Detail

begin

public static <A,LEFT> EitherStep1<A,LEFT> begin(Either<LEFT,A> either)

Begin a new Steps expresison, using the Either type.

This assumes a Right-Biased Either, and will therefore continue evaluating steps on right results, and break out early on the first left result.

Type Parameters:

A - The right hand side type for the initial Either

LEFT - The left hand side type for the initial Either

Parameters:

either - The start value for this steps.

Returns:

A class allowing continuation of this first Step

See Also:

Either, for description of Steps usage with examples

begin

public static <A> OptionStep1<A> begin(Option<A> option)

Begin a new Steps expresison, using the Option type.

This will continue evaluating steps on some results, and break out early on the first none result.

Type Parameters:

A - The type for the initial Option

Parameters:

option - The start value for this steps.

Returns:

A class allowing continuation of this first Step

See Also:

Option, for description of Steps usage with examples

begin

public static <A> OptionalStep1<A> begin(Optional<A> optional)

Begin a new Steps expresison, using the Optional type.

This will continue evaluating steps on of results, and break out early on the first empty result.

Type Parameters:

A - The type for the initial Optional

Parameters:

optional - The start value for this steps.

Returns:

A class allowing continuation of this first Step

See Also:

Optional, for description of Steps usage with examples

begin

public static <A> TryStep1<A> begin(Try<A> aTry)

Begin a new Steps expresison, using the Try type.

This will continue evaluating steps on success results, and break out early on the first failure result.

Type Parameters:

A - The type for the initial Try

Parameters:

aTry - The start value for this steps.

Returns:

A class allowing continuation of this first Step

See Also:

Try, for description of Steps usage with examples