jackrabbit-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ju...@apache.org
Subject svn commit: r354386 - in /incubator/jackrabbit/trunk/jackrabbit/src/site/xdoc: doc/config.xml navigation.xml
Date Tue, 06 Dec 2005 09:20:17 GMT
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"/>



Mime
View raw message