Defining a Content Pipeline
Filters and content pipelines are normally defined using XML files. In Arbortext software, the .ccf (publishing configuration file) XML document defines a content pipeline by listing a series of filters, starting with a generator and ending with a serializer. A filter may be defined in the .ccf file, but usually a filter is defined in an .ent (XML or SGML entity) file, so that its definition can be reused in several .ccf files without the need to repeat the definition in each .ccf file.
A filter definition consists of an XML FilterDef element which defines the Java classes that implement and invoke the filter. It also contains a series of Parameter elements which define the parameters that are passed to the filter to control its operation.
A pipeline definition consists an XML Interface element which contains Parameter elements that define pipeline parameters, a Resource element that contains filter definitions (usually entity references to the .ent files), and a Pipeline element that defines the initial filter of the pipeline, the order in which the filters are chained together, and the mapping of pipeline parameters to filter parameters.
The most complex part of a pipeline definition is mapping pipeline parameters to filter parameters. Essentially, the pipeline parameters are a series of string name and value pairs that are passed to the content pipeline at runtime to control its operation. To avoid namespace collisions among filter parameters, the content pipeline definition maps pipeline parameter names to filter parameter names. A single pipeline parameter might be used by two different filters, yet each filter might have its own name for the parameter.
As an example of a content pipeline definition, consider the files epicGenerator.ent and pdf.ccf, both distributed in the Arbortext-path\composer directory. The epicGenerator.ent entity contains a definition of the epicGenerator filter. The definition specifies the filter's ID, the filter's type, and the names of Java classes that implement the filter and provide an interface to it. In its parameters list, each parameter has an ID (so that the parameter definition can be referenced), a name (so that the parameter can be mapped to a pipeline parameter) and attributes like parameter type, whether the parameter is required, and a default value.
The file pdf.ccf defines a content pipeline that uses the epicGenerator filter. The pipeline definition first defines the pipeline parameters by:
• a name attribute, which is used to identify the parameter value in the global parameter array when the pipeline runs.
• an idref attribute that references the ID of the Parameter element that defines the parameter in the filter definition.
The first Parameter in the Interface section of pdf.ccf has a name of document and an idref of epicGenerator.docId. This means the Parameter element with the ID epicGenerator.docId provides the parameter definition (to obtain its type, default value, whether it's required or optional, and so on). At run time, when an Arbortext PE sub-process is given an associative array of parameters, the parameter with a name of document will have to match this parameter definition.
The pdf.ccf continues with a Resource section that defines the filters it needs. The filter definitions are entity references, to the entity file epicGenerator.ent as well as others. It ends with a Pipeline element that lists the filters that define the pipeline.
The first Filter has the id of epic_generator. But it is the value of the filterDefRef attribute, epicGenerator, which maps to the filter defined in epicGenerator.ent. epicGenerator matches the id attribute of the FilterDef element in epicGenerator.ent.
In pdf.ccf the epic_generator filter’s first FilterParameter configures the filter parameter named docId to be initialized from the pipeline parameter named document. There is a double reference in the file: the Parameter element in the epicGenerator filter named docId is referenced twice in pdf.ccf.
1. the first Parameter element’s idref attribute (in the Interface section)
This first reference retrieves the parameter definition. Several pipeline parameters could be defined with different names but all using the same idref value to reference the same definition. The pipeline would then have several parameters with different names, but with the same parameter type, default value, and so on.
2. the name of the first FilterParameter element in the epic_generator filter (in the Pipeline section).
The second reference assigns a pipeline parameter value to the filter parameter at run time. The pipeline could contain multiple occurrences of the same filter, each having the same filter parameter name but initialized by a different pipeline parameter. Conversely, the same pipeline parameter may be used to initialize the filter parameters of several unrelated filters.