Orbeon Forms User Guide

Getting Started
- Welcome
- Changes
- Installing
- Orbeon Forms Tutorial
- Frequently Asked Questions
Core Technologies Reference
- XForms
- Page Flow
  - Page Flow Controller
  - Page Flow Epilogue
- XML Pipelines (XPL)
  - Introduction to XPL
  - XPL 1.0 W3C Submission
Other Technologies Reference
- Resource Managers
- Properties
- Non-XML Documents
- Error Page and Dialog
- Listeners
- URL Rewriting
- XML Namespaces
Processors Reference
- Producing XML
- Serializing XML
  - HTTP Serializer
  - Other Serializers
- Transforming XML
- Querying Data
- Interoperability
  - Delegation
  - Java
- Document Formats
- Messaging
  - Email
  - Instant Messaging
- XML Pipelines (XPL)
  - Pipeline
- Validation
- Scheduler
- Other Processors
API Reference
- Processor API
- Pipeline Engine API
Integration

Resource Managers

1. Introduction
2. General Configuration
3. Filesystem Resource Manager
- 3.1. Example
4. ClassLoader Resource Manager
- 4.1. Example
5. WebApp Resource Manager
- 5.1. Example
6. URL Resource Manager
- 6.1. Example
7. WebDAV Resource Manager
- 7.1. Example
8. Priority Resource Manager
- 8.1. Example
9. Caché Database Resource Manager
- 9.1. Importing XML Files into Caché
- 9.2. Example

1. Introduction

A resource manager is an Orbeon Forms component responsible for reading and writing XML and other resources like binary and text documents. A resource manager abstracts the actual mechanisms used to store resources. An important benefit of using such an abstraction is that it is possible to store all your application files in a sandbox which can be moved at will within a filesystem or between storage mechanisms. For instance, resources can be stored:

