A simple and straightforward way of creating a pipeline is to use an XML configuration file. Commons Pipeline provides a set of Digester rules that can be used to set up a pipeline based upon such a file.
One important thing to note is that, due to the way that Digester handles the mapping of XML attributes to object properties, it is not possible to define a comprehensive DTD that fully describes the XML syntax for all possible legal configuration files; however, this does not prove to be a significant limitation and the flexibility that it provides outweighs the disadvantages of the limited possibility for validation.
<pipeline>
<branch>
<pipeline>...</pipeline>
</branch>
<listener/>
<driverFactory/>
<env>
<value/>
<object/>
</env>
<stage></stage>
<feed>
<value/>
<object/>
</feed>
</pipeline>
Attributes for each element are discussed in their respective subsections.
The <pipeline> element is the root element of the document. It is used to define primary pipeline that will be created. The root <pipeline> tag does not support any attributes by default; instances of the tag nested within <branch> tags support the following attributes:
This tag is used to add a branch to a pipeline. The contents of this tag should be one or more <pipeline> declarations. Branch pipelines added in this fashion must be configured with an attribute named key that specifies the name used to refer to the branch.
Branch pipelines may be configured either inline in the main configuration file or in a separate file referred to by the configURI pipeline attribute.
The <listener> element is used to register a StageEventListener with the pipeline. This element supports any number of attributes, with the className attribute being reserved to define the class of the registered listener. All other attributes are mapped to properties that are set on the created listener object, using standard Java bean naming conventions.
The <driverFactory> element is used to create and configure a StageDriverFactory that will be used to create StageDriver instances for stages in the parent pipeline. Each StageDriverFactory is identified by a unique string identifier that is used by the <stage> tag to identify the factory used to create the driver for the stage. This tag supports two attributes, id and className . All other attributes are mapped to properties that are set on the created factory, using standard Java bean naming conventions.
The <env> element can be used to add global environment variable values to the pipeline by means of the <value> and <object> child tags. Variables assigned in this fashion will be accessible to any stage in the pipeline via the getEnv() method of the StageContext provided to the stage during initialization. Use the <value> tag to add string-valued environment variables; use the <object> tag to create more complex objects. All environment variables are referred to by a string key.
A java.lang.String value containing to the body content of the tag will be set as the value corresponding to the specified key.
This tag is used to add arbitrary objects to the environment. It supports two attributes, key and className . All other attributes are mapped to properties that are set on the created object, using standard Java bean naming conventions.
A single stage is created, configured, and added to the parent pipeline using this tag. Stages created in this manner are added to the pipeline in the order that they occur in the configuration file. This tag supports two attributes, className and driverFactoryId . All other attributes are mapped to properties that are set on the created stage object using standard Java bean naming conventions.
This tag is used to specify a collection of objects that will be fed into the pipeline on startup. Two different modes of usage are supported: string mode and object mode. Use the <value> tag to feed string values into the pipeline; use the <object> tag to feed more complex objects.
This tag supports no attributes. A java.lang.String object representing the body content of the tag will be fed to the first stage in the pipeline.
This tag is used to feed arbitrary objects into the pipeline. It supports a single attribute, className . All other attributes are mapped to properties that are set on the created object, using standard Java bean naming conventions.
This tag is used to set a non-primitive bean property on the object created by the enclosing tag, in a similar fashion to how primitive-valued properties may be set in Digester using XML attributes. This tag constructs an object of the specified class, configures its properties based upon the other XML attributes and any nested <property> tags, then passes the generated object to the appropriate setter method of the object created by the enclosing tag.