Class Either<L,R>

java.lang.Object
io.atlassian.fugue.Either<L,R>
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
Either.Left, Either.Right
public abstract class Either<L,R> extends Object implements Serializable
A class that acts as a container for a value of one of two types. An Either will be either Left or Right.

Checking which type an Either is can be done by calling the @ isLeft() and isRight() methods.

An Either can be used to express a success or failure case. By convention, Right is used to store the success value, (you can use the play on words "right" == "correct" as a mnemonic) and Left is used to store failure values (such as exceptions).

While this class is public and abstract it does not expose a constructor as only the concrete Left and Right subclasses are meant to be used.

Either is immutable, but does not force immutability on contained objects; if the contained objects are mutable then equals and hashcode methods should not be relied on.

Since 2.2, there have been some right-biased methods added. With 2.3 the available right-biased methods has increased. The purpose of these is that you can do something like either.map(...) directly, which is identical to calling either.right().map(...).

Since:
1.0
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    (package private) class 
    Either.AbstractProjection<A,B>
    Holds the common implementation for both projections.
    (package private) static final class 
    Either.Left<L,R>
     
    final class 
    Either.LeftProjection
    A left projection of an either value.
    static interface 
    Either.Projection<A,B,L,R>
     
    (package private) static final class 
    Either.Right<L,R>
     
    final class 
    Either.RightProjection
    A right projection of an either value.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static final long
    serialVersionUID
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    Either()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    <X> Either<L,X>
    ap(Either<L, Function<R,X>> either)
    Function application on this projection's value.
    <X> Either<L,X>
    apply(Either<L, Function<R,X>> either)
    Deprecated.
    since 3.0 see ap(Either)
    abstract <LL,RR> Either<LL,RR>
    bimap(Function<? super L, ? extends LL> ifLeft, Function<? super R, ? extends RR> ifRight)
    Map the given functions across the appropriate side.
    final boolean
    contains(R elem)
    Tests whether the option contains a given value as an element.
    final boolean
    exists(Predicate<? super R> p)
    Return `true` if this is a right value and applying the predicate to the contained value returns true.
    final Option<Either<L,R>>
    filter(Predicate<? super R> p)
    Returns None if this is a left or if the given predicate p does not hold for the contained value, otherwise, returns a right in Some.
    final Either<L,R>
    filterOrElse(Predicate<? super R> p, Supplier<? extends L> orElseSupplier)
    Return a Right if this is a Right and the contained values satisfies the given predicate.
    final <X, LL extends L>
    Either<L,X>
    flatMap(Function<? super R, Either<LL,X>> f)
    Binds the given function across the right hand side value if it is one.
    abstract <V> V
    fold(Function<? super L, V> ifLeft, Function<? super R, V> ifRight)
    Applies the function to the wrapped value, applying ifLeft if this is a Left and ifRight if this is a Right.
    final boolean
    forall(Predicate<? super R> p)
    Returns true if it is a left or the result of the application of the given predicate on the contained value.
    final void
    foreach(Effect<? super R> effect)
    Deprecated.
    use forEach(Consumer) instead
    final void
    forEach(Consumer<? super R> effect)
    Perform the given side-effect for the contained element if it is a right
    (package private) L
    getLeft()
     
    final R
    getOr(Supplier<? extends R> supplier)
    Get the value if it is a right or call the supplier and return its value if not.
    final R
    getOrElse(Supplier<? extends R> supplier)
    Deprecated.
    since 4.3, use getOr(Supplier) instead
    final <X extends R>
    R
    getOrElse(X other)
    Get the value if it is a right, otherwise returns other.
    final R
    getOrError(Supplier<String> msg)
    Get the contained value or throws an error with the supplied message if left.
    final R
    getOrNull()
    Get the value if it is right or null if not.
    final <X extends Throwable>
    R
    getOrThrow(Supplier<X> ifUndefined)
    Get the contained value or throws the supplied throwable if left
    (package private) R
    getRight()
     
    abstract boolean
    isLeft()
    Returns true if this either is a left, false otherwise.
    abstract boolean
    isRight()
    Returns true if this either is a right, false otherwise.
    final Either<L,R>.LeftProjection
    left()
    Projects this either as a left.
    static <L,R> Either<L,R>
    left(L left)
    left.
    final <X> Either<X,R>
    leftMap(Function<? super L, X> f)
    Map the given function across the left hand side value if it is one.
    final L
    leftOr(Function<R, ? extends L> rightTransformer)
    If this is a left return the contained value, else return the result of applying rightTransformer on right
    final <X> Either<L,X>
    map(Function<? super R, X> f)
    Map the given function across the right hand side value if it is one.
    final Either<L,R>
    orElse(Either<? extends L, ? extends R> orElse)
    If this is a right, return the same right.
    final Either<L,R>
    orElse(Supplier<? extends Either<? extends L, ? extends R>> orElse)
    If this is a right, return the same right.
    final Either<L,R>.RightProjection
    right()
    Projects this either as a right.
    static <L,R> Either<L,R>
    right(R right)
    right.
    final R
    rightOr(Function<L, ? extends R> leftTransformer)
    If this is a right return the contained value, else return the result of applying leftTransformer on left
    <X> Either<L,X>
    sequence(Either<L,X> e)
    Will return the supplied Either if this one is right, otherwise this one if left.
    abstract Either<R,L>
    swap()
    If this is a left, then return the left value in right, or vice versa.
    final Option<R>
    toOption()
    Convert this Either to an Option.
    final Optional<R>
    toOptional()
    Convert this Either to an Optional.
    final Stream<R>
    toStream()
    Convert this Either to a Stream.
    final R
    valueOr(Function<L, ? extends R> or)
    Deprecated.
    In favor of rightOr

    Methods inherited from class Object

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

  • Field Details

  • Constructor Details

    • Either

      Either()

  • Method Details

    • left

      public static <L,R> Either<L,R> left(L left)

      left.

      Type Parameters:
      L - the LHS type
      R - the RHS type
      Parameters:
      left - the value to be stored, must not be null
      Returns:
      a Left containing the supplied value
      Since:
      1.0

    • right

      public static <L,R> Either<L,R> right(R right)

      right.

      Type Parameters:
      L - the LHS type
      R - the RHS type
      Parameters:
      right - the value to be stored, must not be null
      Returns:
      a Right containing the supplied value
      Since:
      1.0

    • left

      public final Either<L,R>.LeftProjection left()
      Projects this either as a left.
      Returns:
      A left projection of this either.

    • right

      public final Either<L,R>.RightProjection right()
      Projects this either as a right.
      Returns:
      A right projection of this either.

    • getOr

      public final R getOr(Supplier<? extends R> supplier)
      Get the value if it is a right or call the supplier and return its value if not.
      Parameters:
      supplier - called if this is a left
      Returns:
      the wrapped value or the value from the Supplier
      Since:
      4.3

    • getOrElse

      @Deprecated public final R getOrElse(Supplier<? extends R> supplier)
      Deprecated.
      since 4.3, use getOr(Supplier) instead
      Get the value if it is a right or call the supplier and return its value if not.
      Parameters:
      supplier - called if this is a left
      Returns:
      the wrapped value or the value from the Supplier
      Since:
      2.3

    • getOrElse

      public final <X extends R> R getOrElse(X other)
      Get the value if it is a right, otherwise returns other.
      Type Parameters:
      X - default type
      Parameters:
      other - value to return if this is a left
      Returns:
      wrapped value if this is a right, otherwise returns other
      Since:
      2.3

    • getOrNull

      public final R getOrNull()
      Get the value if it is right or null if not.

      Although the use of null is discouraged, code written to use these must often interface with code that expects and returns nulls.

      Returns:
      the contained value or null
      Since:
      2.3

    • getOrError

      public final R getOrError(Supplier<String> msg)
      Get the contained value or throws an error with the supplied message if left.

      Used when absolutely sure this is a right.

      Parameters:
      msg - the message for the error.
      Returns:
      the contained value.
      Since:
      2.3

    • getOrThrow

      public final <X extends Throwable> R getOrThrow(Supplier<X> ifUndefined) throws X
      Get the contained value or throws the supplied throwable if left

      Used when absolutely sure this is a right.

      Type Parameters:
      X - exception type
      Parameters:
      ifUndefined - the supplier of the throwable.
      Returns:
      the contained value.
      Throws:
      X - the throwable the supplier creates if there is no value.
      Since:
      2.3

    • map

      public final <X> Either<L,X> map(Function<? super R, X> f)
      Map the given function across the right hand side value if it is one.
      Type Parameters:
      X - the RHS type
      Parameters:
      f - The function to map .
      Returns:
      A new either value after mapping with the function applied if this is a Right.
      Since:
      2.2

    • flatMap

      public final <X, LL extends L> Either<L,X> flatMap(Function<? super R, Either<LL,X>> f)
      Binds the given function across the right hand side value if it is one.
      Type Parameters:
      X - the RHS type
      LL - result type
      Parameters:
      f - the function to bind.
      Returns:
      A new either value after binding with the function applied if this is a Right.
      Since:
      2.2

    • exists

      public final boolean exists(Predicate<? super R> p)
      Return `true` if this is a right value and applying the predicate to the contained value returns true.
      Parameters:
      p - the predicate to test.
      Returns:
      true if right and the predicate returns true for the right value, false otherwise.
      Since:
      2.3

    • forall

      public final boolean forall(Predicate<? super R> p)
      Returns true if it is a left or the result of the application of the given predicate on the contained value.
      Parameters:
      p - The predicate function to test on the contained value.
      Returns:
      true if no value or returns the result of the application of the given function to the value.
      Since:
      2.3

    • contains

      public final boolean contains(R elem)
      Tests whether the option contains a given value as an element.
      Parameters:
      elem - the element to test
      Returns:
      true if the option has an element that is equal to elem, false otherwise
      Since:
      6.1

    • foreach

      @Deprecated public final void foreach(Effect<? super R> effect)
      Deprecated.
      use forEach(Consumer) instead
      Perform the given side-effect for the contained element if it is a right
      Parameters:
      effect - the input to use for performing the effect on contained value.
      Since:
      2.3

    • forEach

      public final void forEach(Consumer<? super R> effect)
      Perform the given side-effect for the contained element if it is a right
      Parameters:
      effect - the input to use for performing the effect on contained value.
      Since:
      3.1

    • orElse

      public final Either<L,R> orElse(Either<? extends L, ? extends R> orElse)
      If this is a right, return the same right. Otherwise, return orElse .
      Parameters:
      orElse - either to return if this is left
      Returns:
      this or orElse
      Since:
      2.3

    • orElse

      public final Either<L,R> orElse(Supplier<? extends Either<? extends L, ? extends R>> orElse)
      If this is a right, return the same right. Otherwise, return value supplied by orElse.
      Parameters:
      orElse - either to return if this is left
      Returns:
      this or orElse
      Since:
      2.3

    • valueOr

      @Deprecated public final R valueOr(Function<L, ? extends R> or)
      Deprecated.
      In favor of rightOr
      If this is a right return the contained value, else return the result of running function on left
      Parameters:
      or - Function to run if this is a left
      Returns:
      contained value of R or result of or
      Since:
      2.3
      See Also:

    • rightOr

      public final R rightOr(Function<L, ? extends R> leftTransformer)
      If this is a right return the contained value, else return the result of applying leftTransformer on left
      Parameters:
      leftTransformer - Function to run on left if this is a left
      Returns:
      contained value of right or result of leftTransformer
      Since:
      3.2

    • leftOr

      public final L leftOr(Function<R, ? extends L> rightTransformer)
      If this is a left return the contained value, else return the result of applying rightTransformer on right
      Parameters:
      rightTransformer - Function to run on right if this is a right
      Returns:
      contained value of left or result of rightTransformer
      Since:
      3.2

    • filter

      public final Option<Either<L,R>> filter(Predicate<? super R> p)
      Returns None if this is a left or if the given predicate p does not hold for the contained value, otherwise, returns a right in Some.
      Parameters:
      p - The predicate function to test on the right contained value.
      Returns:
      None if this is a left or if the given predicate p does not hold for the right contained value, otherwise, returns a right in Some.
      Since:
      2.3

    • filterOrElse

      public final Either<L,R> filterOrElse(Predicate<? super R> p, Supplier<? extends L> orElseSupplier)
      Return a Right if this is a Right and the contained values satisfies the given predicate. If this is a Right but the predicate is not satisfied, return a Left with the value provided by the orElseSupplier. Return a Left if this a Left with the contained value.
      Parameters:
      p - The predicate function to test on the right contained value.
      orElseSupplier - The supplier to execute when is a right, and predicate is unsatisfied
      Returns:
      a new Either that will be either the existing left/right or a left with result of orElseSupplier
      Since:
      4.7.0

    • toOptional

      public final Optional<R> toOptional()
      Convert this Either to an Optional. Returns with Optional.of(Object) if it is a right, otherwise Optional.empty().
      Returns:
      The right projection's value in of if it exists, otherwise empty.
      Since:
      4.0

    • toOption

      public final Option<R> toOption()
      Convert this Either to an Option. Returns Some with a value if it is a right, otherwise None.
      Returns:
      The right projection's value in Some if it exists, otherwise None.
      Since:
      2.6

    • toStream

      public final Stream<R> toStream()
      Convert this Either to a Stream. Returns with Stream.of(Object) if it is a right, otherwise Stream.empty().
      Returns:
      The right projection's value in of if it exists, otherwise empty.
      Since:
      4.5.0

    • sequence

      public <X> Either<L,X> sequence(Either<L,X> e)
      Will return the supplied Either if this one is right, otherwise this one if left.
      Type Parameters:
      X - the RHS type
      Parameters:
      e - The value to bind with.
      Returns:
      An either after binding through this projection.
      Since:
      2.6

    • apply

      @Deprecated public <X> Either<L,X> apply(Either<L, Function<R,X>> either)
      Deprecated.
      since 3.0 see ap(Either)
      Given a right containing a function from the right type <R> to a new type <X> apply that function to the value inside this either. When any of the input values are left return that left value.
      Type Parameters:
      X - the RHS type
      Parameters:
      either - The either of the function to apply if this is a Right.
      Returns:
      The result of function application within either.
      Since:
      2.6

    • ap

      public <X> Either<L,X> ap(Either<L, Function<R,X>> either)
      Function application on this projection's value.
      Type Parameters:
      X - the RHS type
      Parameters:
      either - The either of the function to apply on this projection's value.
      Returns:
      The result of function application within either.
      Since:
      3.0

    • leftMap

      public final <X> Either<X,R> leftMap(Function<? super L, X> f)
      Map the given function across the left hand side value if it is one.
      Type Parameters:
      X - the LHS type
      Parameters:
      f - The function to map.
      Returns:
      A new either value after mapping with the function applied if this is a Left.
      Since:
      2.2

    • isLeft

      public abstract boolean isLeft()
      Returns true if this either is a left, false otherwise.
      Returns:
      true if this either is a left, false otherwise.

    • isRight

      public abstract boolean isRight()
      Returns true if this either is a right, false otherwise.
      Returns:
      true if this either is a right, false otherwise.

    • swap

      public abstract Either<R,L> swap()
      If this is a left, then return the left value in right, or vice versa.
      Returns:
      an Either that is a Left if this is a Right or a Right if this is a Left. The value remains the same.

    • fold

      public abstract <V> V fold(Function<? super L, V> ifLeft, Function<? super R, V> ifRight)
      Applies the function to the wrapped value, applying ifLeft if this is a Left and ifRight if this is a Right.
      Type Parameters:
      V - the destination type
      Parameters:
      ifLeft - the function to apply if this is a Left
      ifRight - the function to apply if this is a Right
      Returns:
      the result of the applies function

    • bimap

      public abstract <LL,RR> Either<LL,RR> bimap(Function<? super L, ? extends LL> ifLeft, Function<? super R, ? extends RR> ifRight)
      Map the given functions across the appropriate side.
      Type Parameters:
      LL - the LHS type
      RR - the RHS type
      Parameters:
      ifLeft - The function to map if this Either is a left.
      ifRight - The function to map if this Either is a right.
      Returns:
      A new either value after mapping with the appropriate function applied.
      Since:
      2.2

    • getLeft

      L getLeft()

    • getRight

      R getRight()