cascading.cascade

## Interface Cascade

- All Superinterfaces:
    UnitOfWork<CascadeStats>
  All Known Implementing Classes:
    BaseCascade

      public interface Cascade
      extends UnitOfWork<CascadeStats>

  A Cascade is an assembly of `Flow` instances that share or depend on equivalent `Tap` instances and are executed as a single group. The most common case is where one Flow instance depends on a Tap created by a second Flow instance. This dependency chain can continue as practical.

  Note Flow instances that have no shared dependencies will be executed in parallel.

  Additionally, a Cascade allows for incremental builds of complex data processing processes. If a given source `Tap` is newer than a subsequent sink `Tap` in the assembly, the connecting `Flow`(s) will be executed when the Cascade executed. If all the targets (sinks) are up to date, the Cascade exits immediately and does nothing.

  The concept of 'stale' is pluggable, see the `FlowSkipStrategy` class.

  When a Cascade starts up, if first verifies which Flow instances have stale sinks, if the sinks are not stale, the method `BaseFlow.deleteSinksIfNotUpdate()` is called. Before appends/updates were supported (logically) the Cascade deleted all the sinks in a Flow. Then and now, the `SinkMode.KEEP` is not honored when the Tap is participating in a Cascade.

  The new consequence of this is if the Cascade fails, but does complete a Flow that appended or updated data, re-running the Cascade (and the successful append/update Flow) will re-update data to the source. Some systems may be idempotent and may not have any side-effects. So plan accordingly.

  Use the `CascadeListener` to receive any events on the life-cycle of the Cascade as it executes. Any `Tap` instances owned by managed Flows also implementing CascadeListener will automatically be added to the set of listeners.
  See Also:
    `CascadeListener`, `Flow`, `FlowSkipStrategy`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addListener(CascadeListener cascadeListener)`
    `void` | `complete()` Method complete begins the current Cascade process if method `start()` was not previously called.
    `java.util.List<Flow>` | `findFlows(java.lang.String regex)` Method findFlows returns a List of flows whose names match the given regex pattern.
    `java.util.Collection<Flow>` | `findFlowsSinkingTo(java.lang.String identifier)` Method findFlowsSinkingTo returns all Flow instances that writes to a sink with the given identifier.
    `java.util.Collection<Flow>` | `findFlowsSourcingFrom(java.lang.String identifier)` Method findFlowsSourcingFrom returns all Flow instances that reads from a source with the given identifier.
    `java.util.Collection<Tap>` | `getAllTaps()` Method getAllTaps returns all source, sink, and checkpoint Tap instances associated with the managed Flow instances in this Cascade instance.
    `CascadeStats` | `getCascadeStats()` Method getCascadeStats returns the cascadeStats of this Cascade object.
    `java.util.Collection<Tap>` | `getCheckpointsTaps()` Method getCheckpointTaps returns all checkpoint Tap instances from all the Flow instances in this Cascade instance.
    `java.util.List<Flow>` | `getFlows()` Method getFlows returns the flows managed by this Cascade object.
    `FlowSkipStrategy` | `getFlowSkipStrategy()` Method getFlowSkipStrategy returns the current `FlowSkipStrategy` used by this Flow.
    `java.util.Collection<Flow>` | `getHeadFlows()` Method getHeadFlows returns all Flow instances that are at the "head" of the flow graph.
    `java.util.Collection<Flow>` | `getIntermediateFlows()` Method getIntermediateFlows returns all Flow instances that are neither at the "tail" or "tail" of the flow graph.
    `java.util.Collection<Tap>` | `getIntermediateTaps()` Method getIntermediateTaps returns all Tap instances that are neither at the source or sink of the flow graph.
    `java.util.Collection<Flow>` | `getPredecessorFlows(Flow flow)` Method getPredecessorFlows returns a Collection of all the Flow instances that will be executed before the given Flow instance.
    `java.util.Collection<Tap>` | `getSinkTaps()` Method getSinkTaps returns all sink Tap instances in this Cascade instance.
    `java.util.Collection<Tap>` | `getSourceTaps()` Method getSourceTaps returns all source Tap instances in this Cascade instance.
    `java.util.Collection<Flow>` | `getSuccessorFlows(Flow flow)` Method getSuccessorFlows returns a Collection of all the Flow instances that will be executed after the given Flow instance.
    `java.util.Collection<Flow>` | `getTailFlows()` Method getTailFlows returns all Flow instances that are at the "tail" of the flow graph.
    `boolean` | `hasListeners()`
    `boolean` | `removeListener(CascadeListener flowListener)`
    `FlowSkipStrategy` | `setFlowSkipStrategy(FlowSkipStrategy flowSkipStrategy)` Method setFlowSkipStrategy sets a new `FlowSkipStrategy`, the current strategy, if any, is returned.
    `void` | `start()` Method start begins the current Cascade process.
    `void` | `stop()`
    `void` | `writeDOT(java.lang.String filename)` Method writeDOT writes this element graph to a DOT file for easy visualization and debugging.

    - ### Methods inherited from interface cascading.management.UnitOfWork

      `cleanup, getID, getName, getSpawnStrategy, getStats, getTags, prepare, setSpawnStrategy`

- - ### Method Detail

    - #### hasListeners

          boolean hasListeners()

    - #### addListener

          void addListener(CascadeListener cascadeListener)

    - #### removeListener

          boolean removeListener(CascadeListener flowListener)

    - #### getCascadeStats

          CascadeStats getCascadeStats()

      Method getCascadeStats returns the cascadeStats of this Cascade object.
      Returns:
        the cascadeStats (type CascadeStats) of this Cascade object.

    - #### getFlows

          java.util.List<Flow> getFlows()

      Method getFlows returns the flows managed by this Cascade object. The returned `Flow` instances will be in topological order.
      Returns:
        the flows (type Collection) of this Cascade object.

    - #### findFlows

          java.util.List<Flow> findFlows(java.lang.String regex)

      Method findFlows returns a List of flows whose names match the given regex pattern.
      Parameters:
        `regex` - of type String
      Returns:
        List

    - #### getHeadFlows

          java.util.Collection<Flow> getHeadFlows()

      Method getHeadFlows returns all Flow instances that are at the "head" of the flow graph.

      That is, they are the first to execute and have no Tap source dependencies with Flow instances in the this Cascade instance.
      Returns:
        Collection

    - #### getTailFlows

          java.util.Collection<Flow> getTailFlows()

      Method getTailFlows returns all Flow instances that are at the "tail" of the flow graph.

      That is, they are the last to execute and have no Tap sink dependencies with Flow instances in the this Cascade instance.
      Returns:
        Collection

    - #### getIntermediateFlows

          java.util.Collection<Flow> getIntermediateFlows()

      Method getIntermediateFlows returns all Flow instances that are neither at the "tail" or "tail" of the flow graph.
      Returns:
        Collection

    - #### getSourceTaps

          java.util.Collection<Tap> getSourceTaps()

      Method getSourceTaps returns all source Tap instances in this Cascade instance.

      That is, none of returned Tap instances are the sinks of other Flow instances in this Cascade.

      All `CompositeTap` instances are unwound if addressed directly by a managed Flow instance.
      Returns:
        Collection

    - #### getSinkTaps

          java.util.Collection<Tap> getSinkTaps()

      Method getSinkTaps returns all sink Tap instances in this Cascade instance.

      That is, none of returned Tap instances are the sources of other Flow instances in this Cascade.

      All `CompositeTap` instances are unwound if addressed directly by a managed Flow instance.

      This method will return checkpoint Taps managed by Flow instances if not used as a source by other Flow instances.
      Returns:
        Collection

    - #### getCheckpointsTaps

          java.util.Collection<Tap> getCheckpointsTaps()

      Method getCheckpointTaps returns all checkpoint Tap instances from all the Flow instances in this Cascade instance.
      Returns:
        Collection

    - #### getIntermediateTaps

          java.util.Collection<Tap> getIntermediateTaps()

      Method getIntermediateTaps returns all Tap instances that are neither at the source or sink of the flow graph.

      This method does consider checkpoint Taps managed by Flow instances in this Cascade instance.
      Returns:
        Collection

    - #### getAllTaps

          java.util.Collection<Tap> getAllTaps()

      Method getAllTaps returns all source, sink, and checkpoint Tap instances associated with the managed Flow instances in this Cascade instance.
      Returns:
        Collection

    - #### getSuccessorFlows

          java.util.Collection<Flow> getSuccessorFlows(Flow flow)

      Method getSuccessorFlows returns a Collection of all the Flow instances that will be executed after the given Flow instance.
      Parameters:
        `flow` - of type Flow
      Returns:
        Collection

    - #### getPredecessorFlows

          java.util.Collection<Flow> getPredecessorFlows(Flow flow)

      Method getPredecessorFlows returns a Collection of all the Flow instances that will be executed before the given Flow instance.
      Parameters:
        `flow` - of type Flow
      Returns:
        Collection

    - #### findFlowsSourcingFrom

          java.util.Collection<Flow> findFlowsSourcingFrom(java.lang.String identifier)

      Method findFlowsSourcingFrom returns all Flow instances that reads from a source with the given identifier.
      Parameters:
        `identifier` - of type String
      Returns:
        Collection

    - #### findFlowsSinkingTo

          java.util.Collection<Flow> findFlowsSinkingTo(java.lang.String identifier)

      Method findFlowsSinkingTo returns all Flow instances that writes to a sink with the given identifier.
      Parameters:
        `identifier` - of type String
      Returns:
        Collection

    - #### getFlowSkipStrategy

          FlowSkipStrategy getFlowSkipStrategy()

      Method getFlowSkipStrategy returns the current `FlowSkipStrategy` used by this Flow.
      Returns:
        FlowSkipStrategy

    - #### setFlowSkipStrategy

          FlowSkipStrategy setFlowSkipStrategy(FlowSkipStrategy flowSkipStrategy)

      Method setFlowSkipStrategy sets a new `FlowSkipStrategy`, the current strategy, if any, is returned. If a strategy is given, it will be used as the strategy for all `BaseFlow` instances managed by this Cascade instance. To revert back to consulting the strategies associated with each Flow instance, re-set this value to `null`, its default value.

      FlowSkipStrategy instances define when a Flow instance should be skipped. The default strategy is `FlowSkipIfSinkNotStale` and is inherited from the Flow instance in question. An alternative strategy would be `FlowSkipIfSinkExists`.

      A FlowSkipStrategy will not be consulted when executing a Flow directly through `start()`
      Parameters:
        `flowSkipStrategy` - of type FlowSkipStrategy
      Returns:
        FlowSkipStrategy

    - #### start

          void start()

      Method start begins the current Cascade process. It returns immediately. See method `complete()` to block until the Cascade completes.
      Specified by:
        `start` in interface `UnitOfWork<CascadeStats>`

    - #### complete

          void complete()

      Method complete begins the current Cascade process if method `start()` was not previously called. This method blocks until the process completes.
      Specified by:
        `complete` in interface `UnitOfWork<CascadeStats>`
      Throws:
        `java.lang.RuntimeException` - wrapping any exception thrown internally.

    - #### stop

          void stop()

      Specified by:
        `stop` in interface `UnitOfWork<CascadeStats>`

    - #### writeDOT

          void writeDOT(java.lang.String filename)

      Method writeDOT writes this element graph to a DOT file for easy visualization and debugging.
      Parameters:
        `filename` - of type String

Copyright © 2007-2015 Xplenty, Inc. All Rights Reserved.