Orbeon Forms User Guide

Configuration Properties

1. Overview

  • Rationale ??? The Orbeon Forms properties are used by some processors to configure or customize their behavior. This section describes how the system is configured, and lists all the customizable properties.

  • Properties File Location ??? The properties sub-system is initialized after the Resource Manager (the properties being read like any other Orbeon Forms resources). By default it tries to load a file from the URLoxf:/properties.xml. This value can be overridden in the Web application descriptor web.xml with the oxf.properties initialization parameter:

    <context-param><param-name>oxf.properties</param-name><param-value>oxf:/config/properties.xml</param-value></context-param>

  • Standard Property Files ??? Even though the location of the property file can be configured in web.xml, Orbeon Forms uses the following locations:

    • oxf:/config/properties.xml: the main property file. This file is stored within orbeon-resources-public.jar. In turn, it uses XInclude to include the following files:
    • oxf:/config/properties-base.xml: base Orbeon Forms properties. This file is under WEB-INF/resources/config/.
    • oxf:/config/properties-xforms.xml: XForms engine properties. This file is under WEB-INF/resources/config/.
    • oxf:/config/properties-form-runner.xml: Orbeon Form Runner properties. This file is under WEB-INF/resources/config/.
    • oxf:/config/properties-form-builder.xml: Orbeon Form Builder properties. This file is under WEB-INF/resources/config/.
    • oxf:/config/properties-local.xml: optional file with properties local to the deployment. This file can also contain properties that override properties in the above files. This file should be placed under WEB-INF/resources/config/.
  • Automatic Reloading ??? The property file is reloaded every time it is changed (after a short delay), however some properties are taken into account only when the server is first started.

  • Property types ??? Properties have a type, which must be one of the following XML Schema simple types:xs:anyURI, xs:integer, xs:boolean, xs:QName, xs:string, xs:date, xs:dateTime.

  • Global and Processor Properties ??? There are two types of properties: global properties that apply to the system as a whole, and processor-specific properties. For instance, you set the cache size with a global property:

    <property as="xs:integer" name="oxf.cache.size" value="200"/>
    On the other hand setting the maximum amount of bytes that can be uploaded to the server is set with a processor specific property. Note the additional processor-name attribute:
    <property as="xs:integer" processor-name="oxf:request" name="max-upload-size" value="100000000"/>

  • Wildcards ??? Property names may be defined using wildcards. A property name is assumed to be built as a series of path elements separated by . characters. A path element may contain a * character instead of an actual path element value.

    <property as="xs:anyURI" name="oxf.fr.persistence.app.uri.*.*.*" value="/fr/service/exist"/><property as="xs:anyURI" name="oxf.fr.persistence.app.uri.*.*.data" value="/fr/service/oracle"/><property as="xs:anyURI" name="oxf.fr.persistence.app.uri.orbeon.builder.form" value="/fr/service/resource"/>

    In this example:

    • If the property name oxf.fr.persistence.app.uri.orbeon.builder.form is requested, the value /fr/service/resource is returned (exact match).

    • If the property name oxf.fr.persistence.app.uri.orbeon.foobar.data is requested, the value /fr/service/oracle is returned, because the path elements orbeon, foobar match wildcards, and data matches the last path element.

    • If the property name oxf.fr.persistence.app.uri.orbeon.foobar.form is requested, the value /fr/service/exist is returned, because the path elements orbeon, foobar and form all match wildcards.

    This allows creating hierarchical properties with generic defaults and more specific values.

2. Global Properties

2.1. oxf.log4j-config

Purpose Configures the logging system
Type xs:anyURI
Default Value The logging system not initialized with a warning if this property is not present.

Orbeon Forms uses the log4j logging framework. In Orbeon Forms, log4j is configured with an XML file. Here is a sample log4j configuration:

<log4j:configuration xmlns:log4j="log4j"><appender name="ConsoleAppender" class="org.apache.log4j.ConsoleAppender"><param name="Target" value="System.out"/><layout class="org.apache.log4j.PatternLayout"><param name="ConversionPattern" value="%-4r [%t] %-5p %c %x - %m%n"/></layout></appender><catagory name="org.orbeon.oxf.processor.DebugProcessor"><priority value="info"/></catagory><root><priority value="error"/><appender-ref ref="ConsoleAppender"/></root></log4j:configuration>

