com.hammurapi.common

## Class Joiner<T,C,R>

- java.lang.Object
- - com.hammurapi.common.Joiner<T,C,R>

- Type Parameters:
    `T` - Join element type.
    `C` - Context type passed from addInput to join.
    `R` - Return type passed from join to to addInput.
  Direct Known Subclasses:
    LocalJoiner

      public abstract class Joiner<T,C,R>
      extends Object

  Helper class to join data from several inputs.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Joiner.CollectionAdapter<T>` Adapter for collections.
    `static interface` | `Joiner.Collector<T>` Collector of objects to join.
    `static class` | `Joiner.InputConsumer` Interface to consume inputs in join() method.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `Joiner(Joiner.Collector<T>[] inputCollectors, Class<T> inputType, boolean outerJoin)` Creates joiner.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `List<R>` | `addInput(int index, T input, C context)` Adds input.
    `void` | `addPredicate(Predicate<T,C> predicate)` Adds join predicate.
    `protected abstract void` | `endJoin()` This method is invoked after join is finished.
    `protected boolean` | `isValidInput(int index, T input)` This method is invoked for all inputs before joining.
    `protected abstract R` | `join(T[] inputs, C context, Joiner.InputConsumer consumer, int activator)` This method is invoked for every combination of valid inputs.
    `protected void` | `join(T[] inputs, int currentIndex, int inputIndex, C context, Joiner.InputConsumer consumer, Map<C,Map<Extractor<T,? super Boolean,C>,? super Boolean>> cache, List<R> resultCollector)` This method can be overridden to implement concurrent joining, i.e.
    `protected boolean` | `partialJoin(T[] inputs, C context, Joiner.InputConsumer consumer, int index, int activator)` This method is invoked to validate already joined inputs.
    `void` | `reset()` Clears join collections.
    `protected abstract void` | `startJoin()` Start join is invoked before join.

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

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

- - ### Constructor Detail

    - #### Joiner

          protected Joiner(Joiner.Collector<T>[] inputCollectors,
                Class<T> inputType,
                boolean outerJoin)

      Creates joiner.
      Parameters:
        `inputCollectors` - Input collectors.
        `inputType` - Input type is required because of erasure of generics and T is needed at runtime.
        `outerJoin` - If true, each input addition triggers invocation of join, even if other input collectors don't have any data.

  - ### Method Detail

    - #### addPredicate

          public void addPredicate(Predicate<T,C> predicate)

      Adds join predicate.
      Parameters:
        `predicate` -

    - #### startJoin

          protected abstract void startJoin()

      Start join is invoked before join. Typically this method shall obtain a lock on input collectors.

    - #### endJoin

          protected abstract void endJoin()

      This method is invoked after join is finished. Typically this method shall release the lock on input collectors.

    - #### addInput

          public List<R> addInput(int index,
                         T input,
                         C context)
                           throws Exception

      Adds input. Input is joined with other accumulated inputs.
      Parameters:
        `index` - Input index.
        `input` - Input.
      Throws:
        `Exception`

    - #### join

          protected void join(T[] inputs,
                  int currentIndex,
                  int inputIndex,
                  C context,
                  Joiner.InputConsumer consumer,
                  Map<C,Map<Extractor<T,? super Boolean,C>,? super Boolean>> cache,
                  List<R> resultCollector)
                       throws Exception

      This method can be overridden to implement concurrent joining, i.e. at particular indices the sub-method wraps call to the super-method into a task executed in a separate thread.
      Parameters:
        `inputs` -
        `currentIndex` -
        `inputIndex` -
        `context` -
        `consumer` -
        `cache` -
        `resultCollector` -
      Throws:
        `Exception`

    - #### join

          protected abstract R join(T[] inputs,
               C context,
               Joiner.InputConsumer consumer,
               int activator)
                             throws Exception

      This method is invoked for every combination of valid inputs.
      Parameters:
        `inputs` - Inputs
        `context` - Join context passed from addInput
        `consumer` - callback interface to consume inputs.
        `activator` - Index of join activator.
      Returns:
        Join result.
      Throws:
        `Exception`

    - #### isValidInput

          protected boolean isValidInput(int index,
                             T input)

      This method is invoked for all inputs before joining. It is useful for situation when inputs in internal collections may become invalid over the course of life of joiner.
      Parameters:
        `index` -
        `input` -
      Returns:

    - #### partialJoin

          protected boolean partialJoin(T[] inputs,
                            C context,
                            Joiner.InputConsumer consumer,
                            int index,
                            int activator)
                                 throws Exception

      This method is invoked to validate already joined inputs. If this method returns false, further joining is abandoned.
      Parameters:
        `inputs` - Inputs array.
        `index` - Index of last already joined input.
        `consumer` - Callback interface to consume inputs.
      Returns:
      Throws:
        `Exception`

    - #### reset

          public void reset()

      Clears join collections.