Repository configuration

The repository configuration file, typically called repository.xml, specifies global options like security, versioning and clustering settings. A default workspace configuration template is also included in the repository configuration file. The exact format of this XML configuration file is defined in the following document type definition (DTD) files published by the Apache Jackrabbit project.

• -//The Apache Software Foundation//DTD Jackrabbit 1.5//EN
• -//The Apache Software Foundation//DTD Jackrabbit 1.4//EN
• -//The Apache Software Foundation//DTD Jackrabbit 1.2//EN
• -//The Apache Software Foundation//DTD Jackrabbit 1.0//EN

All Jackrabbit 1.x versions are fully backwards compatible, so you can use a recent Jackrabbit version without having to modify your existing repository configuration. Of course you will need to make configuration changes if you want to enable new features like the data store introduced in Jackrabbit 1.4.

The top-level structure of the repository configuration file is shown below. The <!DOCTYPE> declaration is optional, but if you include it Jackrabbit 1.5 will use XML validation to make sure that the configuration file is correctly formatted.

<!DOCTYPE Repository
	  PUBLIC "-//The Apache Software Foundation//DTD Jackrabbit 1.5//EN"
	  "http://jackrabbit.apache.org/dtd/repository-1.5.dtd">
<Repository>
  <FileSystem .../>
  <Security .../>
  <Workspaces .../>
  <Workspace .../>
  <Versioning .../>
  <SearchIndex .../>  <!-- optional -->
  <Cluster .../>	  <!-- optional, available since 1.2 -->
  <DataStore .../>	  <!-- optional, available since 1.4 -->
</Repository>

Starting with Jackrabbit 1.5, the order of the configuration elements below <Repository/> is now fixed.

The repository configuration elements are:

• FileSystem: The virtual file system used by the repository to store things like registered namespaces and node types.
• Security: Authentication and authorization configuration.
• Workspaces: Configuration on where and how workspaces are managed.
• Workspace: Default workspace configuration template.
• Versioning: Configuration of the repository-wide version store.
• SearchIndex: Configuration of the search index that covers the repository-wide /jcr:system content tree.
• Cluster: Clustering configuration.
• DataStore: Data store configuration.

See the Jackrabbit 1.5 default configuration , for an example repository configuration file.

It is a good idea to place the repository.xml file inside the repository home directory. This keeps your repository and its configuration nicely contained within a single directory tree.

<ConfigurationElement class="fully.qualified.ClassName">
  <param name="property1" value="...">
  <param name="property2" value="...">
<ConfigurationElement>

Security configuration

The security configuration element is used to specify authentication and authorization settings for the repository. The structure of the security configuration element is:

<Security appName="Jackrabbit">
  <SecurityManager .../>     <!-- optional, available since 1.5 -->
  <AccessManager .../>	 <!-- mandatory until 1.4, optional since 1.5 -->
  <LoginModule .../>	 <!-- optional -->
</Security>

By default Jackrabbit uses the Java Authentication and Authorization Service (JAAS) to authenticate users who try to access the repository. The appName parameter in the <Security/> element is used as the JAAS application name of the repository.

If JAAS authentication is not available or (as is often the case) too complex to set up, Jackrabbit allows you to specify a repository-specific JAAS LoginModule that is then used for authenticating repository users. The default SimpleLoginModule class included in Jackrabbit implements a trivially simple authentication mechanism that accepts any username and any password as valid authentication credentials.

