Like other eXo services, eXo JCR can be configured and used in the 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 (see more in Container configuration):

JCR service configuration looks like:

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

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:

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.

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: The 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 session-max-age is not set up, idle session will never be removed.

lock-remover-max-threads: Number of threads that can serve LockRemover tasks. Default value is 1. Repository may have many workspaces, each workspace have own LockManager. JCR supports Locks with defined lifetime. Such a lock must be removed is it become expired. That is what LockRemovers does. But LockRemovers is not an independent timer-threads, its a task that executed each 30 seconds. Such a task is served by ThreadPoolExecutor which may use different number of threads.

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.

class: A workspace data container class name.

properties: The list of properties (name-value pairs) for the concrete Workspace 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.

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 Clustering). Also it replaces workspace element parameters auto-init-root-nodetype and auto-init-permissions with root-nodetype and root-permissions.

enabled: If workspace cache is enabled or not.

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:

properties: The list of properties (name-value pairs) for Workspace cache.

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 or not.

statistic-clean: If true cache statistic will be cleaned after was gathered, false by default or not.

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

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

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.

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 one.

<!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>

Products that use eXo JCR, sometimes missuse it since they continue to use a session that has been closed through a method call on a node, a property or even the session itself. To prevent bad practices we propose three modes which are the folllowing:

The effective configuration of all the repositories and their workspaces can be known thanks to the method getConfigurationXML() that is exposed through JMX at the RepositoryServiceConfiguration level in case of a PortalContainer the name of the related MBean will be of type exo:portal=${portal-container-name},service=RepositoryServiceConfiguration. This method will give you the effective configuration in XML format that has been really interpreted by the the JCR core. This could be helpful to understand how your repositories/workspaces are configured especially if you would like to overwrite the configuration for some reasons.