Chaining API

Page Contents:

Chaining API Overview

Swiz provides a simple, yet powerful and extensible API for chaining actions together. At the heart of this API are the IChain and IChainStep interfaces. Let's look at them here, starting with IChain.

Most of the methods are self explanatory, so we'll only discuss the most important one directly. The doProceed() method is where a chain does its work. It's where EventChain dispatches events, and where CommandChain executes commands. If you clicked either of those links, you may have noticed that both chain types contain very little code other than their doProceed() implementations. This is because they both extend AbstractChain, which implements the entire IChain interface besides doProceed(). It does not actually implement IChain, however, which forces custom chain types to do so and to implement doProceed(). AbstractChain does implement IChainStep though, which means chains can be nested. Also note that chains can be run in either sequence or parallel mode, with constants defined for each in the ChainType class

IChainStep is the base interface for objects that can be part of a chain. The methods are again pretty self explanatory, but do notice the complete() and error() methods, which correspond to the stepComplete() and stepError() methods of IChain.

The last interface of the Swiz chaining API is IAutonomousChainStep.

While chains will often have specific logic for executing their constituent steps, sometimes it is beneficial for a step to control its own execution. This is especially useful for constructing chains with steps of varying types.

Provided implementations

Swiz provides some useful implementations of the chaining API for you. We previously mentioned EventChain, which is exactly what it sounds like. It allows you to string together EventChainStep instances, and also supports IAutonomousChainStep instances. EventChains can be extremely useful for things like application boot strapping and making multiple remote service calls.

CommandChain provides a mechanism for assembling CommandChainStep instances, as well as AsyncCommandChainStep instances (they extend CommandChainStep and implement IResponder) and implementations of IAutonomousChainStep.

Here is an example of a simple EventChain that dispatches a series of events as a single unit:

EventChainSteps may optionally specify a dispatcher. If none is specified, the EventChain will assign its dispatcher to the EventChainStep before executing that step.

FunctionChainStep is another useful class that implements IAutonomousChainStep and allows for deferred function invocation.

Finally, note that BaseChainStep provides a base implementation of IChainStep, making your custom implementations that much easier to write.

Custom implementations

It is extremely easy to extend the chaining API to meet your specific needs. As mentioned above, creating a custom chain type essentially boils down to extending AbstractChain, adding "implements IChain" and then implementing the doProceed() method. Your doProceed() method could execute custom chain step types, log or otherwise audit chain progress or perform any other custom behavior you desire. A simple chain that relies on autonomous steps is shown below.

Custom chain steps can be made to perform virtually any action. They will need to implement IChainStep, which is most easily done by extending BaseChainStep. If they implement IAutonomousChainStep they can be virtually self contained, and can easily be combined with other chain step types. An example of a custom chain step which sets a property on an object is shown below.

Automatic Asynchronous Handling in Chains

The Event Chaining API also supports automatic asynchronous handling of chain steps. If an [EventHandler] method is called as part of an event chain, it can return an AsyncToken or IAsynchronousOperation to participate in automatic asynchronous handling. In that case, the chain that is executing will wait until the operation is complete before proceeding to the next chain step. Further, if there are multiple [EventHandler]'s for a given Event, the chain will wait until all associated asynchronous operations are complete before proceeding to the next chain step.

Not all asynchronous Flash or Flex API operations return AsyncToken. Consequently, the internal logic related to asynchronous handling is based upon IAsynchronousOperation. Swiz provides three concrete implementations that adapt typical Flash / Flex asynchronous operations into IAsynchronousOperations.

1. AsyncTokenOperation - which adapts an AsyncToken.
2. AsynchronousChainOperation - which adapts an asynchronous IChain.
3. AsynchronousIOOperation - which adapts Flash or Flex API operations that signal success or failure by dispatching Event.COMPLETE / Event.CANCEL / IOEvent.IO_ERROR / SecurityErrorEvent.SECURITY_ERROR events (ex. FileReference). AsynchronousIOOperation extends AbstractAsynchronousDispatcherOperation, so you can extend this abstract base class to adapt other asynchronous operations that signal their success or failure via Events if necessary.

As noted earlier, [EventHandler] methods can simply return an AsyncToken. The [EventHandler] metadata processor will automatically adapt the AsyncToken via AsyncTokenOperation.

For example, here is an event chain that will automatically wait for a service call to complete before moving on to the next step. First, we'll see the event that will be used for the asynchronous events in the chain. Note that it extends AsynchronousEvent, which is necessary to allow the event to keep track of the chain step it is associated with:

And then the code that actually builds up the chain and starts the processing:

As another example, a URL request is adapted via AsynchronousIOOperation to allow Swiz to wait for completion before the chain proceeds:

An [EventHandler] method can also construct an asynchronous chain and return that chain as an operation (adapting it via AsynchronousChainOperation). In that case, the original EventChainStep will not proceed until the entire child chain is complete.

Go forth and chain stuff!

Hopefully this page has shown you the ease, power and extensibility of the Swiz chaining API. If you have questions or comments about the API or any of the built in implementations, or even just ideas you'd like to discuss, please head over to the mailing list and we'll be happy to help!