Comments? Feedback?

This wiki does not yet support public comments (a limitation of Google Sites), so we encourage you to post your comments either:

On Twitter by responding to @orbeon.

On our community mailing list: subscribe sending an email to ops-users-subscribe@ow2.org (content of subject/body doesn't matter), you'll get a response with the email to use to send your message to the community mailing list.

Recent site activity

Configuration Properties - Base

Default values

For the latest configuration, see properties-base.xml.

Global properties

oxf.cache.size

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

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.

oxf.cache.xpath.size

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

This property configures the maximum number of compiled XPath expressions to keep in the XPath cache. To tune the cache size, see the suggestions in the Performance and Tuning section.

[SINCE: 2010-06-30] The default value is changed to 2000 from 600 previously.

NOTE: A profiler run shows that 2000 cache entries takes, for fairly typical XPath expressions, about 5 MB of memory.

XSLT output location mode 

During development, the following XSLT transformer configuration helps with line number errors. The following values are allowed:
  • none: no XSLT output line number information provided. This is the default, and recommended for deployment.
  • dumb: minimal XSLT output line number information provided.
  • smart: maximal XSLT output line number information provided. This is recommended for development.

<property as="xs:string" processor-name="oxf:builtin-saxon" name="location-mode" value="none"/>
<property as="xs:string" processor-name="oxf:unsafe-builtin-saxon" name="location-mode" value="none"/>
<!-- This property was used prior to January 2010 builds -->
<property as="xs:string" processor-name="oxf:saxon8" name="location-mode" value="none"/>

HTTP Client

Proxy setup

To configure an HTTP proxy to be used for all the HTTP connections established by Orbeon Forms, add the following two properties:

<property as="xs:string"  name="oxf.http.proxy.host"    value="localhost"/>
<property as="xs:integer" name="oxf.http.proxy.port"    value="8090"/>
<property as="xs:boolean" name="oxf.http.proxy.use-ssl" value="false"/>

By default, the host and port properties are commented and Orbeon Forms doesn't use a proxy. Some of the use cases where you will want to define a proxy include:
  • Your network setup requires you to go through a proxy.
  • You would like see what goes through HTTP by using a tool that acts as an HTTP proxy, such as Apache TCPMon.
[SINCE 2011-05-22] To connect to the proxy over HTTPS, instead of HTTP which is the default, set the oxf.http.proxy.use-ssl property to true.

SSL hostname verifier

[SINCE 2011-05-25] When connecting to an HTTPS server, you can specify how the hostname of the server is checked against the hostname in its certificate. You do so with the following property:

<property as="xs:string"  name="oxf.http.ssl.hostname-verifier" value="strict"/>

The possible values are:
Typically, you'll leave this property to its default value (strict). However, you might need to set it to allow-all to be able to connect to a server with a self-signed certificate if the cn in the certificate doesn't match the hostname you're using to connect to that server.

State setup

When Orbeon Forms performs XForms submissions, or retrieves documents in XPL over HTTP, it has the ability to keep state across requests. State information includes:
  • Cookies, including session cookies
  • Credentials / authentication information, e.g. HTTP Basic authentication
By default, these settings are stored in the current user session:

<property as="xs:string"  name="oxf.http.state" value="session"/>

You can change the property to the following values:
  • none: state is not stored at all between HTTP requests
  • request: state is stored for the duration of an HTTP request from the user's browser
  • session: state is stored for the duration of the user's session
  • application: state is stored for the duration of the web application's life
NOTE: This behavior is new since July 2009 builds. Before such builds, the default was none as this feature was not implemented.

This setting impacts the following HTTP requests:
  • Loading of XForms instances with xforms:instance/@src
  • Requests issued by xforms:submission
  • Requests issued by HTTP URLs in XPL pipelines
  • Requests issued by oxf:url-generator in XPL pipelines
  • Requests issued by oxf:xhtml-to-pdf when requesting external resources such as CSS, JavaScript, and image files
In fact, any HTTP request from Orbeon Forms should be handled by the above mechanisms. If you find an exception, please let Orbeon know on ops-users!

NOTE: These settings only control how the HTTP client in Orbeon Forms handles cookies and credentials.

Headers forwarding

When Orbeon Forms performs XForms submissions, or retrieves documents in XPL over HTTP, it has the ability to forward incoming HTTP headers. For example, if you want to forward the "Authorization" header to your services:

<property as="xs:string" name="oxf.http.forward-headers" value="Authorization"/>

NOTE: For security reasons, you should be careful with header forwarding, as this might cause non trusted services to receive client headers.

Cookies forwarding

[SINCE: 2011-07-29]

Similar to general headers forwarding, cookies can be forwarded. By default, the property is as follows:

<property as="xs:string" name="oxf.http.forward-cookies" value="JSESSIONID JSESSIONIDSSO"/>

This is typically used to forward session cookies to the same application server.

Before this property was available, cookies JSESSIONID and JSESSIONIDSSO were automatically forwarded by default.

Be sure to place the main session cookie name first in the list, as special handling takes place with that cookie.

NOTE: When a username for HTTP Basic authentication is specified, cookies are not forwarded.

NOTE: For security reasons, you should be careful with cookies forwarding, as this might cause non trusted services to receive client cookies.

Stale checking

This property is tied to the HttpClient stale checking:

Defines whether stale connection check is to be used. Disabling stale connection check may result in slight performance improvement at the risk of getting an I/O error when executing a request over a connection that has been closed at the server side.

By default, Orbeon checks for stale HTTP connections. You can disabling stale connection checking by setting the following property to false (it is true by default):

<property as="xs:boolean" name="oxf.http.stale-checking-enabled" value="false"/>


Socket timeout

This property is tied to the HttpClient SO timeout:

Sets the default socket timeout (SO_TIMEOUT) in milliseconds which is the timeout for waiting for data. A timeout value of zero is interpreted as an infinite timeout.

By default, Orbeon doesn't set a timeout with HttpClient. Setting a timeout can be potentially dangerous as it can lead to service calls that take longer to run than the timeout you specified to fail in a way that can be unpredictable, as it is possible for your services to sometimes return before the timeout and sometimes after. If, nevertheless, you need to set a timeout, you can do so by adding the following property, e.g. here setting a timeout at 1 minute:

<property as="xs:integer" name="oxf.http.so-timeout" value="60000"/>


URL rewriting

See also: XForms - JavaScript and CSS Resources.

oxf.url-rewriting.service.base-uri

Name: oxf.url-rewriting.service.base-uri
Purpose: Specify the base URL for rewriting service URLs.
Type: xs:anyURI
Subtype: HTTP or HTTPS URL
Default: Empty. Rewriting is done against the incoming request.

If this property is set to a non-blank value, URLs are rewritten against it.

Example:

<property as="xs:anyURI" name="oxf.url-rewriting.service.base-uri" value="http://localhost:8080/orbeon"/>

Usually Orbeon Forms will use the host, port, and context name as seen by the browser, e.g. http://www.mycompany.com/orbeon, to infer how to reach itself when calling service URLs. In some cases, this needs to be changed e.g.:
  • You have a web server (e.g. Apache httpd) which forwards requests to the application server (e.g. Tomcat).
  • The application server cannot connect to the web server because of a specific network configuration.
In those cases, the application server will try to connect to http://www.mycompany.com/orbeon/... which isn't reachable. To solve those, you can use the oxf.url-rewriting.service.base-uri property to provide a URL for the application server which can be reached by the application server, for instance: http://localhost:8080/orbeon.

[TODO: Explain where this property is used.]

oxf.url-rewriting.platform-paths

Name: oxf.url-rewriting.platform-paths
Purpose: Set which incoming resource paths are to be considered platform paths (i.e. paths handled by Orbeon Forms as opposed to an application).
Type: xs:string
Subtype: Regular expression.
Default: See example below.
Note: You don't usually need to modify this property.

Example:

<property as="xs:string" name="oxf.url-rewriting.platform-paths"
          value="^/(ops/|config/|xbl/orbeon/|forms/orbeon/|apps/fr/|xforms-server).*$"/>

This property is used by URL rewriting when versioned resources are enabled.

oxf.url-rewriting.app-paths

Name: 
oxf.url-rewriting.app-paths
Purpose: 
S
et which incoming resource paths are to be considered application paths (if they are not platform paths).
Type: 
xs:string
Subtype: Regular expression.
Default: 
See example below.
Note: You don't usually need to modify this property.

Example:

<property as="xs:string" name="oxf.url-rewriting.app-paths"
          value="^/(apps|xbl|forms)/.*$"/>

This property is used by URL rewriting when versioned resources are enabled.

oxf.url-rewriting.app-prefix

Name: 
oxf.url-rewriting.app-prefix
Purpose: Prepend
a prefix to incoming resource paths which are neither platform paths nor application paths. This is particularly useful as you package your XForms code into apps that you put in the apps directory. Say you have an app books. Requests to /books/*, like /books/listing, are handled by your apps/books/page-flow.xml. Without an app-prefix configured, the URL to an image books/banner.png needs to be /apps/books/banner.png. It is inconvenient to have pages use URLs like /books/listings and resources use URLs like /apps/books/banner.png. Setting up an app-prefix, allows you to use /books/banner.png, as Orbeon Forms automatically adds the /apps to the beginning of the path when looking up the resource.
Type: 
xs:string
Subtype: Absolute path starting with "/" end not ending with "/".
Default: /apps [SINCE: 2011-03-11]
Note: You don't usually need to modify this property.

Example:

<property as="xs:string" name="oxf.url-rewriting.app-prefix" value="/apps"/>

oxf.url-rewriting.strategy.servlet

Name: 
oxf.url-rewriting.strategy.servlet
Purpose: Specify which client URL rewriting strategy the Orbeon servlet should use
Type: 
xs:string
Subtype: 
servlet
 or wsrp
Default: 
servlet
Note: You don't usually need to modify this property.

Changing the default value of servlet to wsrp is useful if you deploy Orbeon as a servlet and interact with it from a proxy portlet.

NOTE: As of 2011-10-18 builds, this is no longer need as the Orbeon-Container header is used instead.

Example:

<property as="xs:string" name="oxf.url-rewriting.strategy.servlet" value="wsrp"/>

oxf.url-rewriting. wsrp.context

Name: 
oxf.url-rewriting.wsrp.context
Purpose:
Specify an optional context path when the wsrp rewriting strategy is used.
Type:
xs:string
Subtype: Absolute path starting with "/" end not ending with "/".
Default: Empty.

Example:

<property as="xs:string" name="oxf.url-rewriting.wsrp.context" value=""/>

oxf.url-rewriting. wsrp.encode-resources

[SINCE: 2011-09-14]

Name: 
 
oxf.url-rewriting.wsrp.encode-resources
Purpose: 
Specify whether resource URLs must be encoded when the wsrp rewriting strategy is used.
Type: 
xs:boolean
Default: false.

Example:

<property as="xs:string" name="oxf.url-rewriting.wsrp.encode-resources" value="true"/>

Epilogue and theme properties

oxf.epilogue.theme

Name oxf.epilogue.theme
Purpose Specifies the theme stylesheet. This can be overwritten for a given app by placing a file theme.xsl inside the app directory.
Type xs:anyURI
Default Value oxf:/config/theme-examples.xsl

 oxf.epilogue.theme.embeddable

Name oxf.epilogue.theme.embeddable
Purpose Specifies the theme stylesheet to use when within a portlet or in embeddable mode. This can be overwritten for a given app by placing a file theme-embeddable.xsl inside the app directory.
Type xs:anyURI
Default Value oxf:/config/theme-portlet-examples.xsl

oxf.epilogue.theme.renderer

Name oxf.epilogue.theme.renderer
Purpose Specifies the theme stylesheet to use when using the XForms filter, whether in integrated or separate deployment mode. By default, this is a plain theme.
Type xs:anyURI
Default Value oxf:/config/theme-portlet-examples.xsl

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

oxf.epilogue.use-theme

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

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

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

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

oxf.epilogue.xforms.widgets

[SINCE: 2011-10-10] This property is no longer supported 

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

Rarely used properties

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 the default Orbeon Forms 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.

Note: You don't usually need to modify this property.


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.

NOTE: It is  strongly discouraged to disable validation, as validation can highly contribute to the robustness of the application.

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.

NOTE: It is  strongly discouraged to disable validation, as validation can highly contribute to the robustness of the application.

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>
Note: You don't usually need to modify this property.

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.

Note: You don't usually need to enable this property.

oxf.pipeline.trace.class

NOTE: The property name was renamed from pipeline.trace on 2010-07-06.

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 the following implementations of Trace:

  • org.orbeon.oxf.processor.trace.SystemOutTrace: send the information to the standard output
Note: You don't usually need to enable this property.

Sign in  |  Recent Site Activity  |  Revision History  |  Terms  |  Report Abuse  |  Print page  |  Powered by Google Sites