eXo JCR configuration

1 Related documents

• Configuration persister
• Search Configuration
• JDBC Data Container config
• External Value Storages
• Workspace Simple DB storage
• Workspace Persistence Storage

2 Portal and Standalone configuration

Like other eXo services eXo JCR can be configured and used in portal or embedded mode (as a service embedded in eXo Portal) and in standalone mode.

In Embedded mode, JCR services are registered in the Portal container and the second option is to use a Standalone container. The main difference between these container types is that the first one is intended to be used in a Portal (Web) environment, while the second one can be used standalone (see the comprehensive page Service Configuration for Beginners for more details).

The following setup procedure is used to obtain a Standalone configuration (find more in Container configuration):

• Configuration that is set explicitly using StandaloneContainer.addConfigurationURL(String url) or StandaloneContainer.addConfigurationPath(String path) before getInstance()
• Configuration from $base:directory/exo-configuration.xml or $base:directory/conf/exo-configuration.xml file. Where $base:directory is either AS's home directory in case of J2EE AS environment or just the current directory in case of a standalone application.
• /conf/exo-configuration.xml in the current classloader (e.g. war, ear archive)
• Configuration from $service_jar_file/conf/portal/configuration.xml. WARNING: do not rely on some concrete jar's configuration if you have more than one jar containing conf/portal/configuration.xml file. In this case choosing a configuration is unpredictable.

<component>
    <key>org.exoplatform.services.jcr.RepositoryService</key>
    <type>org.exoplatform.services.jcr.impl.RepositoryServiceImpl</type>
  </component>
  <component>
    <key>org.exoplatform.services.jcr.config.RepositoryServiceConfiguration</key>
    <type>org.exoplatform.services.jcr.impl.config.RepositoryServiceConfigurationImpl</type>
    <init-params>
      <value-param>
        <name>conf-path</name>
        <description>JCR repositories configuration file</description>
        <value>jar:/conf/standalone/exo-jcr-config.xml</value>
      </value-param>
      <properties-param>
        <name>working-conf</name>
        <description>working-conf</description>
        <property name="source-name" value="jdbcjcr" />
        <property name="dialect" value="hsqldb" />
        <property name="persister-class-name" value="org.exoplatform.services.jcr.impl.config.JDBCConfigurationPersister" />
      </properties-param>
    </init-params>
  </component>

conf-path : a path to a RepositoryService JCR Configuration.

working-conf : optional; JCR configuration persister configuration. If there isn't a working-conf the persister will be disabled.

3 JCR Configuration

The Configuration is defined in an XML file (see DTD below)

JCR Service can use multiple Repositories and each repository can have multiple Workspaces.

From v.1.9 JCR repositories configuration parameters support human-readable formats of values. They are all case-insensitive:

• Numbers formats: K,KB - kilobytes, M,MB - megabytes, G,GB - gigabytes, T,TB - terabytes.
  Examples: 100.5 - digit 100.5, 200k - 200 Kbytes, 4m - 4 Mbytes, 1.4G - 1.4 Gbytes, 10T - 10 Tbytes
  
  
• Time format endings: ms - milliseconds, m - minutes, h - hours, d - days, w - weeks, if no ending - seconds.
  Examples: 500ms - 500 milliseconds, 20 - 20 seconds, 30m - 30 minutes, 12h - 12 hours, 5d - 5 days, 4w - 4 weeks.

4 Repository service configuration (JCR repositories configuration)

Service configuration may be placed in jar:/conf/standalone/exo-jcr-config.xml for standalone mode. For portal mode it is located in the portal web application portal/WEB-INF/conf/jcr/repository-configuration.xml

default-repository - the name of a default repository (one returned by RepositoryService.getRepository())

repositories - the list of repositories

5 Repository configuration:

name - the name of a repository

default-workspace - the name of a workspace obtained using Session's login() or login(Credentials) methods (ones without an explicit workspace name)

system-workspace - name of workspace where /jcr:system node is placed

security-domain - the name of a security domain for JAAS authentication

access-control - the name of an access control policy. There can be 3 types: optional - ACL is created on-demand(default), disable - no access control, mandatory - an ACL is created for each added node(not supported yet)

authentication-policy - the name of an authentication policy class

workspaces - the list of workspaces

session-max-age - the time after which an idle session will be removed (called logout). If not set, the idle session will never be removed.

6 Workspace configuration:

name - the name of a workspace

auto-init-root-nodetype - DEPRECATED in JCR 1.9 (use initializer). The node type for root node initialization

container - workspace data container (physical storage) configuration

initializer - workspace initializer configuration

cache - workspace storage cache configuration

query-handler - query handler configuration

auto-init-permissions - DEPRECATED in JCR 1.9 (use initializer). Default permissions of the root node. It is defined as a set of semicolon-delimited permissions containing a group of space-delimited identities (user, group etc, see Organization service documentation for details) and the type of permission. For example any read;:/admin read;:/admin add_node;:/admin set_property;:/admin remove means that users from group admin have all permissions and other users have only a 'read' permission.

