XPL - Command Line Applications

Introduction

You can use Orbeon Forms to build standalone command-line applications running pipelines. Use cases include: creating a hardcopy of a web site, importing or exporting XML data to and from a relational database, testing pipelines, automating repetitive operations on XML files (selection, transformation, aggregation, etc.). Orbeon Forms becomes your "XML toolbox".

Command line interface

Orbeon Forms ships with a command line interface (CLI). The easiest way to run it is to use the executable orbeon-cli.jar file and pass it a pipeline file:

java -jar orbeon-cli.jar pipeline.xpl

In this case, a pipeline can use relative URLs, or, if using absolute URLs, can use either the file: protocol to access files or, equivalently, the oxf: protocol.

Sometimes, it is better to group files under a resources sandbox addressed by the oxf: protocol. This is the standard way of accessing resources (files) within web applications, but it is also useful with command-line applications. In such cases, specify a resource manager root directory with the -r option, for example:

java -jar orbeon-cli.jar -r . oxf:/pipeline.xpl

or:

java -jar orbeon-cli.jar -r C:/my-example oxf:/pipeline.xpl

When specifying a resource manager root directory, it is mandatory to use a protocol and an absolute path within the sandbox, as shown above.

[Since 2012-05-30] Pipeline inputs and outputs can be specified as URLs using --input (aka -i) and --output (aka -o) options:

java -jar orbeon-cli.jar -i "data1=oxf:/data1.xml" -i "data2=oxf:/data2.xml" -o "data=oxf:/data.xml" -r C:/my-example oxf:/pipeline.xpl

The system: URL pseudo protocol can be used to designate:
  • The standard input: system:in
  • The standard output: system:out
  • The error output: system:err
Note: these URLs can be used in command line arguments but also in the pipeline itself.
 
To provide more flexibility, inputs can be specified not only by their URLs as shown above, but also as XML fragments (starting with a <):

java -jar orbeon-cli.jar -i "data=<foo>bar</foo>" -o "data=oxf:/data.xml" -r C:/my-example oxf:/pipeline.xpl


NOTE: Orbeon Forms's jar file (orbeon-cli.jar) is executable via the java -jar mechanism. However, it depends on a number of libraries that must be in the 'lib' directory beneath the directory containing orbeon-cli.jar. It is recommended to expand the WAR file, and refer to the orbeon-cli.jar file under the WAR file's WEB-INF directory.

Examples

Orbeon Forms comes with simple examples of command-line applications under the src/examples/cli directory. To run those examples, from a command prompt, enter either one of the subdirectories and run the java command following the explanations above, for example, from the simple directory:

java -jar /path/to/orbeon-war/WEB-INF/orbeon-cli.jar stdout.xpl

or, from the transform directory:

java -jar /path/to/orbeon-war/WEB-INF/orbeon-cli.jar transform.xpl

Notice that those two example pipelines use serializers, for example:

<p:config xmlns:p="http://www.orbeon.com/oxf/pipeline" xmlns:oxf="http://www.orbeon.com/oxf/processors">

<p:processor name="oxf:xslt">
<p:input name="data" href="foo.xml"/>
<p:input name="config" href="foo.xsl"/>
<p:output name="data" id="result"/>
</p:processor>

<p:processor name="oxf:xml-serializer">
<p:input name="config">
<config/>
</p:input>
<p:input name="data" href="#result"/>
</p:processor>

</p:config>

It is important to note that, when running from within a servlet or portlet environment, serializers send their data to the web client, such as a web browser. When running from a command-line environment, serializers output data to the standard output.

[Since 2012-05-30]

In the transform directory, generic-transform.xpl embeds a XSLT processor:

<p:config xmlns:p="http://www.orbeon.com/oxf/pipeline"
          xmlns:oxf="http://www.orbeon.com/oxf/processors">

    <!-- The inputs and output of this pipeline must be connected using -i and -o command line options -->

    <p:param name="transformation" type="input"/>
    <p:param name="data" type="input"/>
    <p:param name="data" type="output"/>

    <!-- Execute the XSLT transformation -->
    <p:processor name="oxf:xslt">
        <p:input name="data" href="#data"/>
        <p:input name="config" href="#transformation"/>
        <p:output name="data" ref="data"/>
    </p:processor>