If this property is not set, the log4j initialization is skipped. This is useful if another subsystem of your application has already initialized log4j prior to the loading of Orbeon Forms.

2.2. oxf.cache.size

Purpose Setup the size of the Orbeon Forms cache
Type xs:integer
Default Value 200

Orbeon Forms uses an efficient caching system. Orbeon Forms automatically determines what can be cached and when to expire objects. The cache has a default size of 200, meaning that it can hold 200 objects. This size is reasonable for most applications. A bigger cache tends to make the application faster, but it uses more memory. To tune the cache size, see the suggestions in the Performance and Tuning section.

2.3. oxf.validation.processor

Purpose Controls the automatic processor validation
Type xs:boolean
Default Value Enabled

Many processors validate their configuration input with a schema. This validation is automatic and allows meaningful error reporting. To potentially improve the performance of the application, validation can be disabled in production environments. It is however strongly discouraged to do so, as validation can highly contribute to the robustness of the application.

2.4. oxf.validation.user

Purpose Controls user-defined validation
Type boolean
Default Value Enabled

User-defined validation is activated in the XML Pipeline Definition Language with the attributes schema-href and schema-uri. To potentially improve the performance of the application, validation can be disabled in production environments. It is however strongly discouraged to do so, as validation can highly contribute to the robustness of the application.

2.5. oxf.prologue

Purpose Defines Orbeon Forms processors
Type xs:anyURI
Default Value A default prologue is loaded automatically

Loads a Orbeon Forms prologue file, where processors are declared. Orbeon Forms is bundled with a default prologue file containing all processors. You can create processors (see the processor API) and declare them in a custom prologue. The custom prologue doesn't replace, but completes the default prologue. It is possible to override a default processor with a custom implementation by binding it to the same URI as the default processor. The following example shows a simple custom prologue declaring an hypothetical processor:

<processors><processor name="oxf:myprocessor"><class name="com.company.oxf.MyProcessor"/></processor></processors>

2.6. sax.inspection

Purpose Enable inspection SAX events
Type xs:boolean
Default Value false

SAX is the underlying mechanism in Orbeon Forms by which processors receive and generate XML data. Given only the constraints of the SAX API, it is possible for a processor to generate an invalid sequence of SAX events. Another processor that receives that invalid sequence of events may or may not be able to deal with it without throwing an exception. Some processors try to process invalid SAX events, while others throw exceptions. This means that when a processor generating an invalid sequence of SAX events is used in a pipeline, the problem might go unnoticed, or it might cause some other processor downstream to throw an exception.

To deal more efficiently with those cases, the sax.inspection property can be set to true. When it is set to true, the pipeline engine checks the outputs of every processor at runtime and makes sure that valid SAX events are generated. When an error is detected, an exception is thrown right away, with information about the processor that generated the invalid SAX events.

There is a performance penalty for enabling SAX events inspection. So this property should not be enabled on a production system.

2.7. processor.trace

Purpose Specify the name of a class that implements the interface org.orbeon.oxf.pipeline.api.PipelineContext.Trace.
Type xs:NCName
Default Value None

Orbeon Forms ships with two implementations of Trace:

  • NetworkTrace sends profiling information to Studio. Studio then displays the data in the trace views. When using NetworkTrace, you also need to specify the host and port to which the information is sent to with the processor.trace.host and processor.trace.port properties.
  • StdOutTrace simply dumps profiling information to standard output.

2.8. processor.trace.host

Purpose Specify the host name that org.orbeon.oxf.processor.NetworkTrace will send data to.
Type xs:NMTOKEN
Default Value localhost

2.9. processor.trace.port

Purpose Specify the port that org.orbeon.oxf.processor.NetworkTrace will send data to.
Type xs:nonNegativeInteger
Default Value 9191

3. Epilogue Properties

3.1. oxf.epilogue.theme

Name oxf.epilogue.theme
Purpose Specifies the theme stylesheet
Type xs:anyURI
Default Value oxf:/config/theme-examples.xsl

3.2. oxf.epilogue.theme.portlet

