The contents of the processor chains controlled by a Pipeline Manager can be determined programmatically, as described in the next section, Creating and Editing Processor Chains Programmatically, or can be configured by an XML definition file, as specified by the Pipeline Manager’s definitionFile property. This section describes how to create an XML definition file for a Pipeline Manager.
Configuring processor chains with a pipeline definition file is useful for creating chains that are not edited or creating generic chains that will later be edited dynamically using the API based on some other criteria. This configuration file must be written in XML.
A pipeline definition file can use the following tags:
Tag | Description | Attributes |
|---|---|---|
| The top level tag that encloses a definition of a Pipeline Manager. | none |
| Tag defining a given processor chain in the Pipeline Manager. A Pipeline Manager can include any number of processor chains, each defined by a | name - (required) The name of the processor chain (for example, headlink - (required) The first processor in the chain to be executed. transaction - The default transactional mode of all the processors in this chain. The valid modes are: TX_REQUIRED classname - The full name of a Java class which is to be instantiated and used as the resultclassname - The full name of a Java class which is to be instantiated and used as the |
| Defines a processor within the chain and names it. | name - (required) A name for this processor (for example, transaction - A transactional mode that overrides the default mode of the chain. The valid modes are: TX_REQUIRED |
| The name of the | class - The processor class to be instantiated or referenced to. If the attribute is of the form jndi - The processor class to be referenced to. The object is resolved through JNDI and its reference is used as the processor. |
| A reference to the next link to be executed mapped by a return value. | returnvalue - (required) An integer string that is used to define the next pipeline element. link - (required) The name of a |
Document Type Definition for Pipeline Definition Files
Pipeline definition files use the following XML document type definition:
<!ENTITY %transactionmodes "(TX_REQUIRED|TX_REQUIRES_NEW|TX_SUPPORTS|TX_NOT_SUPPORTED|TX_MANDATORY)"> <!ELEMENT PipelineManager (pipelinechain*)> <!ELEMENT pipelinechain (pipelinelink*)> <!ATTLIST pipelinechain name ID #REQUIRED headlink IDREF #REQUIRED transaction %transactionmodes; "TX_REQUIRED" classname CDATA "atg.service.pipeline.PipelineChain" resultclassname CDATA "atg.service.pipeline.PipelineResultImpl"> <!ELEMENT pipelinelink (processor,transition*)> <!ATTLIST pipelinelink name ID #REQUIRED transaction %transactionmodes; "TX_REQUIRED"> <!ELEMENT processor EMPTY> <!ATTLIST processor class CDATA #IMPLIED jndi CDATA #IMPLIED> <!ELEMENT transition EMPTY <!ATTLIST transition returnvalue CDATA #REQUIRED link IDREF #REQUIRED>
Pipeline Definition File Example
The following file, PipelineManager.xml, is an example of a pipeline definition file that might be used for initializing a pipeline.
<?xml version="1.0"?> <!DOCTYPE PipelineManager SYSTEM "PipelineManager.dtd"> <PipelineManager> <pipelinechain name="AddToCart" transaction="TX_REQUIRED" headlink="proc1"> <pipelinelink name="proc1"> <processor class="atg.commerce.addA"/> <transition returnvalue="1" link="proc2"/> <transition returnvalue="2" link="proc3"/> </pipelinelink> <pipelinelink name="proc2" transaction="TX_REQUIRES_NEW"> <processor class="atg.commerce.addB"/> <transition returnvalue="1" link="proc4"/> <transition returnvalue="2" link="proc5"/> </pipelinelink> <pipelinelink name="proc3"> <processor class="atg.commerce.addE"/> <transition returnvalue="1" link="proc6"/> <transition returnvalue="2" link="proc7"/> <transition returnvalue="3" link="proc2"/> </pipelinelink> <pipelinelink name="proc4"> <processor class="atg.commerce.addC"/> </pipelinelink> <pipelinelink name="proc5" transaction="TX_REQUIRES_NEW"> <processor class="atg.commerce.addD"/> </pipelinelink> <pipelinelink name="proc6" transaction="TX_NOT_SUPPORTED"> <processor class="atg.commerce.addF"/> </pipelinelink> <pipelinelink name="proc7" transaction="TX_SUPPORTS"> <processor jndi="/dynamo/atg/commerce/addG"/> </pipelinelink> </pipelinechain> <pipelinechain name="RemoveFromCart" transaction="TX_REQUIRED" headlink="proc99" classname="atg.service.pipeline.PipelineMonoChain"> <pipelinelink name="proc99"> <processor class="atg.commerce.removeA"/> </pipelinelink> </pipelinechain> </PipelineManager>
Each section of the PipelineManager.xml file is described below.
The first line says that this file compiles with the XML version 1.0 specification.
<?xml version="1.0"?>
The following line says that this is an XML file and that its DTD (document type definition) is in the file PipelineManager.dtd.
<!DOCTYPE PipelineManager SYSTEM "PipelineManager.dtd">
This following line is the start of the PipelineManager definition. A <PipelineManager> tag encloses all of the processor chain definitions.
<PipelineManager>
The following line begins the definition for a chain named AddToCart. The default transactional mode of the PipelineLinks is TX_REQUIRED. The head link is proc1, which specifies the name of a PipelineProcessor defined later in the file.
<pipelinechain name="AddToCart" transaction="TX_REQUIRED"
headlink="proc1">
The next section is the definition of a PipelineLink with name proc1 and PipelineProcessor class name atg.commerce.addA. The PipelineManager initialization routine will construct the object atg.commerce.addA and set the PipelineLink’s processor reference to this object. This PipelineLink has two transitions coming out of it, one with return value 1 which links to proc2 and one with return value 2 which links to proc3. Both proc2 and proc3 are defined later in the file.
<pipelinelink name="proc1"> <processor class="atg.commerce.addA"/> <transition returnvalue="1" link="proc2"/> <transition returnvalue="2" link="proc3"/> </pipelinelink>
The next section defines two additional PipelineLinks. It is like the previous section, except that proc2 has defined an overriding transactional mode, TX_REQUIRES_NEW.
<pipelinelink name="proc2" transaction="TX_REQUIRES_NEW"> <processor class="atg.commerce.addB"/> <transition returnvalue="1" link="proc4"/> <transition returnvalue="2" link="proc5"/> </pipelinelink> <pipelinelink name="proc3"> <processor class="atg.commerce.addE"/> <transition returnvalue="1" link="proc6"/> <transition returnvalue="2" link="proc7"/> <transition returnvalue="3" link="proc2"/> </pipelinelink>
This section defines four more PipelineLink objects, some with overriding transactional modes. The interesting part of this section is the processor definition for proc7. Instead of using a Java class name definition, this processor is defined with a JNDI reference as jndi="/dynamo/atg/commerce/addG". This JNDI reference will be resolved at initialization time and used as the processor for this link. The final line is the closing </pipelinechain> tag for the processor chain.
<pipelinelink name="proc4"> <processor class="atg.commerce.addC"/> </pipelinelink> <pipelinelink name="proc5" transaction="TX_REQUIRES_NEW"> <processor class="atg.commerce.addD"/> </pipelinelink> <pipelinelink name="proc6" transaction="TX_NOT_SUPPORTED"> <processor class="atg.commerce.addF"/> </pipelinelink> <pipelinelink name="proc7" transaction="TX_SUPPORTS"> <processor jndi="/dynamo/atg/commerce/addG"/> </pipelinelink> </pipelinechain>
The last section defines another PipelineChain called RemoveFromCart with default transaction mode TX_REQUIRED, headlink proc99. It specifies that the classname to be used for the construction of the PipelineChain is called PipelineMonoChain. The last line is the closing tag that closes off the PipelineManager definition.
<pipelinechain name="RemoveFromCart" transaction="TX_REQUIRED" headlink="proc99" classname="atg.service.pipeline.PipelineMonoChain"> <pipelinelink name="proc99"> <processor class="atg.commerce.removeA"/> </pipelinelink> </pipelinechain> </PipelineManager>
After the XML file is defined, start the Pipeline Manager component to construct the PipelineManager and its chains automatically.
