You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jackrabbit.apache.org by ju...@apache.org on 2005/12/06 10:20:17 UTC
svn commit: r354386 - in
/incubator/jackrabbit/trunk/jackrabbit/src/site/xdoc: doc/config.xml
navigation.xml
Author: jukka
Date: Tue Dec 6 01:20:12 2005
New Revision: 354386
URL: http://svn.apache.org/viewcvs?rev=354386&view=rev
Log:
JCR-151: Copied the "Configuring Jackrabbit" section from the draft installation manual.
Added:
incubator/jackrabbit/trunk/jackrabbit/src/site/xdoc/doc/config.xml (with props)
Modified:
incubator/jackrabbit/trunk/jackrabbit/src/site/xdoc/navigation.xml
Added: incubator/jackrabbit/trunk/jackrabbit/src/site/xdoc/doc/config.xml
URL: http://svn.apache.org/viewcvs/incubator/jackrabbit/trunk/jackrabbit/src/site/xdoc/doc/config.xml?rev=354386&view=auto
==============================================================================
--- incubator/jackrabbit/trunk/jackrabbit/src/site/xdoc/doc/config.xml (added)
+++ incubator/jackrabbit/trunk/jackrabbit/src/site/xdoc/doc/config.xml Tue Dec 6 01:20:12 2005
@@ -0,0 +1,473 @@
+<?xml version="1.0"?>
+<!--
+ Copyright 2004-2005 The Apache Software Foundation or its licensors,
+ as applicable.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+ -->
+<document>
+ <properties>
+ <title>Configuring Jackrabbit</title>
+ </properties>
+ <body>
+ <section name="Configuring Jakcrabbit">
+ <p>
+ Jackrabbit needs two pieces of information to set up a runtime
+ content repository instance:
+ </p>
+ <dl>
+ <dt>Repository home directory</dt>
+ <dd>
+ 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.
+ </dd>
+ <dt>Repository configuration file</dt>
+ <dd>
+ 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.
+ </dd>
+ </dl>
+ <p>
+ 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.
+ </p>
+ <subsection name="Repository configuration file">
+ <p>
+ 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:
+ </p>
+<source><![CDATA[<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> ]
+ </SearcIndex> ]
+ </Workspace>
+ <Versioning rootPath="...">
+ <FileSystem class="...">...</FileSystem>
+ <PersistenceManager class="...">...</PersistenceManager>
+ </Versioning>
+</Repository>
+]]></source>
+ <p>
+ See <a href="http://svn.apache.org/viewcvs.cgi/incubator/jackrabbit/trunk/jackrabbit/src/main/config/repository.xml?view=markup">src/main/config/repository.xml</a>
+ for a working example configuration file. The file also contains
+ a commented Document Type Definition (DTD) for the XML configuration
+ file format.
+ </p>
+ </subsection>
+ <subsection name="Configuration variables">
+ <p>
+ 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 <code>${variable}</code> are replaced
+ before the attribute string is interpreted.
+ </p>
+ <dl>
+ <dt><code>${rep.home}</code></dt>
+ <dd>
+ 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.
+ </dd>
+ <dt><code>${wsp.name}</code></dt>
+ <dd>
+ Workspace name. This variable is only available within the
+ <code>Workspace</code> template element and is replaced by
+ the name of the workspace being configured.
+ </dd>
+ <dt><code>${wsp.home}</code></dt>
+ <dd>
+ Workspace home directory. This variable is only available within
+ the <code>Workspace</code> template element and is replaced by the
+ directory path assigned to the workspace being configured.
+ </dd>
+ </dl>
+ </subsection>
+ <subsection name="Security configuration">
+ <p>TODO</p>
+ </subsection>
+ <subsection name="Workspace configuration">
+ <p>
+ The <code>Workspace</code> element is used as a template for
+ separate <em>workspace configuration files</em> created for each
+ new workspace. Because of this the <code>Workspace</code> 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.
+ </p>
+ <p>
+ The workspace configuration consists of a virtual file system,
+ a persistence manager, and an optional search index component.
+ The <a href="#PersistenceManager">persistence manager</a> component
+ is used to store the content of the workspace. The
+ <a href="#FileSystem">virtual file system</a> component is used
+ as the base file system for the persistence manager in case
+ file system access is needed. The optional
+ <a href="#QueryHandler">search index</a> 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.
+ </p>
+ <p>
+ A common workspace configuration example using the
+ <a href="#LocalFileSystem">LocalFileSystem</a>,
+ <a href="#DerbyPersistenceManager">DerbyPersistenceManager</a>, and
+ <a href="#SearchIndex">Lucene SearchIndex</a> components
+ is shown below.
+ </p>
+<source><![CDATA[<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.state.db.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>
+]]></source>
+ </subsection>
+ <subsection name="Versioning configuration">
+ <p>
+ The <code>Versioning</code> 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 <code>rootPath</code>
+ attribute.
+ </p>
+ <p>
+ An common versioning configuration example using the
+ <a href="#LocalFileSystem">LocalFileSystem</a> and
+ <a href="#DerbyPersistenceManager">DerbyPersistenceManager</a>
+ components is shown below.
+ </p>
+<source><![CDATA[<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.state.db.DerbyPersistenceManager">
+ <param name="url" value="jdbc:derby:${rep.home}/version/db;create=true"/>
+ <param name="schemaObjectPrefix" value="version_"/>
+ </PersistenceManager>
+</Versioning>
+]]></source>
+ </subsection>
+ <subsection name="Modifying the repository configuration">
+ <p>
+ 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 <code>Security</code> 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.
+ </p>
+ </subsection>
+ </section>
+ <section name="Access managers" id="AccessManager">
+ <p>TODO</p>
+ </section>
+ <section name="Login modules" id="LoginModule">
+ <p>TODO</p>
+ </section>
+ <section name="Persistence managers" id="PersistenceManager">
+ <p>
+ Persistence managers are Jackrabbit components that manage the
+ persistent storage of content nodes and properties.
+ The <code>org.apache.jackrabbit.core.state.PersistenceManger</code>
+ </p>
+ <p>
+ A separate persistence manager is assigned to each workspace and the
+ global versioning store. The persistence manager implementations to
+ use are configured using the <code>PersistenceManager</code>
+ configuration element within the <code>Workspace</code> configuration
+ template (and the instantiated workspace configuration files) and the
+ <code>Versioning</code> configuration element. The layout of a
+ <code>PersistenceManager</code> configuration element is shown below.
+ </p>
+<source><![CDATA[<PersistenceManager class="...">
+ <param name="...">...</param>
+ ...
+</PersistenceManager>
+]]></source>
+ <p>
+ The <code>class</code> attribute of the <code>PersistenceManager</code>
+ element contains the fully qualified class name of the persistence
+ manager implementation class. The class must implement the
+ <code>org.apache.jackrabbit.core.state.PersistenceManager</code>
+ interface and have an empty default constructor. String properties
+ can be assigned using the <code>param</code> elements according to
+ the JavaBean conventions.
+ </p>
+ <p>
+ See the <a href="apidocs/org/apache/jackrabbit/core/state/PersistenceManager.html">PersistenceManager javadocs</a>
+ for more details.
+ </p>
+ <subsection name="InMemPersistenceManager" id="InMemPersistenceManager">
+ <p>
+ The <code>org.apache.jackrabbit.core.state.mem.InMemPersistenceManager</code>
+ class implements a simple persistence manager that keeps all content
+ in memory. A custom binary serializer is optionally used to load
+ and store the persistent state during initialization and shutdown
+ of the persistence maanger.
+ </p>
+ <p>
+ This persistence manager is best suited for testing and for small
+ workspaces that need extra performance at the cost of reliable
+ persistence. The configuration parameters for the
+ <code>InMemPersistenceManager</code> class are:
+ </p>
+ <dl>
+ <dt><code>persistent</code></dt>
+ <dd>
+ Set to <code>true</code> to enable the use of the binary
+ serializer to persistently load and store the managed content
+ during startup and shutdown.
+ </dd>
+ <dt><code>initialCapacity</code></dt>
+ <dd>
+ The initial capacity of the hash maps used to store the
+ content items. The default value should be fine for almost
+ all uses of this persistence manager.
+ </dd>
+ <dt><code>loadFactory</code></dt>
+ <dd>
+ The load factor of the hash maps. The default value should be
+ fine for almost all uses fo this persistence manager.
+ </dd>
+ </dl>
+ <p>
+ See the <a href="apidocs/org/apache/jackrabbit/core/state/db/InMemPersistenceManager.html">InMemPersistenceManager javadocs</a>
+ for more details.
+ </p>
+ </subsection>
+ <subsection name="ObjectPersistenceManager" id="ObjectPersistenceManager">
+ <p>
+ The <code>org.apache.jackrabbit.core.state.obj.ObjectPersistenceManager</code>
+ class implements a persistence manager that uses a custom binary
+ serialization format to store the managed content directly in
+ the underlying virtual file system. The virtual file system is
+ expected to perform well with a large number of small files.
+ </p>
+ <p>
+ There are no configuration parameters for the
+ <code>ObjectPersistenceManager</code> class.
+ </p>
+ <p>
+ See the <a href="apidocs/org/apache/jackrabbit/core/state/obj/ObjectPersistenceManager.html">ObjectPersistenceManager javadocs</a>
+ for more details.
+ </p>
+ </subsection>
+ <subsection name="XMLPersistenceManager" id="XMLPersistenceManager">
+ <p>
+ The <code>org.apache.jackrabbit.core.state.xml.XMLPersistenceManager</code>
+ class implements a persistence manager that uses XML files stored
+ in the underlying virtual file system. The difference between this
+ persistence manager and the ObjectPersistenceManager is the storage
+ format used. The XMLPersistenceManager is best suited for testing
+ and debugging where readability of the content files is more
+ important than repository performance.
+ </p>
+ <p>
+ There are no configuration parameters for the
+ <code>XMLPersistenceManager</code> class.
+ </p>
+ <p>
+ See the <a href="apidocs/org/apache/jackrabbit/core/state/xml/XMLPersistenceManager.html">XMLPersistenceManager javadocs</a>
+ for more details.
+ </p>
+ </subsection>
+ <subsection name="SimpleDbPersistenceManager" id="SimpleDbPersistenceManager">
+ <p>
+ The <code>org.apache.jackrabbit.core.state.db.SimpleDbPersistenceManager</code>
+ class implements a generic Java Database Connectivity (JDBC) -based
+ persistence manager. Content is stored in a set of simple
+ non-normalized tables that are created automatically unless they
+ already exist. The configuration parameters for the
+ <code>SimpleDbPersistenceManager</code> class are:
+ </p>
+ <dl>
+ <dt><code>driver</code></dt>
+ <dd>
+ The fully qualified name of the JDBC driver class.
+ </dd>
+ <dt><code>url</code></dt>
+ <dd>
+ The JDBC database URL.
+ </dd>
+ <dt><code>user</code></dt>
+ <dd>
+ The database user. The user should have full access to the
+ content tables and administrative access to create the tables
+ if the tables have not already been created.
+ </dd>
+ <dt><code>password</code></dt>
+ <dd>
+ The password of the database user.
+ </dd>
+ <dt><code>schema</code></dt>
+ <dd>
+ The type of database schema to use for creating the content tables
+ if needed. (<code>mysql</code>, <code>mssql</code>, etc.)
+ </dd>
+ <dt><code>schemaObjectPrefix</code></dt>
+ <dd>
+ The prefix to use for the names of the content tables.
+ </dd>
+ <dt><code>externalBLOBs</code></dt>
+ <dd>
+ Set to <code>true</code> (the default) to store binary properties
+ in the underlying virtual file system. Set to <code>false</code>
+ to store binary properties in the database.
+ </dd>
+ </dl>
+ <p>
+ See the <a href="apidocs/org/apache/jackrabbit/core/state/db/SimpleDbPersistenceManager.html">SimpleDbPersistenceManager javadocs</a>
+ for more details.
+ </p>
+ </subsection>
+ <subsection name="DerbyPersistenceManager" id="DerbyPersistenceManager">
+ <p>
+ The <code>org.apache.jackrabbit.core.state.db.DerbyPersistenceManager</code>
+ is a subclass of the <code>SimpleDbPersistenceManager</code>. It
+ implements a persistence manager that uses an embedded
+ <a href="http://db.apache.org/derby/">Apache Derby</a> database
+ to manage content.
+ </p>
+ <p>
+ The <code>DerbyPersistenceManager</code> class has the same
+ configuration parameters as the
+ <code>SimpleDbPersistenceManager</code>, but provides Derby-specific
+ defaults for the <code>driver</code> and <code>schema</code>
+ parameters. The <code>url</code> parameter should normally be
+ something like <code>jdbc:derby:${wsp.home}/db;create=true</code>
+ and the <code>user</code> and <code>password</code> parameters can
+ be ignored. As Derby has reasonable support for binary content,
+ it often makes sense to set the <code>externalBLOBs</code> parameter
+ to <code>false</code>.
+ </p>
+ <p>
+ See the <a href="apidocs/org/apache/jackrabbit/core/state/db/DerbyPersistenceManager.html">DerbyPersistenceManager javadocs</a>
+ for more details.
+ </p>
+ </subsection>
+ </section>
+ <section name="Query handlers" id="QueryHandler">
+ <p>TODO</p>
+ </section>
+ <section name="Virtual file systems" id="FileSystem">
+ <p>
+ Jackrabbit uses the <code>org.apache.jackrabbit.core.fs.FileSystem</code>
+ 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.
+ </p>
+ <p>
+ 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 <code>FileSystem</code>
+ configuration element:
+ </p>
+<source><![CDATA[<FileSystem class="...">
+ <param name="...">...</param>
+ ...
+</FileSystem>
+]]></source>
+ <p>
+ The <code>class</code> attribute of the <code>FileSystem</code> element
+ contains the fully qualified class name of the file system
+ implementation class. The class must implement the
+ <code>org.apache.jackrabbit.core.fs.FileSystem</code> interface and
+ have an empty default constructor. String properties can be assigned
+ using the <code>param</code> elements according to the JavaBean
+ conventions.
+ </p>
+ <p>
+ See the <a href="apidocs/org/apache/jackrabbit/core/fs/FileSystem.html">FileSystem javadocs</a>
+ for more details.
+ </p>
+ <subsection name="LocalFileSystem" id="LocalFileSystem">
+ <p>
+ The <code>org.apache.jackrabbit.core.fs.local.LocalFileSystem</code>
+ class implements a simple virtual file system based on a directory
+ within the local file system. The configuration parameters for the
+ <code>LocalFileSystem</code> class are:
+ </p>
+ <dl>
+ <dt><code>path</code></dt>
+ <dd>
+ The path of the local directory that is used to contain the
+ virtual file system. Uses "<code>/</code>" as the path separator
+ regardless of the underlying operating system.
+ </dd>
+ <dt><code>enableHandleMonitor</code></dt>
+ <dd>
+ Set to <code>true</code> to enable tracking of open file handles.
+ </dd>
+ </dl>
+ <p>
+ See the <a href="apidocs/org/apache/jackrabbit/core/fs/local/LocalFileSystem.html">LocalFileSystem javadocs</a>
+ for more details.
+ </p>
+ </subsection>
+ </section>
+ </body>
+</document>
Propchange: incubator/jackrabbit/trunk/jackrabbit/src/site/xdoc/doc/config.xml
------------------------------------------------------------------------------
svn:eol-style = native
Modified: incubator/jackrabbit/trunk/jackrabbit/src/site/xdoc/navigation.xml
URL: http://svn.apache.org/viewcvs/incubator/jackrabbit/trunk/jackrabbit/src/site/xdoc/navigation.xml?rev=354386&r1=354385&r2=354386&view=diff
==============================================================================
--- incubator/jackrabbit/trunk/jackrabbit/src/site/xdoc/navigation.xml (original)
+++ incubator/jackrabbit/trunk/jackrabbit/src/site/xdoc/navigation.xml Tue Dec 6 01:20:12 2005
@@ -35,6 +35,7 @@
<item name="Model 2 (Shared)" href="/doc/deploy/howto-model2.html"/>
<item name="Model 3 (Server)" href="/doc/deploy/howto-model3.html"/>
</item>
+ <item name="Configuring Jackrabbit" href="/doc/config.html" />
<item name="Nodetype Modelling" href="/doc/nodetype.html" />
</item>
<item name="Layout" href="/layout.html"/>