Name oxf.epilogue.theme.portlet
Purpose Specifies the theme stylesheet to use when within a portlet
Type xs:anyURI
Default Value
  • For Form Runner pages: oxf:/config/theme-portlet-fr.xsl
  • For all other pages: oxf:/config/theme-portlet-examples.xsl

3.3. oxf.epilogue.theme.error

Name oxf.epilogue.theme.error
Purpose Specifies the theme stylesheet to use on the error page
Type xs:anyURI
Default Value oxf:/config/theme-error.xsl

3.4. oxf.epilogue.use-theme

Name oxf.epilogue.use-theme
Purpose Specifies whether a theme stylesheet must be applied
Type xs:boolean
Default Value true

3.5. oxf.epilogue.output-xhtml

Name oxf.epilogue.output-xhtml
Purpose Whether to output XHTML to the browser or not
Type xs:boolean
Default Value false

3.6. oxf.epilogue.renderer-rewrite

Name oxf.epilogue.renderer-rewrite
Purpose Whether the XForms renderer used in separate deployment must rewrite URLs
Type xs:boolean
Default Value false

3.7. oxf.epilogue.process-svg

Name oxf.epilogue.process-svg
Purpose Whether SVG content must be converted server-side to images
Type xs:boolean
Default Value true

3.8. oxf.epilogue.xforms.widgets

Name oxf.epilogue.xforms.widgets
Purpose Whether the XForms widgets XSLT stylesheet must be applied
Type xs:boolean
Default Value true

4. Java Processor Properties

4.1. Class Path

Name classpath
Purpose Defines a directory where Java class files are located. The Java processor dynamically compiles Java code, and may need some libraries. This property defines the classpath used by the compiler.
Processor name oxf:java
Type xs:string
Default Value None

4.2. JAR Path

Name jarpath
Purpose Defines a list of directories where JAR files are located. The Java processor dynamically compiles Java code, and may need some libraries. This property defines a "JAR path", a list of directories containing JAR files that will be added to the classpath when compiling and running the processor executed by the Java processor.
Processor name oxf:java
Type xs:string
Default Value None

4.3. Compiler JAR

Name compiler-jar
Purpose Define a URL pointing to a JAR file containing the Java compiler to use. If this property is set, the Java processor adds the specified JAR file to the class path used to search for the main compiler class.
Processor name oxf:java
Type xs:anyURI
Default Value If the property is not specified, the Java processor tries to load the main compiler class first using the current class loader. If this fails, it retrieves the java.home system property which specifies a directory on disk. If that directory is called jre, and there exists a JAR file relative to that directory under ../lib/tools.jar, that JAR file is added to the class path used to search for the main compiler class. This covers most cases where the standard Sun JDK is used, so that the compiler-jar property does not have to be specified.

4.4. Compiler Main Class

Name compiler-class
Purpose Define a class name containing the Java compiler to use. The Java processor loads the corresponding class and calls a static method on this class with the following signature: public static int compile(String[] commandLine, PrintWriter printWriter).
Processor name oxf:java
Type xs:string
Default Value com.sun.tools.javac.Main

5. Email Processor Properties

5.1. Global SMTP Host

The following property can be specified globally as a property instead of being part of the processor configuration:

Name smtp-host
Purpose Configure the SMTP host for all email processors. This global property can be overridden by local processor configurations.
Processor name oxf:email
Type xs:string
Default Value None

The following properties can be used for testing purposes:

5.2. Test SMTP host

Name test-smtp-host
Purpose Configure a test SMTP host for all email processors. This global property when specified overrides all the other SMTP host configurations for all Email processors, whether in the processor configuration or using the smtp-host property.
Processor name oxf:email
Type xs:string
Default Value None

Note

This property replaces the deprecated smtp property.

5.3. Test Recipient

Name test-to
Purpose Configure a test recipient email address for all email processors. This global property when specified overrides all the other SMTP recipient configurations for all Email processors.
Processor name oxf:email
Type xs:string
Default Value None

Note

This property replaces the deprecated forceto property.

For example, those properties can be used as follows:

<property as="xs:string" processor-name="oxf:email" name="smtp-host" value="mail.example.org"/><property as="xs:string" processor-name="oxf:email" name="test-smtp-host" value="test.example.org"/><property as="xs:string" processor-name="oxf:email" name="test-to" value="joe@example.org"/>

The test properties can easily be commented out for deployment.