gnu.xml.pipeline
Class PipelineFactory
java.lang.Object
|
+--gnu.xml.pipeline.PipelineFactory
public class PipelineFactory
extends java.lang.Object
This provides static factory methods for creating simple event pipelines.
These pipelines are specified by strings, suitable for passing on
command lines or embedding in element attributes. For example, one way
to write a pipeline that restores namespace syntax, validates (stopping
the pipeline on validity errors) and then writes valid data to standard
output is this:
nsfix | validate | write ( stdout )
In this syntax, the tokens are always separated by whitespace, and each
stage of the pipeline may optionally have a parameter (which can be a
pipeline) in parentheses. Interior stages are called filters, and the
rightmost end of a pipeline is called a terminus.
Stages are usually implemented by a single class, which may not be
able to act as both a filter and a terminus; but any terminus can be
automatically turned into a filter, through use of a
TeeConsumer.
The stage identifiers are either class names, or are one of the following
short identifiers built into this class. (Most of these identifiers are
no more than aliases for classes.) The built-in identifiers include:
Stage | Parameter | Terminus | Description |
---|
dom | none | yes | Applications code can access a DOM Document built
from the input event stream. When used as a filter, this buffers
data up to an endDocument call, and then uses a DOM parser
to report everything that has been recorded (which can easily be
less than what was reported to it). |
nsfix | none | no | This stage ensures that the XML element and attribute
names in its output use namespace prefixes and declarations correctly.
That is, so that they match the "Namespace plus LocalName" naming data
with which each XML element and attribute is already associated. |
null | none | yes | This stage ignores all input event data. |
server | required server URL | no | Sends its input as XML request to a remote server,
normally a web application server using the HTTP or HTTPS protocols.
The output of this stage is the parsed response from that server. |
tee | required first pipeline | no | This sends its events down two paths; its parameter
is a pipeline descriptor for the first path, and the second path
is the output of this stage. |
validate | none | yes | This checks for validity errors, and reports them
through its error handler. The input must include declaration events
and some lexical events. |
wf | none | yes | This class provides some basic "well formedness"
tests on the input event stream, and reports a fatal error if any
of them fail. One example: start/end calls for elements must match.
No SAX parser is permitted to produce malformed output, but other
components can easily do so. |
write | required "stdout", "stderr", or filename | yes | Writes its input to the specified output, as pretty
printed XML text encoded using UTF-8. Input events must be well
formed and "namespace fixed", else the output won't be XML (or possibly
namespace) conformant. The symbolic names represent
System.out and System.err respectively; names must
correspond to files which don't yet exist. |
xhtml | required "stdout", "stderr", or filename | yes | Like write (above), except that XHTML rules
are followed. The XHTML 1.0 Transitional document type is declared,
and only ASCII characters are written (for interoperability). Other
characters are written as entity or character references; the text is
pretty printed. |
xinclude | none | no | This stage handles XInclude processing.
This is like entity inclusion, except that the included content
is declared in-line rather than in the DTD at the beginning of
a document.
|
xslt | required XSLT stylesheet URI | no | This stage handles XSLT transformation
according to a stylesheet.
The implementation of the transformation may not actually
stream data, although if such an XSLT engine is in use
then that can happen.
|
Note that
EventFilter.bind can automatically eliminate
some filters by setting SAX2 parser features appropriately. This means
that you can routinely put filters like "nsfix", "validate", or "wf" at the
front of a pipeline (for components that need inputs conditioned to match
that level of correctness), and know that it won't actually be used unless
it's absolutely necessary.
- David Brownell
createPipeline
public static EventConsumer createPipeline(java.lang.String description, EventConsumer next)
Extends an existing pipeline by prepending the filter pipeline to the
specified consumer. Some pipelines need more customization than can
be done through this simplified syntax. When they are set up with
direct API calls, use this method to merge more complex pipeline
segments with easily configured ones.
- description
- next
createPipeline
public static EventConsumer createPipeline(java.lang.String description)
Creates a simple pipeline according to the description string passed in.
- description
createPipeline
public static EventConsumer createPipeline(String tokens[] , EventConsumer next)
Extends an existing pipeline by prepending a pre-tokenized filter
pipeline to the specified consumer. Tokens are class names (or the
predefined aliases) left and right parenthesis, and the vertical bar.
- next
server URL
first pipeline
"stdout", "stderr", or filename
"stdout", "stderr", or filename
XSLT stylesheet URI