Package com.pulumi.core

Class Either<L,R>

java.lang.Object
com.pulumi.core.Either<L,R>
Type Parameters:
L - the type contained by the Left instance
R - the type contained by the Right instance
All Implemented Interfaces:
Serializable
@CheckReturnValue public abstract class Either<L,R> extends Object implements Serializable
Represents a value of one of two possible types (a disjoint union). Instances of Either are either an instance of Left or Right.

Either is an algebraic data type similar to the an Option/Optional.

A common use of Either is as an alternative to Optional for dealing with possible missing values. In this usage, Absent is replaced with a Left which can contain useful information. Right takes the place of Present. Convention dictates that Left is used for failure and Right is used for success.

A non-null Either<L,R> reference can be used as an alternative to the classic error handling (exceptions). 

  public static Either<Exception, Integer> divide(int x, int y) {
    try {
      return Either.valueOf(x / y);
    } catch (Exception e) {
      return Either.errorOf(e);
    }
  }
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    abstract <V> V
    either(Function<L,V> leftFunction, Function<R,V> rightFunction)
    Applies leftFunction if this is a Left or rightFunction if this is a Right.
    abstract boolean
    equals(Object object)
    Returns true if object is an Either instance, and either the contained references are equal to each other.
    L
    error()
    Same as left(), a convenience method for Value/Error use case.
    static <L, R> Either<L,R>
    errorOf(L reference)
    Same as ofLeft(L), a convenience method for Value/Error use case.
    abstract <R1> Either<L,R1>
    flatMap(Function<? super R,? extends Either<? extends L,? extends R1>> mapper)
    Applies function if this is a Right or returns Left.
    abstract int
    hashCode()
     
    boolean
    isError()
    Same as isLeft(), a convenience method for Value/Error use case.
    abstract boolean
    isLeft()
     
    abstract boolean
    isRight()
     
    boolean
    isValue()
    Same as isRight(), a convenience method for Value/Error use case.
    abstract L
    left()
    Returns the contained instance, which must be present.
    <R1> Either<L,R1>
    map(Function<? super R,? extends R1> mapper)
    Applies function if this is a Right or returns Left.
    abstract <T, E extends Exception>
    T
    mapOrThrow(Function<L,E> leftFunction, Function<R,T> rightFunction)
    Returns the Right instance, if present, mapped with the given rightFunction; throw leftFunction.apply(left()) otherwise.
    static <L, R> Either<L,R>
    ofLeft(L reference)
    Returns an Either instance containing the given non-null reference.
    static <L, R> Either<L,R>
    ofRight(R reference)
    Returns an Either instance containing the given non-null reference.
    abstract Either<L,R>
    or(Either<? extends L,? extends R> secondChoice)
    Returns this Either if it has the Right value present; secondChoice otherwise.
    abstract R
    or(R defaultValue)
    Returns this Either value if it has the Right value present; defaultValue otherwise.
    abstract <E extends Exception>
    R
    orThrow(Function<L,E> leftFunction)
    Returns the Right value if it is present; throw leftFunction.apply(left()) otherwise.
    abstract R
    right()
    Returns the contained instance, which must be present.
    abstract Either<R,L>
    swap()
    If this is a Left, then return the left value in Right or vice versa.
    abstract String
    toString()
     
    abstract <A, B> Either<A,B>
    transform(Function<L,A> leftFunction, Function<R,B> rightFunction)
    Applies leftFunction if this is a Left or rightFunction if this is a Right.
    R
    value()
    Same as right(), a convenience method for Value/Error use case.
    static <L, R> Either<L,R>
    valueOf(R reference)
    Same as ofRight(R), a convenience method for Value/Error use case.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Method Details

    • valueOf

      public static <L, R> Either<L,R> valueOf(R reference)
      Same as ofRight(R), a convenience method for Value/Error use case.
      Type Parameters:
      L - the type contained by the Left instance
      R - the type contained by the Right instance
      Parameters:
      reference - the value to create the Right instance with
      Returns:
      new Right instance with the given value

    • errorOf

      public static <L, R> Either<L,R> errorOf(L reference)
      Same as ofLeft(L), a convenience method for Value/Error use case.
      Type Parameters:
      L - the type contained by the Left instance
      R - the type contained by the Right instance
      Parameters:
      reference - the value to create the Left instance with
      Returns:
      new Left instance with the given value

    • ofLeft

      public static <L, R> Either<L,R> ofLeft(L reference)
      Returns an Either instance containing the given non-null reference.
      Type Parameters:
      L - the type contained by the Left instance
      R - the type contained by the Right instance
      Parameters:
      reference - the value to create the Left instance with
      Returns:
      new Left instance with the given value
      Throws:
      NullPointerException - if reference is null

    • ofRight

      public static <L, R> Either<L,R> ofRight(R reference)
      Returns an Either instance containing the given non-null reference.
      Type Parameters:
      L - the type contained by the Left instance
      R - the type contained by the Right instance
      Parameters:
      reference - the value to create the Right instance with
      Returns:
      new Right instance with the given value
      Throws:
      NullPointerException - if reference is null

    • isValue

      public boolean isValue()
      Same as isRight(), a convenience method for Value/Error use case.
      Returns:
      true if this is a Right, false otherwise.

    • isError

      public boolean isError()
      Same as isLeft(), a convenience method for Value/Error use case.
      Returns:
      true if this is a Left, false otherwise.

    • isLeft

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

    • isRight

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

    • value

      public R value()
      Same as right(), a convenience method for Value/Error use case.
      Returns:
      the Right instance if present or throw

    • error

      public L error()
      Same as left(), a convenience method for Value/Error use case.
      Returns:
      the Left instance if present or throw

    • left

      public abstract L left()
      Returns the contained instance, which must be present. Otherwise, throw.
      Returns:
      the Left instance if present or throw
      Throws:
      IllegalStateException - if the instance is absent (isLeft() returns false); depending on this specific exception type (over the more general RuntimeException) is discouraged

    • right

      public abstract R right()
      Returns the contained instance, which must be present. Otherwise, throw.
      Returns:
      the Right instance if present or throw
      Throws:
      IllegalStateException - if the instance is absent (isRight() returns false); depending on this specific exception type (over the more general RuntimeException) is discouraged

    • or

      public abstract Either<L,R> or(Either<? extends L,? extends R> secondChoice)
      Returns this Either if it has the Right value present; secondChoice otherwise.
      Parameters:
      secondChoice - the alternative Either
      Returns:
      this instance if Right is present or secondChoice otherwise.

    • or

      public abstract R or(R defaultValue)
      Returns this Either value if it has the Right value present; defaultValue otherwise.
      Parameters:
      defaultValue - the alternative value
      Returns:
      this value if Right is present or defaultValue otherwise.

    • orThrow

      public abstract <E extends Exception> R orThrow(Function<L,E> leftFunction) throws E
      Returns the Right value if it is present; throw leftFunction.apply(left()) otherwise.
      Type Parameters:
      E - type of thrown exception mapped from left
      Parameters:
      leftFunction - the Left mapping function from left to an exception
      Returns:
      the Right value or throw the result of leftFunction
      Throws:
      E - type of thrown exception mapped from Left
      NullPointerException - if right value is absent or the given function is null

    • mapOrThrow

      public abstract <T, E extends Exception> T mapOrThrow(Function<L,E> leftFunction, Function<R,T> rightFunction) throws E
      Returns the Right instance, if present, mapped with the given rightFunction; throw leftFunction.apply(left()) otherwise.
      Type Parameters:
      T - type of the returned value mapped from Right
      E - type of thrown exception mapped from Left
      Parameters:
      leftFunction - the Left mapping function
      rightFunction - the Right mapping function
      Returns:
      T mapped with rightFunction if Right is present, or throw
      Throws:
      E - mapped with leftFunction if Left is present
      NullPointerException - if Right value is absent or a given function is null

    • either

      public abstract <V> V either(Function<L,V> leftFunction, Function<R,V> rightFunction)
      Applies leftFunction if this is a Left or rightFunction if this is a Right.
      Type Parameters:
      V - type of the value returned by either leftFunction or rightFunction
      Parameters:
      leftFunction - Left value mapper
      rightFunction - Right value mapper
      Returns:
      the result of the leftFunction or rightFunction
      Throws:
      NullPointerException - if any of the functions are null

    • transform

      public abstract <A, B> Either<A,B> transform(Function<L,A> leftFunction, Function<R,B> rightFunction)
      Applies leftFunction if this is a Left or rightFunction if this is a Right.
      Type Parameters:
      A - the Left type after transformation
      B - the Right type after transformation
      Parameters:
      leftFunction - Left value mapper
      rightFunction - Right value mapper
      Returns:
      an Either after transformation by leftFunction or rightFunction.
      Throws:
      NullPointerException - if any of the functions are null

    • flatMap

      public abstract <R1> Either<L,R1> flatMap(Function<? super R,? extends Either<? extends L,? extends R1>> mapper)
      Applies function if this is a Right or returns Left.
      Type Parameters:
      R1 - the type contained by the mapped Right instance
      Parameters:
      mapper - Right value mapper, with Either as result
      Returns:
      an Either after conditional transformation by function.
      Throws:
      NullPointerException - if function is null

    • map

      public <R1> Either<L,R1> map(Function<? super R,? extends R1> mapper)
      Applies function if this is a Right or returns Left.
      Type Parameters:
      R1 - the type contained by the mapped Right instance
      Parameters:
      mapper - Right value mapper, with R1 as result
      Returns:
      an Either after conditional transformation by function.
      Throws:
      NullPointerException - if function is null

    • swap

      public abstract Either<R,L> swap()
      If this is a Left, then return the left value in Right or vice versa.
      Returns:
      a new Either<R,L>

    • equals

      public abstract boolean equals(@Nullable Object object)
      Returns true if object is an Either instance, and either the contained references are equal to each other. Note that Either instances of differing parameterized types can be equal.
      Overrides:
      equals in class Object
      Parameters:
      object - the object to compare with
      Returns:
      true if given object is equal to this

    • hashCode

      public abstract int hashCode()
      Overrides:
      hashCode in class Object
      Returns:
      a hash code for this instance.

    • toString

      public abstract String toString()
      Overrides:
      toString in class Object
      Returns:
      a string representation for this instance.