As files on disk (using your operating system's file system)
As resources within a WAR file
As resources within one or more JAR files
In a WebDAV server

A resource manager is both used:

Internally by Orbeon Forms
By your own Orbeon Forms applications through URLs with the oxf: protocol

This chapter describes the different types of resource managers and explains their configuration.

2. General Configuration

A single resource manager is initialized per Orbeon Forms web application. Configuration is handled in the web application descriptor (web.xml) by setting a number of context parameters. The first parameter indicates the resource manager factory:

<context-param><param-name>oxf.resources.factory</param-name><param-value>org.orbeon.oxf.resources.DefaultResourceManagerFactory</param-value></context-param>

Other properties depend on the resource manager defined by the factory. These properties are described in the following sections.

3. Filesystem Resource Manager

Purpose Loading resources from a filesystem

Factory org.orbeon.oxf.resources.FilesystemResourceManagerFactory

Properties oxf.resources.filesystem.sandbox-directory

The Filesystem resource manager loads resources from a filesystem. This is especially useful during development, since no packaging of resources is necessary. The oxf.resources.filesystem.sandbox-directory property can be used to define a sandbox, and if used must point to a valid directory on a filesystem. If not specified, no sandbox is defined, and it is possible to access all the files on the filesystem.

Using the Filesystem resource manager without a sandbox is particularly useful for command-line applications.

3.1. Example

<context-param><param-name>oxf.resources.factory</param-name><param-value>org.orbeon.oxf.resources.FilesystemResourceManagerFactory</param-value></context-param><context-param><param-name>oxf.resources.filesystem.sandbox-directory</param-name><param-value>/home/user/oxf/myapp/resources</param-value></context-param>

4. ClassLoader Resource Manager

Purpose Loading resources from a JAR file in the classpath

Factory org.orbeon.oxf.resources.ClassLoaderResourceManagerFactory

Properties None

The class loader resource manager can load resource from a JAR file or from a directory in the classpath. This resource manager is required to load internal resources for Orbeon Forms.

4.1. Example

<context-param><param-name>oxf.resources.factory</param-name><param-value>org.orbeon.oxf.resources.ClassLoaderResourceManagerFactory</param-value></context-param>

5. WebApp Resource Manager

Purpose Loading resources from a WAR file or deployed Web Application

Factory org.orbeon.oxf.resources.WebAppResourceManagerFactory

Properties oxf.resources.webapp.rootdir

This resource manager is useful when you want to package an application into a single WAR file for distribution and deployment. The configuration property indicates the path prefix of the resources directory inside a WAR file. It is recommended to store resources under the WEB-INF directory to make sure that the resources are not exposed to remote clients.

5.1. Example

<context-param><param-name>oxf.resources.factory</param-name><param-value>org.orbeon.oxf.resources.WebAppResourceManagerFactory</param-value></context-param><context-param><param-name>oxf.resources.webapp.rootdir</param-name><param-value>/WEB-INF/resources</param-value></context-param>

6. URL Resource Manager

Purpose Loading resources from a URL

Factory org.orbeon.oxf.resources.URLResourceManagerFactory

Properties oxf.resources.url.base

This resource manager is able to load resources form any URL (http or ftp). It can be used if your resources are located on a web server or a content management system with an HTTP interface.

6.1. Example

<context-param><param-name>oxf.resources.factory</param-name><param-value>org.orbeon.oxf.resources.URLResourceManagerFactory</param-value></context-param><context-param><param-name>oxf.resources.url.base</param-name><param-value>http://www.somwhere.com/base/</param-value></context-param>

7. WebDAV Resource Manager

Purpose Loading resources from a WebDAV repository

Factory org.orbeon.oxf.resources.WebDAVResourceManagerFactory

Properties oxf.resources.webdav.base
oxf.resources.webdav.username
oxf.resources.webdav.password

This resource manager is able to load resources form a WebDAV repository through HTTP. Examples of WebDAV repositories include:

For more information about WebDAV, please consult WebDAV Resources.

7.1. Example

<context-param><param-name>oxf.resources.factory</param-name><param-value>org.orbeon.oxf.resources.WebDAVResourceManagerFactory</param-value></context-param><context-param><param-name>oxf.resources.webdav.base</param-name><param-value>http://www.somwhere.com/base/</param-value></context-param><context-param><param-name>oxf.resources.webdav.username</param-name><param-value>joe</param-value></context-param><context-param><param-name>oxf.resources.webdav.password</param-name><param-value>password</param-value></context-param>

Warning

The WebDAV resource manager is considered experimental.

8. Priority Resource Manager

Purpose Chains several resource managers in order

Factory org.orbeon.oxf.resources.PriorityResourceManagerFactory

Properties oxf.resources.priority.1 oxf.resources.priority.2 oxf.resources.priority.n

With the priority resource manager you can chain several resource managers. It is crucial to be able to load resources from multiple sources since some resources are bundled in the Orbeon Forms JAR file. Thus, the class loader resource manager must always be in the priority chain. It usually has the lowest priority so the application developer can override system resources.

There can be any number of chained resource managers. They are configured by adding a oxf.resources.priority.n property, where n is an integer.

Warning

The priority resource manager is more efficient when most resources are found in the first resource manager specified.

8.1. Example

<context-param><param-name>oxf.resources.factory</param-name><param-value>org.orbeon.oxf.resources.PriorityResourceManagerFactory</param-value></context-param><context-param><param-name>oxf.resources.webapp.rootdir</param-name><param-value>/WEB-INF/resources</param-value></context-param><context-param><param-name>oxf.resources.priority.1</param-name><param-value>org.orbeon.oxf.resources.WebAppResourceManagerFactory</param-value></context-param><context-param><param-name>oxf.resources.priority.2</param-name><param-value>org.orbeon.oxf.resources.ClassLoaderResourceManagerFactory</param-value></context-param>

9. Caché Database Resource Manager

Purpose Loading resources from the Caché database

Factory org.orbeon.oxf.resources.CacheResourceManagerFactory

Properties oxf.resources.cache.url
oxf.resources.cache.username
oxf.resources.cache.password

This resource manager loads XML documents from InterSystems Caché Object Database. eXtc provides a W3C DOM interface to Caché and allows Orbeon Forms to store and retrieve XML documents. This section assumes Caché and eXtc are already installed on your system.

Note

To enable this Resource Manager, you must copy CacheDB.jar from Caché distribution into Orbeon Forms WEB-INF/lib directory.

Warning

The Caché Resource Manager only supports XML document. To serve other document types (like text, images), you must cascade a second resource manager with the help of the Priority Resource Manager.

9.1. Importing XML Files into Caché

Orbeon Forms ships with CacheImport to populate the database with resource from a directory. Set your CLASSPATH environment variable to include the following JAR files to run CacheImport:

orbeon.jar
CacheDB.jar
commons-cli.jar
xercesImpl-2_2_1_orbeon.jar
xml-apis-2_5_1.jar
dom4j-1_4.jar

The options below are available:

Option Meaning

-u,--url arg Caché URL

-l,--login arg Caché Login

-p,--password arg Caché Password

-r,--root arg Resource Root

You run CacheImport with the following command:

java org.orbeon.oxf.resources.CacheImport

9.2. Example

<context-param><param-name>oxf.resources.factory</param-name><param-value>org.orbeon.oxf.resources.CacheResourceManagerFactory</param-value></context-param><context-param><param-name>oxf.resources.cache.url</param-name><param-value>jdbc:Cache://localhost:1972/OXF</param-value></context-param><context-param><param-name>oxf.resources.cache.username</param-name><param-value>_SYSTEM</param-value></context-param><context-param><param-name>oxf.resources.cache.password</param-name><param-value>sys</param-value></context-param>