h4. API
Swiz provides a simple, yet powerful and extensible API for chaining actions together. At the heart of this API are the [IChain|http://github.com/swiz/swiz-framework/blob/master/src/org/swizframework/utils/chain/IChain.as] and [IChainStep|http://github.com/swiz/swiz-framework/blob/master/src/org/swizframework/utils/chain/IChainStep.as] interfaces. Let's look at them here, starting with IChain.
{html}<script src="http://gist.github.com/410557.js?file=IChain.as"></script>{html}
\\
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|http://github.com/swiz/swiz-framework/blob/master/src/org/swizframework/utils/chain/EventChain.as] dispatches events, and where [CommandChain|http://github.com/swiz/swiz-framework/blob/master/src/org/swizframework/utils/chain/CommandChain.as] 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|http://github.com/swiz/swiz-framework/blob/master/src/org/swizframework/utils/chain/AbstractChain.as], which implements the entire IChain interface besides doProceed(). It does not actually implement IChain, however, forcing custom chain types to do so and to implement doProceed(). AbstractChain does implement IChainStep, however, which means chains can be nested. Note that chains can be run in either sequence or parallel mode, with constants defined for each in the [ChainType|http://github.com/swiz/swiz-framework/blob/master/src/org/swizframework/utils/chain/ChainType.as] class.
{html}<script src="http://gist.github.com/410557.js?file=IChainStep.as"></script>{html}
\\
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|http://github.com/swiz/swiz-framework/blob/master/src/org/swizframework/utils/chain/IAutonomousChainStep.as].
{html}<script src="http://gist.github.com/410557.js?file=IAutonomousChainStep.as"></script>{html}
\\
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 building chains that contain steps of multiple types.
//\\
h4. Provided implementations
Swiz provides some useful implementations of the chaining API for you. We previously mentioned [EventChain|http://github.com/swiz/swiz-framework/blob/master/src/org/swizframework/utils/chain/EventChain.as], which is exactly what it sounds like. It allows you to string together [EventChainStep|http://github.com/swiz/swiz-framework/blob/master/src/org/swizframework/utils/chain/EventChainStep.as] instances, and also supports IAutonomousChainStep instances. EventChains can be extremely useful for things like application boot strapping and making multiple remote service calls.
[CommandChain|http://github.com/swiz/swiz-framework/blob/master/src/org/swizframework/utils/chain/CommandChain.as] provides a mechanism for assembling [CommandChainStep|http://github.com/swiz/swiz-framework/blob/master/src/org/swizframework/utils/chain/CommandChainStep.as] instances, as well as [AsyncCommandChainStep|http://github.com/swiz/swiz-framework/blob/master/src/org/swizframework/utils/chain/AsyncCommandChainStep.as] instances (they extend CommandChainStep and implement IResponder) and implementations of IAutonomousChainStep.
[FunctionChainStep|http://github.com/swiz/swiz-framework/blob/master/src/org/swizframework/utils/chain/FunctionChainStep.as] is another useful class that implements IAutonomousChainStep and allows for deferred function invocation.
Finally, note that [BaseChainStep|http://github.com/swiz/swiz-framework/blob/master/src/org/swizframework/utils/chain/BaseChainStep.as] provides a base implementation of IChainStep, making your custom implementations that much easier to write.
//\\
h4. 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.
{html}<script src="http://gist.github.com/405843.js?file=CompositeChain.as"></script>{html}
\\
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. A couple of examples of custom chain steps can be seen below.
{html}<script src="http://gist.github.com/405843.js?file=PropertySetterStep.as"></script>{html}
{html}<script src="http://gist.github.com/405843.js?file=DispatchEventStep.as"></script>{html}
//\\
h4. 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|http://groups.google.com/group/swiz-framework] and we'll be happy to help!
|