jackrabbit-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Jackrabbit: Jackrabbit Configuration (page edited)
Date Tue, 14 Oct 2008 17:58:00 GMT
Jackrabbit Configuration (JCR) edited by Jukka Zitting
      Page: http://cwiki.apache.org/confluence/display/JCR/Jackrabbit+Configuration
   Changes: http://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=75311&originalVersion=8&revisedVersion=9


JCR-151: Installation guide (work in progress)

Change summary:

JCR-151: Installation guide (work in progress)

Change summary:

JCR-151: Installation guide (work in progress)

Change summary:

JCR-151: Installation guide (work in progress)

Change summary:

JCR-151: Installation guide (work in progress)



Apache 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

These two 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.

For each workspace that was created, there will also be a workspace.xml file created inside
the workspace home directory that will be used for the workspace - these files have to be
changed, too, because the workspace-specific configuration inside repository.xml is only used
as a template for new workspaces, ie. if you use the createWorkspace of the Jackrabbit API,
the workspace.xml is just a copy of the Workspace element inside repository.xml. You can also
manually create the workspace folder with a workspace.xml file to create a new workspace yourself
(Note that depending on the persistence manager you will also have to setup a database and
configure the access to it).

h2. {anchor:repository} 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.4//EN|http://jackrabbit.apache.org/dtd/repository-1.4.dtd]
   * [-//The Apache Software Foundation//DTD Jackrabbit 1.2//EN|http://jackrabbit.apache.org/dtd/repository-1.2.dtd]
   * [-//The Apache Software Foundation//DTD Jackrabbit 1.0//EN|http://jackrabbit.apache.org/dtd/repository-1.0.dtd]

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.

<!DOCTYPE Repository
          PUBLIC "-//The Apache Software Foundation//DTD Jackrabbit 1.4//EN"
  <SearchIndex/>    <!-- optional -->
  <Cluster/>        <!-- optional, available since 1.2 -->
  <DataStore/>      <!-- optional, available since 1.4 -->

The repository configuration elements are:

   * {{FileSystem}}:  The virtual file system used by the repository to store things like
registered namespaces and node types. See the [File system configuration|#filesystem] section.
   * {{Security}}:    Authentication and authorization configuration. See the [Security configuration|#security]
   * {{Workspaces}}:  Configuration on where and how workspaces are managed. See the [Workspace
configuration|#workspace] section.
   * {{Workspace}}:   Default workspace configuration template. See the [Workspace configuration|#workspace]
   * {{Versioning}}:  Configuration of the repository-wide version store. See the [Versioning
configuration|#version] section.
   * {{SearchIndex}}: Configuration of the search index that covers the repository-wide {{/jcr:system}}
content tree. See the [Search configuration|#search] section. 
   * {{Cluster}}:     Clustering configuration. See the [Cluster configuration|#cluster] section.
   * {{DataStore}}:   Data store configuration. See the [Data store configuration|#datastore]

See the Jackrabbit 1.4 [default configuration|^repository.xml], for an example repository
configuration file.

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

h3. Bean configuration

Most of the entries in the configuration file are based on the following generic JavaBean
configuration pattern. Such configuration specifies that the repository should use an instance
of the specified class with the specified properties for the named functionality.

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

h3. Configuration variables

Jackrabbit supports configuration variables of the form _$\{name\}_. These variables can be
used to avoid hardcoding specific options in the configuration files. The following variables
are available in all Jackrabbit versions:

* {{$\{rep.home\}}}: Repository home directory.
* {{$\{wsp.name\}}}: Workspace name. Only available in workspace configuration.
* {{$\{wsp.home\}}}: Workspace home directory. Only available in workspace configuration.

Since Jackrabbit 1.4 (see [JCR-1304|https://issues.apache.org/jira/browse/JCR-1304]) it has
been possible to use system properties or any application-specific settings as configuration

h2. {anchor:security} 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">
  <LoginModule/>    <!-- optional -->

By default Jackrabbit uses the [Java Authentication and Authorization Service|http://java.sun.com/j2se/1.4.2/docs/guide/security/jaas/JAASRefGuide.html]
(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|http://java.sun.com/j2se/1.4.2/docs/api/javax/security/auth/spi/LoginModule.html]
that is then used for authenticating repository users. The default [SimpleLoginModule|http://jackrabbit.apache.org/api/1.4/org/apache/jackrabbit/core/security/SimpleLoginModule.html]
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|http://jackrabbit.apache.org/api/1.4/org/apache/jackrabbit/core/security/AccessManager.html]
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.4/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|http://jackrabbit.apache.org/api/1.4/org/apache/jackrabbit/core/security/SimpleJBossAccessManager.html]
class was contributed (see [JCR-650|https://issues.apache.org/jira/browse/JCR-650]) to Jackrabbit
1.3. This class is designed for use with the [JBoss Application Server|http://www.jboss.org/jbossas/],
and it maps JBoss roles to Jackrabbit permissions.

h2. {anchor:workspace} 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 [JackrabbitWorkspace|http://jackrabbit.apache.org/api/1.4/org/apache/jackrabbit/api/JackrabbitWorkspace.html]
for more details on workspace creating workspaces.

The workspace settings in the repository configuration file are:

<Workspaces rootPath="${rep.home}/workspaces" defaultWorkspace="default"
            configRootPath="" maxIdleTime="0"/>  <!-- optional attributes -->

<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}}: (optional) 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}}: (optional) 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 as well as each {{workspace.xml}} configuration file
has the following structure:

  <SearchIndex/>          <!-- optional -->
  <ISMLocking/>           <!-- optional, available since 1.4 -->

The {{FileSystem}} element specifies the virtual file system that gets passed to the configured
persistence manager and search index. See the [File system configuration|#filesystem] section
for details.

The {{PersistenceManager}} element specifies how content in this workspace is persisted. See
the [Persistence configuration|#persistence] section for details.

The {{SearchIndex}} element specifies how workspace content is indexed and how search queries
are handled. See the [Search configuration|#search] section for details.

h2. {anchor:filesystem} File system configuration

Early versions on Jackrabbit were designed to abstract their persistence mechanism using a
virtual file system layer defined in the [FileSystem|http://jackrabbit.apache.org/api/1.4/org/apache/jackrabbit/core/fs/FileSystem.html]
interface. This low-level approach turned out to be insufficient, so nowadays most of the
persistence abstraction is handled on a higher level. However, certain parts of Jackrabbit
still use this file system abstraction to store information.

A virtual file system is configured in a {{<FileSystem/>}} bean configuration element.
See the main file system implementations [LocalFileSystem|http://jackrabbit.apache.org/api/1.4/org/apache/jackrabbit/core/fs/local/LocalFileSystem.html],
(including subclasses), and [MemoryFileSystem|http://jackrabbit.apache.org/api/1.4/org/apache/jackrabbit/core/fs/mem/MemoryFileSystem.html]
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.

The repository file system, configured inside the {{Repository}} element, is used to store
registered namespaces and node types. Optionally also workspace configuration files are stored
within this file system.

<FileSystem class="org.apache.jackrabbit.core.fs.local.LocalFileSystem">
  <param name="path" value="${rep.home}/repository"/>

The versioning file system, configured inside the {{Versioning}} element, is passed to the
configured versioning persistence manager. It is up to the persistence manager implementation
to decide whether and how it uses the file system abstraction.

<FileSystem class="org.apache.jackrabbit.core.fs.local.LocalFileSystem">
  <param name="path" value="${rep.home}/version"/>

The workspace file system, configured inside the {{Workspace}} element of the workspace configuration
file, is passed to the configured workspace persistence manager and search index. It is up
to those implementations to decide whether and how to use the file system abstraction.

<FileSystem class="org.apache.jackrabbit.core.fs.local.LocalFileSystem">
  <param name="path" value="${wsp.home}"/>

h2. {anchor:version} 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.
<Versioning rootPath="${rep.home}/version">
    <FileSystem class="org.apache.jackrabbit.core.fs.local.LocalFileSystem">
        <param name="path" value="${rep.home}/version"/>
    <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_"/>

h2. {anchor:search} Search configuration


This message is automatically generated by Confluence

Unsubscribe or edit your notifications preferences

If you think it was sent incorrectly contact one of the administrators

If you want more information on Confluence, or have a bug to report see

View raw message