[CONF] Apache Jackrabbit: Jackrabbit Configuration (page edited)

[co...@apache.org]

Jackrabbit Configuration (JCR) edited by Thomas Mueller
      Page: http://cwiki.apache.org/confluence/display/JCR/Jackrabbit+Configuration
   Changes: http://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=75311&originalVersion=5&revisedVersion=6

Comment:
---------------------------------------------------------------------

bundle pm

Change summary:
---------------------------------------------------------------------

bundle pm

Change summary:
---------------------------------------------------------------------

bundle pm

Change summary:
---------------------------------------------------------------------

bundle pm

Change summary:
---------------------------------------------------------------------

bundle pm

Content:
---------------------------------------------------------------------

Jackrabbit needs two pieces of information to set up a runtime content repository instance:
* *Repository home directory* The filesystem path of the directory containing the content repository accessed by the runtime instance of Jackrabbit. This directory usually contains all the repository content, search indexes, internal configuration, and other persistent information managed within the content repository. Note that this is not absolutely required and some persistence managers and other Jackrabbit components may well be configured to access files and even other resources (like remote databases) outside the repository home directory. A designated repository home directory is however always needed even if some components choose to not use it. Jackrabbit will automatically fill in the repository home directory with all the required files and subdirectories when the repository is first instantiated.
* *Repository configuration file* The filesystem path of the repository configuration XML file. This file specifies the class names and properties of the various Jackrabbit components used to manage and access the content repository. Jackrabbit parses this configuration file and instantiates the specified components when the runtime content repository instance is created.

These to configuration parameters are passed either directly to Jackrabbit when creating a repository instance or indirectly through settings for a JNDI object factory or some other component management system.

h2. Repository configuration file

The repository configuration file is an XML file that specifies the components and configuration of a Jackrabbit content repository. The configuration file has the following overall outline:
{code}
<Repository>
    <FileSystem class="...">...</FileSystem>
    <Security>
        <AccessManager class="...">...</AccessManager>
        [ <LoginModule class="...">...</LoginModule> ]
    </Security>
    <Workspaces rootPath="..." defaultWorkspace="..."/>
    <Workspace name="...">
        <FileSystem class="...">...</FileSystem>
        <PersistenceManager class="...">...</PersistenceManager>
        [ <SearchIndex class="...">
            ...
            [ <FileSystem class="...">...</FileSystem> ]
          </SearchIndex> ]
    </Workspace>
    <Versioning rootPath="...">
        <FileSystem class="...">...</FileSystem>
        <PersistenceManager class="...">...</PersistenceManager>
    </Versioning>
</Repository>
{code}
See {{src/main/config/repository.xml}} for a working example configuration file. The file also contains a commented Document Type Definition (DTD) for the XML configuration file format.

h3. Configuration variables

The XML attribute values in the configuration file are interpreted as plain strings except for a few special variables. The following variables of the form $\{variable\} are replaced before the attribute string is interpreted.
* *$\{rep.home\}* Repository home directory. This variable is replaced by the repository home directory path given when the repository was instantiated. This variable makes it possible to use a single configuration file for multiple different repositories.
* *$\{wsp.name\}* Workspace name. This variable is only available within the Workspace template element and is replaced by the name of the workspace being configured.
* *$\{wsp.home\}* Workspace home directory. This variable is only available within the Workspace template element and is replaced by the directory path assigned to the workspace being configured.

h3. Security configuration

TODO

h3. Workspace configuration

The Workspace element is used as a template for separate workspace configuration files created for each new workspace. Because of this the Workspace element is not interpreted directly from the repository configuration file. Instead the workspace configuration template is first copied into the workspace configuration file which is then interpreted to set up the configured workspace components. Thus modifying the workspace configuration template in the repository configuration file will not affect existing workspace configurations.

The workspace configuration consists of a virtual file system, a persistence manager, and an optional search index component. The persistence manager component is used to store the content of the workspace. The virtual file system component is used as the base file system for the persistence manager in case file system access is needed. The optional search index component takes care of indexing and querying the content of the workspace. If a search index component is not specified, then the workspace will not be searchable. An optional virtual file system component can be specified for the search index as well.

