Dispatches

Last updated: August 12th, 2023
Release:

Dispatches in the Chain system are primarily data carriers. Any information that should be carried along a chain to its nodes should be stored within the dispatch. During traversal, nodes can read from the dispatch and write to it for later nodes to see, or for the end result.

Concept

Dispatches by default have three 'states' that can be queried. Each defaults to false and must be set by any dispatch during initialization. The states are as follows:

  • Consumable
  • Stateful
  • Valid
Consumable

When a dispatch is marked as consumable, it tells the ChainHelper to stop traversing the chain if the dispatched is marked as 'consumed' by a node. This can be helpful for building chains that resemble the chain-of-responsibility pattern.

Stateful

All nodes are given the ability to store results in dispatches, and the dispatch's stateful setting will determine if only one result is allowed or multiple are kept. If multiple are set, they are returned as an array. A single result is returned if only one result is stored, and null is returned if there are no stored results.

Valid

In order for the ChainHelper to traverse a chain it must have both nodes and a valid dispatch. This gives developers the ability to enforce custom restrictions on data validity at initialization in order to stop chain traversal.

DispatchBase

All dispatches must implement the DispatchBase abstract class. This provides some minimum functionality and requires developers to implement an initialize() method. The following are the properties and methods defined in DispatchBase:

Properties

protected boolean $_isConsumable Whether or not the dispatch is 'consumable' protected boolean $_isStateful Whether or not the dispatch should retain multiple results protected boolean $_isConsumed Whether or not the dispatch has been consumed by a node protected mixed[] $_results Collection of results from processing nodes protected boolean $_isValid Whether or not the dispatch is valid for processing protected DateTimeInterface $_calledDateTime Date and time the dispatch was marked valid

Methods

public string __toString() Converts the class into a readable string public boolean consume() Marks dispatch as having been consumed public DateTimeInterface getCalledDateTime() Returns the date and time the dispatch was marked valid public mixed[]|mixed|null getResults() Returns any results stored in dispatch, single result if one, array of results if many, null if none abstract public void initialize(mixed $input) Abstract method that dispatch classes should use to handle initialization public boolean isConsumable() Returns whether or not the dispatch can be consumed public boolean isConsumed() Returns whether or not the dispatch has been consumed public boolean isStateful() Returns whether or not the dispatch will hold multiple results public boolean isValid() Returns whether or not the dispatch is valid for traversal protected DispatchBase makeConsumable() Sets a dispatch as consumable protected DispatchBase makeStateful() Sets a dispatch as stateful protected DispatchBase makeValid() Sets dispatch as valid and sets 'called' date and time in UTC offset public integer numResults() Returns the number of results stored in dispatch public DispatchBase setResult(mixed $result) Sets a result in the dispatch

Examples

For examples, see the 'Dispatch' section of the Examples page.

Further Reading

Next Up

Continue to read about nodes, or visit the Table of Contents.