7 Workspace data container configuration:

class - A workspace data container class name

properties - the list of properties (name-value pairs) for the concrete Workspace data container

value-storages - the list of value storage plugins

8 Value Storage plugin configuration (for data container):

value-storage - Optional value Storage plugin definition:

class- a value storage plugin class name (attribute)

properties - the list of properties (name-value pairs) for a concrete Value Storage plugin

filters - the list of filters defining conditions when this plugin is applicable

9 Initializer configuration (optional):

class - initializer implementation class.

properties - the list of properties (name-value pairs). Properties are supported:

    root-nodetype - The node type for root node initialization

    root-permissions - Default permissions of the root node. It is defined as a set of semicolon-delimited permissions containing a group of space-delimited identities (user, group etc, see Organization service documentation for details) and the type of permission. For example any read;:/admin read;:/admin add_node;:/admin set_property;:/admin remove means that users from group admin have all permissions and other users have only a 'read' permission.

Configurable initializer adds a capability to override workspace initial startup procedure (used for Cluster). Also it replaces workspace element parameters auto-init-root-nodetype and auto-init-permissions with root-nodetype and root-permissions.

10 Cache configuration:

enabled - if workspace cache is enabled

class - cache implementation class, optional from 1.9. Default value is org.exoplatform.services.jcr.impl.dataflow.persistent.LinkedWorkspaceStorageCacheImpl.

Cache can be configured to use concrete implementation of WorkspaceStorageCache interface. JCR core has two implementation to use:

• LinkedWorkspaceStorageCacheImpl - default, with configurable read behavior and statistic.
• WorkspaceStorageCacheImpl - pre 1.9, still can be used.

    max-size - cache maximum size (maxSize prior to v.1.9).

    live-time - cached item live time (liveTime prior to v.1.9).

From 1.9 LinkedWorkspaceStorageCacheImpl supports additional optional parameters.

    statistic-period - period (time format) of cache statistic thread execution, 5 minutes by default.

    statistic-log - if true cache statistic will be printed to default logger (log.info), false by default.

    statistic-clean - if true cache statistic will be cleaned after was gathered, false by default.

    cleaner-period - period of eldest items remover execution, 20 minutes by default.

    blocking-users-count - number of concurrent users allowed to read cache storage, 0 - unlimited by default.

11 Query Handler configuration:

class - A Query Handler class name

properties - the list of properties (name-value pairs) for a Query Handler (indexDir)

    properties and advanced features described in *Search Configuration*

12 Lock Manager configuration:

time-out - time after which the unused global lock will be removed.

persister - a class for storing lock information for future use. For example, remove lock after jcr restart.

path - a lock folder, each workspace has its own.

Additional information about the configuration of the lock you can see in *JCR LOCKS IMPLEMENTATION Specification*

<!ELEMENT repository-service (repositories)>
  <!ATTLIST repository-service default-repository NMTOKEN #REQUIRED>
  <!ELEMENT repositories (repository)>
  <!ELEMENT repository (security-domain,access-control,session-max-age,authentication-policy,workspaces)>
  <!ATTLIST repository
	default-workspace NMTOKEN #REQUIRED
	name NMTOKEN #REQUIRED
	system-workspace NMTOKEN #REQUIRED
  >
  <!ELEMENT security-domain (#PCDATA)>
  <!ELEMENT access-control (#PCDATA)>
  <!ELEMENT session-max-age (#PCDATA)>
  <!ELEMENT authentication-policy (#PCDATA)>
  <!ELEMENT workspaces (workspace+)>
  <!ELEMENT workspace (container,initializer,cache,query-handler)>
  <!ATTLIST workspace name NMTOKEN #REQUIRED>
  <!ELEMENT container (properties,value-storages)>
  <!ATTLIST container class NMTOKEN #REQUIRED>
  <!ELEMENT value-storages (value-storage+)>
  <!ELEMENT value-storage (properties,filters)>
  <!ATTLIST value-storage class NMTOKEN #REQUIRED>
  <!ELEMENT filters (filter+)>
  <!ELEMENT filter EMPTY>
  <!ATTLIST filter property-type NMTOKEN #REQUIRED>
  <!ELEMENT initializer (properties)>
  <!ATTLIST initializer class NMTOKEN #REQUIRED>
  <!ELEMENT cache (properties)>
  <!ATTLIST cache 
        enabled NMTOKEN #REQUIRED
        class NMTOKEN #REQUIRED
  >
  <!ELEMENT query-handler (properties)>
  <!ATTLIST query-handler class NMTOKEN #REQUIRED>
  <!ELEMENT access-manager (properties)>
  <!ATTLIST access-manager class NMTOKEN #REQUIRED>
  <!ELEMENT lock-manager (time-out,persister)>
  <!ELEMENT time-out (#PCDATA)>
  <!ELEMENT persister (properties)>
  <!ELEMENT properties (property+)>
  <!ELEMENT property EMPTY>