Once a user has been authenticated, Jackrabbit will use the configured AccessManager to control what parts of the repository content the user is allowed to access and modify. The default [SimpleAccessManager|http://jackrabbit.apache.org/api/1.5/org/apache/jackrabbit/core/security/SimpleAccessManager.html] class included in Jackrabbit implements a trivially simple authorization mechanism that grants full read access to all users and write access to everyone except anonymous users.

The slightly more advanced SimpleJBossAccessManager class was added in Jackrabbit 1.3 (see JCR-650). This class is designed for use with the JBoss Application Server, where it maps JBoss roles to Jackrabbit permissions.

Workspace configuration

A Jackrabbit repository contains one or more workspaces that are each configured in a separate workspace.xml configuration file. The Workspaces element of the repository configuration specifies where and how the workspaces are managed. The repository configuration also contains a default workspace configuration template that is used to create the workspace.xml file of a new workspace unless more specific configuration is given when the workspace is created. See the createWorkspace methods in the JackrabbitWorkspace interface for more details on workspace creating workspaces.

The workspace settings in the repository configuration file are:

<Workspaces rootPath="${rep.home}/workspaces"
    defaultWorkspace="default"
    configRootPath="..."  <!-- optional -->
    maxIdleTime="..."/>   <!-- optional -->
<Workspace .../>   <!-- default workspace configuration template -->

The following global workspace configuration options are specified in the Workspaces element:

• rootPath:
  The native file system directory for workspaces. A subdirectory is automatically created for each workspace, and the path of that subdirectory can be used in the workspace configuration as the ${wsp.path} variable.
• defaultWorkspace:
  Name of the default workspace. This workspace is automatically created when the repository is first started.
• configRootPath:
  By default the configuration of each workspace is stored in a workspace.xml file within the workspace directory within the rootPath directory. If this option is specified, then the workspace configuration files are stored within the specified path in the virtual file system (see above) configured for the repository.
• maxIdleTime:
  By default Jackrabbit only releases resources associated with an opened workspace when the entire repository is closed. This option, if specified, sets the maximum number of seconds that a workspace can remain unused before the workspace is automatically closed.

The workspace configuration template and all workspace.xml configuration files have the following structure:

<Workspace name="${wsp.name}">
    <FileSystem .../>
    <PersistenceManager .../>
    <SearchIndex .../>	      <!-- optional -->
    <ISMLocking .../>	      <!-- optional, available since 1.4 -->
</Workspace>

The workspace configuration elements are:

• FileSystem: The virtual file system passed to the persistence manager and search index.
• PersistenceManager: Persistence configuration for workspace content.
• SearchIndex: Configuration of the workspace search index.
• ISMLocking: Locking configuration for concurrent access to workspace content.

To modify the configuration of an existing workspace, you need to change the workspace.xml file of that workspace. Changing the <Workspace/> element in the repository configuration file will not affect existing workspaces.

Versioning configuration

The version histories of all versionable nodes are stored in a repository-wide version store configured in the Versioning element of the repository configuration. The versioning configuration is much like workspace configuration as they are both used by Jackrabbit for storing content. The main difference between versioning and workspace configuration is that no search index is specified for the version store as version histories are indexed and searched using the repository-wide search index. Another difference is that there are no ${wsp.name} or ${wsp.path} variables for the versioning configuration. Instead the native file system path of the version store is explicitly specified in the configuration.

The structure of the versioning configuration is:

<Versioning rootPath="${rep.home}/version">
  <FileSystem .../>
  <PersistenceManager .../>
  <ISMLocking .../>	      <!-- optional, available since 1.4 -->
</Versioning>

The versioning configuration elements are:

• FileSystem: The virtual file system passed to the persistence manager.
• PersistenceManager: Persistence configuration for the version store.
• ISMLocking: Locking configuration for concurrent access to workspace content.

Search configuration

See the Search page on the Jackrabbit wiki.

Persistence configuration

The Persistence Manager is one of the most important parts of the configuration, because it actually takes care of storing the nodes and properties. There are various very different implementations, but most of them are using databases to store the data. If you use a database PM and like to connect to an external database, you might also have to setup the database. This might include access rights for the Jackrabbit database user to allow creation of tables, because the name of the table typically depends on the workspace name (see the individual PM's javadoc for more information).

For large binary properties there is the option to use the DataStore instead of the Persistence Manager.

For more detailed information and an overview of available PMs, see the PersistenceManagerFAQ page on the Jackrabbit wiki.

If you use a database persistence manager, the configured database connection must not be under the control of an external transaction manager. Jackrabbit implements distributed XA transaction support on a higher level, and expects to be in full control of the underlying database connection.

File system configuration

Early versions on Jackrabbit were designed to abstract their persistence mechanism using a virtual file system layer defined in the FileSystem interface. This low-level approach didn't work that well in practice, and so most of the persistence abstraction is now handled in a higher level. However, certain parts of Jackrabbit still use this file system abstraction.

A virtual file system is configured in a <FileSystem/> bean configuration element. See the main file system implementations LocalFileSystem, DatabaseFileSystem (including subclasses), and MemoryFileSystem for the available options. The recommended alternative is to use the LocalFileSystem implementation that simply maps abstract file system accesses to the specified directory within the native file system.

Cluster configuration

See the Clustering page on the Jackrabbit wiki.

Data store configuration

See the DataStore page on the Jackrabbit wiki.

Item state locking configuration

TODO

Passwords in configuration (as of Jackrabbit 2.3)

When using a database-backed persistence manager or another component, you usually need to include the database password in Jackrabbit configuration. If you don't want to store such passwords in plain text inside the configuration file, you can encode the password in base64 and prefix it with {base64}. Jackrabbit will automatically decode such a password before passing it to the underlying database.

As an example, the following two password configuration parameters are equivalent (“dGVzdA==” is the base64 encoding of “test”):

<param name="password" value="test"/>
<param name="password" value="{base64}dGVzdA=="/>