de.caff.generics

## Class UnionBase<T1,T2>

- java.lang.Object
- - de.caff.generics.UnionBase<T1,T2>

- Type Parameters:
    `T1` - first possible type
    `T2` - second possible type
  Direct Known Subclasses:
    NullableUnion, Union

      public abstract class UnionBase<T1,T2>
      extends java.lang.Object

  Helper interface for a union of two exclusive values of different types.

  This is mainly used to be able to compare both `Union` and `NullableUnion`. It can also be used as a type where both can appear. To ensure the invariances of unions, objects of this class cannot be constructed outside of this package.

  Since:
    July 26, 2024
  Author:
    Rammi

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `UnionBase()` Make this class unconstructable outside of this package.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract void` | `dispose(java.util.function.Consumer<? super T1> handler1, java.util.function.Consumer<? super T2> handler2)` Call the appropriate handler depending on this unions' value.
    `abstract <E extends java.lang.Exception> UnionBase<T1,T2>` | `disposeFragile1(FragileProcedure1<E,? super T1> handler)` Call the given handler if this union contains a value of type `T1`.
    `abstract <E extends java.lang.Exception> UnionBase<T1,T2>` | `disposeFragile2(FragileProcedure1<E,? super T2> handler)` Call the given handler if this union contains a value of type `T2`.
    `abstract UnionBase<T1,T2>` | `disposeOnly1(java.util.function.Consumer<? super T1> handler)` Call the given handler if this union contains a value of type `T1`.
    `abstract UnionBase<T1,T2>` | `disposeOnly2(java.util.function.Consumer<? super T2> handler)` Call the given handler if this union contains a value of type `T2`.
    `abstract T1` | `get1()` Get the value if it is of type `T1`.
    `abstract T2` | `get2()` Get the value if it is of type `T2`.
    `abstract java.lang.Object` | `getValue()` Get the value contained in this union.
    `abstract boolean` | `has1()` Does this union contain a value of type `T1`?
    `abstract boolean` | `has2()` Does this union contain a value of type `T2`?
    `(package private) static boolean` | `isEqual1(UnionBase<?,?> definitely1, java.lang.Object maybe1)` Check whether two unions using their first type define the same value.
    `(package private) static boolean` | `isEqual2(UnionBase<?,?> definitely2, java.lang.Object maybe2)` Check whether two unions using their first type define the same value.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### UnionBase

          UnionBase()

      Make this class unconstructable outside of this package. This is the only reason this is implemented as an abstract class instead of an interface.

  - ### Method Detail

    - #### has1

          public abstract boolean has1()

      Does this union contain a value of type `T1`?
      Returns:
        `true`: if this union contains a value of type `T1`
        `false`: if this union contains a value of type `T2`
      See Also:
        `get1()`

    - #### has2

          public abstract boolean has2()

      Does this union contain a value of type `T2`?
      Returns:
        `true`: if this union contains a value of type `T2`
        `false`: if this union contains a value of type `T1`
      See Also:
        `get2()`

    - #### get1

          public abstract T1 get1()
                           throws java.lang.IllegalStateException

      Get the value if it is of type `T1`. Throw an exception otherwise.
      Returns:
        value of type `T1`
      Throws:
        `java.lang.IllegalStateException` - if this union does contain a value of type `T2`
      See Also:
        `has1()`

    - #### get2

          public abstract T2 get2()
                           throws java.lang.IllegalStateException

      Get the value if it is of type `T2`. Throw an exception otherwise.
      Returns:
        value of type `T2`
      Throws:
        `java.lang.IllegalStateException` - if this union does contain a value of type `T1`
      See Also:
        `has1()`

    - #### getValue

          public abstract java.lang.Object getValue()

      Get the value contained in this union.
      Returns:
        the value of this union, having either type `T1` or `T2`

    - #### dispose

          public abstract void dispose(@NotNull
                                       java.util.function.Consumer<? super T1> handler1,
                                       @NotNull
                                       java.util.function.Consumer<? super T2> handler2)

      Call the appropriate handler depending on this unions' value.
      Parameters:
        `handler1` - called if this union contains a value of type `T1`
        `handler2` - called if this union contains a value of type `T2`

    - #### disposeOnly1

          @NotNull
          public abstract UnionBase<T1,T2> disposeOnly1(@NotNull
                                                                 java.util.function.Consumer<? super T1> handler)

      Call the given handler if this union contains a value of type `T1`.
      Parameters:
        `handler` - called with the value of this union if the contained type is `T1`, not called otherwise
      Returns:
        this union for chaining, allowing to call disposeOnly2(Consumer) or disposeFragile2(FragileProcedure1) next

    - #### disposeOnly2

          @NotNull
          public abstract UnionBase<T1,T2> disposeOnly2(@NotNull
                                                                 java.util.function.Consumer<? super T2> handler)

      Call the given handler if this union contains a value of type `T2`.
      Parameters:
        `handler` - called with the value of this union if the contained type is `T2`, not called otherwise
      Returns:
        this union for chaining, allowing to call disposeOnly1(Consumer) or disposeFragile1(FragileProcedure1) next

    - #### disposeFragile1

          @NotNull
          public abstract <E extends java.lang.Exception> UnionBase<T1,T2> disposeFragile1(@NotNull
                                                                                                    FragileProcedure1<E,? super T1> handler)
                                                                                             throws E extends java.lang.Exception

      Call the given handler if this union contains a value of type `T1`. Allows for a handler which might throw a checked exception.
      Type Parameters:
        `E` - exception the handler might throw
      Parameters:
        `handler` - called with the value of this union if the contained type is `T1`, not called otherwise
      Returns:
        this union for chaining, allowing to call disposeOnly2(Consumer) or disposeFragile2(FragileProcedure1) next
      Throws:
        `E` - if `handler` throws it
        `E extends java.lang.Exception`

    - #### disposeFragile2

          @NotNull
          public abstract <E extends java.lang.Exception> UnionBase<T1,T2> disposeFragile2(@NotNull
                                                                                                    FragileProcedure1<E,? super T2> handler)
                                                                                             throws E extends java.lang.Exception

      Call the given handler if this union contains a value of type `T2`. Allows for a handler which might throw a checked exception.
      Type Parameters:
        `E` - exception the handler might throw
      Parameters:
        `handler` - called with the value of this union if the contained type is `T2`, not called otherwise
      Returns:
        this union for chaining, allowing to call disposeOnly1(Consumer) or disposeFragile1(FragileProcedure1) next
      Throws:
        `E` - if `handler` throws it
        `E extends java.lang.Exception`

    - #### isEqual1

          static boolean isEqual1(@NotNull
                                  UnionBase<?,?> definitely1,
                                  @Nullable
                                  java.lang.Object maybe1)

      Check whether two unions using their first type define the same value.
      Parameters:
        `definitely1` - a union which definitely contains a value of type `V1`
        `maybe1` - a possible union which may contain a first value of type `V1`
      Returns:
        `true`: `maybe1` is using its first type, and the object contained is the same as the one from `definitely1`

    - #### isEqual2

          static boolean isEqual2(@NotNull
                                  UnionBase<?,?> definitely2,
                                  @Nullable
                                  java.lang.Object maybe2)

      Check whether two unions using their first type define the same value.
      Parameters:
        `definitely2` - a union which definitely contains a value of type `V2`
        `maybe2` - a possible union which may contain a first value of type `V2`
      Returns:
        `true`: `maybe1` is using its second type, and the object contained is the same as the one from `definitely1`