A common workspace configuration example using the LocalFileSystem, DerbyPersistenceManager, and Lucene SearchIndex components is shown below.
{code}
<Workspace name="${wsp.name}">
    <FileSystem class="org.apache.jackrabbit.core.fs.local.LocalFileSystem">
        <param name="path" value="${wsp.home}"/>
    </FileSystem>
    <PersistenceManager class="org.apache.jackrabbit.core.persistence.bundle.DerbyPersistenceManager">
        <param name="url" value="jdbc:derby:${wsp.home}/db;create=true"/>
        <param name="schemaObjectPrefix" value="${wsp.name}_"/>
    </PersistenceManager>
    <SearchIndex class="org.apache.jackrabbit.core.query.lucene.SearchIndex">
        <param name="path" value="${wsp.home}/index"/>
        <param name="useCompoundFile" value="true"/>
        <param name="minMergeDocs" value="100"/>
        <param name="volatileIdleTime" value="3"/>
        <param name="maxMergeDocs" value="100000"/>
        <param name="mergeFactor" value="10"/>
        <param name="bufferSize" value="10"/>
        <param name="cacheSize" value="1000"/>
        <param name="forceConsistencyCheck" value="false"/>
        <param name="autoRepair" value="true"/>
        <param name="analyzer" value="org.apache.lucene.analysis.standard.StandardAnalyzer"/>
    </SearchIndex>
</Workspace>
{code}

h3. Versioning configuration

The Versioning configuration element specifies the virtual file system and the persistence manager used to manage the version histories of all the nodes within the content repository. The version storage is much like a normal workspace without a search index. Instead of a workspace name, the version storage is given a root directory path using the rootPath attribute.

An common versioning configuration example using the LocalFileSystem and bundle DerbyPersistenceManager components is shown below.
{code}
<Versioning rootPath="${rep.home}/version">
    <FileSystem class="org.apache.jackrabbit.core.fs.local.LocalFileSystem">
        <param name="path" value="${rep.home}/version"/>
    </FileSystem>
    <PersistenceManager class="org.apache.jackrabbit.core.persistence.bundle.DerbyPersistenceManager">
        <param name="url" value="jdbc:derby:${rep.home}/version/db;create=true"/>
        <param name="schemaObjectPrefix" value="version_"/>
    </PersistenceManager>
</Versioning>
{code}

h3. Modifying the repository configuration

In general you should be very careful when modifying a repository configuration file once the repository has been initialized. Usually (but not always\!) it is safe to change the authentication and access control settings within the Security element and some of the parameters of the other components. See the documentation of individual components for more information on the use of specific configuration parameters.

h3. Access managers

TODO

h3. Login modules

TODO

h3. Persistence managers

For more information about persistence managers, see the Persistence Manager FAQ in the Wiki section.

h3. Query handlers

TODO

h3. Virtual file systems

Jackrabbit uses the org.apache.jackrabbit.core.fs.FileSystem interface as a virtual file system abstraction. Although this interface does not cover all direct file system use of Jackrabbit, it still allows for flexibility in selecting where and how to store various parts of the persistent repository state. For example in some cases it might make sense to store the search indexes on a fast disk and the archived node versions on a slower but more reliable disk.

It is possible to configure separate virtual file systems for the global repository state, workspaces, search indexes, and versioning. A virtual file system is configured using the FileSystem configuration element:
{code}
<FileSystem class="...">
    <param name="...">...</param>
    ...
</FileSystem>
{code}
The class attribute of the FileSystem element contains the fully qualified class name of the file system implementation class. The class must implement the org.apache.jackrabbit.core.fs.FileSystem interface and have an empty default constructor. String properties can be assigned using the param elements according to the JavaBean conventions.

See the FileSystem javadocs for more details.

h4. LocalFileSystem

The org.apache.jackrabbit.core.fs.local.LocalFileSystem class implements a simple virtual file system based on a directory within the local file system. The configuration parameters for the LocalFileSystem class are:
* *path* The path of the local directory that is used to contain the virtual file system. Uses "/" as the path separator regardless of the underlying operating system.
* *enableHandleMonitor* Set to true to enable tracking of open file handles.

See the LocalFileSystem javadocs for more details.

---------------------------------------------------------------------
CONFLUENCE INFORMATION
This message is automatically generated by Confluence

Unsubscribe or edit your notifications preferences
   http://cwiki.apache.org/confluence/users/viewnotifications.action

If you think it was sent incorrectly contact one of the administrators
   http://cwiki.apache.org/confluence/administrators.action

If you want more information on Confluence, or have a bug to report see
   http://www.atlassian.com/software/confluence