Ports

Ports provide the inputs and outputs of pipelines and their steps. There are input ports and output ports. Ports have to be named. There are some identifications being required by convention. The most frequent ones are “source“ and “result“. When using the so-called “Built-In“ steps, these identifications are often obligatory and in the event of non-compliance may lead to appropriate errors. The following graphic shall demonstrate the concept of ports:

XProc ports

Figure: XProc ports

There are primary ports in order to not to have to define a separate port for each step. This is a standard port on which each step automatically receives its input and produces its output.

p:input

<p:input
   port = NCName
   sequence? = boolean
   primary? = boolean
   kind? = "document"
   select? = XPathExpression>
  (p:empty |
     (p:document |
     p:inline |
     p:data)+)?
</p:input>

With <p:input> an input port is defined. The corresponding name of the port is assigned to the “port“ attribute. In general, the identifications required by convention, “source“ or “result“. The Boolean attribute “sequence“ is set to “false“ per default. If sequence is set to “true“, a sequence of documents is expected at the input port (from zero up to any number). If this attribute is “false“ and a sequence is loaded, this would inevitably lead to a dynamic error. Because exactly one document is expected here.

The “primary“ attribute is also of Boolean type. If it is set to “true“, the port is switched to the primary port. Similarly, it is switched to a “normal“ port, if the value is set to “false“. By default this value is set to “true“.

The “kind“ attribute indicates which kind of input is used. XProc differentiates between two indications. The standard value is “document“, which means that the port will receive and process regular documents. In the event that the user wants to enter certain parameter specifications, the value “parameter“ has to be indicated.

The “select“ attribute expects a XPath expression. Here, the user has the possibility to select parts of the document arriving at the input port (e.g. with the help of <p:document> or <p:data>) in order to pass it on to the following step. This does not work for explicit connection specifications (only when using direct connections within the document).

Inside the <p:input> step the document specifications have to be made. They define which documents are to be load. For this purpose, the user may use the elements <p:empty>, <p:document>, <p:inline> and <p:data>.

<p:input port="source">
   <p:document href="FilmCollection.xml"/>
</p:input>

The example shows a standard definition of a <p:input> port. The port has the name “source“ and loads the XML document “FilmCollection.xml“ which it passes on to the accordingly connected steps.

<p:output
  port = NCName
  sequence? = boolean
  primary? = boolean/>

With the help of <p:output>, an output port is generated. The port gets its identification through the “port“ attribute. A name which often appears by convention is “result“. Names must not be assigned more than once (this leads to a “static error“).

With the help of the Boolean value within the “sequence“ attribute, you can determine wheter the output of the port is a sequence of documents or not. If several documents are outputted and this value is not set to “true“, this results in a dynamic error.

In the “primary“ attribute which also expects a Boolean value, the port is switched to a primary output port (if "true") or to a normal port (if "false").

p:output

<p:output
  port = NCName
  sequence? = boolean
  primary? = boolean>
   (p:empty |
   (p:pipe |
   p:document |
   p:inline |
   p:data)+)?
</p:output>

The indication of a document by <p:document> would bring the output port to read and output the document. Similarly, the processor would also do this with <p:emtpy>, <p:inline> and <p:data>. However, when using an Atomic Step, this does not work (dynamic error). With <p:pipe> the port can be bound on a step.

<p:output port="result"/>

This short example shows a typical output port with the identification “result“.

<< back next >>