</p:config>

This simple example gives us some opportunities to show how inputs and outputs can be connected.

To simulate transform.xpl and connect the transformation input to foo.xsl, the data input to foo.xml and the data output to the standard output, write:

/src/examples-cli/transform$ java -jar /path/to/orbeon-war/WEB-INF/orbeon-cli.jar -r . -i "data=oxf:/foo.xml" -i "transformation=oxf:/foo.xsl" -o "data=system:out" oxf:/generic-transform.xpl 2>/tmp/err
<?xml version="1.0" encoding="UTF-8"?><list><item>1</item><item>2</item><item>3</item><sum>6</sum></list>

To pass the data input in a command line parameter:

/src/examples-cli/transform$ java -jar ~/projects/orbeon-forms/build/orbeon-war/WEB-INF/orbeon-cli.jar -r . -i "data=<list><item>1</item><item>10</item></list>" -i "transformation=oxf:/foo.xsl" -o "data=system:out" oxf:/generic-transform.xpl 2>/tmp/err
<?xml version="1.0" encoding="UTF-8"?><list><item>1</item><item>10</item><sum>11</sum></list>


To get the data input from the standard input:

/src/examples-cli/transform$ java -jar ~/projects/orbeon-forms/build/orbeon-war/WEB-INF/orbeon-cli.jar -r . -i "data=system:in" -i "transformation=oxf:/foo.xsl" -o "data=system:out" oxf:/generic-transform.xpl 2>/tmp/err
<list>
<item>20</item>
<item>30</item>
</list>
^D
<?xml version="1.0" encoding="UTF-8"?><list><item>20</item><item>30</item><sum>50</sum></list>

And of course, working with the standard input and output, you can pipe or redirect them.

Advanced usage

When using orbeon-cli.jar, it is important to note that:

  • The classpath is defined in the orbeon-cli.jar manifest file and includes the jars from the Orbeon Forms lib subdirectory that are needed to run pipelines.
  • The resource manager is configured to use (in this order):
  1. the directory that has been defined as the root of the sandbox through the -r argument (or / if this argument has not been provided)
  2. the class loader resource manager that reads resources from jars and classes included in the classpath
Note: orbeon-cli.jar and the libraries referred in its manifest file are the only resources from the Orbeon Forms installation that are used in command line mode.

Adding external libraries

If your application requires additional libraries, you may want to include them is to add them to the manifest file. There are many ways to do so, among them, you can:

  1. Go to WEB-INF.
  2. Create a "lib-custom" directory and copy your external libraries in this directory
  3. Unzip orbeon-cli.jar
  4. Edit its META-INF/MANIFEST.MF file to add the paths to your jars at the bottom of the file (you need to use the same format, with 70 character lines and a space in the first column.
  5. Zip the resulting META-INF directory as custom-cli.jar and move this jar under WEB-INF
  6. You're done and can use custom-cli.jar instead of orbeon-cli.jar to run pipelines that use your external libraries.
Note: orbeon-cli.jar may differ from one version to the next one (and is different between Orbeon-CE and Orbeon-PE) and you may have to redo this operation when you upgrade Orbeon Forms.

Log4j customization

In command line mode, Orbeon Forms reads its log4j configuration under the root directory. This default configuration directs the log to the error output.

To override the default one that is provided by the class loader resource manager, use the -r option to set a sandbox root and add a log4j.xml configuration file under this root.

Other properties and configuration (including the Orbeon PE license file)

Other configuration files (such as properties, local processors and license files) are located under the config directory.

As mentioned before, the libraries are the only resources from the Orbeon Forms installation that are used in command line and orbeon-cli will not search them under WEB-INF/resources/config like this is the case in web application mode.

To provide or override these file, you need to use the -r option (unless you want to create a /config directory on your file system which wouldn't be such a nice idea), create a config directory under your sandbox root and move your configuration files there.

Comments