JBoss.orgCommunity Documentation

Reference Guide / eXo JCR

Java Content Repository and Extension services


1. eXoJCR
1.1. Introduction in eXoJCR
1.1.1. Data model
1.2. Why use JCR?
1.2.1. What is JCR?
1.2.2. Why use JCR?
1.2.3. What does eXo do?
1.2.4. Further Reading
1.3. eXo JCR Implementation
1.3.1. Related Documents
1.3.2. How it works
1.3.3. Workspace Data Model
1.4. Advantages of eXo JCR
1.4.1. Advantages for application developers
1.4.2. Advantages for managers
1.5. Compatibility Levels
1.5.1. Level 1
1.5.2. Level 2
1.5.3. Optional features
1.6. Using JCR
1.6.1. Obtaining a Repository object
1.6.2. JCR Session common considerations
1.6.3. JCR Application practices
1.7. JCR Service Extensions
1.7.1. Concept
1.7.2. Implementation
1.7.3. Configuration
1.7.4. Related Pages
1.8. eXo JCR Application Model
1.9. NodeType Registration
1.9.1. Interfaces and methods
1.9.2. Node type registration
1.9.3. Changing existing node type
1.9.4. Removing node type
1.9.5. Practical How to
1.10. Registry Service
1.10.1. Concept
1.10.2. The API
1.10.3. Configuration
1.11. Namespace altering
1.11.1. Adding new namespace
1.11.2. Changing existing namespace
1.11.3. Removing existing namespace
1.12. Node Types and Namespaces
1.12.1. Node Types definition
1.12.2. Namespaces definition
1.13. eXo JCR configuration
1.13.1. Related documents
1.13.2. Portal and Standalone configuration
1.13.3. JCR Configuration
1.13.4. Repository service configuration (JCR repositories configuration)
1.13.5. Repository configuration
1.13.6. Workspace configuration
1.13.7. Value Storage plugin configuration (for data container):
1.13.8. Initializer configuration (optional)
1.13.9. Cache configuration
1.13.10. Query Handler configuration
1.13.11. Lock Manager configuration
1.13.12. Help application to prohibit the use of closed sessions
1.13.13. Help application to allow the use of closed datasources
1.13.14. Getting the effective configuration at Runtime of all the repositories
1.13.15. Configuration of workspaces using system properties
1.14. Multi-language support in eXo JCR RDB backend
1.14.1. Oracle
1.14.2. DB2
1.14.3. MySQL
1.14.4. PostgreSQL/PostgrePlus
1.15. How to host several JCR instances on the same database instance?
1.15.1. LockManager configuration
1.15.2. HibernateService configuration
1.16. Search Configuration
1.16.1. XML Configuration
1.16.2. Configuration parameters
1.16.3. Global Search Index
1.16.4. Indexing Adjustments
1.17. JCR Configuration persister
1.17.1. Idea
1.17.2. Usage
1.18. JDBC Data Container Config
1.18.1. General recommendations for database configuration
1.18.2. Isolated-database Configuration
1.18.3. Multi-database Configuration
1.18.4. Single-database configuration
1.18.5. Simple and Complex queries
1.18.6. Forse Query Hints
1.18.7. Notes for Microsoft Windows users
1.19. External Value Storages
1.19.1. Tree File Value Storage
1.19.2. Simple File Value Storage
1.19.3. Content Addressable Value storage (CAS) support
1.19.4. Disabling value storage
1.20. Workspace Data Container
1.20.1. Database's dialects
1.21. REST Services on Groovy
1.21.1. Usage
1.22. Configuring JBoss AS with eXo JCR in cluster
1.22.1. Launching Cluster
1.22.2. Requirements
1.23. JBoss Cache configuration
1.23.1. JBoss cache configuration for indexer, lock manager and data container
1.23.2. JGroups configuration
1.23.3. Allow to share JBoss Cache instances
1.23.4. Shipped JBoss Cache configuration templates
1.24. LockManager configuration
1.24.1. CacheableLockManagerImpl
1.25. QueryHandler configuration
1.25.1. Indexing in clustered environment
1.25.2. Configuration
1.25.3. Asynchronous reindexing
1.25.4. Advanced tuning
1.26. JBossTransactionsService
1.26.1. Configuration
1.27. TransactionManagerLookup
1.28. Infinispan integration
1.28.1. Components configuration requirements
1.28.2. Workspaces configuration requirements
1.28.3. Shipped Infinispan Cache configuration templates
1.29. RepositoryCreationService
1.29.1. Dependencies
1.29.2. How it works
1.29.3. Configuration
1.29.4. RepositoryCreationService Interface
1.29.5. Conclusions and restrictions
1.30. JCR Query Usecases
1.30.1. Query Lifecycle
1.30.2. Query result settings
1.30.3. Type Constraints
1.30.4. Property Constraints
1.30.5. Path Constraint
1.30.6. Ordering specifying
1.30.7. Section 1.32, “Fulltext Search And Affecting Settings”
1.30.8. Indexing rules and additional features
1.30.9. Query Examples
1.30.10. Tips and tricks
1.31. Searching Repository Content
1.31.1. Bi-directional RangeIterator (since 1.9)
1.31.2. Fuzzy Searches (since 1.0)
1.31.3. SynonymSearch (since 1.9)
1.31.4. High-lighting (Since 1.9)
1.31.5. SpellChecker
1.31.6. Similarity (Since 1.12)
1.32. Fulltext Search And Affecting Settings
1.32.1. Property content indexing
1.32.2. Lucene Analyzers
1.32.3. How are different properties indexed?
1.32.4. Fulltext search query examples
1.32.5. Different analyzers in action
1.33. JCR API Extensions
1.33.1. API and usage
1.33.2. Configuration
1.33.3. Implementation notices
1.34. WebDAV
1.34.1. Configuration
1.34.2. Screenshots
1.34.3. Comparison table of WebDav and JCR commands
1.34.4. Restrictions
1.35. FTP
1.35.1. Configuration Parameters
1.36. eXo JCR Backup Service
1.36.1. Concept
1.36.2. How it works
1.36.3. Configuration
1.36.4. RDBMS backup
1.36.5. Usage
1.36.6. Restore existing workspace or repository
1.36.7. Restore a workspace or a repository using original configuration
1.36.8. Backup set portability
1.36.9. DB type migration
1.37. HTTPBackupAgent and backup client
1.37.1. HTTPBackupAgent
1.37.2. Backup Client
1.37.3. Backup Client Usage
1.37.4. Full example about creating backup and restoring it for workspace 'backup'
1.37.5. Full example about creating backup and restoring it for repository 'repository'
1.38. How to backup the data of your JCR using an external backup tool in 3 steps?
1.38.1. Step 1: Suspend the Repository
1.38.2. Step 2: Backup the data
1.38.3. Step 3: Resume the Repository
1.39. eXo JCR statistics
1.39.1. Statistics on the Database Access Layer
1.39.2. Statistics on the JCR API accesses
1.39.3. Statistics Manager
1.40. Checking and repairing repository integrity and consistency
1.40.1. Recommendations on how to fix corrupted JCR manually
1.41. JTA
1.42. The JCA Resource Adapter
1.42.1. The SessionFactory
1.42.2. Configuration
1.42.3. Deployment
1.43. Access Control
1.43.1. Standard Action Permissions
1.43.2. eXo Access Control
1.44. Access Control Extension
1.44.1. Prerequisites
1.44.2. Access Context Action
1.44.3. The Invocation Context
1.44.4. Custom Extended Access Manager
1.44.5. Example of a custom Access Manager
1.45. Link Producer Service
1.46. Binary Values Processing
1.46.1. Configuration
1.46.2. Usage
1.46.3. Value implementations
1.47. JCR Resources:
1.48. JCR Workspace Data Container (architecture contract)
1.48.1. Concepts
1.48.2. Requirements
1.48.3. Value storages API
1.49. How to implement Workspace Data Container
1.49.1. Notes on Value storage usage:
1.50. DBCleanService
1.50.1. Methods of DBCleanService
1.50.2. Need to clean only single workspace
1.50.3. Need to clean the whole repository
1.51. JCR Performance Tuning Guide
1.51.1. JCR Performance and Scalability
1.51.2. Performance Tuning Guide
2. eXoKernel
2.1. ExoContainer info
2.1.1. Container hierarchy
2.2. Service Configuration for Beginners
2.2.1. Requirements
2.2.2. Services
2.2.3. Configuration File
2.2.4. Execution Modes
2.2.5. Containers
2.2.6. Configuration Retrieval
2.2.7. Service instantiation
2.2.8. Miscellaneous
2.2.9. Further Reading
2.3. Service Configuration in Detail
2.3.1. Requirements
2.3.2. Sample Service
2.3.3. Parameters
2.3.4. External Plugin
2.3.5. Import
2.3.6. System properties
2.3.7. Understanding the prefixes supported by the configuration manager
2.4. Container Configuration
2.4.1. Kernel configuration namespace
2.4.2. Understanding how configuration files are loaded
2.4.3. eXo Container hot reloading
2.4.4. System property configuration
2.4.5. Variable Syntaxes
2.4.6. Runtime configuration profiles
2.4.7. Component request life cycle
2.4.8. Thread Context Holder
2.5. Inversion Of Control
2.5.1. How
2.5.2. Injection
2.5.3. Side effects
2.6. Services Wiring
2.6.1. Portal Instance
2.6.2. Introduction to the XML schema of the configuration.xml file
2.6.3. Configuration retrieval and log of this retrieval
2.7. Component Plugin Priority
2.8. Understanding the ListenerService
2.8.1. What is the ListenerService ?
2.8.2. How does it work?
2.8.3. How to configure a listener?
2.8.4. Concrete Example
2.9. Initial Context Binder
2.9.1. API
2.10. Job Scheduler Service
2.10.1. Where is Job Scheduler Service used in eXo Products?
2.10.2. How does Job Scheduler work?
2.10.3. Reference
2.11. eXo Cache
2.11.1. Basic concepts
2.11.2. Advanced concepts
2.11.3. eXo Cache extension
2.11.4. eXo Cache based on JBoss Cache
2.11.5. eXo Cache based on Infinispan
2.12. TransactionService
2.12.1. Existing TransactionService implementations
2.13. The data source provider
2.13.1. Configuration
2.14. JNDI naming
2.14.1. Prerequisites
2.14.2. How it works
2.14.3. Configuration examples
2.14.4. Recommendations for Application Developers
2.15. Logs configuration
2.15.1. Logs configuration initializer
2.15.2. Configuration examples
2.15.3. Tips and Troubleshooting
2.16. Manageability
2.16.1. Managed framework API
2.16.2. JMX Management View
2.16.3. Example
2.17. RPC Service
2.17.1. Configuration
2.17.2. The SingleMethodCallCommand
3. eXoCore
3.1. Database Creator
3.1.1. API
3.1.2. Configuration examples
3.1.3. Examples of DDL script
3.2. Security Service
3.2.1. Framework
3.2.2. Usage
3.3. Organization Service
3.3.1. Organizational Model
3.3.2. Custom Organization Service implementation instructions
3.4. Organization Service Initializer
3.5. Organization Listener
3.5.1. Writing your own listeners
3.5.2. Registering your listeners
3.6. Update ConversationState when user's Membership changed
3.7. DB Schema creator service (JDBC implementation)
3.8. Database Configuration for Hibernate
3.8.1. Generic configuration
3.8.2. Example DB configuration
3.8.3. Caching configuration
3.8.4. Registering custom annotated classes and Hibernate XML files into the service
3.9. LDAP Configuration
3.9.1. Quickstart
3.9.2. Configuration
3.9.3. Advanced topics
3.10. JCR organization service Configuration
3.10.1. Quickstart
3.10.2. Configuration
3.10.3. Migration
3.11. Organization Service TCK tests configuration
3.11.1. Maven pom.xml file configuration
3.11.2. Standalone container and Organization Service configuration
3.12. Tika Document Reader Service
3.12.1. Architecture
3.12.2. Configuration
3.12.3. Old-style DocumentReaders and Tika Parsers
3.12.4. TikaDocumentReader features and notes
3.13. Digest Authentication
3.13.1. Server configuration
3.13.2. OrganizationService implementation requirements
4. eXoWS
4.1. Introduction to the Representational State Transfer (REST)
4.2. Overwrite default providers
4.2.1. Motivation
4.2.2. Usage
4.2.3. Example
4.3. RestServicesList Service
4.3.1. Usage
4.4. Groovy Scripts as REST Services
4.4.1. Loading script and save it in JCR
4.4.2. Instantiation
4.4.3. Deploying newly created Class as RESTful service
4.4.4. Script Lifecycle Management
4.4.5. Getting node UUID example
4.4.6. Groovy script restrictions
4.5. Framework for cross-domain AJAX
4.5.1. Motivation
4.5.2. Scheme (how it works)
4.5.3. A Working Sequence:
4.5.4. How to use it
5. Frequently Asked Question
5.1. JCR FAQ
5.1.1. Kernel
5.1.2. JCR
6. eXo JCR with GateIn
6.1. How to extend my GateIn instance?
6.1.1. Motivations
6.1.2. Prerequisites
6.1.3. FAQ
6.1.4. Recommendations
6.2. How to use AS Managed DataSource under JBoss AS
6.2.1. Declaring the datasources in the AS
6.2.2. Do not let eXo bind datasources explicitly
1.1. Introduction in eXoJCR
1.1.1. Data model
1.2. Why use JCR?
1.2.1. What is JCR?
1.2.2. Why use JCR?
1.2.3. What does eXo do?
1.2.4. Further Reading
1.3. eXo JCR Implementation
1.3.1. Related Documents
1.3.2. How it works
1.3.3. Workspace Data Model
1.4. Advantages of eXo JCR
1.4.1. Advantages for application developers
1.4.2. Advantages for managers
1.5. Compatibility Levels
1.5.1. Level 1
1.5.2. Level 2
1.5.3. Optional features
1.6. Using JCR
1.6.1. Obtaining a Repository object
1.6.2. JCR Session common considerations
1.6.3. JCR Application practices
1.7. JCR Service Extensions
1.7.1. Concept
1.7.2. Implementation
1.7.3. Configuration
1.7.4. Related Pages
1.8. eXo JCR Application Model
1.9. NodeType Registration
1.9.1. Interfaces and methods
1.9.2. Node type registration
1.9.3. Changing existing node type
1.9.4. Removing node type
1.9.5. Practical How to
1.10. Registry Service
1.10.1. Concept
1.10.2. The API
1.10.3. Configuration
1.11. Namespace altering
1.11.1. Adding new namespace
1.11.2. Changing existing namespace
1.11.3. Removing existing namespace
1.12. Node Types and Namespaces
1.12.1. Node Types definition
1.12.2. Namespaces definition
1.13. eXo JCR configuration
1.13.1. Related documents
1.13.2. Portal and Standalone configuration
1.13.3. JCR Configuration
1.13.4. Repository service configuration (JCR repositories configuration)
1.13.5. Repository configuration
1.13.6. Workspace configuration
1.13.7. Value Storage plugin configuration (for data container):
1.13.8. Initializer configuration (optional)
1.13.9. Cache configuration
1.13.10. Query Handler configuration
1.13.11. Lock Manager configuration
1.13.12. Help application to prohibit the use of closed sessions
1.13.13. Help application to allow the use of closed datasources
1.13.14. Getting the effective configuration at Runtime of all the repositories
1.13.15. Configuration of workspaces using system properties
1.14. Multi-language support in eXo JCR RDB backend
1.14.1. Oracle
1.14.2. DB2
1.14.3. MySQL
1.14.4. PostgreSQL/PostgrePlus
1.15. How to host several JCR instances on the same database instance?
1.15.1. LockManager configuration
1.15.2. HibernateService configuration
1.16. Search Configuration
1.16.1. XML Configuration
1.16.2. Configuration parameters
1.16.3. Global Search Index
1.16.4. Indexing Adjustments
1.17. JCR Configuration persister
1.17.1. Idea
1.17.2. Usage
1.18. JDBC Data Container Config
1.18.1. General recommendations for database configuration
1.18.2. Isolated-database Configuration
1.18.3. Multi-database Configuration
1.18.4. Single-database configuration
1.18.5. Simple and Complex queries
1.18.6. Forse Query Hints
1.18.7. Notes for Microsoft Windows users
1.19. External Value Storages
1.19.1. Tree File Value Storage
1.19.2. Simple File Value Storage
1.19.3. Content Addressable Value storage (CAS) support
1.19.4. Disabling value storage
1.20. Workspace Data Container
1.20.1. Database's dialects
1.21. REST Services on Groovy
1.21.1. Usage
1.22. Configuring JBoss AS with eXo JCR in cluster
1.22.1. Launching Cluster
1.22.2. Requirements
1.23. JBoss Cache configuration
1.23.1. JBoss cache configuration for indexer, lock manager and data container
1.23.2. JGroups configuration
1.23.3. Allow to share JBoss Cache instances
1.23.4. Shipped JBoss Cache configuration templates
1.24. LockManager configuration
1.24.1. CacheableLockManagerImpl
1.25. QueryHandler configuration
1.25.1. Indexing in clustered environment
1.25.2. Configuration
1.25.3. Asynchronous reindexing
1.25.4. Advanced tuning
1.26. JBossTransactionsService
1.26.1. Configuration
1.27. TransactionManagerLookup
1.28. Infinispan integration
1.28.1. Components configuration requirements
1.28.2. Workspaces configuration requirements
1.28.3. Shipped Infinispan Cache configuration templates
1.29. RepositoryCreationService
1.29.1. Dependencies
1.29.2. How it works
1.29.3. Configuration
1.29.4. RepositoryCreationService Interface
1.29.5. Conclusions and restrictions
1.30. JCR Query Usecases
1.30.1. Query Lifecycle
1.30.2. Query result settings
1.30.3. Type Constraints
1.30.4. Property Constraints
1.30.5. Path Constraint
1.30.6. Ordering specifying
1.30.7. Section 1.32, “Fulltext Search And Affecting Settings”
1.30.8. Indexing rules and additional features
1.30.9. Query Examples
1.30.10. Tips and tricks
1.31. Searching Repository Content
1.31.1. Bi-directional RangeIterator (since 1.9)
1.31.2. Fuzzy Searches (since 1.0)
1.31.3. SynonymSearch (since 1.9)
1.31.4. High-lighting (Since 1.9)
1.31.5. SpellChecker
1.31.6. Similarity (Since 1.12)
1.32. Fulltext Search And Affecting Settings
1.32.1. Property content indexing
1.32.2. Lucene Analyzers
1.32.3. How are different properties indexed?
1.32.4. Fulltext search query examples
1.32.5. Different analyzers in action
1.33. JCR API Extensions
1.33.1. API and usage
1.33.2. Configuration
1.33.3. Implementation notices
1.34. WebDAV
1.34.1. Configuration
1.34.2. Screenshots
1.34.3. Comparison table of WebDav and JCR commands
1.34.4. Restrictions
1.35. FTP
1.35.1. Configuration Parameters
1.36. eXo JCR Backup Service
1.36.1. Concept
1.36.2. How it works
1.36.3. Configuration
1.36.4. RDBMS backup
1.36.5. Usage
1.36.6. Restore existing workspace or repository
1.36.7. Restore a workspace or a repository using original configuration
1.36.8. Backup set portability
1.36.9. DB type migration
1.37. HTTPBackupAgent and backup client
1.37.1. HTTPBackupAgent
1.37.2. Backup Client
1.37.3. Backup Client Usage
1.37.4. Full example about creating backup and restoring it for workspace 'backup'
1.37.5. Full example about creating backup and restoring it for repository 'repository'
1.38. How to backup the data of your JCR using an external backup tool in 3 steps?
1.38.1. Step 1: Suspend the Repository
1.38.2. Step 2: Backup the data
1.38.3. Step 3: Resume the Repository
1.39. eXo JCR statistics
1.39.1. Statistics on the Database Access Layer
1.39.2. Statistics on the JCR API accesses
1.39.3. Statistics Manager
1.40. Checking and repairing repository integrity and consistency
1.40.1. Recommendations on how to fix corrupted JCR manually
1.41. JTA
1.42. The JCA Resource Adapter
1.42.1. The SessionFactory
1.42.2. Configuration
1.42.3. Deployment
1.43. Access Control
1.43.1. Standard Action Permissions
1.43.2. eXo Access Control
1.44. Access Control Extension
1.44.1. Prerequisites
1.44.2. Access Context Action
1.44.3. The Invocation Context
1.44.4. Custom Extended Access Manager
1.44.5. Example of a custom Access Manager
1.45. Link Producer Service
1.46. Binary Values Processing
1.46.1. Configuration
1.46.2. Usage
1.46.3. Value implementations
1.47. JCR Resources:
1.48. JCR Workspace Data Container (architecture contract)
1.48.1. Concepts
1.48.2. Requirements
1.48.3. Value storages API
1.49. How to implement Workspace Data Container
1.49.1. Notes on Value storage usage:
1.50. DBCleanService
1.50.1. Methods of DBCleanService
1.50.2. Need to clean only single workspace
1.50.3. Need to clean the whole repository
1.51. JCR Performance Tuning Guide
1.51.1. JCR Performance and Scalability
1.51.2. Performance Tuning Guide

eXo provides JCR implementation called eXo JCR.

This part will show you how to configure and use eXo JCR in GateIn and standalone.

How do you know the data of your website are stored? The images are probably in a file system, the meta data are in some dedicated files - maybe in XML - the text documents and pdfs are stored in different folders with the meta data in an other place (a database?) and in a proprietary structure. How do you manage to update these data and how do you manage the access rights? If your boss asks you to manage different versions of each document or not? The larger your website is, the more you need a Content Management Systems (CMS) which tackles all these issues.

These CMS solutions are sold by different vendors and each vendor provides its own API for interfacing the proprietary content repository. The developers have to deal with this and need to learn the vendor-specific API. If in the future you wish to switch to a different vendor, everything will be different and you will have a new implementation, a new interface, etc.

JCR provides a unique java interface for interacting with both text and binary data, for dealing with any kind and amount of meta data your documents might have. JCR supplies methods for storing, updating, deleting and retrieving your data, independent of the fact if this data is stored in a RDBMS, in a file system or as an XML document - you just don't need to care about. The JCR interface is also defined as classes and methods for searching, versioning, access control, locking, and observation.

Furthermore, an export and import functionality is specified so that a switch to a different vendor is always possible.

eXo fully complies a JCR standard JSR 170; therefore with eXo JCR you can use a vendor-independent API. It means that you could switch any time to a different vendor. Using the standard lowers your lifecycle cost and reduces your long term risk.

Of course eXo does not only offer JCR, but also the complete solution for ECM (Enterprise Content Management) and for WCM (Web Content Management).

eXo Repository Service is a standard eXo service and is a registered IoC component, i.e. can be deployed in some eXo Containers (see Service configuration for details). The relationships between components are shown in the picture below:

eXo Container: some subclasses of org.exoplatform.container.ExoContainer (usually org.exoplatform.container.StandaloneContainer or org.exoplatform.container.PortalContainer) that holds a reference to Repository Service.

  • Repository Service: contains information about repositories. eXo JCR is able to manage many Repositories.

  • Repository: Implementation of javax.jcr.Repository. It holds references to one or more Workspace(s).

  • Workspace: Container of a single rooted tree of Items. (Note that here it is not exactly the same as javax.jcr.Workspace as it is not a per Session object).

Usual JCR application use case includes two initial steps:

  • Obtaining Repository object by getting Repository Service from the current eXo Container (eXo "native" way) or via JNDI lookup if eXo repository is bound to the naming context using (see Service configuration for details).

  • Creating javax.jcr.Session object that calls Repository.login(..).

The following diagram explains which components of eXo JCR implementation are used in a data flow to perform operations specified in JCR API

The Workspace Data Model can be split into 4 levels by data isolation and value from the JCR model point of view.

The Java Content Repository specification JSR-170 has been split into two compliance levels as well as a set of optional features.

Level 1 defines a read-only repository.

Level 2 defines methods for writing content and bidirectional interaction with the repository.

eXo JCR supports JSR-170 level 1 and level 2 and all optional features. The recent JSR-283 is not yet supported.

Level 1 includes read-only functionality for very simple repositories. It is useful to port an existing data repository and convert it to a more advanced form step by step. JCR uses a well-known Session abstraction to access the repository data (similar to the sessions we have in OS, web, etc).

The features of level 1:

(one-shot logout for all opened sessions)

Use org.exoplatform.services.jcr.ext.common.SessionProvider which is responsible for caching/obtaining your JCR Sessions and closing all opened sessions at once.

public class SessionProvider implements SessionLifecycleListener {

  /**
   * Creates a SessionProvider for a certain identity
   * @param cred
   */
  public SessionProvider(Credentials cred)
  
  /**
   * Gets the session from internal cache or creates and caches a new one 
   */
  public Session getSession(String workspaceName, ManageableRepository repository) 
    throws LoginException, NoSuchWorkspaceException, RepositoryException 

  /**
   * Calls a logout() method for all cached sessions
   */
  public void close() 

  /**
   * a Helper for creating a System session provider
   * @return System session
   */
  public static SessionProvider createSystemProvider() 

  /**
   * a Helper for creating an Anonimous session provider
   * @return System session
   */
  public static SessionProvider createAnonimProvider()

    /**
    * Helper for creating  session provider from AccessControlEntry.
    *
    * @return System session
    */
  SessionProvider createProvider(List<AccessControlEntry> accessList)

    /**
    * Remove the session from the cache
    */
  void onCloseSession(ExtendedSession session)

    /**
    * Gets the current repository used
    */
  ManageableRepository getCurrentRepository()

     /**
     * Gets the current workspace used
     */
  String getCurrentWorkspace()

     /**
     * Set the current repository to use
     */
  void setCurrentRepository(ManageableRepository currentRepository)

     /**
     * Set the current workspace to use
     */
  void setCurrentWorkspace(String currentWorkspace)

}

The SessionProvider is per-request or per-user object, depending on your policy. Create it with your application before performing JCR operations, use it to obtain the Sessions and close at the end of an application session(request). See the following example:

// (1) obtain current javax.jcr.Credentials, for example get it from AuthenticationService
Credentials cred = ....

// (2) create SessionProvider for current user
SessionProvider sessionProvider = new SessionProvider(ConversationState.getCurrent());

// NOTE: for creating an Anonymous or System Session use  the corresponding static SessionProvider.create...() method
// Get appropriate Repository as described in "Obtaining Repository object" section for example
ManageableRepository repository = (ManageableRepository) ctx.lookup("repositoryName");

// get an appropriate workspace's session 
Session session = sessionProvider.getSession("workspaceName", repository);

 .........
// your JCR code
 .........

 // Close the session provider
 sessionProvider.close(); 

As shown above, creating the SessionProvider involves multiple steps and you may not want to repeat them each time you need to get a JCR session. In order to avoid all this plumbing code, we provide the SessionProviderService whose goal is to help you to get a SessionProvider object.

The org.exoplatform.services.jcr.ext.app.SessionProviderService interface is defined as follows:

public interface SessionProviderService {
  void setSessionProvider(Object key, SessionProvider sessionProvider);
  SessionProvider getSessionProvider(Object key);
  void removeSessionProvider(Object key);
}

Using this service is pretty straightforward, the main contract of an implemented component is getting a SessionProvider by key. eXo provides two implementations :


For any implementation, your code should follow the following sequence :

  • Call SessionProviderService.setSessionProvider(Object key, SessionProvider sessionProvider) at the beginning of a business request for Stateless application or application's session for Statefull policy.

  • Call SessionProviderService.getSessionProvider(Object key) for obtaining a SessionProvider object

  • Call SessionProviderService.removeSessionProvider(Object key) at the end of a business request for Stateless application or application's session for Statefull policy.

eXo JCR supports observation (JSR-170 8.3), which enables applications to register interest in events that describe changes to a workspace, and then monitor and respond to those events. The standard observation feature allows dispatching events when persistent change to the workspace is made.

eXo JCR also offers a proprietary Extension Action which dispatches and fires an event upon each transient session level change, performed by a client. In other words, the event is triggered when a client's program invokes some updating methods in a session or a workspace (such as: Session.addNode(), Session.setProperty(), Workspace.move() etc.

By default when an action fails, the related exception is simply logged. In case you would like to change the default exception handling, you can implement the interface AdvancedAction. In case the JCR detects that your action is of type AdvancedAction, it will call the method onError instead of simply logging it. A default implementation of the onError method is available in the abstract class AbstractAdvancedAction. It reverts all pending changes of the current JCR session for any kind of event corresponding to a write operation. Then in case the provided exception is an instance of type AdvancedActionException, it will throw it otherwise it will log simply it. An AdvancedActionException will be thrown in case the changes could not be reverted.

One important recommendation should be applied for an extension action implementation. Each action will add its own execution time to standard JCR methods (Session.addNode(), Session.setProperty(), Workspace.move() etc.) execution time. As a consequence, it's necessary to minimize Action.execute(Context) body execution time.

To make the rule, you can use the dedicated Thread in Action.execute(Context) body for a custom logic. But if your application logic requires the action to add items to a created/updated item and you save these changes immediately after the JCR API method call is returned, the suggestion with Thread is not applicable for you in this case.

Add a SessionActionCatalog service and an appropriate AddActionsPlugin (see the example below) configuration to your eXo Container configuration. As usual, the plugin can be configured as in-component-place, which is the case for a Standalone Container or externally, which is a usual case for Root/Portal Container configuration).

Each Action entry is exposed as org.exoplatform.services.jcr.impl.ext.action. ActionConfiguration of actions collection of org.exoplatform.services.jcr.impl.ext.action.AddActionsPlugin$ActionsConfig (see an example below). The mandatory field named actionClassName is the fully qualified name of org.exoplatform.services.command.action.Action implementation - the command will be launched in case the current event matches the criteria. All other fields are criteria. The criteria are *AND*ed together. In other words, for a particular item to be listened to, it must meet ALL the criteria:

* workspace: the comma delimited (ORed) list of workspaces

* eventTypes: a comma delimited (ORed) list of event names (see below) to be listened to. This is the only mandatory field, others are optional and if they are missing they are interpreted as ANY.

* path - a comma delimited (ORed) list of item absolute paths (or within its subtree if isDeep is true, which is the default value)

* nodeTypes - a comma delimited (ORed) list of the current NodeType. Since version 1.6.1 JCR supports the functionalities of nodeType and parentNodeType. This parameter has different semantics, depending on the type of the current item and the operation performed. If the current item is a property it means the parent node type. If the current item is a node, the semantic depends on the event type: ** add node event: the node type of the newly added node. ** add mixin event: the newly added mixing node type of the current node. ** remove mixin event the removed mixin type of the current node. ** other events: the already assigned NodeType(s) of the current node (can be both primary and mixin).

The list of supported Event names: addNode, addProperty, changeProperty, removeProperty, removeNode, addMixin, removeMixin, lock, unlock, checkin, checkout, read.

<component>
   <type>org.exoplatform.services.jcr.impl.ext.action.SessionActionCatalog</type>
   <component-plugins>
      <component-plugin>
         <name>addActions</name>
         <set-method>addPlugin</set-method>
         <type>org.exoplatform.services.jcr.impl.ext.action.AddActionsPlugin</type>
         <description>add actions plugin</description>
         <init-params>
            <object-param>
               <name>actions</name>
               <object type="org.exoplatform.services.jcr.impl.ext.action.AddActionsPlugin$ActionsConfig">
               <field  name="actions">
                  <collection type="java.util.ArrayList">
                     <value>
                        <object type="org.exoplatform.services.jcr.impl.ext.action.ActionConfiguration">
                          <field  name="eventTypes"><string>addNode,removeNode</string></field>
                          <field  name="path"><string>/test,/exo:test</string></field>       
                          <field  name="isDeep"><boolean>true</boolean></field>       
                          <field  name="nodeTypes"><string>nt:file,nt:folder,mix:lockable</string></field>       
                          <!-- field  name="workspace"><string>backup</string></field -->
                          <field  name="actionClassName"><string>org.exoplatform.services.jcr.ext.DummyAction</string></field>       
                        </object>
                     </value>
                  </collection>
               </field>
            </object>
          </object-param>
        </init-params>
      </component-plugin>
    </component-plugins>
</component>

eXo JCR implementation supports two ways of Nodetypes registration:

The ExtendedNodeTypeManager (from JCR 1.11) interface provides the following methods related to registering node types:

public static final int IGNORE_IF_EXISTS  = 0;

public static final int FAIL_IF_EXISTS    = 2;

public static final int REPLACE_IF_EXISTS = 4;

 /**
  * Return NodeType for a given InternalQName.
  *
  * @param qname nodetype name
  * @return NodeType
  * @throws NoSuchNodeTypeException if no nodetype found with the name
  * @throws RepositoryException Repository error
  */
NodeType findNodeType(InternalQName qname) throws NoSuchNodeTypeException, RepositoryException;

/**
 * Registers node type using value object.
 * 
 * @param nodeTypeValue
 * @param alreadyExistsBehaviour
 * @throws RepositoryException
 */
NodeType registerNodeType(NodeTypeValue nodeTypeValue, int alreadyExistsBehaviour) throws RepositoryException;

/**
 * Registers all node types using XML binding value objects from xml stream.
 * 
 * @param xml a InputStream
 * @param alreadyExistsBehaviour a int
 * @throws RepositoryException
 */
NodeTypeIterator registerNodeTypes(InputStream xml, int alreadyExistsBehaviour, String contentType)
   throws RepositoryException;

/**
 * Gives the {@link NodeTypeManager}
 * 
 * @throws RepositoryException if another error occurs.
 */
NodeTypeDataManager getNodeTypesHolder() throws RepositoryException;

/**
 * Return <code>NodeTypeValue</code> for a given nodetype name. Used for
 * nodetype update. Value can be edited and registered via
 * <code>registerNodeType(NodeTypeValue nodeTypeValue, int alreadyExistsBehaviour)</code>
 * .
 * 
 * @param ntName nodetype name
 * @return NodeTypeValue
 * @throws NoSuchNodeTypeException if no nodetype found with the name
 * @throws RepositoryException Repository error
 */
NodeTypeValue getNodeTypeValue(String ntName) throws NoSuchNodeTypeException, RepositoryException;

/**
 * Registers or updates the specified <code>Collection</code> of
 * <code>NodeTypeValue</code> objects. This method is used to register or
 * update a set of node types with mutual dependencies. Returns an iterator
 * over the resulting <code>NodeType</code> objects. <p/> The effect of the
 * method is "all or nothing"; if an error occurs, no node types are
 * registered or updated. <p/> Throws an
 * <code>InvalidNodeTypeDefinitionException</code> if a
 * <code>NodeTypeDefinition</code> within the <code>Collection</code> is
 * invalid or if the <code>Collection</code> contains an object of a type
 * other than <code>NodeTypeDefinition</code> . <p/> Throws a
 * <code>NodeTypeExistsException</code> if <code>allowUpdate</code> is
 * <code>false</code> and a <code>NodeTypeDefinition</code> within the
 * <code>Collection</code> specifies a node type name that is already
 * registered. <p/> Throws an
 * <code>UnsupportedRepositoryOperationException</code> if this implementation
 * does not support node type registration.
 * 
 * @param values a collection of <code>NodeTypeValue</code>s
 * @param alreadyExistsBehaviour a int
 * @return the registered node types.
 * @throws InvalidNodeTypeDefinitionException if a
 *           <code>NodeTypeDefinition</code> within the
 *           <code>Collection</code> is invalid or if the
 *           <code>Collection</code> contains an object of a type other than
 *           <code>NodeTypeDefinition</code>.
 * @throws NodeTypeExistsException if <code>allowUpdate</code> is
 *           <code>false</code> and a <code>NodeTypeDefinition</code> within
 *           the <code>Collection</code> specifies a node type name that is
 *           already registered.
 * @throws UnsupportedRepositoryOperationException if this implementation does
 *           not support node type registration.
 * @throws RepositoryException if another error occurs.
 */
public NodeTypeIterator registerNodeTypes(List<NodeTypeValue> values, int alreadyExistsBehaviour)
   throws UnsupportedRepositoryOperationException, RepositoryException;

/**
 * Unregisters the specified node type.
 * 
 * @param name a <code>String</code>.
 * @throws UnsupportedRepositoryOperationException if this implementation does
 *           not support node type registration.
 * @throws NoSuchNodeTypeException if no registered node type exists with the
 *           specified name.
 * @throws RepositoryException if another error occurs.
 */
public void unregisterNodeType(String name) throws UnsupportedRepositoryOperationException, NoSuchNodeTypeException,
   RepositoryException;

/**
 * Unregisters the specified set of node types.<p/> Used to unregister a set
 * of node types with mutual dependencies.
 * 
 * @param names a <code>String</code> array
 * @throws UnsupportedRepositoryOperationException if this implementation does
 *           not support node type registration.
 * @throws NoSuchNodeTypeException if one of the names listed is not a
 *           registered node type.
 * @throws RepositoryException if another error occurs.
 */
public void unregisterNodeTypes(String[] names) throws UnsupportedRepositoryOperationException,
   NoSuchNodeTypeException, RepositoryException;

The NodeTypeValue interface represents a simple container structure used to define node types which are then registered through the ExtendedNodeTypeManager.registerNodeType method. The implementation of this interface does not contain any validation logic.

/**
 * @return Returns the declaredSupertypeNames.
 */
public List<String> getDeclaredSupertypeNames();

/**
 * @param declaredSupertypeNames
 *The declaredSupertypeNames to set.
 */
public void setDeclaredSupertypeNames(List<String> declaredSupertypeNames);

/**
 * @return Returns the mixin.
 */
public boolean isMixin();

/**
 * @param mixin
 *The mixin to set.
 */
public void setMixin(boolean mixin);

/**
 * @return Returns the name.
 */
public String getName();

/**
 * @param name
 *The name to set.
 */
public void setName(String name);

/**
 * @return Returns the orderableChild.
 */
public boolean isOrderableChild();

/**
 * @param orderableChild
 *The orderableChild to set.
 */
public void setOrderableChild(boolean orderableChild);

/**
 * @return Returns the primaryItemName.
 */
public String getPrimaryItemName();

/**
 * @param primaryItemName
 *The primaryItemName to set.
 */
public void setPrimaryItemName(String primaryItemName);

/**
 * @return Returns the declaredChildNodeDefinitionNames.
 */
public List<NodeDefinitionValue> getDeclaredChildNodeDefinitionValues();

/**
 * @param declaredChildNodeDefinitionNames
 *The declaredChildNodeDefinitionNames to set.
 */
public void setDeclaredChildNodeDefinitionValues(List<NodeDefinitionValue> declaredChildNodeDefinitionValues);

/**
 * @return Returns the declaredPropertyDefinitionNames.
 */
public List<PropertyDefinitionValue> getDeclaredPropertyDefinitionValues();

/**
 * @param declaredPropertyDefinitionNames
 *The declaredPropertyDefinitionNames to set.
 */
public void setDeclaredPropertyDefinitionValues(List<PropertyDefinitionValue> declaredPropertyDefinitionValues);

The Registry Service is one of the key parts of the infrastructure built around eXo JCR. Each JCR that is based on service, applications, etc may have its own configuration, settings data and other data that have to be stored persistently and used by the approptiate service or application. ( We call it "Consumer").

The service acts as a centralized collector (Registry) for such data. Naturally, a registry storage is JCR based i.e. stored in some JCR workspace (one per Repository) as an Item tree under /exo:registry node.

Despite the fact that the structure of the tree is well defined (see the scheme below), it is not recommended for other services to manipulate data using JCR API directly for better flexibility. So the Registry Service acts as a mediator between a Consumer and its settings.

The proposed structure of the Registry Service storage is divided into 3 logical groups: services, applications and users:

 exo:registry/          <-- registry "root" (exo:registry)
   exo:services/        <-- service data storage (exo:registryGroup)
     service1/
       Consumer data    (exo:registryEntry)
     ...
   exo:applications/    <-- application data storage (exo:registryGroup)
     app1/
       Consumer data    (exo:registryEntry)
     ...
   exo:users/           <-- user personal data storage (exo:registryGroup)
     user1/
       Consumer data    (exo:registryEntry)
     ...

Each upper level eXo Service may store its configuration in eXo Registry. At first, start from xml-config (in jar etc) and then from Registry. In configuration file, you can add force-xml-configuration parameter to component to ignore reading parameters initialization from RegistryService and to use file instead:

<value-param>
  <name>force-xml-configuration</name>
  <value>true</value>
</value-param>

The main functionality of the Registry Service is pretty simple and straightforward, it is described in the Registry abstract class as the following:

public abstract class Registry
{

   /**
    * Returns Registry node object which wraps Node of "exo:registry" type (the whole registry tree)
    */
   public abstract RegistryNode getRegistry(SessionProvider sessionProvider) throws RepositoryConfigurationException,
      RepositoryException;

   /**
    * Returns existed RegistryEntry which wraps Node of "exo:registryEntry" type
    */
   public abstract RegistryEntry getEntry(SessionProvider sessionProvider, String entryPath)
      throws PathNotFoundException, RepositoryException;

   /**
    * creates an entry in the group. In a case if the group does not exist it will be silently
    * created as well
    */
   public abstract void createEntry(SessionProvider sessionProvider, String groupPath, RegistryEntry entry)
      throws RepositoryException;

   /**
    * updates an entry in the group
    */
   public abstract void recreateEntry(SessionProvider sessionProvider, String groupPath, RegistryEntry entry)
      throws RepositoryException;

   /**
    * removes entry located on entryPath (concatenation of group path / entry name)
    */
   public abstract void removeEntry(SessionProvider sessionProvider, String entryPath) throws RepositoryException;

}

As you can see it looks like a simple CRUD interface for the RegistryEntry object which wraps registry data for some Consumer as a Registry Entry. The Registry Service itself knows nothing about the wrapping data, it is Consumer's responsibility to manage and use its data in its own way.

To create an Entity Consumer you should know how to serialize the data to some XML structure and then create a RegistryEntry from these data at once or populate them in a RegistryEntry object (using RegistryEntry(String entryName) constructor and then obtain and fill a DOM document).

Example of RegistryService using:

    RegistryService regService = (RegistryService) container
    .getComponentInstanceOfType(RegistryService.class);

    RegistryEntry registryEntry = regService.getEntry(sessionProvider,
            RegistryService.EXO_SERVICES + "/my-service");

    Document doc = registryEntry.getDocument();
    
    String mySetting = getElementsByTagName("tagname").item(index).getTextContent();
     .....

Support of node types and namespaces is required by the JSR-170 specification. Beyond the methods required by the specification, eXo JCR has its own API extension for the Node type registration as well as the ability to declaratively define node types in the Repository at the start-up time.

Node type registration extension is declared in org.exoplatform.services.jcr.core.nodetype.ExtendedNodeTypeManager interface

Your custom service can register some neccessary predefined node types at the start-up time. The node definition should be placed in a special XML file (see DTD below) and declared in the service's configuration file thanks to eXo component plugin mechanism, described as follows:

<external-component-plugins>
  <target-component>org.exoplatform.services.jcr.RepositoryService</target-component>
      <component-plugin>
        <name>add.nodeType</name>
        <set-method>addPlugin</set-method>
        <type>org.exoplatform.services.jcr.impl.AddNodeTypePlugin</type>
        <init-params>
          <values-param>
            <name>autoCreatedInNewRepository</name>
            <description>Node types configuration file</description>
            <value>jar:/conf/test/nodetypes-tck.xml</value>
            <value>jar:/conf/test/nodetypes-impl.xml</value>
          </values-param>
    <values-param> 
            <name>repo1</name> 
            <description>Node types configuration file for repository with name repo1</description> 
            <value>jar:/conf/test/nodetypes-test.xml</value> 
          </values-param>
    <values-param> 
            <name>repo2</name> 
            <description>Node types configuration file for repository with name repo2</description> 
            <value>jar:/conf/test/nodetypes-test2.xml</value> 
          </values-param>
        </init-params>
      </component-plugin>

There are two types of registration. The first type is the registration of node types in all created repositories, it is configured in values-param with the name autoCreatedInNewRepository. The second type is registration of node types in specified repository and it is configured in values-param with the name of repository.

Node type definition file format:

  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE nodeTypes [
   <!ELEMENT nodeTypes (nodeType)*>
      <!ELEMENT nodeType (supertypes?|propertyDefinitions?|childNodeDefinitions?)>

      <!ATTLIST nodeType
         name CDATA #REQUIRED
         isMixin (true|false) #REQUIRED
         hasOrderableChildNodes (true|false)
         primaryItemName CDATA
      >
      <!ELEMENT supertypes (supertype*)>
      <!ELEMENT supertype (CDATA)>
   
      <!ELEMENT propertyDefinitions (propertyDefinition*)>

      <!ELEMENT propertyDefinition (valueConstraints?|defaultValues?)>
      <!ATTLIST propertyDefinition
         name CDATA #REQUIRED
         requiredType (String|Date|Path|Name|Reference|Binary|Double|Long|Boolean|undefined) #REQUIRED
         autoCreated (true|false) #REQUIRED
         mandatory (true|false) #REQUIRED
         onParentVersion (COPY|VERSION|INITIALIZE|COMPUTE|IGNORE|ABORT) #REQUIRED
         protected (true|false) #REQUIRED
         multiple  (true|false) #REQUIRED
      >    
    <!-- For example if you need to set ValueConstraints [], 
      you have to add an empty element <valueConstraints/>. 
      The same order is for other properties like defaultValues, requiredPrimaryTypes etc.
      -->  
      <!ELEMENT valueConstraints (valueConstraint*)>
      <!ELEMENT valueConstraint (CDATA)>
      <!ELEMENT defaultValues (defaultValue*)>
      <!ELEMENT defaultValue (CDATA)>

      <!ELEMENT childNodeDefinitions (childNodeDefinition*)>

      <!ELEMENT childNodeDefinition (requiredPrimaryTypes)>
      <!ATTLIST childNodeDefinition
         name CDATA #REQUIRED
         defaultPrimaryType  CDATA #REQUIRED
         autoCreated (true|false) #REQUIRED
         mandatory (true|false) #REQUIRED
         onParentVersion (COPY|VERSION|INITIALIZE|COMPUTE|IGNORE|ABORT) #REQUIRED
         protected (true|false) #REQUIRED
         sameNameSiblings (true|false) #REQUIRED
      >
      <!ELEMENT requiredPrimaryTypes (requiredPrimaryType+)>
      <!ELEMENT requiredPrimaryType (CDATA)>  
]>

This section provides you the knowledge about eXo JCR configuration in details, including the basic and advanced configuration.

Like other eXo services, eXo JCR can be configured and used in the portal or embedded mode (as a service embedded in GateIn) 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):

  • 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: Don't 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.

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>
    <value-param>
      <name>max-backup-files</name>
      <value>5</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.

max-backup-files : max number of backup files. This option lets you specify the number of stored backups. Number of backups can't exceed this value. File which will exceed the limit will replace the oldest file.

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

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.

Note

Also see lock-remover-max-threads repository configuration parameter.

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

You can configure values of properties defined in the file repository-configuration.xml using System Properties. This is quite helpful especially when you want to change the default configuration of all the workspaces for example if we want to disable the rdms indexing for all the workspace without this kind of improvement it is very error prone. For all components that can be configured thanks to properties such as container, value-storage, workspace-initializer, cache, query-handler, lock-manager, access-manager and persister the logic for example for the component 'container' and the property called 'foo' will be the following:

To turn on this feature you need to define a component called SystemParametersPersistenceConfigurator. A simple example:

  <component>
    <key>org.exoplatform.services.jcr.config.SystemParametersPersistenceConfigurator</key>
    <type>org.exoplatform.services.jcr.config.SystemParametersPersistenceConfigurator</type>
    <init-params>
      <value-param>
        <name>file-path</name>
        <value>target/temp</value>
      </value-param>
      <values-param>
        <name>unmodifiable</name>
        <value>cache.test-parameter-I</value>
      </values-param>
      <values-param>
        <name>before-initialize</name>
        <value>value-storage.enabled</value>
      </values-param>
    </init-params>
  </component>

To make the configuration process easier here you can define thee parameters.

The parameter in the list have the following format: {component-name}.{parameter-name}. This takes affect for every workspace component called {component-name}.

Please take into account that if this component is not defined in the configuration, the workspace configuration overriding using system properties mechanism will be disabled. In other words: if you don't configure SystemParametersPersistenceConfigurator, the system properties are ignored.

Whenever relational database is used to store multilingual text data of eXo Java Content Repository, it is necessary to adapt configuration in order to support UTF-8 encoding. Here is a short HOWTO instruction for several supported RDBMS with examples.

The configuration file you have to modify: .../webapps/portal/WEB-INF/conf/jcr/repository-configuration.xml

In order to run multilanguage JCR on an Oracle backend Unicode encoding for characters set should be applied to the database. Other Oracle globalization parameters don't make any impact. The only property to modify is NLS_CHARACTERSET.

We have tested NLS_CHARACTERSET = AL32UTF8 and it works well for many European and Asian languages.

Example of database configuration (used for JCR testing):

NLS_LANGUAGE             AMERICAN
NLS_TERRITORY            AMERICA
NLS_CURRENCY             $
NLS_ISO_CURRENCY         AMERICA
NLS_NUMERIC_CHARACTERS   .,
NLS_CHARACTERSET         AL32UTF8
NLS_CALENDAR             GREGORIAN
NLS_DATE_FORMAT          DD-MON-RR
NLS_DATE_LANGUAGE        AMERICAN
NLS_SORT                 BINARY
NLS_TIME_FORMAT          HH.MI.SSXFF AM
NLS_TIMESTAMP_FORMAT     DD-MON-RR HH.MI.SSXFF AM
NLS_TIME_TZ_FORMAT       HH.MI.SSXFF AM TZR
NLS_TIMESTAMP_TZ_FORMAT  DD-MON-RR HH.MI.SSXFF AM TZR
NLS_DUAL_CURRENCY        $
NLS_COMP                 BINARY
NLS_LENGTH_SEMANTICS     BYTE
NLS_NCHAR_CONV_EXCP      FALSE
NLS_NCHAR_CHARACTERSET   AL16UTF16

Create database with Unicode encoding and use Oracle dialect for the Workspace Container:

<workspace name="collaboration">
          <container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer">
            <properties>
              <property name="source-name" value="jdbcjcr" />
              <property name="dialect" value="oracle" />
              <property name="multi-db" value="false" />
              <property name="max-buffer-size" value="200k" />
              <property name="swap-directory" value="target/temp/swap/ws" />
            </properties>
          .....

DB2 Universal Database (DB2 UDB) supports UTF-8 and UTF-16/UCS-2. When a Unicode database is created, CHAR, VARCHAR, LONG VARCHAR data are stored in UTF-8 form. It's enough for JCR multi-lingual support.

Example of UTF-8 database creation:

DB2 CREATE DATABASE dbname USING CODESET UTF-8 TERRITORY US

Create database with UTF-8 encoding and use db2 dialect for Workspace Container on DB2 v.9 and higher:

<workspace name="collaboration">
          <container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer">
            <properties>
              <property name="source-name" value="jdbcjcr" />
              <property name="dialect" value="db2" />
              <property name="multi-db" value="false" />
              <property name="max-buffer-size" value="200k" />
              <property name="swap-directory" value="target/temp/swap/ws" />
            </properties>
          .....

Note

For DB2 v.8.x support change the property "dialect" to db2v8.

JCR MySQL-backend requires special dialect MySQL-UTF8 to be used for internationalization support. But the database default charset should be latin1 to use limited index space effectively (1000 bytes for MyISAM engine, 767 for InnoDB). If database default charset is multibyte, a JCR database initialization error is thrown concerning index creation failure. In other words, JCR can work on any singlebyte default charset of database, with UTF8 supported by MySQL server. But we have tested it only on latin1 database default charset.

Repository configuration, workspace container entry example:

<workspace name="collaboration">
          <container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer">
            <properties>
              <property name="source-name" value="jdbcjcr" />
              <property name="dialect" value="mysql-utf8" />
              <property name="multi-db" value="false" />
              <property name="max-buffer-size" value="200k" />
              <property name="swap-directory" value="target/temp/swap/ws" />
            </properties>
          .....

You will need also to indicate the charset name either at server level using the server parameter --character-set-server (find more details there ) or at datasource configuration level by adding a new property as below:

          <property name="connectionProperties" value="useUnicode=yes;characterEncoding=utf8;characterSetResults=UTF-8;" />
     

On PostgreSQL/PostgrePlus-backend, multilingual support can be enabled in different ways:

  • Using the locale features of the operating system to provide locale-specific collation order, number formatting, translated messages, and other aspects. UTF-8 is widely used on Linux distributions by default, so it can be useful in such case.

  • Providing a number of different character sets defined in the PostgreSQL/PostgrePlus server, including multiple-byte character sets, to support storing text of any languages, and providing character set translation between client and server. We recommend to use UTF-8 database charset, it will allow any-to-any conversations and make this issue transparent for the JCR.

Create database with UTF-8 encoding and use a PgSQL dialect for Workspace Container:

<workspace name="collaboration">
          <container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer">
            <properties>
              <property name="source-name" value="jdbcjcr" />
              <property name="dialect" value="pgsql" />
              <property name="multi-db" value="false" />
              <property name="max-buffer-size" value="200k" />
              <property name="swap-directory" value="target/temp/swap/ws" />
            </properties>
          .....

Frequently, a single database instance must be shared by several other applications. But some of our customers have also asked for a way to host several JCR instances in the same database instance. To fulfill this need, we had to review our queries and scope them to the current schema; it is now possible to have one JCR instance per DB schema instead of per DB instance. To benefit of the work done for this feature you will need to apply the configuration changes described below.

To enable this feature you need to replace org.jboss.cache.loader.JDBCCacheLoader with org.exoplatform.services.jcr.impl.core.lock.jbosscache.JDBCCacheLoader in JBossCache configuration file.

Here is an example of this very part of the configuration:

<jbosscache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:jboss:jbosscache-core:config:3.1">

   <locking useLockStriping="false" concurrencyLevel="500" lockParentForChildInsertRemove="false"
      lockAcquisitionTimeout="20000" />

   <clustering mode="replication" clusterName="${jbosscache-cluster-name}">
      <stateRetrieval timeout="20000" fetchInMemoryState="false" />
      <sync />
   </clustering>

   <loaders passivation="false" shared="true">
      <!-- All the data of the JCR locks needs to be loaded at startup -->
      <preload>
         <node fqn="/" />
      </preload>  
      <!--
      For another cache-loader class you should use another template with
      cache-loader specific parameters
      -->
      <loader class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.JDBCCacheLoader" async="false" fetchPersistentState="false"
         ignoreModifications="false" purgeOnStartup="false">
         <properties>
            cache.jdbc.table.name=${jbosscache-cl-cache.jdbc.table.name}
            cache.jdbc.table.create=${jbosscache-cl-cache.jdbc.table.create}
            cache.jdbc.table.drop=${jbosscache-cl-cache.jdbc.table.drop}
            cache.jdbc.table.primarykey=${jbosscache-cl-cache.jdbc.table.primarykey}
            cache.jdbc.fqn.column=${jbosscache-cl-cache.jdbc.fqn.column}
            cache.jdbc.fqn.type=${jbosscache-cl-cache.jdbc.fqn.type}
            cache.jdbc.node.column=${jbosscache-cl-cache.jdbc.node.column}
            cache.jdbc.node.type=${jbosscache-cl-cache.jdbc.node.type}
            cache.jdbc.parent.column=${jbosscache-cl-cache.jdbc.parent.column}
            cache.jdbc.datasource=${jbosscache-cl-cache.jdbc.datasource}
         </properties>
      </loader>
   </loaders>
</jbosscache>

You can also obtain file example from GitHub.

Search is an important function in eXo JCR, so it is very necessary for you to know how to configure the eXo JCR Search tool.

Table 1.2. 

ParameterDefaultDescriptionSince
index-dirnoneThe location of the index directory. This parameter is mandatory. Up to 1.9, this parameter called "indexDir"1.0
use-compoundfiletrueAdvises lucene to use compound files for the index files.1.9
min-merge-docs100Minimum number of nodes in an index until segments are merged.1.9
volatile-idle-time3Idle time in seconds until the volatile index part is moved to a persistent index even though minMergeDocs is not reached.1.9
max-merge-docsInteger.MAX_VALUEMaximum number of nodes in segments that will be merged. The default value changed in JCR 1.9 to Integer.MAX_VALUE.1.9
merge-factor10Determines how often segment indices are merged.1.9
max-field-length10000The number of words that are fulltext indexed at most per property.1.9
cache-size1000Size of the document number cache. This cache maps uuids to lucene document numbers1.9
force-consistencycheckfalseRuns a consistency check on every startup. If false, a consistency check is only performed when the search index detects a prior forced shutdown.1.9
auto-repairtrueErrors detected by a consistency check are automatically repaired. If false, errors are only written to the log.1.9
query-classQueryImplClass name that implements the javax.jcr.query.Query interface.This class must also extend from the class: org.exoplatform.services.jcr.impl.core.query.AbstractQueryImpl.1.9
document-ordertrueIf true and the query does not contain an 'order by' clause, result nodes will be in document order. For better performance when queries return a lot of nodes set to 'false'.1.9
result-fetch-sizeInteger.MAX_VALUEThe number of results when a query is executed. Default value: Integer.MAX_VALUE (-> all).1.9
excerptprovider-classDefaultXMLExcerptThe name of the class that implements org.exoplatform.services.jcr.impl.core.query.lucene.ExcerptProvider and should be used for the rep:excerpt() function in a query.1.9
support-highlightingfalseIf set to true additional information is stored in the index to support highlighting using the rep:excerpt() function.1.9
synonymprovider-classnoneThe name of a class that implements org.exoplatform.services.jcr.impl.core.query.lucene.SynonymProvider. The default value is null (-> not set).1.9
synonymprovider-config-pathnoneThe path to the synonym provider configuration file. This path interpreted is relative to the path parameter. If there is a path element inside the SearchIndex element, then this path is interpreted and relative to the root path of the path. Whether this parameter is mandatory or not, it depends on the synonym provider implementation. The default value is null (-> not set).1.9
indexing-configuration-pathnoneThe path to the indexing configuration file.1.9
indexing-configuration-classIndexingConfigurationImplThe name of the class that implements org.exoplatform.services.jcr.impl.core.query.lucene.IndexingConfiguration.1.9
force-consistencycheckfalseIf setting to true, a consistency check is performed, depending on the parameter forceConsistencyCheck. If setting to false, no consistency check is performed on startup, even if a redo log had been applied.1.9
spellchecker-classnoneThe name of a class that implements org.exoplatform.services.jcr.impl.core.query.lucene.SpellChecker.1.9
spellchecker-more-populartrueIf setting true, spellchecker returns only the suggest words that are as frequent or more frequent than the checked word. If setting false, spellchecker returns null (if checked word exit in dictionary), or spellchecker will return most close suggest word.1.10
spellchecker-min-distance0.55fMinimal distance between checked word and proposed suggest word.1.10
errorlog-size50(Kb)The default size of error log file in Kb.1.9
upgrade-indexfalseAllows JCR to convert an existing index into the new format. Also, it is possible to set this property via system property, for example: -Dupgrade-index=true Indexes before JCR 1.12 will not run with JCR 1.12. Hence you have to run an automatic migration: Start JCR with -Dupgrade-index=true. The old index format is then converted in the new index format. After the conversion the new format is used. On the next start, you don't need this option anymore. The old index is replaced and a back conversion is not possible - therefore better take a backup of the index before. (Only for migrations from JCR 1.9 and later.)1.12
analyzerorg.apache.lucene.analysis.standard.StandardAnalyzerClass name of a lucene analyzer to use for fulltext indexing of text.1.12

Note

The Maximum number of clauses permitted per BooleanQuery, can be changed via the System property org.apache.lucene.maxClauseCount. The default value of this parameter is Integer.MAX_VALUE.

By default Exo JCR uses the Lucene standard Analyzer to index contents. This analyzer uses some standard filters in the method that analyzes the content:

public TokenStream tokenStream(String fieldName, Reader reader) {
    StandardTokenizer tokenStream = new StandardTokenizer(reader, replaceInvalidAcronym);
    tokenStream.setMaxTokenLength(maxTokenLength);
    TokenStream result = new StandardFilter(tokenStream);
    result = new LowerCaseFilter(result);
    result = new StopFilter(result, stopSet);
    return result;
  }

For specific cases, you may wish to use additional filters like ISOLatin1AccentFilter, which replaces accented characters in the ISO Latin 1 character set (ISO-8859-1) by their unaccented equivalents.

In order to use a different filter, you have to create a new analyzer, and a new search index to use the analyzer. You put it in a jar, which is deployed with your application.

You may also add a condition to the index rule and have multiple rules with the same nodeType. The first index rule that matches will apply and all remain ones are ignored:

<?xml version="1.0"?>
<!DOCTYPE configuration SYSTEM "http://www.exoplatform.org/dtd/indexing-configuration-1.0.dtd">
<configuration xmlns:nt="http://www.jcp.org/jcr/nt/1.0">
  <index-rule nodeType="nt:unstructured"
              boost="2.0"
              condition="@priority = 'high'">
    <property>Text</property>
  </index-rule>
  <index-rule nodeType="nt:unstructured">
    <property>Text</property>
  </index-rule>
</configuration>

In the above example, the first rule only applies if the nt:unstructured node has a priority property with a value 'high'. The condition syntax supports only the equals operator and a string literal.

You may also refer properties in the condition that are not on the current node:

<?xml version="1.0"?>
<!DOCTYPE configuration SYSTEM "http://www.exoplatform.org/dtd/indexing-configuration-1.0.dtd">
<configuration xmlns:nt="http://www.jcp.org/jcr/nt/1.0">
  <index-rule nodeType="nt:unstructured"
              boost="2.0"
              condition="ancestor::*/@priority = 'high'">
    <property>Text</property>
  </index-rule>
  <index-rule nodeType="nt:unstructured"
              boost="0.5"
              condition="parent::foo/@priority = 'low'">
    <property>Text</property>
  </index-rule>
  <index-rule nodeType="nt:unstructured"
              boost="1.5"
              condition="bar/@priority = 'medium'">
    <property>Text</property>
  </index-rule>
  <index-rule nodeType="nt:unstructured">
    <property>Text</property>
  </index-rule>
</configuration>

The indexing configuration also allows you to specify the type of a node in the condition. Please note however that the type match must be exact. It does not consider sub types of the specified node type.

<?xml version="1.0"?>
<!DOCTYPE configuration SYSTEM "http://www.exoplatform.org/dtd/indexing-configuration-1.0.dtd">
<configuration xmlns:nt="http://www.jcp.org/jcr/nt/1.0">
  <index-rule nodeType="nt:unstructured"
              boost="2.0"
              condition="element(*, nt:unstructured)/@priority = 'high'">
    <property>Text</property>
  </index-rule>
</configuration>

Sometimes it is useful to include the contents of descendant nodes into a single node to easier search on content that is scattered across multiple nodes.

JCR allows you to define indexed aggregates, basing on relative path patterns and primary node types.

The following example creates an indexed aggregate on nt:file that includes the content of the jcr:content node:

<?xml version="1.0"?>
<!DOCTYPE configuration SYSTEM "http://www.exoplatform.org/dtd/indexing-configuration-1.0.dtd">
<configuration xmlns:jcr="http://www.jcp.org/jcr/1.0"
               xmlns:nt="http://www.jcp.org/jcr/nt/1.0">
  <aggregate primaryType="nt:file">
    <include>jcr:content</include>
  </aggregate>
</configuration>

You can also restrict the included nodes to a certain type:

<?xml version="1.0"?>
<!DOCTYPE configuration SYSTEM "http://www.exoplatform.org/dtd/indexing-configuration-1.0.dtd">
<configuration xmlns:jcr="http://www.jcp.org/jcr/1.0"
               xmlns:nt="http://www.jcp.org/jcr/nt/1.0">
  <aggregate primaryType="nt:file">
    <include primaryType="nt:resource">jcr:content</include>
  </aggregate>
</configuration>

You may also use the * to match all child nodes:

<?xml version="1.0"?>
<!DOCTYPE configuration SYSTEM "http://www.exoplatform.org/dtd/indexing-configuration-1.0.dtd">
<configuration xmlns:jcr="http://www.jcp.org/jcr/1.0"
               xmlns:nt="http://www.jcp.org/jcr/nt/1.0">
  <aggregate primaryType="nt:file">
    <include primaryType="nt:resource">*</include>
  </aggregate>
</configuration>

If you wish to include nodes up to a certain depth below the current node, you can add multiple include elements. E.g. the nt:file node may contain a complete XML document under jcr:content:

<?xml version="1.0"?>
<!DOCTYPE configuration SYSTEM "http://www.exoplatform.org/dtd/indexing-configuration-1.0.dtd">
<configuration xmlns:jcr="http://www.jcp.org/jcr/1.0"
               xmlns:nt="http://www.jcp.org/jcr/nt/1.0">
  <aggregate primaryType="nt:file">
    <include>*</include>
    <include>*/*</include>
    <include>*/*/*</include>
  </aggregate>
</configuration>

When using analyzers, you may encounter an unexpected behavior when searching within a property compared to searching within a node scope. The reason is that the node scope always uses the global analyzer.

Let's suppose that the property "mytext" contains the text : "testing my analyzers" and that you haven't configured any analyzers for the property "mytext" (and not changed the default analyzer in SearchIndex).

If your query is for example:

xpath = "//*[jcr:contains(mytext,'analyzer')]"
        

This xpath does not return a hit in the node with the property above and default analyzers.

Also a search on the node scope

xpath = "//*[jcr:contains(.,'analyzer')]"

won't give a hit. Realize that you can only set specific analyzers on a node property, and that the node scope indexing/analyzing is always done with the globally defined analyzer in the SearchIndex element.

Now, if you change the analyzer used to index the "mytext" property above to

<analyzer class="org.apache.lucene.analysis.Analyzer.GermanAnalyzer">
     <property>mytext</property>
</analyzer>

and you do the same search again, then for

xpath = "//*[jcr:contains(mytext,'analyzer')]"

you would get a hit because of the word stemming (analyzers - analyzer).

The other search,

xpath = "//*[jcr:contains(.,'analyzer')]"
        

still would not give a result, since the node scope is indexed with the global analyzer, which in this case does not take into account any word stemming.

In conclusion, be aware that when using analyzers for specific properties, you might find a hit in a property for some search text, and you do not find a hit with the same search text in the node scope of the property!

eXo JCR supports some advanced features, which are not specified in JSR 170:

eXo JCR allows using persister to store configuration. In this section, you will understand how to use and configure eXo JCR persister.

On startup RepositoryServiceConfiguration component checks if a configuration persister was configured. In that case, it uses the provided ConfigurationPersister implementation class to instantiate the persister object.

Configuration with persister:

<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 configuration file</description>
        <value>/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="mysql" />
        <property name="persister-class-name" value="org.exoplatform.services.jcr.impl.config.JDBCConfigurationPersister" />
      </properties-param>
    </init-params>
  </component>
  

Where:

ConfigurationPersister interface:

/**
   * Init persister.
   * Used by RepositoryServiceConfiguration on init. 
   * @return - config data stream
   */
  void init(PropertiesParam params) throws RepositoryConfigurationException;
  
  /**
   * Read config data.
   * @return - config data stream
   */
  InputStream read() throws RepositoryConfigurationException;
  
  /**
   * Create table, write data.
   * @param confData - config data stream
   */
  void write(InputStream confData) throws RepositoryConfigurationException;
  
  /**
   * Tell if the config exists.
   * @return - flag
   */
  boolean hasConfig() throws RepositoryConfigurationException;
  

JCR Core implementation contains a persister which stores the repository configuration in the relational database using JDBC calls - org.exoplatform.services.jcr.impl.config.JDBCConfigurationPersister.

The implementation will crate and use table JCR_CONFIG in the provided database.

But the developer can implement his own persister for his particular usecase.

eXo JCR persistent data container can work in two configuration modes:

The data container uses the JDBC driver to communicate with the actual database software, i.e. any JDBC-enabled data storage can be used with eXo JCR implementation.

Currently the data container is tested with the following configurations:

Each database software supports ANSI SQL standards but also has its own specifics. So, each database has its own configuration in eXo JCR as a database dialect parameter. If you need a more detailed configuration of the database, it's possible to do that by editing the metadata SQL-script files.

SQL-scripts you can obtain from jar-file exo.jcr.component.core-XXX.XXX.jar:conf/storage/. They also can be found at GitHub here.

In the next two tables correspondence between the scripts and databases is shown.

Table 1.3. Single-database
MySQL DB jcr-sjdbc.mysql.sql
MySQL DB with utf-8 jcr-sjdbc.mysql-utf8.sql
MySQL DB with MyISAM* jcr-sjdbc.mysql-myisam.sql
MySQL DB with MyISAM and utf-8* jcr-sjdbc.mysql-myisam-utf8.sql
MySQL DB with NDB engine jcr-sjdbc.mysql-ndb.sql
MySQL DB with NDB engine and utf-8 jcr-sjdbc.mysql-ndb-utf8.sql
PostgresSQL and Postgre Plus jcr-sjdbc.pqsql.sql
Oracle DB jcr-sjdbc.ora.sql
DB2 jcr-sjdbc.db2.sql
MS SQL Server jcr-sjdbc.mssql.sql
Sybase jcr-sjdbc.sybase.sql
HSQLDB jcr-sjdbc.sql
H2 jcr-sjdbc.h2.sql
Table 1.4. Multi-database
MySQL DB jcr-mjdbc.mysql.sql
MySQL DB with utf-8 jcr-mjdbc.mysql-utf8.sql
MySQL DB with MyISAM* jcr-mjdbc.mysql-myisam.sql
MySQL DB with MyISAM and utf-8* jcr-mjdbc.mysql-myisam-utf8.sql
MySQL DB with NDB engine jcr-mjdbc.mysql-ndb.sql
MySQL DB with NDB engine and utf-8 jcr-mjdbc.mysql-ndb-utf8.sql
PostgresSQL and Postgre Plus jcr-mjdbc.pqsql.sql
Oracle DB jcr-mjdbc.ora.sql
DB2 jcr-mjdbc.db2.sql
MS SQL Server jcr-mjdbc.mssql.sql
Sybase jcr-mjdbc.sybase.sql
HSQLDB jcr-mjdbc.sql
H2 jcr-mjdbc.h2.sql

In case the non-ANSI node name is used, it's necessary to use a database with MultiLanguage support. Some JDBC drivers need additional parameters for establishing a Unicode friendly connection. E.g. under mysql it's necessary to add an additional parameter for the JDBC driver at the end of JDBC URL. For instance: jdbc:mysql://exoua.dnsalias.net/portal?characterEncoding=utf8

There are preconfigured configuration files for HSQLDB. Look for these files in /conf/portal and /conf/standalone folders of the jar-file exo.jcr.component.core-XXX.XXX.jar or source-distribution of eXo JCR implementation.

By default, the configuration files are located in service jars /conf/portal/configuration.xml (eXo services including JCR Repository Service) and exo-jcr-config.xml (repositories configuration). In GateIn product, JCR is configured in portal web application portal/WEB-INF/conf/jcr/jcr-configuration.xml (JCR Repository Service and related serivces) and repository-configuration.xml (repositories configuration).

Read more about Repository configuration.

  • Oracle DB automatically collects statistics to optimize performance of queries, but you can manually call 'ANALYZE' command to start collecting statistics immediately which may improve performance. For example

    ANALYZE TABLE JCR_SITEM COMPUTE STATISTICS
    ANALYZE TABLE JCR_SVALUE COMPUTE STATISTICS
    ANALYZE TABLE JCR_SREF COMPUTE STATISTICS
    ANALYZE INDEX JCR_PK_SITEM COMPUTE STATISTICS
    ANALYZE INDEX JCR_IDX_SITEM_PARENT_FK COMPUTE STATISTICS
    ANALYZE INDEX JCR_IDX_SITEM_PARENT COMPUTE STATISTICS
    ANALYZE INDEX JCR_IDX_SITEM_PARENT_NAME COMPUTE STATISTICS
    ANALYZE INDEX JCR_IDX_SITEM_PARENT_ID COMPUTE STATISTICS
    ANALYZE INDEX JCR_PK_SVALUE COMPUTE STATISTICS
    ANALYZE INDEX JCR_IDX_SVALUE_PROPERTY COMPUTE STATISTICS
    ANALYZE INDEX JCR_PK_SREF COMPUTE STATISTICS
    ANALYZE INDEX JCR_IDX_SREF_PROPERTY COMPUTE STATISTICS
    ANALYZE INDEX JCR_PK_SCONTAINER COMPUTE STATISTICS

Isolated-database configuration allows to configure single database for repository but separate database tables for each workspace. First step is to configure the data container in the org.exoplatform.services.naming.InitialContextInitializer service. It's the JNDI context initializer, which registers (binds) naming resources (DataSources) for data containers.

For example:

 <external-component-plugins>
    <target-component>org.exoplatform.services.naming.InitialContextInitializer</target-component>
    <component-plugin>
      <name>bind.datasource</name>
      <set-method>addPlugin</set-method>
      <type>org.exoplatform.services.naming.BindReferencePlugin</type>
      <init-params>
        <value-param>
          <name>bind-name</name>
          <value>jdbcjcr</value>
        </value-param>
        <value-param>
          <name>class-name</name>
          <value>javax.sql.DataSource</value>
        </value-param>
        <value-param>
          <name>factory</name>
          <value>org.apache.commons.dbcp.BasicDataSourceFactory</value>
        </value-param>
          <properties-param>
            <name>ref-addresses</name>
            <description>ref-addresses</description>
            <property name="driverClassName" value="org.postgresql.Driver"/>
            <property name="url" value="jdbc:postgresql://exoua.dnsalias.net/portal"/>
            <property name="username" value="exoadmin"/>
            <property name="password" value="exo12321"/>
          </properties-param>
      </init-params>
    </component-plugin>
  </external-component-plugins>

We configure the database connection parameters:

When the data container configuration is done, we can configure the repository service. Each workspace will be configured for the same data container.

For example:

<workspaces>
   <workspace name="ws">
      <!-- for system storage -->
      <container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer">
         <properties>
            <property name="source-name" value="jdbcjcr" />
            <property name="db-structure-type" value="isolated" />
            ...
         </properties>
         ...
      </container>
      ...
   </workspace>

   <workspace name="ws1">
      <container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer">
         <properties>
            <property name="source-name" value="jdbcjcr" />
            <property name="db-structure-type" value="isolated" />
            ...
         </properties>
         ...
      </container>
      ...
   </workspace>
</workspaces>

In this way, we have configured two workspace which will be persisted in different database tables.

Note

Starting from v.1.9 repository configuration parameters supports human-readable formats of values (e.g. 200K - 200 Kbytes, 30m - 30 minutes etc)

You need to configure each workspace in a repository. You may have each one on different remote servers as far as you need.

First of all configure the data containers in the org.exoplatform.services.naming.InitialContextInitializer service. It's the JNDI context initializer which registers (binds) naming resources (DataSources) for data containers.

For example:

<component>
   <key>org.exoplatform.services.naming.InitialContextInitializer</key>
   <type>org.exoplatform.services.naming.InitialContextInitializer</type>
   <component-plugins>
      <component-plugin>
         <name>bind.datasource</name>
         <set-method>addPlugin</set-method>
         <type>org.exoplatform.services.naming.BindReferencePlugin</type>
         <init-params>
            <value-param>
               <name>bind-name</name>
               <value>jdbcjcr</value>
            </value-param>
            <value-param>
               <name>class-name</name>
               <value>javax.sql.DataSource</value>
            </value-param>
            <value-param>
               <name>factory</name>
               <value>org.apache.commons.dbcp.BasicDataSourceFactory</value>
            </value-param>
            <properties-param>
               <name>ref-addresses</name>
               <description>ref-addresses</description>
               <property name="driverClassName" value="org.hsqldb.jdbcDriver"/>
               <property name="url" value="jdbc:hsqldb:file:target/temp/data/portal"/>
               <property name="username" value="sa"/>
               <property name="password" value=""/>
            </properties-param>
         </init-params>
      </component-plugin>
      <component-plugin>
         <name>bind.datasource</name>
         <set-method>addPlugin</set-method>
         <type>org.exoplatform.services.naming.BindReferencePlugin</type>
         <init-params>
            <value-param>
               <name>bind-name</name>
               <value>jdbcjcr1</value>
            </value-param>
            <value-param>
               <name>class-name</name>
               <value>javax.sql.DataSource</value>
            </value-param>
            <value-param>
               <name>factory</name>
               <value>org.apache.commons.dbcp.BasicDataSourceFactory</value>
            </value-param>
            <properties-param>
               <name>ref-addresses</name>
               <description>ref-addresses</description>
               <property name="driverClassName" value="com.mysql.jdbc.Driver"/>
               <property name="url" value="jdbc:mysql://exoua.dnsalias.net/jcr"/>
               <property name="username" value="exoadmin"/>
               <property name="password" value="exo12321"/>
               <property name="maxActive" value="50"/>
               <property name="maxIdle" value="5"/>
               <property name="initialSize" value="5"/>
            </properties-param>
         </init-params>
      </component-plugin>
   <component-plugins>
</component>
                    

When the data container configuration is done, we can configure the repository service. Each workspace will be configured for its own data container.

For example:

<workspaces>
   <workspace name="ws">
      <container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer">
         <properties>
            <property name="source-name" value="jdbcjcr"/>
            <property name="db-structure-type" value="multi"/>
            ...
         </properties>
      </container>
      ...
   </workspace>

   <workspace name="ws1">
      <container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer">
         <properties>
            <property name="source-name" value="jdbcjcr1"/>
            <property name="db-structure-type" value="multi"/>
            ...
         </properties>
      </container>
      ...
   </workspace>
</workspaces>                                     

In this way, we have configured two workspace which will be persisted in two different databases (ws in HSQLDB, ws1 in MySQL).

It's simplier to configure a single-database data container. We have to configure one naming resource.

For example:

<external-component-plugins>
    <target-component>org.exoplatform.services.naming.InitialContextInitializer</target-component>
    <component-plugin>
        <name>bind.datasource</name>
        <set-method>addPlugin</set-method>
        <type>org.exoplatform.services.naming.BindReferencePlugin</type>
        <init-params>
          <value-param>
            <name>bind-name</name>
            <value>jdbcjcr</value>
          </value-param>
          <value-param>
            <name>class-name</name>
            <value>javax.sql.DataSource</value>
          </value-param>
          <value-param>
            <name>factory</name>
            <value>org.apache.commons.dbcp.BasicDataSourceFactory</value>
          </value-param>
          <properties-param>
            <name>ref-addresses</name>
            <description>ref-addresses</description>
            <property name="driverClassName" value="org.postgresql.Driver"/>
            <property name="url" value="jdbc:postgresql://exoua.dnsalias.net/portal"/>
            <property name="username" value="exoadmin"/>
            <property name="password" value="exo12321"/>
            <property name="maxActive" value="50"/>
            <property name="maxIdle" value="5"/>
            <property name="initialSize" value="5"/>
          </properties-param>
        </init-params>
    </component-plugin>
  </external-component-plugins>
  

And configure repository workspaces in repositories configuration with this one database.

For example:

<workspaces>
  <workspace name="ws">
    <container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer">
      <properties>
        <property name="source-name" value="jdbcjcr"/>
        <property name="db-structure-type" value="single" />
        ...
      </properties>
    </container>
    ...
  </workspace>

  <workspace name="ws1">
    <container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer">
    <properties>
      <property name="source-name" value="jdbcjcr"/>
      <property name="db-structure-type" value="single" />
      ...
    </properties>
    ...
  </workspace>
</workspaces>

In this way, we have configured two workspaces which will be persisted in one database (PostgreSQL).

The current configuration of eXo JCR uses Apache DBCP connection pool (org.apache.commons.dbcp.BasicDataSourceFactory). It's possible to set a big value for maxActive parameter in configuration.xml. That means usage of lots of TCP/IP ports from a client machine inside the pool (i.e. JDBC driver). As a result, the data container can throw exceptions like "Address already in use". To solve this problem, you have to configure the client's machine networking software for the usage of shorter timeouts for opened TCP/IP ports.

Microsoft Windows has MaxUserPort, TcpTimedWaitDelay registry keys in the node HKEY_LOCAL_MACHINESYSTEMCurrentControlSetServicesTcpipParameters, by default these keys are unset, set each one with values like these:

  • "TcpTimedWaitDelay"=dword:0000001e, sets TIME_WAIT parameter to 30 seconds, default is 240.

  • "MaxUserPort"=dword:00001b58, sets the maximum of open ports to 7000 or higher, default is 5000.

A sample registry file is below:

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters]
"MaxUserPort"=dword:00001b58
"TcpTimedWaitDelay"=dword:0000001e

By default JCR Values are stored in the Workspace Data container along with the JCR structure (i.e. Nodes and Properties). eXo JCR offers an additional option of storing JCR Values separately from Workspace Data container, which can be extremely helpful to keep Binary Large Objects (BLOBs) for example.

Value storage configuration is a part of Repository configuration, find more details there.

Tree-based storage is recommended for most of cases. If you run an application on Amazon EC2 - the S3 option may be interesting for architecture. Simple 'flat' storage is good in speed of creation/deletion of values, it might be a compromise for a small storages.

Holds Values in tree-like FileSystem files. path property points to the root directory to store the files.

This is a recommended type of external storage, it can contain large amount of files limited only by disk/volume free space.

A disadvantage is that it's a higher time on Value deletion due to unused tree-nodes remove.

<value-storage id="Storage #1" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage">
     <properties>
       <property name="path" value="data/values"/>
     </properties>
     <filters>
       <filter property-type="Binary" min-value-size="1M"/>
     </filters>

Where :

id: The value storage unique identifier, used for linking with properties stored in workspace container.
path: A location where value files will be stored.

Each file value storage can have the filter(s) for incoming values. A filter can match values by property type (property-type), property name (property-name), ancestor path (ancestor-path) and/or size of values stored (min-value-size, in bytes). In code sample, we use a filter with property-type and min-value-size only. I.e. storage for binary values with size greater of 1MB. It's recommended to store properties with large values in file value storage only.

Another example shows a value storage with different locations for large files (min-value-size a 20Mb-sized filter). A value storage uses ORed logic in the process of filter selection. That means the first filter in the list will be asked first and if not matched the next will be called etc. Here a value matches the 20 MB-sized filter min-value-size and will be stored in the path "data/20Mvalues", all other in "data/values".

<value-storages>
  <value-storage id="Storage #1" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage">
    <properties>
      <property name="path" value="data/20Mvalues"/>
    </properties>
    <filters>
      <filter property-type="Binary" min-value-size="20M"/>
    </filters>
  <value-storage>
  <value-storage id="Storage #2" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage">
    <properties>
      <property name="path" value="data/values"/>
    </properties>
    <filters>
      <filter property-type="Binary" min-value-size="1M"/>
    </filters>
  <value-storage>
<value-storages>

eXo JCR supports Content-addressable storage feature for Values storing.

Content Addressable Value storage stores unique content once. Different properties (values) with same content will be stored as one data file shared between those values. We can tell the Value content will be shared across some Values in storage and will be stored on one physical file.

Storage size will be decreased for application which governs potentially same data in the content.

If property Value changes, it is stored in an additional file. Alternatively the file is shared with other values, pointing to the same content.

The storage calculates Value content address each time the property was changed. CAS write operations are much more expensive compared to the non-CAS storages.

Content address calculation based on java.security.MessageDigest hash computation and tested with MD5 and SHA1 algorithms.

CAS support can be enabled for Tree and Simple File Value Storage types.

To enable CAS support, just configure it in JCR Repositories configuration as we do for other Value Storages.

<workspaces>
        <workspace name="ws">
          <container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer">
            <properties>
              <property name="source-name" value="jdbcjcr"/>
              <property name="dialect" value="oracle"/>
              <property name="multi-db" value="false"/>
              <property name="max-buffer-size" value="200k"/>
              <property name="swap-directory" value="target/temp/swap/ws"/>
            </properties>
            <value-storages>
<!------------------- here ----------------------->
              <value-storage id="ws" class="org.exoplatform.services.jcr.impl.storage.value.fs.CASableTreeFileValueStorage">
                <properties>
                  <property name="path" value="target/temp/values/ws"/>
                  <property name="digest-algo" value="MD5"/>
                  <property name="vcas-type" value="org.exoplatform.services.jcr.impl.storage.value.cas.JDBCValueContentAddressStorageImpl"/>
                  <property name="jdbc-source-name" value="jdbcjcr"/>
                  <property name="jdbc-dialect" value="oracle"/>
                </properties>
                <filters>
                  <filter property-type="Binary"/>
                </filters>
              </value-storage>
            </value-storages>

Properties:

digest-algo: Digest hash algorithm (MD5 and SHA1 were tested);
vcas-type: Value CAS internal data type, JDBC backed is currently implemented org.exoplatform.services.jcr.impl.storage.value.cas.JDBCValueContentAddressStorageImp;l
jdbc-source-name: JDBCValueContentAddressStorageImpl specific parameter, database will be used to save CAS metadata. It's simple to use same as in workspace container;
jdbc-dialect: JDBCValueContentAddressStorageImpl specific parameter, database dialect. It's simple to use the same as in workspace container;

Each Workspace of JCR has its own persistent storage to hold workspace's items data. eXo Content Repository can be configured so that it can use one or more workspaces that are logical units of the repository content. Physical data storage mechanism is configured using mandatory element container. The type of container is described in the attribute class = fully qualified name of org.exoplatform.services.jcr.storage.WorkspaceDataContainer subclass like

<container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer">
  <properties>
    <property name="source-name" value="jdbcjcr1"/>
    <property name="dialect" value="hsqldb"/>
    <property name="multi-db" value="true"/>
    <property name="max-buffer-size" value="200K"/>
    <property name="swap-directory" value="target/temp/swap/ws"/>
    <property name="lazy-node-iterator-page-size" value="50"/>
    <property name="acl-bloomfilter-false-positive-probability" value="0.1d"/>
    <property name="acl-bloomfilter-elements-number" value="1000000"/>
    <property name="check-sns-new-connection" value="false"/>
    <property name="batch-size" value="1000"/>
  </properties>

Workspace Data Container specific parameters:

eXo JCR has an RDB (JDBC) based, production ready Workspace Data Container.

JDBC Workspace Data Container specific parameters:

  • source-name: JDBC data source name, registered in JDNI by InitialContextInitializer. ( sourceName prior v.1.9). This property is mandatory.

  • dialect: Database dialect, one of "hsqldb", "h2", "mysql", "mysql-myisam", "mysql-utf8", "mysql-myisam-utf8", "pgsql", "pgsql-scs", "oracle", "oracle-oci", "mssql", "sybase", "derby", "db2" ,"db2-mys", "db2v8". The default value is "auto".

  • multi-db: Enable multi-database container with this parameter (if "true"). Otherwise (if "false") configured for single-database container. Please, be aware, that this property is currently deprecated. It is advised to use db-structure-type instead.

  • db-structure-type: Can be set to isolated, multi, single to set corresponding configuration for data container. This property is mandatory.

  • db-tablename-suffix: If db-structure-type is set to isolated, tables, used by repository service, have the following format:

    • JCR_I${db-tablename-suffix} - for items

    • JCR_V${db-tablename-suffix} - for values

    • JCR_R${db-tablename-suffix} - for references

      db-tablename-suffix by default equals to workspace name, but can be set via configuration to any suitable.

  • batch-size: the batch size. Default value is -1 (disabled)

Workspace Data Container MAY support external storages for javax.jcr.Value (which can be the case for BLOB values for example) using the optional element value-storages. Data Container will try to read or write Value using underlying value storage plugin if the filter criteria (see below) match the current property.

<value-storages>
  <value-storage id="Storage #1" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage">
    <properties>
      <property name="path" value="data/values"/>
    </properties>
    <filters>
     <filter property-type="Binary" min-value-size="1M"/><!-- Values large of 1Mbyte -->
    </filters>
.........
</value-storages>

Where value-storage is the subclass of org.exoplatform.services.jcr.storage.value.ValueStoragePlugin and properties are optional plugin specific parameters.

filters : Each file value storage can have the filter(s) for incoming values. If there are several filter criteria, they all have to match (AND-Condition).

A filter can match values by property type (property-type), property name (property-name), ancestor path (ancestor-path) and/or the size of values stored (min-value-size, e.g. 1M, 4.2G, 100 (bytes)).

In a code sample, we use a filter with property-type and min-value-size only. That means that the storage is only for binary values whose size is greater than 1Mbyte.

It's recommended to store properties with large values in a file value storage only.

Starting from version 1.9, JCR Service supports REST services creation on Groovy script.

The feature bases on RESTful framework and uses ResourceContainer concept.

Scripts should extend ResourceContainer and should be stored in JCR as a node of type exo:groovyResourceContainer.

Detailed REST services step-by-step implementation check there Create REST service step by step.

Component configuration enables Groovy services loader:

<component>
  <type>org.exoplatform.services.jcr.ext.script.groovy.GroovyScript2RestLoader</type>
  <init-params>
    <object-param>
      <name>observation.config</name>
      <object type="org.exoplatform.services.jcr.ext.script.groovy.GroovyScript2RestLoader$ObservationListenerConfiguration">
        <field name="repository">
          <string>repository</string>
        </field>
        <field name="workspaces">
          <collection type="java.util.ArrayList">
            <value>
              <string>collaboration</string>
            </value>
          </collection>
        </field>
      </object>
    </object-param>
  </init-params>
</component>

To deploy eXo JCR to JBoss, do the following steps:

  1. Download the latest version of eXo JCR .ear file distribution.

  2. Copy <jcr.ear> into <%jboss_home%/server/default/deploy>

  3. Put exo-configuration.xml to the root <%jboss_home%/exo-configuration.xml>

  4. Configure JAAS by inserting XML fragment shown below into <%jboss_home%/server/default/conf/login-config.xml>

    <application-policy name="exo-domain">
       <authentication>
          <login-module code="org.exoplatform.services.security.j2ee.JbossLoginModule" flag="required"></login-module>
       </authentication>
    </application-policy>
  5. Ensure that you use JBossTS Transaction Service and JBossCache Transaction Manager. Your exo-configuration.xml must contain such parts:

    <component>
       <key>org.jboss.cache.transaction.TransactionManagerLookup</key>
       <type>org.jboss.cache.GenericTransactionManagerLookup</type>^
    </component>
    
    <component>
       <key>org.exoplatform.services.transaction.TransactionService</key>
       <type>org.exoplatform.services.transaction.jbosscache.JBossTransactionsService</type>
       <init-params>
          <value-param>
             <name>timeout</name>
             <value>300</value>
          </value-param>
       </init-params>
    </component>
  6. Start server:

    • bin/run.sh for Unix

    • bin/run.bat for Windows

  7. Try accessing http://localhostu:8080/browser with root/exo as login/password if you have done everything right, you'll get access to repository browser.

  • To manually configure repository, create a new configuration file (e.g., exo-jcr-configuration.xml). For details, see JCR Configuration. Your configuration must look like:

    <repository-service default-repository="repository1">
       <repositories>
          <repository name="repository1" system-workspace="ws1" default-workspace="ws1">
             <security-domain>exo-domain</security-domain>
             <access-control>optional</access-control>
             <authentication-policy>org.exoplatform.services.jcr.impl.core.access.JAASAuthenticator</authentication-policy>
             <workspaces>
                <workspace name="ws1">
                   <container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer">
                      <properties>
                         <property name="source-name" value="jdbcjcr" />
                         <property name="dialect" value="oracle" />
                         <property name="multi-db" value="false" />
                         <property name="update-storage" value="false" />
                         <property name="max-buffer-size" value="200k" />
                         <property name="swap-directory" value="../temp/swap/production" />
                      </properties>
                      <value-storages>
                         see "Value storage configuration" part.
                      </value-storages>
                   </container>
                   <initializer class="org.exoplatform.services.jcr.impl.core.ScratchWorkspaceInitializer">
                      <properties>
                         <property name="root-nodetype" value="nt:unstructured" />
                      </properties>
                   </initializer>
                   <cache enabled="true" class="org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.JBossCacheWorkspaceStorageCache">
                         see  "Cache configuration" part.
                   </cache>
                   <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex">
                      see  "Indexer configuration" part.
                   </query-handler>
                   <lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl">
                      see  "Lock Manager configuration" part.
                   </lock-manager>
                </workspace>
                <workspace name="ws2">
                            ...
                </workspace>
                <workspace name="wsN">
                            ...
                </workspace>
             </workspaces>
          </repository>
       </repositories>
    </repository-service> 
  • Then, update RepositoryServiceConfiguration configuration in exo-configuration.xml to use this file:

    <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 configuration file</description>
             <value>exo-jcr-configuration.xml</value>
          </value-param>
       </init-params>
    </component>

Configuration of every workspace in repository must contains of such parts:

This section will show you how to use and configure Jboss Cache in the clustered environment. Also, you will know how to use a template-based configuration offered by eXo JCR for JBoss Cache instances.

JGroups is used by JBoss Cache for network communications and transport in a clustered environment. If property "jgroups-configuration" is defined in component configuration, it will be injected into the JBoss Cache instance on startup.

<property name="jgroups-configuration" value="your/path/to/modified-udp.xml" />

As mentioned above, each component (lock manager, data container and query handler) for each workspace requires its own clustered environment. In other words, they have their own clusters with unique names. By default, each cluster should perform multi-casts on a separate port. This configuration leads to much unnecessary overhead on cluster. That's why JGroups offers multiplexer feature, providing ability to use one single channel for set of clusters. This feature reduces network overheads and increase performance and stability of application. To enable multiplexer stack, you should define appropriate configuration file (upd-mux.xml is pre-shipped one with eXo JCR) and set "jgroups-multiplexer-stack" into "true".

<property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" />
<property name="jgroups-multiplexer-stack" value="true" />

It is now highly recommended to use the shared transport instead of the multiplexer, to do so simply disable the multiplexer stack in the configuration of each component then set the property singleton_name of your JGroups configuration to a unique name.

<property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" />
<property name="jgroups-multiplexer-stack" value="false" />

A JBoss Cache instance is quite resource consuming and by default we will have 3 JBoss Cache instances (one instance for the indexer, one for the lock manager and one for the data container) for each workspace, so if you intend to have a lot of workspaces it could make sense to decide to share one JBoss Cache instance with several cache instances of the same type (i.e. indexer, lock manager or data container). This feature is disabled by default and can be enabled at component configuration level (i.e. indexer configuration, lock manager configuration and/or data container configuration) by setting the property "jbosscache-shareable" to true as below:

<property name="jbosscache-shareable" value="true" />

Once enabled this feature will allow the JBoss Cache instance used by the component to be re-used by another components of the same type (i.e. indexer, lock manager or data container) with the exact same JBoss Cache configuration (except the eviction configuration that cans be different), which means that all the parameters of type ${jbosscache-<parameter name>} must be identical between the components of same type of different workspaces. In other words, if we use the same values for the parameters of type ${jbosscache-<parameter name>} in each workspace, we will have only 3 JBoss Cache instances (one instance for the indexer, one for the lock manager and one for the data container) used whatever the total amount of workspaces defined.

eXo JCR implementation is shipped with ready-to-use JBoss Cache configuration templates for JCR's components. They are situated in application package in /conf/porta/ folder.

It's template name is "jbosscache-lock.xml"

<?xml version="1.0" encoding="UTF-8"?>
<jbosscache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:jboss:jbosscache-core:config:3.1">

   <locking useLockStriping="false" concurrencyLevel="500" lockParentForChildInsertRemove="false"
      lockAcquisitionTimeout="20000" />
   <clustering mode="replication" clusterName="${jbosscache-cluster-name}">
      <stateRetrieval timeout="20000" fetchInMemoryState="false" />
      <sync />
   </clustering>
   <loaders passivation="false" shared="true">
      <preload>
         <node fqn="/" />
      </preload>
      <loader class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.JDBCCacheLoader" async="false" fetchPersistentState="false"
         ignoreModifications="false" purgeOnStartup="false">
         <properties>
            cache.jdbc.table.name=${jbosscache-cl-cache.jdbc.table.name}
            cache.jdbc.table.create=${jbosscache-cl-cache.jdbc.table.create}
            cache.jdbc.table.drop=${jbosscache-cl-cache.jdbc.table.drop}
            cache.jdbc.table.primarykey=${jbosscache-cl-cache.jdbc.table.primarykey}
            cache.jdbc.fqn.column=${jbosscache-cl-cache.jdbc.fqn.column}
            cache.jdbc.fqn.type=${jbosscache-cl-cache.jdbc.fqn.type}
            cache.jdbc.node.column=${jbosscache-cl-cache.jdbc.node.column}
            cache.jdbc.node.type=${jbosscache-cl-cache.jdbc.node.type}
            cache.jdbc.parent.column=${jbosscache-cl-cache.jdbc.parent.column}
            cache.jdbc.datasource=${jbosscache-cl-cache.jdbc.datasource}
         </properties>
      </loader>
   </loaders>
</jbosscache>

What LockManager does?

In general, LockManager stores Lock objects, so it can give a Lock object or can release it.

Also, LockManager is responsible for removing Locks that live too long. This parameter may be configured with "time-out" property.

JCR provides one basic implementations of LockManager:

CacheableLockManagerImpl stores Lock objects in JBoss-cache, so Locks are replicable and affect on cluster, not only a single node. Also, JBoss-cache has JDBCCacheLoader, so Locks will be stored to the database.

You can enable LockManager by adding lock-manager-configuration to workspace-configuration.

For example:

<workspace name="ws">
   ...
   <lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl">
      <properties>
         <property name="time-out" value="15m" />
         ...
      </properties>
   </lock-manager>               
   ...
</workspace>

Wher time-out parameter represents interval to remove Expired Locks. LockRemover separates threads, that periodically ask LockManager to remove Locks that live so long.

The configuration uses the template JBoss-cache configuration for all LockManagers.

Lock template configuration

test-jbosscache-lock.xml

<?xml version="1.0" encoding="UTF-8"?>
<jbosscache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:jboss:jbosscache-core:config:3.1">

   <locking useLockStriping="false" concurrencyLevel="500" lockParentForChildInsertRemove="false"
      lockAcquisitionTimeout="20000" />

   <clustering mode="replication" clusterName="${jbosscache-cluster-name}">
      <stateRetrieval timeout="20000" fetchInMemoryState="false" />
      <sync />
   </clustering>

   <loaders passivation="false" shared="true">
      <!-- All the data of the JCR locks needs to be loaded at startup -->
      <preload>
         <node fqn="/" />
      </preload>  
      <!--
      For another cache-loader class you should use another template with
      cache-loader specific parameters
      ->
      <loader class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.JDBCCacheLoader" async="false" fetchPersistentState="false"
         ignoreModifications="false" purgeOnStartup="false">
         <properties>
            cache.jdbc.table.name=${jbosscache-cl-cache.jdbc.table.name}
            cache.jdbc.table.create=${jbosscache-cl-cache.jdbc.table.create}
            cache.jdbc.table.drop=${jbosscache-cl-cache.jdbc.table.drop}
            cache.jdbc.table.primarykey=${jbosscache-cl-cache.jdbc.table.primarykey}
            cache.jdbc.fqn.column=${jbosscache-cl-cache.jdbc.fqn.column}
            cache.jdbc.fqn.type=${jbosscache-cl-cache.jdbc.fqn.type}
            cache.jdbc.node.column=${jbosscache-cl-cache.jdbc.node.column}
            cache.jdbc.node.type=${jbosscache-cl-cache.jdbc.node.type}
            cache.jdbc.parent.column=${jbosscache-cl-cache.jdbc.parent.column}
            cache.jdbc.datasource=${jbosscache-cl-cache.jdbc.datasource}
         </properties>
      </loader>
   </loaders>
</jbosscache>

As you see, all configurable parameters are filled by templates and will be replaced by LockManagers configuration parameters:

<lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl">
   <properties>
      <property name="time-out" value="15m" />
      <property name="jbosscache-configuration" value="test-jbosscache-lock.xml" />
      <property name="jgroups-configuration" value="udp-mux.xml" />
      <property name="jgroups-multiplexer-stack" value="true" />
      <property name="jbosscache-cluster-name" value="JCR-cluster-locks-ws" />
      <property name="jbosscache-cl-cache.jdbc.table.name" value="jcrlocks_ws" />
      <property name="jbosscache-cl-cache.jdbc.table.create" value="true" />
      <property name="jbosscache-cl-cache.jdbc.table.drop" value="false" />
      <property name="jbosscache-cl-cache.jdbc.table.primarykey" value="jcrlocks_ws_pk" />
      <property name="jbosscache-cl-cache.jdbc.fqn.column" value="fqn" />
      <property name="jbosscache-cl-cache.jdbc.fqn.type" value="AUTO"/>
      <property name="jbosscache-cl-cache.jdbc.node.column" value="node" />
      <property name="jbosscache-cl-cache.jdbc.node.type" value="AUTO"/>
      <property name="jbosscache-cl-cache.jdbc.parent.column" value="parent" />
      <property name="jbosscache-cl-cache.jdbc.datasource" value="jdbcjcr" />
      <property name="jbosscache-shareable" value="true" />
   </properties>
</lock-manager>

Configuration requirements:

our udp-mux.xml

<config>
    <UDP
         singleton_name="JCR-cluster" 
         mcast_addr="${jgroups.udp.mcast_addr:228.10.10.10}"
         mcast_port="${jgroups.udp.mcast_port:45588}"
         tos="8" 
         ucast_recv_buf_size="20000000"
         ucast_send_buf_size="640000" 
         mcast_recv_buf_size="25000000" 
         mcast_send_buf_size="640000" 
         loopback="false"
         discard_incompatible_packets="true" 
         max_bundle_size="64000" 
         max_bundle_timeout="30"
         use_incoming_packet_handler="true" 
         ip_ttl="${jgroups.udp.ip_ttl:2}"
         enable_bundling="false" 
         enable_diagnostics="true"
         thread_naming_pattern="cl" 

         use_concurrent_stack="true" 

         thread_pool.enabled="true" 
         thread_pool.min_threads="2"
         thread_pool.max_threads="8" 
         thread_pool.keep_alive_time="5000" 
         thread_pool.queue_enabled="true"
         thread_pool.queue_max_size="1000"
         thread_pool.rejection_policy="discard"

         oob_thread_pool.enabled="true"
         oob_thread_pool.min_threads="1"
         oob_thread_pool.max_threads="8"
         oob_thread_pool.keep_alive_time="5000"
         oob_thread_pool.queue_enabled="false" 
         oob_thread_pool.queue_max_size="100" 
         oob_thread_pool.rejection_policy="Run" />

    <PING timeout="2000"
            num_initial_members="3"/>
    <MERGE2 max_interval="30000"
            min_interval="10000"/>
   <FD_SOCK />
   <FD timeout="10000" max_tries="5" shun="true" />
   <VERIFY_SUSPECT timeout="1500" />
   <BARRIER />
    <pbcast.NAKACK use_stats_for_retransmission="false"
                   exponential_backoff="150"
                   use_mcast_xmit="true" gc_lag="0"
                   retransmit_timeout="50,300,600,1200"
                   discard_delivered_msgs="true"/>
   <UNICAST timeout="300,600,1200" />
    <pbcast.STABLE stability_delay="1000" desired_avg_gossip="50000"
                   max_bytes="1000000"/>
   <VIEW_SYNC avg_send_interval="60000" />
    <pbcast.GMS print_local_addr="true" join_timeout="3000"
                shun="false"
                view_bundling="true"/>
    <FC max_credits="500000"
                    min_threshold="0.20"/>
   <FRAG2 frag_size="60000" />
   <!--pbcast.STREAMING_STATE_TRANSFER /-->
   <pbcast.STATE_TRANSFER />
   <pbcast.FLUSH />
</config>

This section shows you how to configure QueryHandler: Indexing in clustered environment.

JCR offers multiple indexing strategies. They include both for standalone and clustered environments using the advantages of running in a single JVM or doing the best to use all resources available in cluster. JCR uses Lucene library as underlying search and indexing engine, but it has several limitations that greatly reduce possibilities and limits the usage of cluster advantages. That's why eXo JCR offers three strategies that are suitable for it's own usecases. They are standalone, clustered with shared index, clustered with local indexes and RSync-based. Each one has it's pros and cons.

Stanadlone strategy provides a stack of indexes to achieve greater performance within single JVM.

It combines in-memory buffer index directory with delayed file-system flushing. This index is called "Volatile" and it is invoked in searches also. Within some conditions volatile index is flushed to the persistent storage (file system) as new index directory. This allows to achieve great results for write operations.

Clustered implementation with local indexes is built upon same strategy with volatile in-memory index buffer along with delayed flushing on persistent storage.

As this implementation designed for clustered environment it has additional mechanisms for data delivery within cluster. Actual text extraction jobs done on the same node that does content operations (i.e. write operation). Prepared "documents" (Lucene term that means block of data ready for indexing) are replicated withing cluster nodes and processed by local indexes. So each cluster instance has the same index content. When new node joins the cluster it has no initial index, so it must be created. There are some supported ways of doing this operation. The simplest is to simply copy the index manually but this is not intended for use. If no initial index found JCR uses automated sceneries. They are controlled via configuration (see "index-recovery-mode" parameter) offering full re-indexing from database or copying from another cluster node.

For some reasons having a multiple index copies on each instance can be costly. So shared index can be used instead (see diagram below).

This indexing strategy combines advantages of in-memory index along with shared persistent index offering "near" real time search capabilities. This means that newly added content is accessible via search practically immediately. This strategy allows nodes to index data in their own volatile (in-memory) indexes, but persistent indexes are managed by single "coordinator" node only. Each cluster instance has a read access for shared index to perform queries combining search results found in own in-memory index also. Take in account that shared folder must be configured in your system environment (i.e. mounted NFS folder). But this strategy in some extremely rare cases can have a bit different volatile indexes within cluster instances for a while. In a few seconds they will be up2date.

Shared index is consistent and stable enough, but slow, while local index is fast, but requires much time for re-synchronization, when cluster node is leaving a cluster for a small period of time. RSync-based index solves this problem along with local file system advantages in term of speed.

This strategy is the same shared index, but stores actual data on local file system, instead of shared. Eventually triggering a synchronization job, that woks on the level of file blocks, synchronizing only modified data. Diagram shows it in action. Only single node in the cluster is responsible for modifying index files, this is the Coordinator node. When data persisted, corresponding command fired, starting synchronization jobs all over the cluster.

See more about Search Configuration.

Configuration example:

<workspace name="ws">
   <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex">
      <properties>
         <property name="index-dir" value="shareddir/index/db1/ws" />
         <property name="changesfilter-class"
            value="org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter" />
         <property name="jbosscache-configuration" value="jbosscache-indexer.xml" />
         <property name="jgroups-configuration" value="udp-mux.xml" />
         <property name="jgroups-multiplexer-stack" value="true" />
         <property name="jbosscache-cluster-name" value="JCR-cluster-indexer-ws" />
         <property name="max-volatile-time" value="60" />
         <property name="rdbms-reindexing" value="true" />
         <property name="reindexing-page-size" value="1000" />
         <property name="index-recovery-mode" value="from-coordinator" />
         <property name="index-recovery-filter" value="org.exoplatform.services.jcr.impl.core.query.lucene.DocNumberRecoveryFilter" />
         <property name="indexing-thread-pool-size" value="16" />
      </properties>
   </query-handler>
</workspace>

Table 1.9. Config properties description

Property nameDescription
index-dirpath to index
changesfilter-classThe FQN of the class to use to indicate the policy to use to manage the lucene indexes changes. This class must extend org.exoplatform.services.jcr.impl.core.query.IndexerChangesFilter. This must be set in cluster environment to define the clustering strategy to adopt. To use the Shared Indexes Strategy, you can set it to org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter. I you prefer the Local Indexes Strategy, you can set it to org.exoplatform.services.jcr.impl.core.query.jbosscache.LocalIndexChangesFilter.
jbosscache-configurationtemplate of JBoss-cache configuration for all query-handlers in repository (search, cache, locks)
jgroups-configurationThis is the path to JGroups configuration that should not be anymore jgroups' stack definitions but a normal jgroups configuration format with the shared transport configured by simply setting the jgroups property singleton_name to a unique name (it must remain unique from one portal container to another). This file is also pre-bundled with templates and is recommended for use.
jgroups-multiplexer-stackif set to true, it will indicate that the file corresponding to the parameter jgroups-configuration is a actually a file defining a set of jgroups multiplexer stacks. In the XML tag jgroupsConfig within the jboss cache configuration, you will then be able to set the name of the multiplexer stack to use thanks to the attribute multiplexerStack. Please note that the jgroups multiplexer has been deprecated by the jgroups Team and has been replaced by the shared transport so it is highly recommended to not use it anymore.
jbosscache-cluster-namecluster name (must be unique)
max-volatile-timemax time to live for Volatile Index
rdbms-reindexingIndicates whether the rdbms re-indexing mechanism must be used, the default value is true.
reindexing-page-sizemaximum amount of nodes which can be retrieved from storage for re-indexing purpose, the default value is 100
index-recovery-modeIf the parameter has been set to from-indexing, so a full indexing will be automatically launched, if the parameter has been set to from-coordinator (default behavior), the index will be retrieved from coordinator
index-recovery-filterDefines implementation class or classes of RecoveryFilters, the mechanism of index synchronization for Local Index strategy.
async-reindexingControls the process of re-indexing on JCR's startup. If flag set, indexing will be launched asynchronously, without blocking the JCR. Default is "false".
indexing-thread-pool-sizeDefines the total amount of indexing threads.
max-volatile-sizeThe maximum volatile index size in bytes until it is written to disk. The default value is 1048576 (1MB).

Note

If you use postgreSQL and the parameter rdbms-reindexing is set to true, the performances of the queries used while indexing can be improved by setting the parameter "enable_seqscan" to "off" or "default_statistics_target" to at least "50" in the configuration of your database. Then you need to restart DB server and make analyze of the JCR_SVALUE (or JCR_MVALUE) table.

Note

If you use DB2 and the parameter rdbms-reindexing is set to true, the performance of the queiries used while indexing can be improved by making statisticks on tables by running "RUNSTATS ON TABLE <scheme>.<table> WITH DISTRIBUTION AND INDEXES ALL" for JCR_SITEM (or JCR_MITEM) and JCR_SVALUE (or JCR_MVALUE) tables.

Configuration has much in common with Shared Index, it just requires some additional parameters for RSync options. If they are present, JCR switches from shared to RSync-based index. Here is an example configuration:

<query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex">
   <properties>
      <property name="index-dir" value="/var/data/index/repository1/production" />
      <property name="changesfilter-class"
         value="org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter" />
      <property name="jbosscache-configuration" value="jar:/conf/portal/cluster/jbosscache-indexer.xml" />
      <property name="jgroups-configuration" value="jar:/conf/portal/cluster/udp-mux.xml" />
      <property name="jgroups-multiplexer-stack" value="false" />
      <property name="jbosscache-cluster-name" value="JCR-cluster-indexer" />
      <property name="jbosscache-shareable" value="true" />
      <property name="max-volatile-time" value="60" /> 
      <property name="rsync-entry-name" value="index" />
      <property name="rsync-entry-path" value="/var/data/index" />
      <property name="rsync-port" value="8085" />
      <property name="rsync-user" value="rsyncexo" />
      <property name="rsync-password" value="exo" />
   </properties>
</query-handler>

Let's start with authentication: "rsync-user" and "rsync-password". They are optional and can be skipped if RSync Server configured to accept anonymous identity. Before reviewing other RSync index options need to have a look at RSync Server configuration. Sample RSync Server (rsyncd) Configuration

uid = nobody
gid = nobody
use chroot = no
port = 8085
log file = rsyncd.log
pid file = rsyncd.pid
[index]
        path = /var/data/index
        comment = indexes
        read only = true
        auth users = rsyncexo
        secrets file= rsyncd.secrets

This sample configuration shares folder "/var/data/index" as an entry "index". Those parameters should match corresponding properties in JCR configuration. Respectively "rsync-entry-name", "rsync-entry-path", "rsync-port" properties. Notice! Make sure "index-dir" is a descendant folder of RSync shared folder and those paths are the same on each cluster node.

In order to use cluster-ready strategy based on local indexes, when each node has own copy of index on local file system, the following configuration must be applied. Indexing directory must point to any folder on local file system and "changesfilter-class" must be set to "org.exoplatform.services.jcr.impl.core.query.jbosscache.LocalIndexChangesFilter".

<query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex">
   <properties>
      <property name="index-dir" value="/mnt/nfs_drive/index/db1/ws" />
      <property name="changesfilter-class"
         value="org.exoplatform.services.jcr.impl.core.query.jbosscache.LocalIndexChangesFilter" />
      <property name="jbosscache-configuration" value="jbosscache-indexer.xml" />
      <property name="jgroups-configuration" value="udp-mux.xml" />
      <property name="jgroups-multiplexer-stack" value="true" />
      <property name="jbosscache-cluster-name" value="JCR-cluster-indexer-ws" />
      <property name="max-volatile-time" value="60" />
      <property name="rdbms-reindexing" value="true" />
      <property name="reindexing-page-size" value="1000" />
      <property name="index-recovery-mode" value="from-coordinator" />
   </properties>
</query-handler>

Common usecase for all cluster-ready applications is a hot joining and leaving of processing units. Node that is joining cluster for the first time or node joining after some downtime, they all must be in a synchronized state. When having a deal with shared value storages, databases and indexes, cluster nodes are synchronized anytime. But it's an issue when local index strategy used. If new node joins cluster, having no index it is retrieved or recreated. Node can be restarted also and thus index not empty. By default existing index is thought to be actual, but can be outdated. JCR offers a mechanism called RecoveryFilters that will automatically retrieve index for the joining node on startup. This feature is a set of filters that can be defined via QueryHandler configuration:

<property name="index-recovery-filter" value="org.exoplatform.services.jcr.impl.core.query.lucene.DocNumberRecoveryFilter" />

Filter number is not limited so they can be combined:

<property name="index-recovery-filter" value="org.exoplatform.services.jcr.impl.core.query.lucene.DocNumberRecoveryFilter" />
<property name="index-recovery-filter" value="org.exoplatform.services.jcr.impl.core.query.lucene.SystemPropertyRecoveryFilter" />

If any one fires, the index is re-synchronized. Please take in account, that DocNumberRecoveryFilter is used in cases when no filter configured. So, if resynchronization should be blocked, or strictly required on start, then ConfigurationPropertyRecoveryFilter can be used.

This feature uses standard index recovery mode defined by previously described parameter (can be "from-indexing" or "from-coordinator" (default value))

<property name="index-recovery-mode" value="from-coordinator" />

There are couple implementations of filters:

Managing a big set of data using JCR in production environment sometimes requires special operations with Indexes, stored on File System. One of those maintenance operations is a recreation of it. Also called "re-indexing". There are various usecases when it's important to do. They include hardware faults, hard restarts, data-corruption, migrations and JCR updates that brings new features related to index. Usually index re-creation requested on server's startup or in runtime.

Common usecase for updating and re-creating the index is to stop the server and manually remove indexes for workspaces requiring it. When server will be started, missing indexes are automatically recovered by re-indexing. JCR Supports direct RDBMS re-indexing, that usually is faster than ordinary and can be configured via QueryHandler parameter "rdbms-reindexing" set to "true" (for more information please refer to "Query-handler configuration overview"). New feature to introduce is asynchronous indexing on startup. Usually startup is blocked until process is finished. Block can take any period of time, depending on amount of data persisted in repositories. But this can be resolved by using an asynchronous approaches of startup indexation. Saying briefly, it performs all operations with index in background, without blocking the repository. This is controlled by the value of "async-reindexing" parameter in QueryHandler configuration. With asynchronous indexation active, JCR starts with no active indexes present. Queries on JCR still can be executed without exceptions, but no results will be returned until index creation completed. Checking index state is possible via QueryManagerImpl:

boolean online = ((QueryManagerImpl)Workspace.getQueryManager()).getQueryHandeler().isOnline();

"OFFLINE" state means that index is currently re-creating. When state changed, corresponding log event is printed. From the start of background task index is switched to "OFFLINE", with following log event :

[INFO] Setting index OFFLINE (repository/production[system]).

When process finished, two events are logged :

[INFO] Created initial index for 143018 nodes (repository/production[system]).
[INFO] Setting index ONLINE (repository/production[system]).

Those two log lines indicates the end of process for workspace given in brackets. Calling isOnline() as mentioned above, will also return true.

Some hard system faults, error during upgrades, migration issues and some other factors may corrupt the index. Most likely end customers would like the production systems to fix index issues in run-time, without delays and restarts. Current versions of JCR supports "Hot Asynchronous Workspace Reindexing" feature. It allows end-user (Service Administrator) to launch the process in background without stopping or blocking whole application by using any JMX-compatible console (see screenshot below, "JConsole in action").

Server can continue working as expected while index is recreated. This depends on the flag "allow queries", passed via JMX interface to reindex operation invocation. If the flag set, then application continues working. But there is one critical limitation the end-users must be aware. Index is frozen while background task is running. It meant that queries are performed on index present on the moment of task startup and data written into repository after startup won't be available through the search until process finished. Data added during re-indexation is also indexed, but will be available only when task is done. Briefly, JCR makes the snapshot of indexes on asynch task startup and uses it for searches. When operation finished, stale indexes replaced by newly created including newly added data. If flag "allow queries" is set to false, then all queries will throw an exception while task is running. Current state can be acquired using the following JMX operation:

eXo JCR can rely on distributed cache such as Infinispan. This article describes the required configuration.

Each mentioned below components uses instances of Infinispan Cache product for caching in clustered environment. So every element has it's own transport and has to be configured in a proper way. As usual, workspaces have similar configuration. The simplest way to configure them is to define their own configuration files for each component in each workspace. There are several commons parameters.

"infinispan-configuration" defines path to template based configuration for Infinispan Cache instance.

JGroups is used by Infinispan Cache for network communications and transport in a clustered environment. If property "jgroups-configuration" is defined in component configuration, it will be injected into the Infinispan Cache instance on startup.

The another parameter is "infinispan-cluster-name". This defines the name of the cluster. Needs to be the same for all nodes in a cluster in order to find each other.

eXo JCR implementation is shipped with ready-to-use Infinispan Cache configuration templates for JCR's components.

Data container template is "infinispan-data.xml":

<infinispan 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance". 
      xsi:schemaLocation="urn:infinispan:config:5.1 http://www.infinispan.org/schemas/infinispan-config-5.1.xsd". 
      xmlns="urn:infinispan:config:5.1">

    <global>
      <evictionScheduledExecutor factory="org.infinispan.executors.DefaultScheduledExecutorFactory">
        <properties>
          <property name="threadNamePrefix" value="EvictionThread"/>
        </properties>
      </evictionScheduledExecutor>

      <globalJmxStatistics jmxDomain="exo" enabled="true" allowDuplicateDomains="true"/>

      <transport transportClass="org.infinispan.remoting.transport.jgroups.JGroupsTransport" clusterName="${infinispan-cluster-name}" distributedSyncTimeout=
        <properties>
          <property name="configurationFile" value="${jgroups-configuration}"/>
        </properties>
      </transport>
    </global>

    <default>
      <clustering mode="replication">
        <stateTransfer timeout="20000" fetchInMemoryState="false" />
        <sync replTimeout="20000"/>
      </clustering>

      <locking isolationLevel="READ_COMMITTED" lockAcquisitionTimeout="20000" writeSkewCheck="false" concurrencyLevel="500" useLockStriping="true"/>
      <transaction transactionManagerLookupClass="org.exoplatform.services.transaction.infinispan.JBossStandaloneJTAManagerLookup" syncRollbackPhase="true" s
      <jmxStatistics enabled="true"/>
      <eviction strategy="LRU" threadPolicy="DEFAULT" maxEntries="1000000"/>
      <expiration wakeUpInterval="5000"/>
   </default>
</infinispan>

Its template name is "infinispan-lock.xml"

<infinispan 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance". 
      xsi:schemaLocation="urn:infinispan:config:5.1 http://www.infinispan.org/schemas/infinispan-config-5.1.xsd". 
      xmlns="urn:infinispan:config:5.1">

    <global>
      <evictionScheduledExecutor factory="org.infinispan.executors.DefaultScheduledExecutorFactory">
        <properties>
          <property name="threadNamePrefix" value="EvictionThread"/>
        </properties>
      </evictionScheduledExecutor>

      <globalJmxStatistics jmxDomain="exo" enabled="true" allowDuplicateDomains="true"/>

      <transport transportClass="org.infinispan.remoting.transport.jgroups.JGroupsTransport" clusterName="${infinispan-cluster-name}" distributedSyncTimeout=
        <properties>
          <property name="configurationFile" value="${jgroups-configuration}"/>
        </properties>
      </transport>
    </global>

    <default>
      <clustering mode="replication">
        <stateTransfer timeout="20000" fetchInMemoryState="false" />
        <sync replTimeout="20000"/>
      </clustering>

      <locking isolationLevel="READ_COMMITTED" lockAcquisitionTimeout="20000" writeSkewCheck="false" concurrencyLevel="500" useLockStriping="false"/>
      <transaction transactionManagerLookupClass="org.exoplatform.services.transaction.infinispan.JBossStandaloneJTAManagerLookup" syncRollbackPhase="true" s
      <jmxStatistics enabled="true"/>
      <eviction strategy="NONE"/>

      <loaders passivation="false" shared="true" preload="true">
        <loader class="org.infinispan.loaders.jdbc.stringbased.JdbcStringBasedCacheStore" fetchPersistentState="true" ignoreModifications="false" purgeOnStar
          <properties>
             <property name="stringsTableNamePrefix" value="${infinispan-cl-cache.jdbc.table.name}"/>
             <property name="idColumnName" value="${infinispan-cl-cache.jdbc.id.column}"/>
             <property name="dataColumnName" value="${infinispan-cl-cache.jdbc.data.column}"/>
             <property name="timestampColumnName" value="${infinispan-cl-cache.jdbc.timestamp.column}"/>
             <property name="idColumnType" value="${infinispan-cl-cache.jdbc.id.type}"/>
             <property name="dataColumnType" value="${infinispan-cl-cache.jdbc.data.type}"/>
             <property name="timestampColumnType" value="${infinispan-cl-cache.jdbc.timestamp.type}"/>
             <property name="dropTableOnExit" value="${infinispan-cl-cache.jdbc.table.drop}"/>
             <property name="createTableOnStart" value="${infinispan-cl-cache.jdbc.table.create}"/>
             <property name="connectionFactoryClass" value="${infinispan-cl-cache.jdbc.connectionFactory}"/>
             <property name="datasourceJndiLocation" value="${infinispan-cl-cache.jdbc.datasource}"/>
          </properties>
          <async enabled="false"/>
        </loader>
      </loaders>
   </default>

</infinispan>

Have a look at "infinispan-indexer.xml"

<infinispan 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance". 
      xsi:schemaLocation="urn:infinispan:config:5.1 http://www.infinispan.org/schemas/infinispan-config-5.1.xsd". 
      xmlns="urn:infinispan:config:5.1">

    <global>
      <evictionScheduledExecutor factory="org.infinispan.executors.DefaultScheduledExecutorFactory">
        <properties>
          <property name="threadNamePrefix" value="EvictionThread"/>
        </properties>
      </evictionScheduledExecutor>

      <globalJmxStatistics jmxDomain="exo" enabled="true" allowDuplicateDomains="true"/>

      <transport transportClass="org.infinispan.remoting.transport.jgroups.JGroupsTransport" clusterName="${infinispan-cluster-name}" distributedSyncTimeout=
        <properties>
          <property name="configurationFile" value="${jgroups-configuration}"/>
        </properties>
      </transport>
    </global>

    <default>
      <clustering mode="replication">
        <stateTransfer timeout="20000" fetchInMemoryState="false" />
        <sync replTimeout="20000"/>
      </clustering>

      <locking isolationLevel="READ_COMMITTED" lockAcquisitionTimeout="20000" writeSkewCheck="false" concurrencyLevel="500" useLockStriping="false"/>
      <transaction transactionManagerLookupClass="org.exoplatform.services.transaction.infinispan.JBossStandaloneJTAManagerLookup" syncRollbackPhase="true" s
      <jmxStatistics enabled="true"/>
      <eviction strategy="NONE"/>

      <loaders passivation="false" shared="false" preload="false">
        <loader class="${infinispan-cachestore-classname}" fetchPersistentState="false" ignoreModifications="false" purgeOnStartup="false">
          <async enabled="false"/>
        </loader>
      </loaders>
   </default>
</infinispan>

RepositoryCreationService is the service which is used to create repositories in runtime. The service can be used in a standalone or cluster environment.

RepositoryConfigurationService depends to next components:

  • DBCreator - DBCreator used to create new database for each unbinded datasource.

  • BackupManager - BackupManager used to created repository from backup.

  • RPCService - RPCService used for communication between cluster-nodes

    Note

    RPCService may not be configured - in this case, RepositoryService will work as standalone service.

RepositoryCreationService configuration

<component>
   <key>org.exoplatform.services.jcr.ext.backup.BackupManager</key>
   <type>org.exoplatform.services.jcr.ext.backup.impl.BackupManagerImpl</type>
   <init-params>
      <properties-param>
         <name>backup-properties</name>
         <property name="backup-dir" value="target/backup" />
      </properties-param>
   </init-params>
</component>

<component>
   <key>org.exoplatform.services.database.creator.DBCreator</key>
   <type>org.exoplatform.services.database.creator.DBCreator</type>
   <init-params>
      <properties-param>
         <name>db-connection</name>
         <description>database connection properties</description>
         <property name="driverClassName" value="org.hsqldb.jdbcDriver" />
         <property name="url" value="jdbc:hsqldb:file:target/temp/data/" />
         <property name="username" value="sa" />
         <property name="password" value="" />
      </properties-param>
      <properties-param>
         <name>db-creation</name>
         <description>database creation properties</description>
         <property name="scriptPath" value="src/test/resources/test.sql" />
         <property name="username" value="sa" />
         <property name="password" value="" />
      </properties-param>
   </init-params>
</component>

<component>
   <key>org.exoplatform.services.rpc.RPCService</key>
   <type>org.exoplatform.services.rpc.impl.RPCServiceImpl</type>
   <init-params>
      <value-param>
         <name>jgroups-configuration</name>
         <value>jar:/conf/standalone/udp-mux.xml</value>
      </value-param>
      <value-param>
         <name>jgroups-cluster-name</name>
         <value>RPCService-Cluster</value>
      </value-param>
      <value-param>
         <name>jgroups-default-timeout</name>
         <value>0</value>
      </value-param>
   </init-params>
</component>  

<component>
   <key>org.exoplatform.services.jcr.ext.repository.creation.RepositoryCreationService</key>
   <type>
      org.exoplatform.services.jcr.ext.repository.creation.RepositoryCreationServiceImpl
   </type>
     <init-params> 
         <value-param> 
            <name>factory-class-name</name> 
            <value>org.apache.commons.dbcp.BasicDataSourceFactory</value> 
         </value-param> 
      </init-params>
</component>
public interface RepositoryCreationService
{
   /**
    * Reserves, validates and creates repository in a simplified form.
    * 
    * @param rEntry - repository Entry - note that datasource must not exist.
    * @param backupId - backup id
    * @param creationProps - storage creation properties 
    * @throws RepositoryConfigurationException
    *          if some exception occurred during repository creation or repository name is absent in reserved list
    * @throws RepositoryCreationServiceException
    *          if some exception occurred during repository creation or repository name is absent in reserved list
    */
   void createRepository(String backupId, RepositoryEntry rEntry, StorageCreationProperties creationProps)
      throws RepositoryConfigurationException, RepositoryCreationException;

   /**
    * Reserves, validates and creates repository in a simplified form. 
    * 
    * @param rEntry - repository Entry - note that datasource must not exist.
    * @param backupId - backup id
    * @throws RepositoryConfigurationException
    *          if some exception occurred during repository creation or repository name is absent in reserved list
    * @throws RepositoryCreationServiceException
    *          if some exception occurred during repository creation or repository name is absent in reserved list
    */
   void createRepository(String backupId, RepositoryEntry rEntry) throws RepositoryConfigurationException,
      RepositoryCreationException;

   /**
    * Reserve repository name to prevent repository creation with same name from other place in same time
    * via this service.
    * 
    * @param repositoryName - repositoryName
    * @return repository token. Anyone obtaining a token can later create a repository of reserved name.
    * @throws RepositoryCreationServiceException if can't reserve name
    */
   String reserveRepositoryName(String repositoryName) throws RepositoryCreationException;

   /**
    * Creates repository, using token of already reserved repository name. 
    * Good for cases, when repository creation should be delayed or made asynchronously in dedicated thread. 
    * 
    * @param rEntry - repository entry - note, that datasource must not exist
    * @param backupId - backup id
    * @param rToken - token
    * @param creationProps - storage creation properties
    * @throws RepositoryConfigurationException
    *          if some exception occurred during repository creation or repository name is absent in reserved list
    * @throws RepositoryCreationServiceException
    *          if some exception occurred during repository creation or repository name is absent in reserved list
    */
   void createRepository(String backupId, RepositoryEntry rEntry, String rToken, StorageCreationProperties creationProps)
      throws RepositoryConfigurationException, RepositoryCreationException;

   /**
    * Creates  repository, using token of already reserved repository name. Good for cases, when repository creation should be delayed or 
    * made asynchronously in dedicated thread. 
    * 
    * @param rEntry - repository entry - note, that datasource must not exist
    * @param backupId - backup id
    * @param rToken - token
    * @throws RepositoryConfigurationException
    *          if some exception occurred during repository creation or repository name is absent in reserved list
    * @throws RepositoryCreationServiceException
    *          if some exception occurred during repository creation or repository name is absent in reserved list
    */
   void createRepository(String backupId, RepositoryEntry rEntry, String rToken)
      throws RepositoryConfigurationException, RepositoryCreationException;

   /**
    * Remove previously created repository. 
    * 
    * @param repositoryName - the repository name to delete
    * @param forceRemove - force close all opened sessions 
    * @throws RepositoryCreationServiceException
    *          if some exception occurred during repository removing occurred
    */
   void removeRepository(String repositoryName, boolean forceRemove) throws RepositoryCreationException;

}

JCR supports two query languages - JCR and XPath. A query, whether XPath or SQL, specifies a subset of nodes within a workspace, called the result set. The result set constitutes all the nodes in the workspace that meet the constraints stated in the query.

Find all nodes in the repository. Only those nodes are found to which the session has READ permission. See also Access Control.

Find all nodes in repository, that contain a mixin type "mix:title".

Find all nodes with mixin type 'mix:title' where the prop_pagecount property contains a value less than 90. Only select the title of each node.

Find all nodes with mixin type 'mix:title' and where the property 'jcr:title' starts with 'P'.

Find all nodes with a mixin type 'mix:title' and whose property 'jcr:title' starts with 'P%ri'.

As you see "P%rison break" contains the symbol '%'. This symbol is reserved for LIKE comparisons. So what can we do?

Within the LIKE pattern, literal instances of percent ("%") or underscore ("_") must be escaped. The SQL ESCAPE clause allows the definition of an arbitrary escape character within the context of a single LIKE statement. The following example defines the backslash ' \' as escape character:

SELECT * FROM mytype WHERE a LIKE 'foo\%' ESCAPE '\'

XPath does not have any specification for defining escape symbols, so we must use the default escape character (' \').

Find all nodes with a mixin type 'mix:title' and where the property 'jcr:title' does NOT start with a 'P' symbol

Find all fairytales with a page count more than 90 pages.

How does it sound in jcr terms - Find all nodes with mixin type 'mix:title' where the property 'jcr:description' equals "fairytale" and whose "prop_pagecount" property value is less than 90.

Find all documents whose title is 'Cinderella' or whose description is 'novel'.

How does it sound in jcr terms? - Find all nodes with a mixin type 'mix:title' whose property 'jcr:title' equals "Cinderella" or whose "jcr:description" property value is "novel".

Find all nodes with a mixin type 'mix:title' where the property 'jcr:description' does not exist (is null).

Find all nodes with a mixin type 'mix:title' and where the property 'jcr:title' equals 'casesensitive' in lower or upper case.

Find all nodes of primary type "nt:resource" whose jcr:lastModified property value is greater than 2006-06-04 and less than 2008-06-04.

SQL

In SQL you have to use the keyword TIMESTAMP for date comparisons. Otherwise, the date would be interpreted as a string. The date has to be surrounded by single quotes (TIMESTAMP 'datetime') and in the ISO standard format: YYYY-MM-DDThh:mm:ss.sTZD ( http://en.wikipedia.org/wiki/ISO_8601 and well explained in a W3C note http://www.w3.org/TR/NOTE-datetime).

You will see that it can be a date only (YYYY-MM-DD) but also a complete date and time with a timezone designator (TZD).

// make SQL query
QueryManager queryManager = workspace.getQueryManager();
// create query
StringBuffer sb = new StringBuffer();
sb.append("select * from nt:resource where ");
sb.append("( jcr:lastModified >= TIMESTAMP '");
sb.append("2006-06-04T15:34:15.917+02:00");
sb.append("' )");
sb.append(" and ");
sb.append("( jcr:lastModified <= TIMESTAMP '");
sb.append("2008-06-04T15:34:15.917+02:00");
sb.append("' )");
String sqlStatement = sb.toString();
Query query = queryManager.createQuery(sqlStatement, Query.SQL);
// execute query and fetch result
QueryResult result = query.execute();

XPath

Compared to the SQL format, you have to use the keyword xs:dateTime and surround the datetime by extra brackets: xs:dateTime('datetime'). The actual format of the datetime also conforms with the ISO date standard.

// make XPath query
QueryManager queryManager = workspace.getQueryManager();
// create query
StringBuffer sb = new StringBuffer();
sb.append("//element(*,nt:resource)");
sb.append("[");
sb.append("@jcr:lastModified >= xs:dateTime('2006-08-19T10:11:38.281+02:00')");
sb.append(" and ");
sb.append("@jcr:lastModified <= xs:dateTime('2008-06-04T15:34:15.917+02:00')");
sb.append("]");
String xpathStatement = sb.toString();
Query query = queryManager.createQuery(xpathStatement, Query.XPATH);
// execute query and fetch result
QueryResult result = query.execute();

Find all nodes with primary type 'nt:file' whose node name is 'document'. The node name is accessible by a function called "fn:name()".

Find all nodes with the primary type 'nt:unstructured' whose property 'multiprop' contains both values "one" and "two".

Find a node with the primary type 'nt:file' that is located on the exact path "/folder1/folder2/document1".

Find all nodes with the primary type 'nt:folder' that are children of node by path "/root1/root2". Only find children, do not find further descendants.

Find all nodes with the primary type 'nt:folder' that are descendants of the node "/folder1/folder2".

Select all nodes with the mixin type ''mix:title' and order them by the 'prop_pagecount' property.

Select all nodes with the mixin type 'mix:title' containing any word from the set {'brown','fox','jumps'}. Then, sort result by the score in ascending node. This way nodes that match better the query statement are ordered at the last positions in the result list.

Find all nodes containing a mixin type 'mix:title' and whose 'jcr:description' contains "forest" string.

Find nodes with mixin type 'mix:title' where any property contains 'break' string.

In this example, we will create new Analyzer, set it in QueryHandler configuration, and make query to check it.

Standard analyzer does not normalize accents like é,è,à. So, a word like 'tréma' will be stored to index as 'tréma'. But if we want to normalize such symbols or not? We want to store 'tréma' word as 'trema'.

There is two ways of setting up new Analyzer (no matter standarts or our):

There is only one way - create new Analyzer (if there is no previously created and accepted for our needs) and set it in Search index.

  • The second way: Register new Analyzer in QueryHandler configuration (this one eccepted since 1.12 version);

We will use the last one:

  • Create new MyAnalyzer

public class MyAnalyzer extends Analyzer
{
   @Override
   public TokenStream tokenStream(String fieldName, Reader reader)
   {
      StandardTokenizer tokenStream = new StandardTokenizer(reader);
      // process all text with standard filter
      // removes 's (as 's in "Peter's") from the end of words and removes dots from acronyms.
      TokenStream result = new StandardFilter(tokenStream);
      // this filter normalizes token text to lower case
      result = new LowerCaseFilter(result);
      // this one replaces accented characters in the ISO Latin 1 character set (ISO-8859-1) by their unaccented equivalents
      result = new ISOLatin1AccentFilter(result);
      // and finally return token stream
      return result;
   }
}
  • Then, register new MyAnalyzer in configuration

<workspace name="ws">
   ...
   <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex">
      <properties>
         <property name="analyzer" value="org.exoplatform.services.jcr.impl.core.MyAnalyzer"/>
         ...
      </properties>
   </query-handler>
   ...
</workspace>

After that, check it with query:

Find node with mixin type 'mix:title' where 'jcr:title' contains "tréma" and "naïve" strings.

The node type nt:file represents a file. It requires a single child node, called jcr:content. This node type represents images and other binary content in a JCRWiki entry. The node type of jcr:conent is nt:resource which represents the actual content of a file.

Find node with the primary type is 'nt:file' and which whose 'jcr:content' child node contains "cats".

Normally, we can't find nodes (in our case) using just JCR SQL or XPath queries. But we can configure indexing so that nt:file aggregates jcr:content child node.

So, change indexing-configuration.xml:

<?xml version="1.0"?>
<!DOCTYPE configuration SYSTEM "http://www.exoplatform.org/dtd/indexing-configuration-1.2.dtd">
<configuration xmlns:jcr="http://www.jcp.org/jcr/1.0"
               xmlns:nt="http://www.jcp.org/jcr/nt/1.0">
    <aggregate primaryType="nt:file">
        <include>jcr:content</include>
        <include>jcr:content/*</include>
        <include-property>jcr:content/jcr:lastModified</include-property>
    </aggregate>
</configuration>

Now the content of 'nt:file' and 'jcr:content' ('nt:resource') nodes are concatenated in a single Lucene document. Then, we can make a fulltext search query by content of 'nt:file'; this search includes the content of child 'jcr:content' node.

In this example, we will set different boost values for predefined nodes, and will check effect by selecting those nodes and order them by jcr:score.

The default boost value is 1.0. Higher boost values (a reasonable range is 1.0 - 5.0) will yield a higher score value and appear as more relevant.

In this example, we will exclude some 'text' property of nt:unstructured node from indexind. And, therefore, node will not be found by the content of this property, even if it accepts all constraints.

First of all, add rules to indexing-configuration.xml:

<index-rule nodeType="nt:unstructured" condition="@rule='nsiTrue'">
    <!-- default value for nodeScopeIndex is true -->
    <property>text</property>
</index-rule>

<index-rule nodeType="nt:unstructured" condition="@rule='nsiFalse'">
    <!-- do not include text in node scope index -->
    <property nodeScopeIndex="false">text</property>
</index-rule>

In this example, we want to configure indexind in the next way. All properties of nt:unstructured nodes must be excluded from search, except properties whoes names ends with 'Text' string. First of all, add rules to indexing-configuration.xml:

<index-rule nodeType="nt:unstructured"">
   <property isRegexp="true">.*Text</property>
</index-rule>

Now, let's check this rule with simple query - select all nodes with primary type 'nt:unstructured' and containing 'quick' string (fulltext search by full node).

It's also called excerption (see Excerpt configuration in Search Configuration and in Searching Repository article).

The goal of this query is to find words "eXo" and "implementation" with fulltext search and high-light this words in result value.

Find all mix:title nodes where title contains synonims to 'fast' word.

Synonim provider must be configured in indexing-configuration.xml :

<query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex">
   <properties>
      ...
      <property name="synonymprovider-class" value="org.exoplatform.services.jcr.impl.core.query.lucene.PropertiesSynonymProvider" />
      <property name="synonymprovider-config-path" value="../../synonyms.properties" />
      ...
   </properties>
</query-handler>

File synonim.properties contains next synonims list:

ASF=Apache Software Foundation
quick=fast
sluggish=lazy

Check the correct spelling of phrase 'quik OR (-foo bar)' according to data already stored in index.

SpellChecker must be settled in query-handler config.

test-jcr-config.xml:

<query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex">
   <properties>
      ...
   <property name="spellchecker-class" value="org.exoplatform.services.jcr.impl.core.query.lucene.spell.LuceneSpellChecker$FiveSecondsRefreshInterval" />
      ...
   </properties>
</query-handler>

Find similar nodes to node by path '/baseFile/jcr:content'.

In our example, baseFile will contain text where "terms" word happens many times. That's a reason why the existanse of this word will be used as a criteria of node similarity (for node baseFile).

Higlighting support must be added to configuration. test-jcr-config.xml:

<query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex">
   <properties>
      ...
      <property name="support-highlighting" value="true" />
      ...
   </properties>
</query-handler>

If you execute an XPath request like this:

XPath

// get QueryManager
QueryManager queryManager = workspace.getQueryManager(); 
// make XPath query
Query query = queryManager.createQuery("/jcr:root/Documents/Publie/2010//element(*, exo:article)", Query.XPATH);

You will have an error : "Invalid request". This happens because XML does not allow names starting with a number - and XPath is part of XML: http://www.w3.org/TR/REC-xml/#NT-Name

Therefore, you cannot do XPath requests using a node name that starts with a number.

Easy workarounds:

  • Use an SQL request.

  • Use escaping :

XPath

// get QueryManager
QueryManager queryManager = workspace.getQueryManager(); 
// make XPath query
Query query = queryManager.createQuery("/jcr:root/Documents/Publie/_x0032_010//element(*, exo:article)", Query.XPATH);

You can find the JCR configuration file at .../portal/WEB-INF/conf/jcr/repository-configuration.xml. Please read also Search Configuration for more information about index configuration.

JCR supports such features as Lucene Fuzzy Searches Apache Lucene - Query Parser Syntax.

To use it, you have to form a query like the one described below:

QueryManager qman = session.getWorkspace().getQueryManager();
Query q = qman.createQuery("select * from nt:base where contains(field, 'ccccc~')", Query.SQL);
QueryResult res = q.execute();

Searching with synonyms is integrated in the jcr:contains() function and uses the same syntax as synonym searches in Google. If a search term is prefixed by a tilde symbol ( ~ ), also synonyms of the search term are taken into consideration. For example:

SQL: select * from nt:resource where contains(., '~parameter')

XPath: //element(*, nt:resource)[jcr:contains(., '~parameter')

This feature is disabled by default and you need to add a configuration parameter to the query-handler element in your jcr configuration file to enable it.

<param  name="synonymprovider-config-path" value="..you path to configuration file....."/>
<param  name="synonymprovider-class" value="org.exoplatform.services.jcr.impl.core.query.lucene.PropertiesSynonymProvider"/>
/**
 * <code>SynonymProvider</code> defines an interface for a component that
 * returns synonyms for a given term.
 */
public interface SynonymProvider {

   /**
    * Initializes the synonym provider and passes the file system resource to
    * the synonym provider configuration defined by the configuration value of
    * the <code>synonymProviderConfigPath</code> parameter. The resource may be
    * <code>null</code> if the configuration parameter is not set.
    *
    * @param fsr the file system resource to the synonym provider
    *            configuration.
    * @throws IOException if an error occurs while initializing the synonym
    *                     provider.
    */
   public void initialize(InputStream fsr) throws IOException;

   /**
    * Returns an array of terms that are considered synonyms for the given
    * <code>term</code>.
    *
    * @param term a search term.
    * @return an array of synonyms for the given <code>term</code> or an empty
    *         array if no synonyms are known.
    */
   public String[] getSynonyms(String term);
}

An ExcerptProvider retrieves text excerpts for a node in the query result and marks up the words in the text that match the query terms.

By default highlighting words matched the query is disabled because this feature requires that additional information is written to the search index. To enable this feature, you need to add a configuration parameter to the query-handler element in your jcr configuration file to enable it.

<param name="support-highlighting" value="true"/>

Additionally, there is a parameter that controls the format of the excerpt created. In JCR 1.9, the default is set to org.exoplatform.services.jcr.impl.core.query.lucene.DefaultHTMLExcerpt. The configuration parameter for this setting is:

<param name="excerptprovider-class" value="org.exoplatform.services.jcr.impl.core.query.lucene.DefaultXMLExcerpt"/>

The lucene based query handler implementation supports a pluggable spell checker mechanism. By default, spell checking is not available and you have to configure it first. See parameter spellCheckerClass on page Search Configuration. JCR currently provides an implementation class , which uses the lucene-spellchecker to contribute . The dictionary is derived from the fulltext indexed content of the workspace and updated periodically. You can configure the refresh interval by picking one of the available inner classes of org.exoplatform.services.jcr.impl.core.query.lucene.spell.LuceneSpellChecker:

  • OneMinuteRefreshInterval

  • FiveMinutesRefreshInterval

  • ThirtyMinutesRefreshInterval

  • OneHourRefreshInterval

  • SixHoursRefreshInterval

  • TwelveHoursRefreshInterval

  • OneDayRefreshInterval

For example, if you want a refresh interval of six hours, the class name is: org.exoplatform.services.jcr.impl.core.query.lucene.spell.LuceneSpellChecker$SixHoursRefreshInterval. If you use org.exoplatform.services.jcr.impl.core.query.lucene.spell.LuceneSpellChecker, the refresh interval will be one hour.

The spell checker dictionary is stored as a lucene index under "index-dir"/spellchecker. If it does not exist, a background thread will create it on startup. Similarly, the dictionary refresh is also done in a background thread to not block regular queries.

The sense of analyzers is to transform all strings stored in the index in a well-defined condition. The same analyzer(s) is/are used when searching in order to adapt the query string to the index reality.

Therefore, performing the same query using different analyzers can return different results.

Now, let's see how the same string is transformed by different analyzers.



Note

StandardAnalyzer is the default analyzer in exo's jcr search engine. But we do not use stop words.

You can assign your analyzer as described in Search Configuration

eXo JCR implementation offers new extended feature beyond JCR specification. Sometimes one JCR Node has hundreds or even thousands of child nodes. This situation is highly not recommended for content repository data storage, but sometimes it occurs. JCR Team is pleased to announce new feature that will help to have a deal with huge child lists. They can be iterated in a "lazy" manner now giving improvement in term of performance and RAM usage.

Lazy child nodes iteration feature is accessible via extended interface org.exoplatform.services.jcr.core.ExtendedNode, the inheritor of javax.jcr.Node. It provides a new single method shown below:

   /**
    * Returns a NodeIterator over all child Nodes of this Node. Does not include properties 
    * of this Node. If this node has no child nodes, then an empty iterator is returned.
    * 
    * @return A NodeIterator over all child Nodes of this <code>Node</code>.
    * @throws RepositoryException If an error occurs.
    */
   public NodeIterator getNodesLazily() throws RepositoryException;

From the view of end-user or client application, getNodesLazily() works similar to JCR specified getNodes() returning NodeIterator. "Lazy" iterator supports the same set of features as an ordinary NodeIterator, including skip() and excluding remove() features. "Lazy" implementation performs reading from DB by pages. Each time when it has no more elements stored in memory, it reads next set of items from persistent layer. This set is called "page". Must admit that getNodesLazily feature fully supports session and transaction changes log, so it's a functionally-full analogue of specified getNodes() operation. So when having a deal with huge list of child nodes, getNodes() can be simply and safely substituted with getNodesLazily().

JCR gives an experimental opportunity to replace all getNodes() invocations with getNodesLazily() calls. It handles a boolean system property named "org.exoplatform.jcr.forceUserGetNodesLazily" that internally replaces one call with another, without any code changes. But be sure using it only for development purposes. This feature can be used with top level products using eXo JCR to perform a quick compatibility and performance tests without changing any code. This is not recommended to be used as a production solution.

The WebDAV protocol enables you to use the third party tools to communicate with hierarchical content servers via HTTP. It is possible to add and remove documents or a set of documents from a path on the server. DeltaV is an extension of the WebDav protocol that allows managing document versioning. Locking guarantees protection against multiple access when writing resources. The ordering support allows changing the position of the resource in the list and sort the directory to make the directory tree viewed conveniently. The full-text search makes it easy to find the necessary documents. You can search by using two languages: SQL and XPATH.

In eXo JCR, we plug in the WebDAV layer - based on the code taken from the extension modules of the reference implementation - on the top of our JCR implementation so that it is possible to browse a workspace using the third party tools (it can be Windows folders or Mac ones as well as a Java WebDAV client, such as DAVExplorer or IE using File->Open as a Web Folder).

Now WebDav is an extension of the REST service. To get the WebDav server ready, you must deploy the REST application. Then, you can access any workspaces of your repository by using the following URL:

Standalone mode:

http://host:port/rest/jcr/{RepositoryName}/{WorkspaceName}/{Path}

Portal mode:

http://host:port/portal/rest/private/jcr/{RepositoryName}/{WorkspaceName}/{Path}

When accessing the WebDAV server with the URLhttp://localhost:8080/rest/jcr/repository/production, you might also use "collaboration" (instead of "production") which is the default workspace in eXo products. You will be asked to enter your login and password. Those will then be checked by using the organization service that can be implemented thanks to an InMemory (dummy) module or a DB module or an LDAP one and the JCR user session will be created with the correct JCR Credentials.

Related documents

<component>
  <key>org.exoplatform.services.jcr.webdav.WebDavServiceImpl</key>
  <type>org.exoplatform.services.jcr.webdav.WebDavServiceImpl</type>
  <init-params>

    <!-- default node type which is used for the creation of collections -->
    <value-param>
      <name>def-folder-node-type</name>
      <value>nt:folder</value>
    </value-param>

    <!-- default node type which is used for the creation of files -->
    <value-param>
      <name>def-file-node-type</name>
      <value>nt:file</value>
    </value-param>

    <!-- if MimeTypeResolver can't find the required mime type, 
         which conforms with the file extension, and the mimeType header is absent
         in the HTTP request header, this parameter is used 
         as the default mime type-->
    <value-param>
      <name>def-file-mimetype</name>
      <value>application/octet-stream</value>
    </value-param>

    <!-- This parameter indicates one of the three cases when you update the content of the resource by PUT command.
         In case of "create-version", PUT command creates the new version of the resource if this resource exists.
         In case of "replace" - if the resource exists, PUT command updates the content of the resource and its last modification date.
         In case of "add", the PUT command tries to create the new resource with the same name (if the parent node allows same-name siblings).-->

    <value-param>
      <name>update-policy</name>
      <value>create-version</value>
      <!--value>replace</value -->
      <!-- value>add</value -->
    </value-param>

    <!--
        This parameter determines how service responds to a method that attempts to modify file content.
        In case of "checkout-checkin" value, when a modification request is applied to a checked-in version-controlled resource, the request is automatically preceded by a checkout and followed by a checkin operation.
        In case of "checkout" value, when a modification request is applied to a checked-in version-controlled resource, the request is automatically preceded by a checkout operation.
    -->         
    <value-param>
      <name>auto-version</name>
      <value>checkout-checkin</value>
      <!--value>checkout</value -->
    </value-param>

    <!--
        This parameter is responsible for managing Cache-Control header value which will be returned to the client.
        You can use patterns like "text/*", "image/*" or wildcard to define the type of content.
    -->  
    <value-param>
      <name>cache-control</name>
      <value>text/xml,text/html:max-age=3600;image/png,image/jpg:max-age=1800;*/*:no-cache;</value>
    </value-param>
    
    <!--
        This parameter determines the absolute path to the folder icon file, which is shown
        during WebDAV view of the contents
    -->
    <value-param>
      <name>folder-icon-path</name>
      <value>/absolute/path/to/file</value>
    </value-param>

    <!--
        This parameter determines the absolute path to the file icon file, which is shown
        during WebDAV view of the contents
    -->
    <value-param>
      <name>file-icon-path</name>
      <value>/absolute/path/to/file</value>
    </value-param>

    <!-- 
        This parameter is responsible for untrusted user agents definition.
        Content-type headers of listed here user agents should be
        ignored and MimeTypeResolver should be explicitly used instead 
    -->
    <values-param>
      <name>untrusted-user-agents</name>
      <value>Microsoft Office Core Storage Infrastructure/1.0</value>
    </values-param>

    <--
        Allows to define which node type can be used to
        create files via WebDAV.
        Default value: nt:file
    -->
    <values-param>
      <name>allowed-file-node-types</name>
      <value>nt:file</value>
    </values-param>

    <--
        Allows to define which node type can be used to
        create folders via WebDAV.
        Default value: nt:folder
    -->
    <values-param>
      <name>allowed-folder-node-types</name>
      <value>nt:folder</value>
    </values-param>

  </init-params>
</component>

There are some restrictions for WebDAV in different Operating systems.

The JCR-FTP Server represents the standard eXo service, operates as an FTP server with an access to a content stored in JCR repositories in the form of nt:file/nt:folder nodes or their successors. The client of an executed Server can be any FTP client. The FTP server is supported by a standard configuration which can be changed as required.

The main purpose of that feature is to restore data in case of system faults and repository crashes. Also, the backup results may be used as a content history.

The concept is based on the export of a workspace unit in the Full, or Full + Incrementals model. A repository workspace can be backup and restored using a combination of these modes. In all cases, at least one Full (initial) backup must be executed to mark a starting point of the backup history. An Incremental backup is not a complete image of the workspace. It contains only changes for some period. So it is not possible to perform an Incremental backup without an initial Full backup.

The Backup service may operate as a hot-backup process at runtime on an in-use workspace. It's a case when the Full + Incrementals model should be used to have a guaranty of data consistency during restoration. An Incremental will be run starting from the start point of the Full backup and will contain changes that have occured during the Full backup, too.

A restore operation is a mirror of a backup one. At least one Full backup should be restored to obtain a workspace corresponding to some points in time. On the other hand, Incrementals may be restored in the order of creation to reach a required state of a content. If the Incremental contains the same data as the Full backup (hot-backup), the changes will be applied again as if they were made in a normal way via API calls.

According to the model there are several modes for backup logic:

The work of Backup is based on the BackupConfig configuration and the BackupChain logical unit.

BackupConfig describes the backup operation chain that will be performed by the service. When you intend to work with it, the configuration should be prepared before the backup is started.

The configuration contains such values as:

BackupChain is a unit performing the backup process and it covers the principle of initial Full backup execution and manages Incrementals operations. BackupChain is used as a key object for accessing current backups during runtime via BackupManager. Each BackupJob performs a single atomic operation - a Full or Incremental process. The result of that operation is data for a Restore. BackupChain can contain one or more BackupJobs. But at least the initial Full job is always there. Each BackupJobs has its own unique number which means its Job order in the chain, the initial Full job always has the number 0.

Backup process, result data and file location

To start the backup process, it's necessary to create the BackupConfig and call the BackupManager.startBackup(BackupConfig) method. This method will return BackupChain created according to the configuration. At the same time, the chain creates a BackupChainLog which persists BackupConfig content and BackupChain operation states to the file in the service working directory (see Configuration).

When the chain starts the work and the initial BackupJob starts, the job will create a result data file using the destination directory path from BackupConfig. The destination directory will contain a directory with an automatically created name using the pattern repository_workspace-timestamp where timestamp is current time in the format of yyyyMMdd_hhmmss (E.g. db1_ws1-20080306_055404). The directory will contain the results of all Jobs configured for execution. Each Job stores the backup result in its own file with the name repository_workspace-timestamp.jobNumber. BackupChain saves each state (STARTING, WAITING, WORKING, FINISHED) of its Jobs in the BackupChainLog, which has a current result full file path.

BackupChain log file and job result files are a whole and consistent unit, that is a source for a Restore.

Restore requirements

As mentioned before a Restore operation is a mirror of a Backup. The process is a Full restore of a root node with restoring an additional Incremental backup to reach a desired workspace state. Restoring of the workspace Full backup will create a new workspace in the repository using given RepositoyEntry of existing repository and given (preconfigured) WorkspaceEntry for a new target workspace. A Restore process will restore a root node from the SysView XML data.

Finally, we may say that Restore is a process of a new Workspace creation and filling it with a Backup content. In case you already have a target Workspace (with the same name) in a Repository, you have to configure a new name for it. If no target workspace exists in the Repositor, you may use the same name as the Backup one.

As an optional extension, the Backup service is not enabled by default. You need to enable it via configuration.

The following is an example configuration :

<component>
  <key>org.exoplatform.services.jcr.ext.backup.BackupManager</key>
  <type>org.exoplatform.services.jcr.ext.backup.impl.BackupManagerImpl</type>
  <init-params>
    <properties-param>
      <name>backup-properties</name>
      <property name="backup-dir" value="target/backup" />
    </properties-param>
  </init-params>
</component>

Where mandatory paramet is:

Also, there are optional parameters:

Restoration involves reloading the backup file into a BackupChainLog and applying appropriate workspace initialization. The following snippet shows the typical sequence for restoring a workspace :

// find BackupChain using the repository and workspace names (return null if not found)
BackupChain chain = backup.findBackup("db1", "ws1");

// Get the RepositoryEntry and WorkspaceEntry
ManageableRepository repo = repositoryService.getRepository(repository);
RepositoryEntry repoconf = repo.getConfiguration();
List<WorkspaceEntry> entries = repoconf.getWorkspaceEntries();
WorkspaceEntry = getNewEntry(entries, workspace); // create a copy entry from an existing one

// restore backup log using ready RepositoryEntry and WorkspaceEntry
File backLog = new File(chain.getLogFilePath());
BackupChainLog bchLog = new BackupChainLog(backLog);

// initialize the workspace
repository.configWorkspace(workspaceEntry);

// run restoration
backup.restore(bchLog, repositoryEntry, workspaceEntry);

Repository and Workspace initialization from backup can use the BackupWorkspaceInitializer.

Will be configured BackupWorkspaceInitializer in configuration of workspace to restore the Workspace from backup over initializer.

Will be configured BackupWorkspaceInitializer in all configurations workspaces of the Repository to restore the Repository from backup over initializer.

Restoring the repository or workspace requires to shutdown the repository.

Follow these steps:

Example of configuration initializer to restore workspace "backup" over BackupWorkspaceInitializer:

<workspaces>
  <workspace name="backup" ... >
    <container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer">
      ...
    </container>
    <initializer class="org.exoplatform.services.jcr.impl.core.BackupWorkspaceInitializer">
      <properties>
         <property name="restore-path" value="D:\java\exo-working\backup\repository_backup-20110120_044734"/>
      </properties>
   </initializer>
    ...
</workspace>

Example of configuration initializers to restore the repository "repository" over BackupWorkspaceInitializer:

In configuration of repository will be configured initializers of workspace to refer to your backup.

For example:

...
<workspaces>
 <workspace name="system" ... >
  <container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer">
  ...
  </container>
  <initializer class="org.exoplatform.services.jcr.impl.core.BackupWorkspaceInitializer">
   <properties>
    <property name="restore-path" value="D:\java\exo-working\backup\repository_system-20110120_052334"/>
   </properties>
  </initializer>
  ...
 </workspace>

 <workspace name="collaboration" ... >
   <container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer">
   ...
  </container>
  <initializer class="org.exoplatform.services.jcr.impl.core.BackupWorkspaceInitializer">
   <properties>
    <property name="restore-path" value="D:\java\exo-working\backup\repository_collaboration-20110120_052341"/>
   </properties>
  </initializer>
  ...
 </workspace>

 <workspace name="backup" ... >
  <container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer">
  ...
  </container>

  <initializer class="org.exoplatform.services.jcr.impl.core.BackupWorkspaceInitializer">
   <properties>
    <property name="restore-path" value="D:\java\exo-working\backup\repository_backup-20110120_052417"/>
   </properties>
  </initializer>
  ...
  </workspace>
</workspaces>

The resore of existing workspace or repositry is available.

For restore will be used spacial methods:

 /**
    * Restore existing workspace. Previous data will be deleted.
    * For getting status of workspace restore can use 
    * BackupManager.getLastRestore(String repositoryName, String workspaceName) method 
    * 
    * @param workspaceBackupIdentifier
    *          backup identifier
    * @param workspaceEntry
    *          new workspace configuration
    * @param asynchronous
    *          if 'true' restore will be in asynchronous mode (i.e. in separated thread)
    * @throws BackupOperationException
    *           if backup operation exception occurred 
    * @throws BackupConfigurationException
    *           if configuration exception occurred
    */
   void restoreExistingWorkspace(String workspaceBackupIdentifier, String repositoryName, WorkspaceEntry workspaceEntry,
      boolean asynchronous) throws BackupOperationException, BackupConfigurationException;

   /**
    * Restore existing workspace. Previous data will be deleted.
    * For getting status of workspace restore use can use 
    * BackupManager.getLastRestore(String repositoryName, String workspaceName) method 
    * 
    * @param log
    *          workspace backup log
    * @param workspaceEntry
    *          new workspace configuration
    * @param asynchronous
    *          if 'true' restore will be in asynchronous mode (i.e. in separated thread)
    * @throws BackupOperationException
    *           if backup operation exception occurred 
    * @throws BackupConfigurationException
    *           if configuration exception occurred
    */
   void restoreExistingWorkspace(BackupChainLog log, String repositoryName, WorkspaceEntry workspaceEntry, boolean asynchronous)  throws BackupOperationException, BackupConfigurationException;

   /**
    * Restore existing repository. Previous data will be deleted.
    * For getting status of repository restore can use 
    * BackupManager.getLastRestore(String repositoryName) method 
    * 
    * @param repositoryBackupIdentifier
    *          backup identifier
    * @param repositoryEntry
    *          new repository configuration
    * @param asynchronous
    *          if 'true' restore will be in asynchronous mode (i.e. in separated thread)
    * @throws BackupOperationException
    *           if backup operation exception occurred 
    * @throws BackupConfigurationException
    *           if configuration exception occurred
    */
   void restoreExistingRepository(String  repositoryBackupIdentifier, RepositoryEntry repositoryEntry, boolean asynchronous)  throws BackupOperationException, BackupConfigurationException;

   /**
    * Restore existing repository. Previous data will be deleted.
    * For getting status of repository restore can use 
    * BackupManager.getLastRestore(String repositoryName) method 
    * 
    * @param log
    *          repository backup log
    * @param repositoryEntry
    *          new repository configuration
    * @param asynchronous
    *          if 'true' restore will be in asynchronous mode (i.e. in separated thread)
    * @throws BackupOperationException
    *           if backup operation exception occurred 
    * @throws BackupConfigurationException
    *           if configuration exception occurred
    */
   void restoreExistingRepository(RepositoryBackupChainLog log, RepositoryEntry repositoryEntry, boolean asynchronous)
      throws BackupOperationException, BackupConfigurationException;

These methods for restore will do:

The Backup manager allows you to restore a repository or a workspace using the original configuration stored into the backup log:

/**
    * Restore existing workspace. Previous data will be deleted.
    * For getting status of workspace restore can use 
    * BackupManager.getLastRestore(String repositoryName, String workspaceName) method
    * WorkspaceEntry for restore should be contains in BackupChainLog. 
    * 
    * @param workspaceBackupIdentifier
    *          identifier to workspace backup. 
    * @param asynchronous
    *          if 'true' restore will be in asynchronous mode (i.e. in separated thread) 
    * @throws BackupOperationException
    *           if backup operation exception occurred 
    * @throws BackupConfigurationException
    *           if configuration exception occurred 
    */
   void restoreExistingWorkspace(String workspaceBackupIdentifier, boolean asynchronous)
            throws BackupOperationException,
            BackupConfigurationException;

   /**
    * Restore existing repository. Previous data will be deleted.
    * For getting status of repository restore can use 
    * BackupManager.getLastRestore(String repositoryName) method.
    * ReprositoryEntry for restore should be contains in BackupChainLog. 
    * 
    * @param repositoryBackupIdentifier
    *          identifier to repository backup.   
    * @param asynchronous
    *          if 'true' restore will be in asynchronous mode (i.e. in separated thread)
    * @throws BackupOperationException
    *           if backup operation exception occurred 
    * @throws BackupConfigurationException
    *           if configuration exception occurred
    */
   void restoreExistingRepository(String repositoryBackupIdentifier, boolean asynchronous)
            throws BackupOperationException,
            BackupConfigurationException;

   /**
    * WorkspaceEntry for restore should be contains in BackupChainLog. 
    * 
    * @param workspaceBackupIdentifier
    *          identifier to workspace backup. 
    * @param asynchronous
    *          if 'true' restore will be in asynchronous mode (i.e. in separated thread) 
    * @throws BackupOperationException
    *           if backup operation exception occurred 
    * @throws BackupConfigurationException
    *           if configuration exception occurred 
    */
   void restoreWorkspace(String workspaceBackupIdentifier, boolean asynchronous) throws BackupOperationException,
            BackupConfigurationException;

   /**
    * ReprositoryEntry for restore should be contains in BackupChainLog. 
    * 
    * @param repositoryBackupIdentifier
    *          identifier to repository backup.   
    * @param asynchronous
    *          if 'true' restore will be in asynchronous mode (i.e. in separated thread)
    * @throws BackupOperationException
    *           if backup operation exception occurred 
    * @throws BackupConfigurationException
    *           if configuration exception occurred
    */
   void restoreRepository(String repositoryBackupIdentifier, boolean asynchronous) throws BackupOperationException,
            BackupConfigurationException;

    /**
    * Restore existing workspace. Previous data will be deleted.
    * For getting status of workspace restore can use 
    * BackupManager.getLastRestore(String repositoryName, String workspaceName) method
    * WorkspaceEntry for restore should be contains in BackupChainLog. 
    * 
    * @param workspaceBackupSetDir
    *          the directory with backup set  
    * @param asynchronous
    *          if 'true' restore will be in asynchronous mode (i.e. in separated thread) 
    * @throws BackupOperationException
    *           if backup operation exception occurred 
    * @throws BackupConfigurationException
    *           if configuration exception occurred 
    */
   void restoreExistingWorkspace(File workspaceBackupSetDir, boolean asynchronous)
            throws BackupOperationException, BackupConfigurationException;

   /**
    * Restore existing repository. Previous data will be deleted.
    * For getting status of repository restore can use 
    * BackupManager.getLastRestore(String repositoryName) method.
    * ReprositoryEntry for restore should be contains in BackupChainLog. 
    * 
    * @param repositoryBackupSetDir
    *          the directory with backup set     
    * @param asynchronous
    *          if 'true' restore will be in asynchronous mode (i.e. in separated thread)
    * @throws BackupOperationException
    *           if backup operation exception occurred 
    * @throws BackupConfigurationException
    *           if configuration exception occurred
    */
   void restoreExistingRepository(File repositoryBackupSetDir, boolean asynchronous)
            throws BackupOperationException, BackupConfigurationException;

   /**
    * WorkspaceEntry for restore should be contains in BackupChainLog. 
    * 
    * @param workspaceBackupSetDir
    *          the directory with backup set 
    * @param asynchronous
    *          if 'true' restore will be in asynchronous mode (i.e. in separated thread) 
    * @throws BackupOperationException
    *           if backup operation exception occurred 
    * @throws BackupConfigurationException
    *           if configuration exception occurred 
    */
   void restoreWorkspace(File workspaceBackupSetDir, boolean asynchronous) throws BackupOperationException,
            BackupConfigurationException;

   /**
    * ReprositoryEntry for restore should be contains in BackupChainLog. 
    * 
    * @param repositoryBackupSetDir
    *          the directory with backup set   
    * @param asynchronous
    *          if 'true' restore will be in asynchronous mode (i.e. in separated thread)
    * @throws BackupOperationException
    *           if backup operation exception occurred 
    * @throws BackupConfigurationException
    *           if configuration exception occurred
    */
   void restoreRepository(File repositoryBackupSetDir, boolean asynchronous) throws BackupOperationException,
            BackupConfigurationException;

You can use backup/restore mechanism to migrate between different DB types configuration. Currently three DB types supported (single, multi, isolated) and you can migrate between each of them.

To accomplish migration you simply need to set desired DB type in the repository configuration file of backup set. It is highly recommended to make backup at the DB level before starting the migration process.

Before starting migrating the data of your JCR from single/multi data format to isolated data format, you need to have the backupconsole.

See the Building application section for more details.

Or you can download it from ow2 directly.

See the Configuration Backup service section for details.

  • Create a full backup

For example:

             jcrbackup.cmd http://root:exo@localhost:8080/rest start /repository
         

Return

             Successful :
             status code = 200
         
  • Get the backup id

You need get the backup id used in restore action.

For example:

             jcrbackup http://root:exo@localhost:8080 list completed
         

Return

             The completed (ready to restore) backups information :
             1) Repository backup with id 5dcbc851c0a801c9545eb434947dbe87 :
             repository name           : repository
             backup type               : full only
             started time              : lun., 21 janv. 2013 16:48:21 GMT+01:00
             finished time             : lun., 21 janv. 2013 16:48:25 GMT+01:00
         

The backup id: 5dcbc851c0a801c9545eb434947dbe87

See the Backup Client Usage section for more details.

  • Set desired DB type in the repository configuration file of backup

Change db-structure-type to isolated.

For example: In original-repository-config :

              exo-tomcat\temp\backup\repository_repository_backup_1358783301705\original-repository-config
         

replace

             <property name="db-structure-type" value="single"/>
         

by

             <property name="db-structure-type" value="isolated"/>
         

This change must be done for all workspaces.

  • Activate the persister config

Before starting the restore operation, ensure that the persister is configured to save the changes of the repository configuration.

If it's not activated, it should be configured, See the JCR Configuration persister section for more details.

  • Restore repository with original configuation and remove exists

For example:

             jcrbackup.cmd http://root:exo@localhost:8080/rest restore remove-exists 5dcbc851c0a801c9545eb434947dbe87
         

Return

             Successful :
             status code = 200
         
  • Drop the old tables with the old data format

             drop table JCR_SREF;
             drop table JCR_SVALUE;
             drop table JCR_SITEM;
         

See the Configuration Backup service section for details.

  • Create a full backup

For example:

              jcrbackup.cmd http://root:exo@localhost:8080/rest start /repository
          

Return

              Successful :
              status code = 200
          
  • Get the backup id

You need get the backup id to launch the restore action.

For example:

              jcrbackup http://root:exo@localhost:8080 list completed
          

Return

              The completed (ready to restore) backups information :
              1) Repository backup with id 5dcbc851c0a801c9545eb434947dbe87 :
              repository name           : repository
              backup type               : full only
              started time              : lun., 21 janv. 2013 16:48:21 GMT+01:00
              finished time             : lun., 21 janv. 2013 16:48:25 GMT+01:00
          

The backup id: 5dcbc851c0a801c9545eb434947dbe87

See the Backup Client Usage section for more details.

  • Set desired DB type in the repository configuration file of backup

Change db-structure-type to isolated.

For example: In original-repository-config :

              exo-tomcat\temp\backup\repository_repository_backup_1358783301705\original-repository-config
          

replace

              <property name="db-structure-type" value="multi"/>
          

by

              <property name="db-structure-type" value="isolated"/>
          

This change must be done for all workspaces.

  • Configure the datasource name used for the isolated mode

Make sure that in your repository configuration all the workspaces of a same repository share the same datasource.

  • Activate the persister config

Before starting the restore operation, ensure that the persister is configured to save the changes of the repository configuration.

If it's not activated, it should be configured, See the JCR Configuration persister section for more details.

  • Restore repository with original configuation and remove exists

For example:

              jcrbackup.cmd http://root:exo@localhost:8080/rest restore remove-exists 5dcbc851c0a801c9545eb434947dbe87
          

Return

              Successful :
              status code = 200
          
  • Drop the old tables with the old data format

              drop table JCR_MREF;
              drop table JCR_MVALUE;
              drop table JCR_MITEM;
          

GateIn uses context /portal/rest, therefore you need to use http://host:port/portal/rest/ instread of http://host:port/rest/

GateIn uses form authentication, so first you need to login (url to form authentication is http://host:port/portal/login) and then perform requests.

The service org.exoplatform.services.jcr.ext.backup.server.HTTPBackupAgent is REST-based front-end to service org.exoplatform.services.jcr.ext.backup.BackupManager. HTTPBackupAgent is representation BackupManager to creation backup, restore, getting status of current or completed backup/restore, etc.

The backup client is http client for HTTPBackupAgent.

The HTTPBackupAgent is based on REST (see details about the REST Framework).

HTTPBackupAgent is using POST and GET methods for request.

The HTTPBackupAgent allows :

  • Start backup

  • Stop backup

  • Restore from backup

  • Delete the workspace

  • Get information about backup service (BackupManager)

  • Get information about current backup / restores / completed backups

/rest/jcr-backup/start/{repo}/{ws}

Start backup on specific workspace

URL: http://host:port/rest/jcr-backup/start/{repo}/{ws}

Formats: json.

Method: POST

Parameters:

The BackupConfigBean:

header :
"Content-Type" = "application/json; charset=UTF-8"

body:
<JSON to BackupConfigBean>

The JSON bean of org.exoplatform.services.jcr.ext.backup.server.bean.BackupConfigBean :

{"incrementalRepetitionNumber":<Integer>,"incrementalBackupJobConfig":<JSON to BackupJobConfig>,
"backupType":<Integer>,"fullBackupJobConfig":<JSON to BackupJobConfig>,
"incrementalJobPeriod":<Long>,"backupDir":"<String>"}

Where :

backupType                  - the type of backup:
                                  0 - full backup only;
                                  1 - full and incremental backup.
backupDir                   - the path to backup folder;
incrementalJobPeriod        - the incremental job period;
incrementalRepetitionNumber - the incremental repetition number;
fullBackupJobConfig         - the configuration to full backup, JSON to BackupJobConfig;
incrementalJobPeriod        - the configuration to incremental backup, JSON to BackupJobConfig.

The JSON bean of org.exoplatform.services.jcr.ext.backup.server.bean.response.BackupJobConfig :

{"parameters":[<JSON to Pair>, ..., <JSON to pair> ],"backupJob":"<String>"}

Where:

backupJob  - the FQN (fully qualified name) to BackupJob class;
parameters - the list of JSON of Pair.

The JSON bean of org.exoplatform.services.jcr.ext.backup.server.bean.response.Pair :

{"name":"<String>","value":"<String>"}

Where:

name  - the name of parameter;
value - the value of parameter.

Returns:

/rest/jcr-backup/info/backup

Information about the current and completed backups

URL: http://host:port/rest/jcr-backup/info/backup

Formats: json

Method: GET

Parameters: no

Returns:

/rest/jcr-backup/info/backup/{id} Detailed information about a current or completed backup with identifier '{id}'.

URL: http://host:port/rest/jcr-backup/info/backup/{id}

Formats: json

Method: GET

Parameters:

Returns:

/rest/jcr-backup/restore/{repo}/{id}

Restore the workspace from specific backup.

URL: http://host:port/rest/jcr-backup/restore/{repo}/{id}

Formats: json.

Method: POST

Parameters:

The RestoreBean:

header :
"Content-Type" = "application/json; charset=UTF-8"

body:
<JSON to WorkspaceEntry>

The example of JSON bean to org.exoplatform.services.jcr.config.WorkspaceEntry :

{ "accessManager" : null,
  "autoInitPermissions" : null,
  "autoInitializedRootNt" : null,
  "cache" : { "parameters" : [ { "name" : "max-size",
            "value" : "10k"
          },
          { "name" : "live-time",
            "value" : "1h"
          }
        ],
      "type" : "org.exoplatform.services.jcr.impl.dataflow.persistent.LinkedWorkspaceStorageCacheImpl"
    },
  "container" : { "parameters" : [ { "name" : "source-name",
            "value" : "jdbcjcr"
          },
          { "name" : "dialect",
            "value" : "hsqldb"
          },
          { "name" : "multi-db",
            "value" : "false"
          },
          { "name" : "max-buffer-size",
            "value" : "200k"
          },
          { "name" : "swap-directory",
            "value" : "../temp/swap/production"
          }
        ],
      "type" : "org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer",
      "valueStorages" : [ { "filters" : [ { "ancestorPath" : null,
                  "minValueSize" : 0,
                  "propertyName" : null,
                  "propertyType" : "Binary"
                } ],
            "id" : "system",
            "parameters" : [ { "name" : "path",
                  "value" : "../temp/values/production"
                } ],
            "type" : "org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage"
          } ]
    },
  "initializer" : { "parameters" : [ { "name" : "root-nodetype",
            "value" : "nt:unstructured"
          } ],
      "type" : "org.exoplatform.services.jcr.impl.core.ScratchWorkspaceInitializer"
    },
  "lockManager" : 
      "timeout" : 15728640
    },
  "name" : "production",
  "queryHandler" : { "analyzer" : {  },
      "autoRepair" : true,
      "bufferSize" : 10,
      "cacheSize" : 1000,
      "documentOrder" : true,
      "errorLogSize" : 50,
      "excerptProviderClass" : "org.exoplatform.services.jcr.impl.core.query.lucene.DefaultHTMLExcerpt",
      "excludedNodeIdentifers" : null,
      "extractorBackLogSize" : 100,
      "extractorPoolSize" : 0,
      "extractorTimeout" : 100,
      "indexDir" : "../temp/jcrlucenedb/production",
      "indexingConfigurationClass" : "org.exoplatform.services.jcr.impl.core.query.lucene.IndexingConfigurationImpl",
      "indexingConfigurationPath" : null,
      "maxFieldLength" : 10000,
      "maxMergeDocs" : 2147483647,
      "mergeFactor" : 10,
      "minMergeDocs" : 100,
      "parameters" : [ { "name" : "index-dir",
            "value" : "../temp/jcrlucenedb/production"
          } ],
      "queryClass" : "org.exoplatform.services.jcr.impl.core.query.QueryImpl",
      "queryHandler" : null,
      "resultFetchSize" : 2147483647,
      "rootNodeIdentifer" : "00exo0jcr0root0uuid0000000000000",
      "spellCheckerClass" : null,
      "supportHighlighting" : false,
      "synonymProviderClass" : null,
      "synonymProviderConfigPath" : null,
      "type" : "org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex",
      "useCompoundFile" : false,
      "volatileIdleTime" : 3
    },
  "uniqueName" : "repository_production"
}

Returns:

/rest/jcr-backup/info/default-ws-config Will be returned the JSON bean to WorkspaceEntry for default workspace.

URL: http://host:port/rest/jcr-backup/info/default-ws-config

Formats: json

Method: GET

Parameters: no

Returns:

Add the components org.exoplatform.services.jcr.ext.backup.server.HTTPBackupAgent and org.exoplatform.services.jcr.ext.backup.BackupManager to services configuration :

<component>
  <type>org.exoplatform.services.jcr.ext.backup.server.HTTPBackupAgent</type>
</component>

<component>
  <type>org.exoplatform.services.jcr.ext.repository.RestRepositoryService</type>
</component>

<component>
  <key>org.exoplatform.services.jcr.ext.backup.BackupManager</key>
  <type>org.exoplatform.services.jcr.ext.backup.impl.BackupManagerImpl</type>
  <init-params>
    <properties-param>
      <name>backup-properties</name>
      <property name="backup-dir" value="../temp/backup" />
    </properties-param>
  </init-params>
</component>

In case, if you will restore backup in same workspace (so you will drop previous workspace), you need configure RepositoryServiceConfiguration in order to save the changes of the repository configuration. For example

<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/portal/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>

See the eXo JCR Configuration article at the 'Portal and Standalone configuration' section for details.

Backup client is console application.

The backup client is http client for HTTPBackupAgent.

Command signature:

Help info:
 <url_basic_authentication>|<url form authentication>  <cmd> 
 <url_basic_authentication>  :   http(s)//login:password@host:port/<context> 

 <url form authentication>   :   http(s)//host:port/<context> "<form auth parm>" 
     <form auth parm>        :   form <method> <form path>
     <method>                :   POST or GET
     <form path>             :   /path/path?<paramName1>=<paramValue1>&<paramName2>=<paramValue2>...
     Example to <url form authentication> : http://127.0.0.1:8080/portal/rest form POST "/portal/login?initialURI=/portal/private&username=root&password=gtn"

 <cmd>  :   start <repo[/ws]> <backup_dir> [<incr>] 
            stop <backup_id> 
            status <backup_id> 
            restores <repo[/ws]> 
            restore [remove-exists] {{<backup_id>|<backup_set_path>} | {<repo[/ws]> {<backup_id>|<backup_set_path>} [<pathToConfigFile>]}} 
            list [completed] 
            info 
            drop [force-close-session] <repo[/ws]>  
            help  

 start          - start backup of repository or workspace 
 stop           - stop backup 
 status         - information about the current or completed backup by 'backup_id' 
 restores       - information about the last restore on specific repository or workspace 
 restore        - restore the repository or workspace from specific backup 
 list           - information about the current backups (in progress) 
 list completed - information about the completed (ready to restore) backups 
 info           - information about the service backup 
 drop           - delete the repository or workspace 
 help           - print help information about backup console 

 <repo[/ws]>         - /<reponsitory-name>[/<workspace-name>]  the repository or workspace 
 <backup_dir>        - path to folder for backup on remote server 
 <backup_id>         - the identifier for backup 
 <backup_set_dir>    - path to folder with backup set on remote server
 <incr>              - incemental job period 
 <pathToConfigFile>  - path (local) to  repository or workspace configuration 
 remove-exists       - remove fully (db, value storage, index) exists repository/workspace 
 force-close-session - close opened sessions on repository or workspace. 

 All valid combination of parameters for command restore: 
  1. restore remove-exists <repo/ws> <backup_id>       <pathToConfigFile> 
  2. restore remove-exists <repo>    <backup_id>       <pathToConfigFile> 
  3. restore remove-exists <repo/ws> <backup_set_path> <pathToConfigFile> 
  4. restore remove-exists <repo>    <backup_set_path> <pathToConfigFile> 
  5. restore remove-exists <backup_id> 
  6. restore remove-exists <backup_set_path> 
  7. restore <repo/ws> <backup_id>       <pathToConfigFile> 
  8. restore <repo>    <backup_id>       <pathToConfigFile> 
  9. restore <repo/ws> <backup_set_path> <pathToConfigFile> 
 10. restore <repo>    <backup_set_path> <pathToConfigFile> 
 11. restore <backup_id> 
 12. restore <backup_set_path> 
<repository-service default-repository="repository">
  <repositories>
    <repository name="repository" system-workspace="production" default-workspace="production">
      <security-domain>exo-domain</security-domain>
      <access-control>optional</access-control>
      <authentication-policy>org.exoplatform.services.jcr.impl.core.access.JAASAuthenticator</authentication-policy>
      <workspaces>
        
        <workspace name="backup">
          <container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer">
            <properties>
              <property name="source-name" value="jdbcjcr" />
              <property name="dialect" value="pgsql" />
              <property name="multi-db" value="false" />
              <property name="max-buffer-size" value="200k" />
              <property name="swap-directory" value="../temp/swap/backup" />
            </properties>
            <value-storages>
              <value-storage id="draft" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage">
                <properties>
                  <property name="path" value="../temp/values/backup" />
                </properties>
                <filters>
                  <filter property-type="Binary"/>
                </filters>
              </value-storage>
            </value-storages>
          </container>
          <initializer class="org.exoplatform.services.jcr.impl.core.ScratchWorkspaceInitializer">
            <properties>
              <property name="root-nodetype" value="nt:unstructured" />
            </properties>
          </initializer>
          <cache enabled="true" class="org.exoplatform.services.jcr.impl.dataflow.persistent.LinkedWorkspaceStorageCacheImpl">
            <properties>
              <property name="max-size" value="10k" />
              <property name="live-time" value="1h" />
            </properties>
          </cache>
          <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex">
            <properties>
              <property name="index-dir" value="../temp/jcrlucenedb/backup" />
            </properties>
          </query-handler>
          <lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl">
             <properties>
                <property name="time-out" value="15m" />
                <property name="jbosscache-configuration" value="jbosscache-lock.xml" />
                <property name="jbosscache-cl-cache.jdbc.table.name" value="jcrlocks" />
                <property name="jbosscache-cl-cache.jdbc.table.create" value="true" />
                <property name="jbosscache-cl-cache.jdbc.table.drop" value="false" />
                <property name="jbosscache-cl-cache.jdbc.table.primarykey" value="jcrlocks_pk" />
                <property name="jbosscache-cl-cache.jdbc.fqn.column" value="fqn" />
                <property name="jbosscache-cl-cache.jdbc.node.column" value="node" />
                <property name="jbosscache-cl-cache.jdbc.parent.column" value="parent" />
                <property name="jbosscache-cl-cache.jdbc.datasource" value="jdbcjcr" />
                <property name="jbosscache-shareable" value="true" />
             </properties>
          </lock-manager>
        </workspace>
      </workspaces>
    </repository>
  </repositories>
</repository-service>

This usecase needs RestRepositoryService enabled. (Deleting the repository needs it)

<component>
   <type>org.exoplatform.services.jcr.ext.repository.RestRepositoryService</type>
</component>
<repository-service default-repository="repository">
   <repositories>
      <repository name="repository" system-workspace="production" default-workspace="production">
         <security-domain>exo-domain</security-domain>
         <access-control>optional</access-control>
         <authentication-policy>org.exoplatform.services.jcr.impl.core.access.JAASAuthenticator</authentication-policy>
         <workspaces>
            <workspace name="production">
               <!-- for system storage -->
               <container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer">
                  <properties>
                     <property name="source-name" value="jdbcjcr" />
                     <property name="multi-db" value="false" />
                     <property name="max-buffer-size" value="200k" />
                     <property name="swap-directory" value="../temp/swap/production" />
                  </properties>
                  <value-storages>
                     <value-storage id="system" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage">
                        <properties>
                           <property name="path" value="../temp/values/production" />
                        </properties>
                        <filters>
                           <filter property-type="Binary" />
                        </filters>
                     </value-storage>
                  </value-storages>
               </container>
               <initializer class="org.exoplatform.services.jcr.impl.core.ScratchWorkspaceInitializer">
                  <properties>
                     <property name="root-nodetype" value="nt:unstructured" />
                  </properties>
               </initializer>
               <cache enabled="true" class="org.exoplatform.services.jcr.impl.dataflow.persistent.LinkedWorkspaceStorageCacheImpl">
                  <properties>
                     <property name="max-size" value="10k" />
                     <property name="live-time" value="1h" />
                  </properties>
               </cache>
               <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex">
                  <properties>
                     <property name="index-dir" value="../temp/jcrlucenedb/production" />
                  </properties>
               </query-handler>
               <lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl">
                  <properties>
                     <property name="time-out" value="15m" />
                     <property name="jbosscache-configuration" value="jbosscache-lock.xml" />
                     <property name="jbosscache-cl-cache.jdbc.table.name" value="jcrlocks" />
                     <property name="jbosscache-cl-cache.jdbc.table.create" value="true" />
                     <property name="jbosscache-cl-cache.jdbc.table.drop" value="false" />
                     <property name="jbosscache-cl-cache.jdbc.table.primarykey" value="jcrlocks_pk" />
                     <property name="jbosscache-cl-cache.jdbc.fqn.column" value="fqn" />
                     <property name="jbosscache-cl-cache.jdbc.node.column" value="node" />
                     <property name="jbosscache-cl-cache.jdbc.parent.column" value="parent" />
                     <property name="jbosscache-cl-cache.jdbc.datasource" value="jdbcjcr" />
                     <property name="jbosscache-shareable" value="true" />
                  </properties>
               </lock-manager>
            </workspace>

            <workspace name="backup">
               <container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer">
                  <properties>
                     <property name="source-name" value="jdbcjcr" />
                     <property name="multi-db" value="false" />
                     <property name="max-buffer-size" value="200k" />
                     <property name="swap-directory" value="../temp/swap/backup" />
                  </properties>
                  <value-storages>
                     <value-storage id="draft" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage">
                        <properties>
                           <property name="path" value="../temp/values/backup" />
                        </properties>
                        <filters>
                           <filter property-type="Binary" />
                        </filters>
                     </value-storage>
                  </value-storages>
               </container>
               <initializer class="org.exoplatform.services.jcr.impl.core.ScratchWorkspaceInitializer">
                  <properties>
                     <property name="root-nodetype" value="nt:unstructured" />
                  </properties>
               </initializer>
               <cache enabled="true" class="org.exoplatform.services.jcr.impl.dataflow.persistent.LinkedWorkspaceStorageCacheImpl">
                  <properties>
                     <property name="max-size" value="10k" />
                     <property name="live-time" value="1h" />
                  </properties>
               </cache>
               <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex">
                  <properties>
                     <property name="index-dir" value="../temp/jcrlucenedb/backup" />
                  </properties>
               </query-handler>
                <lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl">
                  <properties>
                     <property name="time-out" value="15m" />
                     <property name="jbosscache-configuration" value="jbosscache-lock.xml" />
                     <property name="jbosscache-cl-cache.jdbc.table.name" value="jcrlocks" />
                     <property name="jbosscache-cl-cache.jdbc.table.create" value="true" />
                     <property name="jbosscache-cl-cache.jdbc.table.drop" value="false" />
                     <property name="jbosscache-cl-cache.jdbc.table.primarykey" value="jcrlocks_pk" />
                     <property name="jbosscache-cl-cache.jdbc.fqn.column" value="fqn" />
                     <property name="jbosscache-cl-cache.jdbc.node.column" value="node" />
                     <property name="jbosscache-cl-cache.jdbc.parent.column" value="parent" />
                     <property name="jbosscache-cl-cache.jdbc.datasource" value="jdbcjcr" />
                     <property name="jbosscache-shareable" value="true" />
                  </properties>
               </lock-manager>
            </workspace>

            <workspace name="digital-assets">
               <container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer">
                  <properties>
                     <property name="source-name" value="jdbcjcr" />
                     <property name="multi-db" value="false" />
                     <property name="max-buffer-size" value="200k" />
                     <property name="swap-directory" value="../temp/swap/digital-assets" />
                  </properties>
                  <value-storages>
                     <value-storage id="digital-assets" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage">
                        <properties>
                           <property name="path" value="../temp/values/digital-assets" />
                        </properties>
                        <filters>
                           <filter property-type="Binary" />
                        </filters>
                     </value-storage>
                  </value-storages>
               </container>
               <initializer class="org.exoplatform.services.jcr.impl.core.ScratchWorkspaceInitializer">
                  <properties>
                     <property name="root-nodetype" value="nt:folder" />
                  </properties>
               </initializer>
               <cache enabled="true" class="org.exoplatform.services.jcr.impl.dataflow.persistent.LinkedWorkspaceStorageCacheImpl">
                  <properties>
                     <property name="max-size" value="5k" />
                     <property name="live-time" value="15m" />
                  </properties>
               </cache>
               <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex">
                  <properties>
                     <property name="index-dir" value="../temp/jcrlucenedb/digital-assets" />
                  </properties>
               </query-handler>
               <lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl">
                  <properties>
                     <property name="time-out" value="15m" />
                     <property name="jbosscache-configuration" value="jbosscache-lock.xml" />
                     <property name="jbosscache-cl-cache.jdbc.table.name" value="jcrlocks" />
                     <property name="jbosscache-cl-cache.jdbc.table.create" value="true" />
                     <property name="jbosscache-cl-cache.jdbc.table.drop" value="false" />
                     <property name="jbosscache-cl-cache.jdbc.table.primarykey" value="jcrlocks_pk" />
                     <property name="jbosscache-cl-cache.jdbc.fqn.column" value="fqn" />
                     <property name="jbosscache-cl-cache.jdbc.node.column" value="node" />
                     <property name="jbosscache-cl-cache.jdbc.parent.column" value="parent" />
                     <property name="jbosscache-cl-cache.jdbc.datasource" value="jdbcjcr" />
                     <property name="jbosscache-shareable" value="true" />
                  </properties>
               </lock-manager>
            </workspace>
         </workspaces>
      </repository>
   </repositories>
</repository-service>

This section will show you how to get and manage all statistics provided by eXo JCR.

In order to have a better idea of the time spent into the database access layer, it can be interesting to get some statistics on that part of the code, knowing that most of the time spent into eXo JCR is mainly the database access. This statistics will then allow you to identify without using any profiler what is normally slow in this layer, which could help to fix the problem quickly.

In case you use org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer or org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer as WorkspaceDataContainer, you can get statistics on the time spent into the database access layer. The database access layer (in eXo JCR) is represented by the methods of the interface org.exoplatform.services.jcr.storage.WorkspaceStorageConnection, so for all the methods defined in this interface, we can have the following figures:

Those figures are also available globally for all the methods which gives us the global behavior of this layer.

If you want to enable the statistics, you just need to set the JVM parameter called JDBCWorkspaceDataContainer.statistics.enabled to true. The corresponding CSV file is StatisticsJDBCStorageConnection-${creation-timestamp}.csv for more details about how the csv files are managed, please refer to the section dedicated to the statistics manager.

The format of each column header is ${method-alias}-${metric-alias}. The metric alias are described in the statistics manager section.

The name of the category of statistics corresponding to these statistics is JDBCStorageConnection, this name is mostly needed to access to the statistics through JMX.


In order to know exactly how your application uses eXo JCR, it can be interesting to register all the JCR API accesses in order to easily create real life test scenario based on pure JCR calls and also to tune your eXo JCR to better fit your requirements.

In order to allow you to specify the configuration which part of eXo JCR needs to be monitored without applying any changes in your code and/or building anything, we choose to rely on the Load-time Weaving proposed by AspectJ.

To enable this feature, you will have to add in your classpath the following jar files:

You will also need to get aspectjweaver-1.6.8.jar from the main maven repository http://repo2.maven.org/maven2/org/aspectj/aspectjweaver. At this stage, to enable the statistics on the JCR API accesses, you will need to add the JVM parameter -javaagent:${pathto}/aspectjweaver-1.6.8.jar to your command line, for more details please refer to http://www.eclipse.org/aspectj/doc/released/devguide/ltw-configuration.html.

By default, the configuration will collect statistics on all the methods of the internal interfaces org.exoplatform.services.jcr.core.ExtendedSession and org.exoplatform.services.jcr.core.ExtendedNode, and the JCR API interface javax.jcr.Property. To add and/or remove some interfaces to monitor, you have two configuration files to change that are bundled into the jar exo.jcr.component.statistics-X.Y.Z.jar, which are conf/configuration.xml and META-INF/aop.xml.

The file content below is the content of conf/configuration.xml that you will need to modify to add and/or remove the full qualified name of the interfaces to monitor, into the list of parameter values of the init param called targetInterfaces.

<configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd http://www.exoplatform.org/xml/ns/kernel_1_3.xsd"
 xmlns="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd">

 <component>
   <type>org.exoplatform.services.jcr.statistics.JCRAPIAspectConfig</type>
   <init-params>
     <values-param>
       <name>targetInterfaces</name>
       <value>org.exoplatform.services.jcr.core.ExtendedSession</value>
       <value>org.exoplatform.services.jcr.core.ExtendedNode</value>
       <value>javax.jcr.Property</value>
     </values-param>
   </init-params>
  </component>
</configuration>

The file content below is the content of META-INF/aop.xml that you will need to modify to add and/or remove the full qualified name of the interfaces to monitor, into the expression filter of the pointcut called JCRAPIPointcut. As you can see below, by default only JCR API calls from the exoplatform packages are took into account, don't hesistate to modify this filter to add your own package names.

<aspectj>
  <aspects>
    <concrete-aspect name="org.exoplatform.services.jcr.statistics.JCRAPIAspectImpl" extends="org.exoplatform.services.jcr.statistics.JCRAPIAspect">
      <pointcut name="JCRAPIPointcut"
        expression="(target(org.exoplatform.services.jcr.core.ExtendedSession) || target(org.exoplatform.services.jcr.core.ExtendedNode) || target(javax.jcr.Property)) &amp;&amp; call(public * *(..))" />
    </concrete-aspect>
  </aspects>
  <weaver options="-XnoInline">
    <include within="org.exoplatform..*" />
  </weaver>
</aspectj> 

The corresponding CSV files are of type Statistics${interface-name}-${creation-timestamp}.csv for more details about how the csv files are managed, please refer to the section dedicated to the statistics manager.

The format of each column header is ${method-alias}-${metric-alias}. The method alias will be of type ${method-name}(list of parameter types separeted by ; to be compatible with the CSV format).

The metric alias are described in the statistics manager section.

The name of the category of statistics corresponding to these statistics is the simple name of the monitored interface (e.g. ExtendedSession for org.exoplatform.services.jcr.core.ExtendedSession), this name is mostly needed to access to the statistics through JMX.

Please note that this feature will affect the performances of eXo JCR so it must be used with caution.

The statistics manager manages all the statistics provided by eXo JCR, it is responsible of printing the data into the CSV files and also exposing the statistics through JMX and/or Rest.

The statistics manager will create all the CSV files for each category of statistics that it manages, the format of those files is Statistics${category-name}-${creation-timestamp}.csv. Those files will be created into the user directory if it is possible otherwise it will create them into the temporary directory. The format of those files is CSV (i.e. Comma-Seperated Values), one new line will be added regularily (every 5 seconds by default) and one last line will be added at JVM exit. Each line, will be composed of the 5 figures described below for each method and globaly for all the methods.


You can disable the persistence of the statistics by setting the JVM parameter called JCRStatisticsManager.persistence.enabled to false, by default, it is set to true. You can aslo define the period of time between each record (i.e. line of data into the file) by setting the JVM parameter called JCRStatisticsManager.persistence.timeout to your expected value expressed in milliseconds, by default it is set to 5000.

You can also access to the statistics thanks to JMX, the available methods are the following:

Table 1.47. JMX Methods

getMinGive the minimum time spent into the method corresponding to the given category name and statistics name. The expected arguments are the name of the category of statistics (e.g. JDBCStorageConnection) and the name of the expected method or global for the global value.
getMaxGive the maximum time spent into the method corresponding to the given category name and statistics name. The expected arguments are the name of the category of statistics (e.g. JDBCStorageConnection) and the name of the expected method or global for the global value.
getTotalGive the total amount of time spent into the method corresponding to the given category name and statistics name. The expected arguments are the name of the category of statistics (e.g. JDBCStorageConnection) and the name of the expected method or global for the global value.
getAvgGive the average time spent into the method corresponding to the given category name and statistics name. The expected arguments are the name of the category of statistics (e.g. JDBCStorageConnection) and the name of the expected method or global for the global value.
getTimesGive the total amount of times the method has been called corresponding to the given ,category name and statistics name. The expected arguments are the name of the category of statistics (e.g. JDBCStorageConnection) and the name of the expected method or global for the global value.
resetReset the statistics for the given category name and statistics name. The expected arguments are the name of the category of statistics (e.g. JDBCStorageConnection) and the name of the expected method or global for the global value.
resetAllReset all the statistics for the given category name. The expected argument is the name of the category of statistics (e.g. JDBCStorageConnection).


The full name of the related MBean is exo:service=statistic, view=jcr.

Production and any systems may have faults in some days. They may be caused by hardware and/or software problems, human faults during updates and in many other circumstances. It is important to check integrity and consistency of the system if it is not backed up or stale, or it takes the recovery process much time. The eXo JCR implementation offers an innovative JMX-based complex checking tool. Running inspection, this tool checks every major JCR component, such as persistent data layer and index. The persistent layer includes JDBC Data Container and Value Storage if they are configured. The database is verified using the set of complex specialized domain-specific queries. The Value Storage tool checks the existence and access to each file. Index verification contains two-way pass cycle, existence of each node in the index checks on persistent layer along with opposite direction, when each node from Data Container is validated in the index. Access to the checking tool is exposed via the JMX interface (RepositoryCheckController MBean) with the following operations available:


Among the list of known inconsistencies described in the next section, see below what can be checked and repaired automatically:

  • An item has no parent node: Properties will be removed and the root UUID will be assigned in case of nodes.

  • A node has a single valued property with nothing declared in the VALUE table: This property will be removed if it is not required by primary type of its node.

  • A node has no primary type property: This node and the whole subtree will be removed if it is not required by primary type of its parent.

  • Value record has no related property record: Value record will be removed from database.

  • An item is its own parent: Properties will be removed and root UUID will be assigned in case of nodes.

  • Several versions of same item: All earlier records with earlier versions will be removed from ITEM table.

  • Reference properties without reference records: The property will be removed if it is not required by the primary type of its node.

  • A node is marked as locked in the lockmanager's table but not in ITEM table or the opposite: All lock inconsistencies will be removed from both tables.

Note

The only inconsistency that cannot be fixed automatically is Corrupted VALUE records. Both STORAGE_DESC and DATA fields contain not null value. Since there is no way to determinate which value is valid: either on the file system or in the database.

The list of ValueStorage inconsistencies which can be checked and repaired automatically:

  • Property's value is stored in the File System but the content is missing: A new empty file corresponding to this value will be created.

The list of SearchIndex inconsistencies which can be checked. To repair them we need to reindex the content completely, what also can be done using JMX:

  • Not indexed document

  • Document indexed more than one time

  • Document corresponds to removed node


All tool activities are stored into a file, which can be found in app directory. The syntax of the name of the file is report-<repository name>-dd-MMM-yy-HH-mm.txt.

Here are examples of corrupted JCR and ways to eliminate them:

  1. Items have no parent nodes.

  2. A node has a single valued property with no declaration in the VALUE table.

  3. Node has no primary type property.

  4. All value records have no related property record.

  5. Corrupted VALUE records. Both STORAGE_DESC and DATA fields contain not null value.

  6. Item is its own parent.

  7. Several versions of same item.

  8. Reference properties without reference records.

  9. Node considered to be locked in the lockmanager data, is not locked according to the JCR data or the opposite situation.

  10. A property's value is stored in the file system, but its content is missing.

    This cannot be checked via simple SQL queries.

eXo JCR supports J2EE Connector Architecture 1.5, thus If you would like to delegate the JCR Session lifecycle to your application server, you can use the JCA Resource Adapter for eXo JCR if your application server supports JCA 1.5. This adapter only supports XA Transaction, in other words you cannot use it for local transactions. Since the JCR Sessions have not been designed to be shareable, the session pooling is simply not covered by the adapter.

The equivalent of the javax.resource.cci.ConnectionFactory in JCA terminology is org.exoplatform.connectors.jcr.adapter.SessionFactory in the context of eXo JCR, the resource that you will get thanks to a JNDI lookup is of type SessionFactory and provides the following methods:

   /**
    * Get a JCR session corresponding to the repository
    * defined in the configuration and the default workspace.
    * @return a JCR session corresponding to the criteria
    * @throws RepositoryException if the session could not be created
    */
   Session getSession() throws RepositoryException;

   /**
    * Get a JCR session corresponding to the repository
    * defined in the configuration and the default workspace, using
    * the given user name and password.
    * @param userName the user name to use for the authentication
    * @param password the password to use for the authentication
    * @return a JCR session corresponding to the criteria
    * @throws RepositoryException if the session could not be created
    */
   Session getSession(String userName, String password) throws RepositoryException;

   /**
    * Get a JCR session corresponding to the repository
    * defined in the configuration and the given workspace.
    * @param workspace the name of the expected workspace
    * @return a JCR session corresponding to the criteria
    * @throws RepositoryException if the session could not be created
    */
   Session getSession(String workspace) throws RepositoryException;

   /**
    * Get a JCR session corresponding to the repository
    * defined in the configuration and the given workspace, using
    * the given user name and password.
    * @param workspace the name of the expected workspace
    * @param userName the user name to use for the authentication
    * @param password the password to use for the authentication
    * @return a JCR session corresponding to the criteria
    * @throws RepositoryException if the session could not be created
    */
   Session getSession(String workspace, String userName, String password) throws RepositoryException;

eXo JCR is a complete implementation of the standard JSR 170: Content Repository for Java TM Technology API, including Level 1, Level 2 and Additional Features specified in the JCR Specification.

The JSR170 specification does not define how permissions are managed or checked. So eXo JCR has implemented its own proprietary extension to manage and check permissions on nodes. In essence, this extension uses an Access Control List (ACL) policy model applied to eXo Organization model (see eXo Platform Organization Service).

An access control list (ACL) is a list of permissions attached to an object. An ACL specifies which users, groups or system processes are granted access to JCR nodes, as well as what operations are allowed to be performed on given objects.

eXo JCR Access Control is based on two facets applied to nodes :

Access Control nodetypes are not extendible: The access control mechanism works for exo:owneable and exo:privilegeable nodetypes only, not for their subtypes! So you cannot extend those nodetypes.

Autocreation: By default, newly created nodes are neither exo:privilegeable nor exo:owneable but it is possible to configure the repository to auto-create exo:privilegeable or/and exo:owneable thanks to eXo's JCR interceptors extension (see JCR Extensions)

OR-based Privilege Inheritance: Note, that eXo's Access Control implementation supports a privilege inheritance that follows a strategy of either...or/ and has only an ALLOW privilege mechanism (there is no DENY feature). This means that a session is allowed to perform some operations on some nodes if its identity has an appropriate permission assigned to this node. Only if there is no exo:permission property assigned to the node itself, the permissions of the node's ancestors are used.

In the following example, you see a node named "Politics" which contains two nodes named "Cats" and "Dogs".

<Politics  jcr:primaryType="nt:unstructured" jcr:mixinTypes="exo:owneable exo:datetime exo:privilegeable" exo:dateCreated="2009-10-08T18:02:43.687+02:00" 
exo:dateModified="2009-10-08T18:02:43.703+02:00" 
exo:owner="root" 
exo:permissions="any_x0020_read *:/platform/administrators_x0020_read *:/platform/administrators_x0020_add_node *:/platform/administrators_x0020_set_property *:/platform/administrators_x0020_remove">

<Cats jcr:primaryType="exo:article" 
jcr:mixinTypes="exo:owneable" 
exo:owner="marry"  
exo:summary="The_x0020_secret_x0020_power_x0020_of_x0020_cats_x0020_influences_x0020_the_x0020_leaders_x0020_of_x0020_the_x0020_world." 
exo:text="" exo:title="Cats_x0020_rule_x0020_the_x0020_world" />

<Dogs jcr:primaryType="exo:article" 
jcr:mixinTypes="exo:privilegeable" 
exo:permissions="manager:/organization_x0020_read manager:/organization_x0020_set_property"
exo:summary="Dogs" 
exo:text="" exo:title="Dogs_x0020_are_x0020_friends" />

</Politics>

The "Politics" node is exo:owneable and exo:privilegeable. It has both an exo:owner property and an exo:permissions property. There is an exo:owner="root" property so that the user root is the owner. In the exo:permissions value, you can see the ACL that is a list of access controls. In this example, the group *:/platform/administrators has all rights on this node (remember that the "*" means any kind of membership). any means that any users also have the read permission.s

As you see in the jcr:mixinTypes property, the "Cats" node is exo:owneable and there is an exo:owner="marry" property so that the user marry is the owner. The "Cats" node is not exo:privilegeable and has no exo:permissions. In this case, we can see the inheritance mechanism here is that the "Cats" node has the same permissions as "Politics" node.

Finally, the "Dogs" node is also a child node of "Politics". This node is not exo:owneable and inherits the owner of the "Politics" node (which is the user root). Otherwise, "Dogs" is exo:privilegeable and therefore, it has its own exo:permissions. That means only the users having a "manager" role in the group "/organization" and the user "root" have the rights to access this node.

This session describes how permission is validated for different JCR actions.

An extended Access Control system consists of:

Link Producer Service - a simple service, which generates an .lnk file, that is compatible with the Microsoft link file format. It is an extension of the REST Framework library and is included into the WebDav service. On dispatching a GET request the service generates the content of an .lnk file, which points to a JCR resource via WebDav.

Link Producer has a simple configuration like described below:

<component>
  <key>org.exoplatform.services.jcr.webdav.lnkproducer.LnkProducer</key>
  <type>org.exoplatform.services.jcr.webdav.lnkproducer.LnkProducer</type>
</component>

When using JCR the resource can be addressed by WebDav reference (href) like http://host:port/rest/jcr/repository/workspace/somenode/somefile.extention , the link servlet must be called for this resource by several hrefs, like http://localhost:8080/rest/lnkproducer/openit.lnk?path=/repository/workspace/somenode/somefile.extention

Please note, that when using the portal mode the REST servlet is available using a reference (href) like http://localhost:8080/portal/rest/...

The name of the .lnk file can be any. But for the best compatibility it must be the same as the name of the JCR resource.

Here is a step by step sample of a use case of the link producer... At first, type valid reference to the resource, using the link producer in your browser's adress field:

Internet Explorer will give a dialog window requesting to Open a file or to Save it. Click on the Open button

In Windows system an .lnk file will be downloaded and opened with the application which is registered to open the files, which are pointed to by the .lnk file. In case of a .doc file, Windows opens Microsoft Office Word which will try to open a remote file (test0000.doc). Maybe it will be necessary to enter USERNAME and PASSWORD.

Next, you will be able to edit the file in Microsoft Word.

The Link Producer is necessary for opening/editing and then saving the remote files in Microsoft Office Word, without any further updates.

Also the Link Producer can be referenced to from an HTML page. If page contains code like

<a href="http://localhost:8080/rest/lnkproducer/openit.lnk?path=/repository/workspace/somenode/somefile.extention">somefile.extention</a>

the file "somefile.extention" will open directly.

Processing binary large object (BLOB) is very important in eXo JCR, so this section focuses on explaining how to do it.

In both of the cases, a developer can set/update the binary Property via Node.setProperty(String, InputStream), Property.setValue(InputStream) as described in the spec JSR-170. Also, there is the setter with a ready Value object (obtainer from ValueFactory.createValue(InputStream)).

An example of a specification usage.

// Set the property value with given stream content. 
Property binProp = node.setProperty("BinData", myDataStream);
// Get the property value stream. 
InputStream binStream = binProp.getStream();

// You may change the binary property value with a new Stream, all data will be replaced
// with the content from the new stream.
Property updatedBinProp = node.setProperty("BinData", newDataStream);
// Or update an obtained property
updatedBinProp.setValue(newDataStream);
// Or update using a Value object 
updatedBinProp.setValue(ValueFactory.createValue(newDataStream));
// Get the updated property value stream. 
InputStream newStream = updatedBinProp.getStream();

But if you need to update the property sequentially and with partial content, you have no choice but to edit the whole data stream outside and get it back to the repository each time. In case of really large-sized data, the application will be stuck and the productivity will decrease a lot. JCR stream setters will also check constraints and perform common validation each time.

There is a feature of the eXo JCR extension that can be used for binary values partial writing without frequent session level calls. The main idea is to use a value object obtained from the property as the storage of the property content while writing/reading during runtime.

According to the spec JSR-170, Value interface provides the state of property that can't be changed (edited). The eXo JCR core provides ReadableBinaryValue and EditableBinaryValue interfaces which themselves extend JCR Value. The interfaces allow the user to partially read and change a value content.

ReadableBinaryValue value can be casted from any value, i.e. String, Binary, Date etc.

// get the property value of type PropertyType.STRING 
ReadableBinaryValue extValue = (ReadableBinaryValue) node.getProperty("LargeText").getValue();
// read 200 bytes to a destStream from the position 1024 in the value content
OutputStream destStream = new FileOutputStream("MyTextFile.txt");
extValue.read(destStream, 200, 1024);

But EditableBinaryValue can be applied only to properties of type PropertyType.BINARY. In other cases, a cast to EditableBinaryValue will fail.

After the value has been edited, the EditableBinaryValue value can be applied to the property using the standard setters (Property.setValue(Value), Property.setValues(Value), Node.setProperty(String, Value) etc.). Only after the EditableBinaryValue has been set to the property, it can be obtained in this session by getters (Property.getValue(), Node.getProperty(String) etc.).

The user can obtain an EditableBinaryValue instance and fill it with data in an interaction manner (or any other appropriated to the targets) and return (set) the value to the property after the content will be done.

// get the property value for PropertyType.BINARY Property
EditableBinaryValue extValue = (EditableBinaryValue) node.getProperty("BinData").getValue();

// update length bytes from the stream starting from the position 1024 in existing Value data
extValue.update(dataInputStream, dataLength, 1024);

// apply the edited EditableBinaryValue to the Property
node.setProperty("BinData", extValue);

// save the Property to persistence
node.save();

A practical example of the iterative usage. In this example, the value is updated with data from the sequence of streams and after the update is done, the value will be applied to the property and be visible during the session.

// update length bytes from the stream starting from the particular 
// position in the existing Value data
int dpos = 1024;
while (source.dataAvailable()) {
  extValue.update(source.getInputStream(), source.getLength(), dpos);
  dpos = dpos + source.getLength();
}

// apply the edited EditableBinaryValue to the Property
node.setProperty("BinData", extValue);

The goals of this section are:

Workspace Data Container (container) serves Repository Workspace persistent storage. WorkspacePersistentDataManager (data manager) uses container to perform CRUD operation on the persistent storage. Accessing to the storage in the data manager is implemented via storage connection obtained from the container (WorkspaceDataContainer interface implemenatiton). Each connection represents a transaction on the storage. Storage Connection (connection) should be an implementation of WorkspaceStorageConnection.

WorkspaceStorageConnection openConnection() throws RepositoryException;
WorkspaceStorageConnection openConnection(boolean readOnly) throws RepositoryException;
WorkspaceStorageConnection reuseConnection(WorkspaceStorageConnection original) throws RepositoryException;
boolean isCheckSNSNewConnection();

Container initialization is only based on a configuration. After the container has been created, it's not possible to change parameters. Configuration consists of implementation class and set of properties and Value Storages configuration.

Connection creation and reuse should be a thread safe operation. Connection provides CRUD operations support on the storage.

ItemData getItemData(String identifier) throws RepositoryException, IllegalStateException;
ItemData getItemData(NodeData parentData, QPathEntry name, ItemType itemType) throws RepositoryException, IllegalStateException;
List<NodeData> getChildNodesData(NodeData parent) throws RepositoryException, IllegalStateException;
List<NodeData> getChildNodesData(NodeData parent, ListList<QPathEntryFilter> pattern) throws RepositoryException, IllegalStateException;
List<PropertyData> getChildPropertiesData(NodeData parent) throws RepositoryException, IllegalStateException;
List<PropertyData> getChildPropertiesData(NodeData parent, List<QPathEntryFilter> pattern) throws RepositoryException, IllegalStateException;

This methiod specially dedicated for non-content modification operations (e.g. Items delete).

List<PropertyData> listChildPropertiesData(NodeData parent) throws RepositoryException, IllegalStateException;

It's REFERENCE type: Properties referencing Node with given nodeIdentifier. See more in javax.jcr.Node.getReferences()

List<PropertyData> getReferencesData(String nodeIdentifier) throws RepositoryException, IllegalStateException, UnsupportedOperationException;
boolean getChildNodesDataByPage(NodeData parent, int fromOrderNum, int toOrderNum, List<NodeData> childs) throws RepositoryException;
int getChildNodesCount(NodeData parent) throws RepositoryException;
int getLastOrderNumber(NodeData parent) throws RepositoryException;
void add(NodeData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException;
void add(PropertyData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException;
void update(NodeData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException;
void update(PropertyData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException;
void rename(NodeData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException;
void delete(NodeData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException;
void delete(PropertyData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException;
void prepare() throws IllegalStateException, RepositoryException;
void commit() throws IllegalStateException, RepositoryException;
void rollback() throws IllegalStateException, RepositoryException;

All methods throw IllegalStateException if connection is closed. UnsupportedOperationException if the method is not supported (e.g. JCR Level 1 implementation etc). RepositoryException if some errors occur during preparation, validation or persistence.

To implement Workspace data container, you need to do the following:

  1. Read a bit about the contract.

  2. Start a new implementation project pom.xml with org.exoplatform.jcr parent. It is not required, but will ease the development.

  3. Update sources of JCR Core and read JavaDoc on org.exoplatform.services.jcr.storage.WorkspaceDataContainer and org.exoplatform.services.jcr.storage.WorkspaceStorageConnection interfaces. They are the main part for the implemenation.

  4. Look at org.exoplatform.services.jcr.impl.dataflow.persistent.WorkspacePersistentDataManager sourcecode, check how data menager uses container and its connections (see in save() method)

  5. Create WorkspaceStorageConnection dummy implementation class. It's freeform class, but to be close to the eXo JCR, check how to implement JDBC ( org.exoplatform.services.jcr.impl.storage.jdbc.JDBCStorageConnection. Take in account usage of ValueStoragePluginProvider in both implementations.Value storage is an useful option for production versions. But leave it to the end of implementation work.

  6. Create the connection implementation unit tests to play TTD. (optional, but takes many benefits for the process)

  7. Implement CRUD starting from the read to write etc. Test the methods by using the external implementation ways of data read/write in your backend.

  8. When all methods of the connection done start WorkspaceDataContainer. Container class is very simple, it's like a factory for the connections only.

  9. Care about container reuseConnection(WorkspaceStorageConnection) method logic. For some backends, it cab be same as openConnection(), but for some others, it's important to reuse physical backend connection, e.g. to be in the same transaction - see JDBC container.

  10. It's almost ready to use in data manager. Start another test and go on.

When the container will be ready to run as JCR persistence storage (e.g. for this level testing), it should be configured in Repository configuration.

Assuming that our new implementation class name is org.project.jcr.impl.storage.MyWorkspaceDataContainer.

  <repository-service default-repository="repository">
  <repositories>
    <repository name="repository" system-workspace="production" default-workspace="production">
      .............
      <workspaces>
        <workspace name="production">
          <container class="org.project.jcr.impl.storage.MyWorkspaceDataContainer">
            <properties>
              <property name="propertyName1" value="propertyValue1" />
              <property name="propertyName2" value="propertyValue2" />
              .......
              <property name="propertyNameN" value="propertyValueN" />
            </properties>
            <value-storages>
              .......
            </value-storages>
          </container>

Container can be configured by using set properties.

It is a special service for data removal from database. The section shortly describes the principles of work DBCleanerTool under all databases.

It is special service for data removal from database. The article shortly describes the principles of work DBCleanerTool under all databases

This section will show you possible ways of improving JCR

It is intended to GateIn Administrators and those who wants to use JCR features.

For performance it is better to have loadbalacer, DB server and shared NFS on different computers. If in some reasons you see that one node gets more load than others you can decrease this load using load value in load balancer.

JGroups configuration

It's recommended to use "multiplexer stack" feature present in JGroups. It is set by default in eXo JCR and offers higher performance in cluster, using less network connections also. If there are two or more clusters in your network, please check that they use different ports and different cluster names.

Write performance in cluster

Exo JCR implementation uses Lucene indexing engine to provide search capabilities. But Lucene brings some limitations for write operations: it can perform indexing only in one thread. Thats why write performance in cluster is not higher than in singleton environment. Data is indexed on coordinator node, so increasing write-load on cluster may lead to ReplicationTimeout exception. It occurs because writing threads queue in the indexer and under high load timeout for replication to coordinator will be exceeded.

Taking in consideration this fact, it is recommended to exceed replTimeout value in cache configurations in case of high write-load.

Replication timeout

Some operations may take too much time. So if you get ReplicationTimeoutException try increasing replication timeout:

   <clustering mode="replication" clusterName="${jbosscache-cluster-name}">
      ...
      <sync replTimeout="60000" />
   </clustering>
   

value is set in miliseconds.

2.1. ExoContainer info
2.1.1. Container hierarchy
2.2. Service Configuration for Beginners
2.2.1. Requirements
2.2.2. Services
2.2.3. Configuration File
2.2.4. Execution Modes
2.2.5. Containers
2.2.6. Configuration Retrieval
2.2.7. Service instantiation
2.2.8. Miscellaneous
2.2.9. Further Reading
2.3. Service Configuration in Detail
2.3.1. Requirements
2.3.2. Sample Service
2.3.3. Parameters
2.3.4. External Plugin
2.3.5. Import
2.3.6. System properties
2.3.7. Understanding the prefixes supported by the configuration manager
2.4. Container Configuration
2.4.1. Kernel configuration namespace
2.4.2. Understanding how configuration files are loaded
2.4.3. eXo Container hot reloading
2.4.4. System property configuration
2.4.5. Variable Syntaxes
2.4.6. Runtime configuration profiles
2.4.7. Component request life cycle
2.4.8. Thread Context Holder
2.5. Inversion Of Control
2.5.1. How
2.5.2. Injection
2.5.3. Side effects
2.6. Services Wiring
2.6.1. Portal Instance
2.6.2. Introduction to the XML schema of the configuration.xml file
2.6.3. Configuration retrieval and log of this retrieval
2.7. Component Plugin Priority
2.8. Understanding the ListenerService
2.8.1. What is the ListenerService ?
2.8.2. How does it work?
2.8.3. How to configure a listener?
2.8.4. Concrete Example
2.9. Initial Context Binder
2.9.1. API
2.10. Job Scheduler Service
2.10.1. Where is Job Scheduler Service used in eXo Products?
2.10.2. How does Job Scheduler work?
2.10.3. Reference
2.11. eXo Cache
2.11.1. Basic concepts
2.11.2. Advanced concepts
2.11.3. eXo Cache extension
2.11.4. eXo Cache based on JBoss Cache
2.11.5. eXo Cache based on Infinispan
2.12. TransactionService
2.12.1. Existing TransactionService implementations
2.13. The data source provider
2.13.1. Configuration
2.14. JNDI naming
2.14.1. Prerequisites
2.14.2. How it works
2.14.3. Configuration examples
2.14.4. Recommendations for Application Developers
2.15. Logs configuration
2.15.1. Logs configuration initializer
2.15.2. Configuration examples
2.15.3. Tips and Troubleshooting
2.16. Manageability
2.16.1. Managed framework API
2.16.2. JMX Management View
2.16.3. Example
2.17. RPC Service
2.17.1. Configuration
2.17.2. The SingleMethodCallCommand

eXo Kernel is the basis of all eXo platform products and modules. Any component available in eXo Platform is managed by the Exo Container, our micro container responsible for gluing the services through dependency injection

Therefore, each product is composed of a set of services and plugins registered to the container and configured by XML configuration files.

The Kernel module also contains a set of very low level services.

This section provides you the basic knowledge about modes, services and containers. You will find out where the service configuration files should be placed, and you will also see the overriding mechanism of configurations.

Finally, you will understand how the container creates the services one after the other and what Inversion of Control really means.

Related documents

Nearly everything could be considered a service! To get a better idea, let's look into the exo-tomcat/lib folder where you find all deployed jar files.

For example you find services for databases, caching, ldap and ftp:

Of course, there are many more services, in fact a lot of these jar files are services. To find out you have to open the jar file and then look into its /conf or /conf/portal directory. Only if there is a file named configuration.xml, you are sure to have found a service.

Interface - Implementation It's important to get the idea that you separate the interface and implementation for a service. That is a good concept to reduce dependencies on specific implementations. This concept is well known for JDBC. If you use standard JDBC (=interface), you can connect any database (=implementation) to your application. In a similar way any service in eXo is defined by a java interface and may have many different implementations. The service implementation is then injected by a container into the application.

Singleton Each service has to be implemented as a singleton, which means that each service is created only once - in one single instance.

Service = Component You always read about services, and you imagine a service as a large application which does big things, but that's not true, a service can be just a little component that reads or transforms a document, therefore the term component is often used instead of service - so bear in mind: a service and a component can safely be considered to be the same thing.

The jar file of a service should contain a default configuration, you find this configuration in the configuration.xml file which comes with the jar. A configuration file can specify several services, as well as there can be several services in one jar file.

For example open the exo.kernel.component.cache-2.0.5.jar file and inside this jar open /conf/portal/configuration.xml. You will see:

 
<component>
<key>org.exoplatform.services.cache.CacheService</key> 
<type>org.exoplatform.services.cache.impl.CacheServiceImpl</type> 
...

Here you will note that a service is specified between the <component> tags. Each service has got a key, which defines the kind of service. As you imagine the content of the <key> tag matches the qualified java interface name (org.exoplatform.services.cache.CacheService) of the service. The specific implementation class of the CacheService is defined in the <type> tag.

Parameters You have already opened some configuration files and seen that there are more than just <key> and <type> tags. You can provide your service with init parameters. The parameters can be simple parameters, properties, or object-params. There are also plugins and they are special because the container calls the setters of your service in order to inject your plugin in your service (called setter injection) see Service Configuration in Detail. In general your service is free to use init parameters, they are not required.

If you ever need to create your own service, the minimum is to create an empty interface, an empty class and a constructor for your class - that's all. Ok, you also should put your class and the interface in a jar file and add a default configuration file.

In order to access to a service you need to use a Container. Just open https://github.com/exoplatform/kernel/tree/stable/2.4.x/exo.kernel.container/src/main/java/org/exoplatform/container.

Among the classes you see in this directory, you only will be interested in these three container types:

  • RootContainer: This is a base container. This container plays an important role during startup, but you should not use it directly.

  • PortalContainer: Created at the startup of the portal web application (in the init() method of the PortalController servlet)

  • StandaloneContainer: A context independent eXo Container. The StandaloneContainer is also used for unit tests.

Use only one container Even if there are several container types you always use exactly one. The RootContainer is never directly used and it depends on the execution mode if you use the PortalContainer or the StandaloneContainer. You will ask how to find out the execution mode in my application and how to manage these two modes. It's easy, you don't have to worry about it because the ExoContainerContext class provides a static method that allows you to get the right container from anywhere (see info box).

PicoContainer All containers inherit from the ExoContainer class which itself inherits from a PicoContainer. PicoContainer is a framework which allows eXo to apply the IoC (Inversion of Control) principles. The precise implementations of any service is unknown at compile time. Various implementations can be used, eXo supplies different implementations but they also may be delivered by other vendors. The decision which service to use during runtime is made in configuration files.

These configuration files are read by the container, the container adds all services to a list or more exactly a java HashTable. It's completely correct to suppose that the configuration.xml you already saw plays an important role. But there are more places where a configuration for a service can be defined as you see in the next section.

Note

"In your java code you have to use

ExoContainer myContainer = ExoContainerContext.getCurrentContainer();

in order to access to the current container. It doesn't greatly matter to your application if the current container is a PortalContainer or a StandaloneContainer. Once you have your container you may access to any service registered in this container using

MyService myService = (MyService) myContainer.getComponentInstance(MyService.class);

You easily realize that MyService.class is the name of the service interface.

The configuration you find inside the jar file is considered as the default configuration. If you want to override this default configuration you can do it in different places outside the jar. When the container finds several configurations for the same service, the configuration which is found later replaces completely the one found previously. Let's call this the configuration override mechanism.

As both containers, PortalContainer and StandaloneContainer, depend on the RootContainer, we will start by looking into this one.

The retrieval sequence in short:

HashTable The RootContainer creates a java HashTable which contains key-value pairs for the services. The qualified interface name of each service is used as key for the hashtable. Hopefully you still remember that the <key> tag of the configuration file contains the interface name? The value of each hashtable pair is an object that contains the service configuration (yes, this means the whole structure between the <component> tags of your configuration.xml file).

The RootContainer runs over all jar files you find in exo-tomcat/lib and looks if there is a configuration file at /conf/configuration.xml, the services configured in this file are added to the hashtable. That way - at the end of this process - the default configurations for all services are stored in the hashtable.

If you wish to provide your own configurations for one or several services, you can do it in a general configuration file that has to be placed at exo-tomcat/exo-conf/configuration.xml. Do not search for such a file on your computer - you won't find one, because this option is not used in the default installation. Here again the same rule applies: The posterior configuration replaces the previous one.

The further configuration retrieval depends on the container type.

The PortalContainer takes the hashtable filled by the RootContainer and continues to look in some more places. Here you get the opportunity to replace RootContainer configurations by those which are specific to your portal. Again, the configurations are overridden whenever necessary.

In short PortalContainer configurations are retrieved in the following lookup sequence :

You see, here the /conf/portal/configuration.xml file of each jar enters the game, they are searched at first. Next, there is nearly always a configuration.xml in the portal.war file (or in the portal webapp folder), you find this file at /WEB-INF/conf/configuration.xml. If you open it, you will find a lot of import statements that point to other configuration files in the same portal.war (or portal webapp).

Multiple Portals Be aware that you might set up several different portals ("admin", "mexico", etc.), and each of these portals will use a different PortalContainer. And each of these PortalContainers can be configured separately. As of GateIn you also will be able to provide configurations from outside the jars and wars or webapps. Put a configuration file in exo-tomcat/exo-conf/portal/$portal_name/configuration.xml where $portal_name is the name of the portal you want to configure for . But normally you only have one portal which is called "portal" so you use exo-tomcat/exo-conf/portal/portal/configuration.xml.

In the same way as the PortalContainer the StandaloneContainer takes over the configuration of the RootContainer. After that our configuration gets a little bit more tricky because standalone containers can be initialized using an URL. This URL contains a link to an external configuration. As you probably never need a standalone configuration you can safely jump over the remaining confusing words of this section.

After taking over RootContainer's configuration, there are three cases which depend on the URL initialization, :

As you have already learned the services are all singletons, so that the container creates only one single instance of each container. The services are created by calling the constructors (called constructor injection). If there are only zero-arguments constructors (Foo public Foo(){}) there are no problems to be expected. That's easy.

But now look at OrganizationServiceImpl.java

This JDBC implementation of BaseOrganizationService interface has only one constructor:

public OrganizationServiceImpl(ListenerService listenerService, DatabaseService dbService);

You see this service depends on two other services. In order to be able to call this constructor the container first needs a ListenerService and a DatabaseService. Therefore these services must be instantiated before BaseOrganizationService, because BaseOrganizationService depends on them.

For this purpose the container first looks at the constructors of all services and creates a matrix of service dependencies in order to call the services in a proper order. If for any reason there are interdependencies or circular dependencies you will get a java Exception. In this way the dependencies are injected by the container.

Note

What happens if one service has more than one constructor? The container always tries first to use the constructor with a maximum number of arguments, if this is not possible the container continues step by step with constructors that have less arguments until arriving at the zero-argument constructor (if there is any).

Retrospection. Do you remember your last project where you had some small components and several larger services? How was this organized? Some services had their own configuration files, others had static values in the source code. Most components were probably tightly coupled to the main application, or you called static methods whenever you needed a service in your java class. Presumably you even copied the source code of an earlier project in order to adapt the implementation to your needs. In short:

New Approach. You have seen that eXo uses the Inversion of Control (IoC) pattern which means that the control of the services is given to an independent outside entity, in this case a container. Now the container takes care of everything:

Dependency Injection. You also saw two types of dependency injections:

Do you feel yourself to be an expert now? Not yet? Get a deeper look and read this Services Wiring article. You read so much about configuration, that you should wonder what the XML Schema of the configuration file looks like.

If you wish to see examples of service configurations you should study the Core. Where you find descriptions of some eXo's core services. Finally you might wish to read more about PicoContainer.

This section shows you how to set up a sample service with some configurations and how to access the configuration parameters. The later sections describe all details of the configuration file (parameters, object-params, plugins, imports, and more). It also shows how to access the configuration values. You may consider this document as a reference, but you can also use this document as a tutorial and read it from the beginning to the end.

Related documents

You should have read and understood Service Configuration for Beginners. Obviously you should know java and xml. We are working with examples that are created for teaching reasons only and you will see extracts from the eXo Products default installation. When reading this article, you do not forget that the terms service and component are interchangeable in eXo Products.

You see your service has a configuration file, but you wonder how the file can gain access to its configuration. Imagine that you are asked to implement two different calculation methods: fast and exact.

You create one init parameter containing the calculation methods. For the exact method, you wish to configure more details for the service. Let's enhance the word service configuration file:

  <component>
    <key>com.laverdad.services.ArticleStatsService</key>
    <type>com.laverdad.services.ArticleStatsServiceImpl</type>
    <init-params>
      <value-param>
        <name>calc-method</name>
        <description>calculation method: fast, exact</description>
        <value>fast</value>
      </value-param>
      <properties-param>
        <name>details-for-exact-method</name>
        <description>details for exact phrase counting</description>
        <property name="language" value="English" />
        <property name="variant" value="us" />
      </properties-param>
    </init-params>
  </component>

Now let's see how our service can read this configuration. The implementation of the calcSentences() method serves just as a simple example. It's up to your imagination to implement the exact method.

public class ArticleStatsServiceImpl implements ArticleStatsService {

  private String calcMethod = "fast";
  private String variant = "French";
  private String language = "France";
  
  public ArticleStatsServiceImpl(InitParams initParams) {
    super();
    calcMethod = initParams.getValueParam("calc-method").getValue();
    PropertiesParam detailsForExactMethod = initParams.getPropertiesParam("details-for-exact-method");
    if ( detailsForExactMethod != null) {
      language = detailsForExactMethod.getProperty("language");
      variant = detailsForExactMethod.getProperty("variant");
    }
  }
  
  public int calcSentences(String article) {
    if (calcMethod == "fast") {
      // just count the number of periods "." 
      int res = 0;
      int period = article.indexOf('.');
      while (period != -1) {
        res++;
        article = article.substring(period+1);
        period = article.indexOf('.');
      }      
      return  res;
    } 
    throw new RuntimeException("Not implemented");
    }
}

You see you just have to declare a parameter of org.exoplatform.container.xml.InitParams in your constructor. The container provides an InitParams object that correspond to the xml tree of init-param.

As you want to follow the principle of Inversion of Control, you must not access the service directly. You need a Container to access the service.

With this command you get your current container:

This might be a PortalContainer or a StandaloneContainer, dependant on the execution mode in which you are running your application.

Whenever you need one of the services that you have configured use the method:

  • myContainer.getComponentInstance(class)

In our case:

  • ArticleStatsService statsService = (ArticleStatsService) myContainer.getComponentInstance(ArticleStatsService.class);

Recapitulation:

package com.laverdad.common;

import org.exoplatform.container.ExoContainer;
import org.exoplatform.container.ExoContainerContext;
import com.laverdad.services.*;

public class Statistics {

  public int makeStatistics(String articleText) {
    ExoContainer myContainer = ExoContainerContext.getCurrentContainer();
    ArticleStatsService statsService = (ArticleStatsService)
        myContainer.getComponentInstance(ArticleStatsService.class);    
    int numberOfSentences = statsService.calcSentences(articleText);
    return numberOfSentences;
  }
  
  public static void main( String args[]) {
   Statistics stats = new Statistics();
   String newText = "This is a normal text. The method only counts the number of periods. "
   + "You can implement your own implementation with a more exact counting. "
   + "Let`s make a last sentence.";
  System.out.println("Number of sentences: " + stats.makeStatistics(newText));
  }
}

If you test this sample in standalone mode, you need to put all jars of eXo Kernel in your buildpath, furthermore picoContainer is needed.

Let's have a look at the configuration of the LDAPService. It's not important to know LDAP, we only discuss the parameters.

<component>
    <key>org.exoplatform.services.ldap.LDAPService</key>
    <type>org.exoplatform.services.ldap.impl.LDAPServiceImpl</type>
    <init-params>
      <object-param>
        <name>ldap.config</name>
        <description>Default ldap config</description>
        <object type="org.exoplatform.services.ldap.impl.LDAPConnectionConfig">         
   <field  name="providerURL"><string>ldaps://10.0.0.3:636</string></field>
   <field  name="rootdn"><string>CN=Administrator,CN=Users,DC=exoplatform,DC=org</string></field>
   <field  name="password"><string>exo</string></field>
   <field  name="version"><string>3</string></field>
     <field  name="minConnection"><int>5</int></field>
       <field  name="maxConnection"><int>10</int></field>    
       <field  name="referralMode"><string>ignore</string></field>
       <field  name="serverName"><string>active.directory</string></field>
       </object>
      </object-param>
    </init-params>
</component>

You see here an object-param is being used to pass the parameters inside an object (actually a java bean). It consists of a name, a description and exactly one object. The object defines the type and a number of fields.

Here you see how the service accesses the object:

package org.exoplatform.services.ldap.impl;

public class LDAPServiceImpl implements LDAPService {
...
  public LDAPServiceImpl(InitParams params) {
    LDAPConnectionConfig config = (LDAPConnectionConfig) params.getObjectParam("ldap.config")
                                                               .getObject();
...

The passed object is LDAPConnectionConfig which is a classic java bean. It contains all fields and also the appropriate getters and setters (not listed here). You also can provide default values. The container creates a new instance of your bean and calls all setters whose values are configured in the configuration file.

package org.exoplatform.services.ldap.impl;

public class LDAPConnectionConfig {
  private String providerURL        = "ldap://127.0.0.1:389";
  private String rootdn;
  private String password;                                  
  private String version;                                   
  private String authenticationType = "simple";
  private String serverName         = "default";
  private int    minConnection;
  private int    maxConnection;
  private String referralMode       = "follow";
...

You see that the types (String, int) of the fields in the configuration correspond with the bean. A short glance in the kernel_1_0.xsd file let us discover more simple types:

Have a look on this type test xml file: object.xml.

You also can use java collections to configure your service. In order to see an example, let's open the database-organization-configuration.xml file. This file defines a default user organization (users, groups, memberships/roles) of your portal. They use component-plugins which are explained later. You wil see that object-param is used again.

There are two collections: The first collection is an ArrayList. This ArrayList contains only one value, but there could be more. The only value is an object which defines the field of the NewUserConfig$JoinGroup bean.

The second collection is a HashSet that is a set of strings.

    <component-plugin>
      <name>new.user.event.listener</name>
      <set-method>addListenerPlugin</set-method>
      <type>org.exoplatform.services.organization.impl.NewUserEventListener</type>
      <description>this listener assign group and membership to a new created user</description>
      <init-params>
        <object-param>
          <name>configuration</name>
          <description>description</description>
          <object type="org.exoplatform.services.organization.impl.NewUserConfig">
            <field  name="group">
              <collection type="java.util.ArrayList">
                <value>
                  <object type="org.exoplatform.services.organization.impl.NewUserConfig$JoinGroup">
                    <field  name="groupId"><string>/platform/users</string></field>
                    <field  name="membership"><string>member</string></field>
                  </object>
                </value>               
              </collection>
            </field>
            <field  name="ignoredUser">
              <collection type="java.util.HashSet">
                <value><string>root</string></value>
                <value><string>john</string></value>
                <value><string>marry</string></value>
                <value><string>demo</string></value>
                <value><string>james</string></value>
              </collection>
            </field>
          </object>
        </object-param>
      </init-params>
    </component-plugin>

Let's look at the org.exoplatform.services.organization.impl.NewUserConfig bean:

public class NewUserConfig {
  private List    role;
  private List    group;
  private HashSet ignoredUser;

  ...

  public void setIgnoredUser(String user) {
    ignoredUser.add(user);

  ...

  static public class JoinGroup {
    public String  groupId;
    public String  membership;
  ...
}

You see the values of the HashSet are set one by one by the container, and it's the responsibility of the bean to add these values to its HashSet.

The JoinGroup object is just an inner class and implements a bean of its own. It can be accessed like any other inner class using NewUserConfig.JoinGroup.

The External Plugin allows you to add configuration on the fly.

As you have carefully read Service Configuration for Beginners you know that normally newer configurations always replaces previous configurations. An external plugin allows you to add configuration without replacing previous configurations.

That can be interesting if you adapt a service configuration for your project-specific needs (country, language, branch, project, etc.).

Let's have a look at the configuration of the TaxonomyPlugin of the CategoriesService:

 <external-component-plugins>
    <target-component>org.exoplatform.services.cms.categories.CategoriesService</target-component>    
    <component-plugin>
     <name>predefinedTaxonomyPlugin</name>
      <set-method>addTaxonomyPlugin</set-method>
      <type>org.exoplatform.services.cms.categories.impl.TaxonomyPlugin</type>
      <init-params>
       <value-param>
          <name>autoCreateInNewRepository</name>
          <value>true</value>
         </value-param>         
         <value-param>
          <name>repository</name>
          <value>repository</value>
         </value-param>         
       <object-param>
        <name>taxonomy.configuration</name>
           <description>configuration predefined taxonomies to inject in jcr</description>
           <object type="org.exoplatform.services.cms.categories.impl.TaxonomyConfig">            
            <field  name="taxonomies">
             <collection type="java.util.ArrayList">
               <!-- cms taxonomy -->
              <value>
               <object type="org.exoplatform.services.cms.categories.impl.TaxonomyConfig$Taxonomy">
                 <field  name="name"><string>cmsTaxonomy</string></field>                              
                <field  name="path"><string>/cms</string></field>                                              
               </object>
              </value>
              <value> 
               <object type="org.exoplatform.services.cms.categories.impl.TaxonomyConfig$Taxonomy">
                 <field  name="name"><string>newsTaxonomy</string></field>                              
                <field  name="path"><string>/cms/news</string></field>                                              
               </object>
              </value>
            </field>                     
           </object>
       </object-param>
     </init-params>
   </component-plugin>
<external-component-plugins>

The <target-component> defines the service for which the plugin is defined. The configuration is injected by the container using a method that is defined in <set-method>. The method has exactly one argument of the type org.exoplatform.services.cms.categories.impl.TaxonomyPlugin:

  • addTaxonomyPlugin(org.exoplatform.services.cms.categories.impl.TaxonomyPlugin plugin)

The content of <init-params> corresponds to the structure of the TaxonomyPlugin object.

Note

You can configure the component CategoriesService using the addTaxonomyPlugin as often as you wish, you can also call addTaxonomyPlugin in different configuration files. The method addTaxonomyPlugin is then called several times, everything else depends on the implementation of the method.

The configuration manager allows you to find files using URL with special prefixes that we describe in details below.

GateIn uses PicoContainer, which implements the Inversion of Control (IoC) design pattern. All eXo containers inherit from a PicoContainer. There are mainly two eXo containers used, each of them can provide one or several services. Each container service is delivered in a JAR file. This JAR file may contain a default configuration. The use of default configurations is recommended and most services provide it.

When a Pico Container searches for services and its configurations, each configurable service may be reconfigured to override default values or set additional parameters. If the service is configured in two or more places the configuration override mechanism will be used.

Confused? - You might be interested in the Service Configuration for Beginners section to understand the basics.

GateIn uses PicoContainer, which implements the Inversion of Control (IoC) design pattern. All eXo containers inherit from a PicoContainer. There are mainly two eXo containers used, each of them can provide one or several services. Each container service is delivered in a JAR file. This JAR file may contain a default configuration. The use of default configurations is recommended and most of services provide it.

When a Pico Container searches for services and its configurations, each configurable service may be reconfigured to override default values or set additional parameters. If the service is configured in two or more places, the configuration override mechanism will be used.

The container performs the following steps to make eXo Container configuration retrieval, depending on the container type.

After the processing of all configurations available in system, the container will initialize it and start each service in order of the dependency injection (DI).

The user/developer should be careful when configuring the same service in different configuration files. It's recommended to configure a service in its own JAR only. Or, in case of a portal configuration, strictly reconfigure the services in portal WAR files or in an external configuration.

There are services that can be (or should be) configured more than one time. This depends on business logic of the service. A service may initialize the same resource (shared with other services) or may add a particular object to a set of objects (shared with other services too). In the first case, it's critical who will be the last, i.e. whose configuration will be used. In the second case, it's no matter who is the first and who is the last (if the parameter objects are independent).

Since eXo JCR 1.12, we added a set of new features that have been designed to extend portal applications such as GateIn.

Now we can define precisely a portal container and its dependencies and settings thanks to the PortalContainerDefinition that currently contains the name of the portal container, the name of the rest context, the name of the realm, the web application dependencies ordered by loading priority (i.e. the first dependency must be loaded at first and so on..) and the settings.

To be able to define a PortalContainerDefinition, we need to ensure first of all that a PortalContainerConfig has been defined at the RootContainer level, see an example below:

  <component>
    <!-- The full qualified name of the PortalContainerConfig -->
    <type>org.exoplatform.container.definition.PortalContainerConfig</type>
    <init-params>
      <!-- The name of the default portal container -->
      <value-param>
        <name>default.portal.container</name>
        <value>myPortal</value>
      </value-param>
      <!-- The name of the default rest ServletContext -->
      <value-param>
        <name>default.rest.context</name>
        <value>myRest</value>
      </value-param>
      <!-- The name of the default realm -->
      <value-param>
        <name>default.realm.name</name>
        <value>my-exo-domain</value>
      </value-param>
     <!-- Indicates whether the unregistered webapps have to be ignored -->
     <value-param>
        <name>ignore.unregistered.webapp</name>
        <value>true</value>
     </value-param>
      <!-- The default portal container definition -->
      <!-- It cans be used to avoid duplicating configuration -->
      <object-param>
        <name>default.portal.definition</name>
        <object type="org.exoplatform.container.definition.PortalContainerDefinition">
          <!-- All the dependencies of the portal container ordered by loading priority -->
          <field name="dependencies">
            <collection type="java.util.ArrayList">
              <value>
                <string>foo</string>
              </value>
              <value>
                <string>foo2</string>
              </value>
              <value>
                <string>foo3</string>
              </value>
            </collection>
          </field>        
          <!-- A map of settings tied to the default portal container -->
          <field name="settings">
            <map type="java.util.HashMap">
              <entry>
                <key>
                  <string>foo5</string>
                </key>
                <value>
                  <string>value</string>
                </value>
              </entry>
              <entry>
                <key>
                  <string>string</string>
                </key>
                <value>
                  <string>value0</string>
                </value>
              </entry>
              <entry>
                <key>
                  <string>int</string>
                </key>
                <value>
                  <int>100</int>
                </value>
              </entry>
            </map>
          </field>
          <!-- The path to the external properties file -->
          <field name="externalSettingsPath">
            <string>classpath:/org/exoplatform/container/definition/default-settings.properties</string>
          </field>
        </object>
      </object-param>
    </init-params>
  </component>

Note

All the value of the parameters marked with a (*) can be defined thanks to System properties like any values in configuration files but also thanks to variables loaded by the PropertyConfigurator. For example in GateIn by default, it would be all the variables defined in the file configuration.properties.

A new PortalContainerDefinition can be defined at the RootContainer level thanks to an external plugin, see an example below:

  <external-component-plugins>
    <!-- The full qualified name of the PortalContainerConfig -->
    <target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component>
    <component-plugin>
      <!-- The name of the plugin -->
      <name>Add PortalContainer Definitions</name>
      <!-- The name of the method to call on the PortalContainerConfig in order to register the PortalContainerDefinitions -->
      <set-method>registerPlugin</set-method>
      <!-- The full qualified name of the PortalContainerDefinitionPlugin -->
      <type>org.exoplatform.container.definition.PortalContainerDefinitionPlugin</type>
      <init-params>
        <object-param>
          <name>portal</name>
          <object type="org.exoplatform.container.definition.PortalContainerDefinition">
            <!-- The name of the portal container -->
            <field name="name">
              <string>myPortal</string>
            </field>
            <!-- The name of the context name of the rest web application -->
            <field name="restContextName">
              <string>myRest</string>
            </field>
            <!-- The name of the realm -->
            <field name="realmName">
              <string>my-domain</string>
            </field>
            <!-- All the dependencies of the portal container ordered by loading priority -->
            <field name="dependencies">
              <collection type="java.util.ArrayList">
                <value>
                  <string>foo</string>
                </value>
                <value>
                  <string>foo2</string>
                </value>
                <value>
                  <string>foo3</string>
                </value>
              </collection>
            </field>
            <!-- A map of settings tied to the portal container -->
            <field name="settings">
              <map type="java.util.HashMap">
                <entry>
                  <key>
                    <string>foo</string>
                  </key>
                  <value>
                    <string>value</string>
                  </value>
                </entry>
                <entry>
                  <key>
                    <string>int</string>
                  </key>
                  <value>
                    <int>10</int>
                  </value>
                </entry>
                <entry>
                  <key>
                    <string>long</string>
                  </key>
                  <value>
                    <long>10</long>
                  </value>
                </entry>
                <entry>
                  <key>
                    <string>double</string>
                  </key>
                  <value>
                    <double>10</double>
                  </value>
                </entry>
                <entry>
                  <key>
                    <string>boolean</string>
                  </key>
                  <value>
                    <boolean>true</boolean>
                  </value>
                </entry>                                
              </map>
            </field>            
            <!-- The path to the external properties file -->
            <field name="externalSettingsPath">
              <string>classpath:/org/exoplatform/container/definition/settings.properties</string>
            </field>
          </object>
        </object-param>
      </init-params>
    </component-plugin>
  </external-component-plugins>

Table 2.2. Descriptions of the fields of a PortalContainerDefinition when it is used to define a new portal container

name (*)The name of the portal container. This field is mandatory .
restContextName (*)The name of the context name of the rest web application. This field is optional. The default value will be defined at the PortalContainerConfig level.
realmName (*)The name of the realm. This field is optional. The default value will be defined at the PortalContainerConfig level.
dependenciesAll the dependencies of the portal container ordered by loading priority. This field is optional. The default value will be defined at the PortalContainerConfig level. The dependencies are in fact the list of the context names of the web applications from which the portal container depends. This field is optional. The dependency order is really crucial since it will be interpreted the same way by several components of the platform. All those components, will consider the 1st element in the list less important than the second element and so on. It is currently used to:
  • Know the loading order of all the dependencies.

  • If we have several PortalContainerConfigOwner

    • The ServletContext of all the PortalContainerConfigOwner will be unified, if we use the unified ServletContext (PortalContainer.getPortalContext()) to get a resource, it will try to get the resource in the ServletContext of the most important PortalContainerConfigOwner (i.e. last in the dependency list) and if it cans find it, it will try with the second most important PortalContainerConfigOwner and so on.

    • The ClassLoader of all the PortalContainerConfigOwner will be unified, if we use the unified ClassLoader (PortalContainer.getPortalClassLoader()) to get a resource, it will try to get the resource in the ClassLoader of the most important PortalContainerConfigOwner (i.e. last in the dependency list) and if it can find it, it will try with the second most important PortalContainerConfigOwner and so on.

settingsA java.util.Map of internal parameters that we would like to tie the portal container. Those parameters could have any type of value. This field is optional. If some internal settings are defined at the PortalContainerConfig level, the two maps of settings will be merged. If a setting with the same name is defined in both maps, it will keep the value defined at the PortalContainerDefinition level.
externalSettingsPathThe path of the external properties file to load as default settings to the portal container. This field is optional. If some external settings are defined at the PortalContainerConfig level, the two maps of settings will be merged. If a setting with the same name is defined in both maps, it will keep the value defined at the PortalContainerDefinition level. The external properties files can be either of type "properties" or of type "xml". The path will be interpreted as follows:
  1. The path doesn't contain any prefix of type "classpath:", "jar:" or "file:", we assume that the file could be externalized so we apply the following rules:

    1. A file exists at ${exo-conf-dir}/portal/${portalContainerName}/${externalSettingsPath}, we will load this file.

    2. No file exists at the previous path, we then assume that the path cans be interpreted by the ConfigurationManager.

  2. The path contains a prefix, we then assume that the path cans be interpreted by the ConfigurationManager.


Table 2.3. Descriptions of the fields of a PortalContainerDefinition when it is used to define the default portal container

name (*)The name of the portal container. This field is optional. The default portal name will be:
  1. If this field is not empty, then the default value will be the value of this field.

  2. If this field is empty and the value of the parameter default.portal.container is not empty, then the default value will be the value of the parameter.

  3. If this field and the parameter default.portal.container are both empty, the default value will be "portal".

restContextName (*)The name of the context name of the rest web application. This field is optional. The default value wil be:
  1. If this field is not empty, then the default value will be the value of this field.

  2. If this field is empty and the value of the parameter default.rest.context is not empty, then the default value will be the value of the parameter.

  3. If this field and the parameter default.rest.context are both empty, the default value will be "rest".

realmName (*)The name of the realm. This field is optional. The default value wil be:
  1. If this field is not empty, then the default value will be the value of this field.

  2. If this field is empty and the value of the parameter default.realm.name is not empty, then the default value will be the value of the parameter.

  3. If this field and the parameter default.realm.name are both empty, the default value will be "exo-domain".

dependenciesAll the dependencies of the portal container ordered by loading priority. This field is optional. If this field has a non empty value, it will be the default list of dependencies.
settingsA java.util.Map of internal parameters that we would like to tie the default portal container. Those parameters could have any type of value. This field is optional.
externalSettingsPathThe path of the external properties file to load as default settings to the default portal container. This field is optional. The external properties files can be either of type "properties" or of type "xml". The path will be interpreted as follows:
  1. The path doesn't contain any prefix of type "classpath:", "jar:" or "file:", we assume that the file could be externalized so we apply the following rules:

    1. A file exists at ${exo-conf-dir}/portal/${externalSettingsPath}, we will load this file.

    2. No file exists at the previous path, we then assume that the path cans be interpreted by the ConfigurationManager.

  2. The path contains a prefix, we then assume that the path cans be interpreted by the ConfigurationManager.


Note

All the value of the parameters marked with a (*) can be defined thanks to System properties like any values in configuration files but also thanks to variables loaded by the PropertyConfigurator. For example in GateIn by default, it would be all the variables defined in the file configuration.properties.

Internal and external settings are both optional, but if we give a non empty value for both the application will merge the settings. If the same setting name exists in both settings, we apply the following rules:

  1. The value of the external setting is null, we ignore the value.

  2. The value of the external setting is not null and the value of the internal setting is null, the final value will be the external setting value that is of type String.

  3. Both values are not null, we will have to convert the external setting value into the target type which is the type of the internal setting value, thanks to the static method valueOf(String), the following sub-rules are then applied:

    1. The method cannot be found, the final value will be the external setting value that is of type String.

    2. The method can be found and the external setting value is an empty String, we ignore the external setting value.

    3. The method can be found and the external setting value is not an empty String but the method call fails, we ignore the external setting value.

    4. The method can be found and the external setting value is not an empty String and the method call succeeds, the final value will be the external setting value that is of type of the internal setting value.

We can inject the value of the portal container settings into the portal container configuration files thanks to the variables which name start with "portal.container.", so to get the value of a setting called "foo", just use the following syntax ${portal.container.foo}. You can also use internal variables, such as:


You can find below an example of how to use the variables:

<configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd http://www.exoplatform.org/xml/ns/kernel_1_3.xsd"
  xmlns="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd">
  <component>
    <type>org.exoplatform.container.TestPortalContainer$MyComponent</type>
    <init-params>
      <!-- The name of the portal container -->
      <value-param>
        <name>portal</name>
        <value>${portal.container.name}</value>
      </value-param>
      <!-- The name of the rest ServletContext -->
      <value-param>
        <name>rest</name>
        <value>${portal.container.rest}</value>
      </value-param>
      <!-- The name of the realm -->
      <value-param>
        <name>realm</name>
        <value>${portal.container.realm}</value>
      </value-param>
      <value-param>
        <name>foo</name>
        <value>${portal.container.foo}</value>
      </value-param>
      <value-param>
        <name>before foo after</name>
        <value>before ${portal.container.foo} after</value>
      </value-param>
    </init-params>
  </component>
</configuration>

In the properties file corresponding to the external settings, you can reuse variables previously defined (in the external settings or in the internal settings) to create a new variable. In this case, the prefix "portal.container." is not needed, see an example below:

my-var1=value 1
my-var2=value 2
complex-value=${my-var1}-${my-var2}

In the external and internal settings, you can also use create variables based on value of System paramaters. The System parameters can either be defined at launch time or thanks to the PropertyConfigurator (see next section for more details). See an example below:

temp-dir=${java.io.tmpdir}${file.separator}my-temp

However, for the internal settings, you can use System parameters only to define settings of type java.lang.String.

It cans be also very usefull to define a generic variable in the settings of the default portal container, the value of this variable will change according to the current portal container. See below an example:

my-generic-var=value of the portal container "${name}"

If this variable is defined at the default portal container level, the value of this variable for a portal container called "foo" will be value of the portal container "foo".

It is possible to use component-plugin elements in order to dynamically change a PortalContainerDefinition. In the example below, we add the dependency foo to the default portal container and to the portal containers called foo1 and foo2:

<external-component-plugins>
  <!-- The full qualified name of the PortalContainerConfig -->
  <target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component>
  <component-plugin>
    <!-- The name of the plugin -->
    <name>Change PortalContainer Definitions</name>
    <!-- The name of the method to call on the PortalContainerConfig in order to register the changes on the PortalContainerDefinitions -->
    <set-method>registerChangePlugin</set-method>
    <!-- The full qualified name of the PortalContainerDefinitionChangePlugin -->
    <type>org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin</type>
    <init-params>
      <value-param>
        <name>apply.default</name>
        <value>true</value>
      </value-param>
      <values-param>
        <name>apply.specific</name>
        <value>foo1</value>
        <value>foo2</value>
      </values-param>  
      <object-param>
        <name>change</name>
        <object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependencies">
          <!-- The list of name of the dependencies to add -->
          <field name="dependencies">
            <collection type="java.util.ArrayList">
              <value>
                <string>foo</string>
              </value>
            </collection>
          </field>
        </object>
      </object-param>     
    </init-params>
  </component-plugin>
</external-component-plugins>

Note

All the value of the parameters marked with a (*) can be defined thanks to System properties like any values in configuration files but also thanks to variables loaded by the PropertyConfigurator. For example in GateIn by default, it would be all the variables defined in the file configuration.properties.

To identify the portal containers to which the changes have to be applied, we use the follwing algorithm:

  1. The parameter apply.all has been set to true. The corresponding changes will be applied to all the portal containers. The other parameters will be ignored.

  2. The parameter apply.default has been set to true and the parameter apply.specific is null. The corresponding changes will be applied to the default portal container only.

  3. The parameter apply.default has been set to true and the parameter apply.specific is not null. The corresponding changes will be applied to the default portal container and the given list of specific portal containers.

  4. The parameter apply.default has been set to false or has not been set and the parameter apply.specific is null. The corresponding changes will be applied to the default portal container only.

  5. The parameter apply.default has been set to false or has not been set and the parameter apply.specific is not null. The corresponding changes will be applied to the given list of specific portal containers.

The modifications that can be applied to a PortalContainerDefinition must be a class of type PortalContainerDefinitionChange. The product proposes out of the box some implementations that we describe in the next sub sections.

This modification adds a list of dependencies at the end of the list of dependencies defined into the PortalContainerDefinition. The full qualified name is org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependencies.


See an example below, that will add foo at the end of the dependency list of the default portal container:

<external-component-plugins>
  <!-- The full qualified name of the PortalContainerConfig -->
  <target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component>
  <component-plugin>
    <!-- The name of the plugin -->
    <name>Change PortalContainer Definitions</name>
    <!-- The name of the method to call on the PortalContainerConfig in order to register the changes on the PortalContainerDefinitions -->
    <set-method>registerChangePlugin</set-method>
    <!-- The full qualified name of the PortalContainerDefinitionChangePlugin -->
    <type>org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin</type>
    <init-params>
      <value-param>
        <name>apply.default</name>
        <value>true</value>
      </value-param>
      <object-param>
        <name>change</name>
        <object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependencies">
          <!-- The list of name of the dependencies to add -->
          <field name="dependencies">
            <collection type="java.util.ArrayList">
              <value>
                <string>foo</string>
              </value>
            </collection>
          </field>
        </object>
      </object-param>     
    </init-params>
  </component-plugin>
</external-component-plugins>

This modification adds a list of dependencies before a given target dependency defined into the list of dependencies of the PortalContainerDefinition. The full qualified name is org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependenciesBefore.


See an example below, that will add foo before foo2 in the dependency list of the default portal container:

<external-component-plugins>
  <!-- The full qualified name of the PortalContainerConfig -->
  <target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component>
  <component-plugin>
    <!-- The name of the plugin -->
    <name>Change PortalContainer Definitions</name>
    <!-- The name of the method to call on the PortalContainerConfig in order to register the changes on the PortalContainerDefinitions -->
    <set-method>registerChangePlugin</set-method>
    <!-- The full qualified name of the PortalContainerDefinitionChangePlugin -->
    <type>org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin</type>
    <init-params>
      <value-param>
        <name>apply.default</name>
        <value>true</value>
      </value-param>
      <object-param>
        <name>change</name>
        <object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependenciesBefore">
          <!-- The list of name of the dependencies to add -->
          <field name="dependencies">
            <collection type="java.util.ArrayList">
              <value>
                <string>foo</string>
              </value>
            </collection>
          </field>
          <!-- The name of the target dependency -->
          <field name="target">
            <string>foo2</string>
          </field>
        </object>
      </object-param>     
    </init-params>
  </component-plugin>
</external-component-plugins>

This modification adds a list of dependencies after a given target dependency defined into the list of dependencies of the PortalContainerDefinition. The full qualified name is org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependenciesAfter.


See an example below, that will add foo after foo2 in the dependency list of the default portal container:

<external-component-plugins>
  <!-- The full qualified name of the PortalContainerConfig -->
  <target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component>
  <component-plugin>
    <!-- The name of the plugin -->
    <name>Change PortalContainer Definitions</name>
    <!-- The name of the method to call on the PortalContainerConfig in order to register the changes on the PortalContainerDefinitions -->
    <set-method>registerChangePlugin</set-method>
    <!-- The full qualified name of the PortalContainerDefinitionChangePlugin -->
    <type>org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin</type>
    <init-params>
      <value-param>
        <name>apply.default</name>
        <value>true</value>
      </value-param>
      <object-param>
        <name>change</name>
        <object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependenciesAfter">
          <!-- The list of name of the dependencies to add -->
          <field name="dependencies">
            <collection type="java.util.ArrayList">
              <value>
                <string>foo</string>
              </value>
            </collection>
          </field>
          <!-- The name of the target dependency -->
          <field name="target">
            <string>foo2</string>
          </field>
        </object>
      </object-param>     
    </init-params>
  </component-plugin>
</external-component-plugins>

This modification adds new settings to a PortalContainerDefinition. The full qualified name is org.exoplatform.container.definition.PortalContainerDefinitionChange$AddSettings.


See an example below, that will add the settings string and stringX to the settings of the default portal container:

<external-component-plugins>
  <!-- The full qualified name of the PortalContainerConfig -->
  <target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component>
  <component-plugin>
    <!-- The name of the plugin -->
    <name>Change PortalContainer Definitions</name>
    <!-- The name of the method to call on the PortalContainerConfig in order to register the changes on the PortalContainerDefinitions -->
    <set-method>registerChangePlugin</set-method>
    <!-- The full qualified name of the PortalContainerDefinitionChangePlugin -->
    <type>org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin</type>
    <init-params>
      <value-param>
        <name>apply.default</name>
        <value>true</value>
      </value-param>
      <object-param>
        <name>change</name>
        <object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddSettings">
          <!-- The settings to add to the to the portal containers -->
          <field name="settings">
            <map type="java.util.HashMap">
              <entry>
                <key>
                  <string>string</string>
                </key>
                <value>
                  <string>value1</string>
                </value>
              </entry>
              <entry>
                <key>
                  <string>stringX</string>
                </key>
                <value>
                  <string>value1</string>
                </value>
              </entry>
            </map>
          </field>
        </object>
      </object-param>     
    </init-params>
  </component-plugin>
</external-component-plugins>

It is possible to use component-plugin elements in order to dynamically disable one or several portal containers. In the example below, we disable the portal container named foo:

<external-component-plugins>
  <!-- The full qualified name of the PortalContainerConfig -->
  <target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component>
  <component-plugin>
    <!-- The name of the plugin -->
    <name>Disable a PortalContainer</name>
    <!-- The name of the method to call on the PortalContainerConfig in order to register the changes on the PortalContainerDefinitions -->
    <set-method>registerDisablePlugin</set-method>
    <!-- The full qualified name of the PortalContainerDefinitionDisablePlugin -->
    <type>org.exoplatform.container.definition.PortalContainerDefinitionDisablePlugin</type>
    <init-params>
      <!-- The list of the name of the portal containers to disable -->
      <values-param>
        <name>names</name>
        <value>foo</value>
      </values-param>
    </init-params>
  </component-plugin>
</external-component-plugins>

Note

All the value of the parameters marked with a (*) can be defined thanks to System properties like any values in configuration files but also thanks to variables loaded by the PropertyConfigurator. For example in GateIn by default, it would be all the variables defined in the file configuration.properties.

To prevent any accesses to a web application corresponding to PortalContainer that has been disabled, you need to make sure that the following Http Filter (or a sub class of it) has been added to your web.xml in first position as below:

<filter>
  <filter-name>PortalContainerFilter</filter-name>
  <filter-class>org.exoplatform.container.web.PortalContainerFilter</filter-class>
</filter>  

<filter-mapping>
  <filter-name>PortalContainerFilter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

Note

It is only possible to disable a portal container when at least one PortalContainerDefinition has been registered.

A new property configurator service has been developed for taking care of configuring system properties from the inline kernel configuration or from specified property files.

The services is scoped at the root container level because it is used by all the services in the different portal containers in the application runtime.

The kernel configuration is able to handle configuration profiles at runtime (as opposed to packaging time).

Profiles are configured in the configuration files of the eXo kernel.

A configuration element is profiles capable when it carries a profiles element.

The container package is responsible of building a hierarchy of containers. Each service will then be registered in one container or the other according to the XML configuration file it is defined in. It is important to understand that there can be several PortalContainer instances that all are children of the RootContainer.

The behavior of the hierarchy is similar to a class loader one, hence when you will lookup a service that depends on another one, the container will look for it in the current container and if it cannot be found, then it will look in the parent container. That way you can load all the reusable business logic components in the same container (here the RootContainer) and differentiate the service implementation from one portal instance to the other by just loading different service implementations in two sibling PortalContainers.

Therefore, if you look at the Portal Container as a service repository for all the business logic in a portal instance, then you understand why several PortalContainers allows you to manage several portals (each one deployed as a single war) in the same server by just changing XML configuration files.

The default configuration XML files are packaged in the service jar. There are three configuration.xml files, one for each container type. In that XML file, we define the list of services and their init parameters that will be loaded in the corresponding container.

After deploying you find the configuration.xml file in webapps/portal/WEB-INF/conf Use component registration tags. Let's look at the key tag that defines the interface and the type tag that defines the implementation. Note that the key tag is not mandatory, but it improves performance.

<!-- Portlet container hooks -->
  <component>
    <key>org.exoplatform.services.portletcontainer.persistence.PortletPreferencesPersister</key>
    <type>org.exoplatform.services.portal.impl.PortletPreferencesPersisterImpl</type>
  </component>

Register plugins that can act as listeners or external plugin to bundle some plugin classes in other jar modules. The usual example is the hibernate service to which we can add hbm mapping files even if those are deployed in an other maven artifact.

<external-component-plugins>
  <target-component>org.exoplatform.services.database.HibernateService</target-component>
  <component-plugin> 
    <name>add.hibernate.mapping</name>
    <set-method>addPlugin</set-method>
    <type>org.exoplatform.services.database.impl.AddHibernateMappingPlugin</type>
    <init-params>
      <values-param>
        <name>hibernate.mapping</name>
        <value>org/exoplatform/services/portal/impl/PortalConfigData.hbm.xml</value>
        <value>org/exoplatform/services/portal/impl/PageData.hbm.xml</value>
        <value>org/exoplatform/services/portal/impl/NodeNavigationData.hbm.xml</value>
      </values-param>        
    </init-params>
  </component-plugin>
</external-component-plugins>

In that sample we target the HibernateService and we will call its addPlugin() method with an argument of the type AddHibernateMappingPlugin. That object will first have been filled with the init parameters.

Therefore, it is possible to define services that will be able to receive plugins without implementing any framework interface.

Another example of use is the case of listeners as in the following code where a listener is added to the OrganisationService and will be called each time a new user is created:

<external-component-plugins>
  <target-component>org.exoplatform.services.organization.OrganizationService</target-component>
  <component-plugin>
    <name>portal.new.user.event.listener</name>
    <set-method>addListenerPlugin</set-method>
    <type>org.exoplatform.services.portal.impl.PortalUserEventListenerImpl</type>
    <description>this listener create the portal configuration for the new user</description>
    <init-params>
      <object-param>
        <name>configuration</name>
        <description>description</description>
        <object type="org.exoplatform.services.portal.impl.NewPortalConfig">
          <field  name="predefinedUser">
            <collection type="java.util.HashSet">
              <value><string>admin</string></value>
              <value><string>exo</string></value>
              <value><string>company</string></value>
              <value><string>community</string></value>
              <value><string>portal</string></value>
              <value><string>exotest</string></value>
            </collection>
          </field>
          <field  name="templateUser"><string>template</string></field>
          <field  name="templateLocation"><string>war:/conf/users</string></field>
        </object>
      </object-param>
    </init-params>
  </component-plugin>
...

In the previous XML configuration, we refer the organization service and we will call its method addListenerPlugin with an object of type PortalUserEventListenerImpl. Each time a new user will be created (apart the predefined ones in the list above) methods of the PortalUserEventListenerImpl will be called by the service.

As you can see, there are several types of init parameters, from a simple value param which binds a key with a value to a more complex object mapping that fills a JavaBean with the info defined in the XML.

Many other examples exist such as for the Scheduler Service where you can add a job with a simple XML configuration or the JCR Service where you can add a NodeType from your own configuration.xml file.

When the RootContainer is starting the configuration retrieval looks for configuration files in each jar available from the classpath at jar path /conf/portal/configuration.xml and from each war at path /WEB-INF/conf/configuration.xml. These configurations are added to a set. If a component was configured in a previous jar and the current jar contains a new configuration of that component the latest (from the current jar) will replace the previous configuration.

After the processing of all configurations available on the system the container will initialize it and start each component in order of the dependency injection (DI).

So, in general the user/developer should be careful when configuring the same components in different configuration files. It's recommended to configure service in its own jar only. Or, in case of a portal configuration, strictly reconfigure the component in portal files.

But, there are components that can be (or should be) configured more than one time. This depends on the business logic of the component. A component may initialize the same resource (shared with other players) or may add a particular object to a set of objects (shared with other players too). In the first case it's critical who will be the last, i.e. whose configuration will be used. In second case it doesn't matter who is the first and who is the last (if the parameter objects are independent).

In case of problems with configuration of component it's important to know from which jar/war it comes. For that purpose user/developer can set JVM system property org.exoplatform.container.configuration.debug, in command line:

java -Dorg.exoplatform.container.configuration.debug ...

With that property container configuration manager will report configuration adding process to the standard output (System.out).

   ......
   Add configuration jar:file:/D:/Projects/eXo/dev/exo-working/exo-tomcat/lib/exo.kernel.container-trunk.jar!/conf/portal/configuration.xml
   Add configuration jar:file:/D:/Projects/eXo/dev/exo-working/exo-tomcat/lib/exo.kernel.component.cache-trunk.jar!/conf/portal/configuration.xml
   Add configuration jndi:/localhost/portal/WEB-INF/conf/configuration.xml
        import jndi:/localhost/portal/WEB-INF/conf/common/common-configuration.xml
        import jndi:/localhost/portal/WEB-INF/conf/database/database-configuration.xml
        import jndi:/localhost/portal/WEB-INF/conf/ecm/jcr-component-plugins-configuration.xml
        import jndi:/localhost/portal/WEB-INF/conf/jcr/jcr-configuration.xml 
   ......

Since kernel version 2.0.6 it is possible to setup order of loading for ComponentPlugin. Use the ' priority' tag to define plugin's load priority. By default all plugins get priority '0'; they will be loaded in the container's natural way. If you want one plugin to be loaded later than the others then just set priority for it higher than zero.

Simple example of fragment of a configuration.xml.

...
<component>
  <type>org.exoplatform.services.Component1</type>
</component>

<external-component-plugins>
  <target-component>org.exoplatform.services.Component1</target-component>

  <component-plugin>
    <name>Plugin1</name>
    <set-method>addPlugin</set-method>
    <type>org.exoplatform.services.plugins.Plugin1</type>
    <description>description</description>
    <priority>1</priority>
  </component-plugin>

  <component-plugin>
    <name>Plugin2</name>
    <set-method>addPlugin</set-method>
    <type>org.exoplatform.services.plugins.Plugin2</type>
    <description>description</description>
    <priority>2</priority>
  </component-plugin>

</external-component-plugins>

<external-component-plugins>
  <target-component>org.exoplatform.services.Component1</target-component>
  <component-plugin>
    <name>Plugin3</name>
    <set-method>addPlugin</set-method>
    <type>org.exoplatform.services.plugins.Plugin3</type>
    <description>description</description>
  </component-plugin>
</external-component-plugins>
...

In the above example plugin 'Plugin3' will be loaded first because it has the default priority '0'. Then, plugin 'Plugin1' will be loaded and last one is plugin 'Plugin2'.

This section will first describe how the ListenerService works and then it will show you how to configure the ListenerService.

Related documents

Listeners must be subclasses of org.exoplatform.services.listener.Listener registered by the ListenerService.

To trigger an event, an application can call one of the broadcast() methods of ListenerService.

/**
 * This method is used to broadcast an event. This method should: 1. Check if
 * there is a list of listener that listen to the event name. 2. If there is a
 * list of listener, create the event object with the given name , source and
 * data 3. For each listener in the listener list, invoke the method
 * onEvent(Event)
 * 
 * @param <S> The type of the source that broadcast the event
 * @param <D> The type of the data that the source object is working on
 * @param name The name of the event
 * @param source The source object instance
 * @param data The data object instance
 * @throws Exception 
 */
public <S, D> void broadcast(String name, S source, D data) throws Exception {
   ...
}

/**
 * This method is used when a developer want to implement his own event object
 * and broadcast the event. The method should: 1. Check if there is a list of
 * listener that listen to the event name. 2. If there is a list of the
 * listener, For each listener in the listener list, invoke the method
 * onEvent(Event)
 * 
 * @param <T> The type of the event object, the type of the event object has
 *          to be extended from the Event type
 * @param event The event instance
 * @throws Exception
 */
public <T extends Event> void broadcast(T event) throws Exception {
   ...
}

The boadcast() methods retrieve the name of the event and find the registered listeners with the same name and call the method onEvent() on each listener found.

Each listener is a class that extends org.exoplatform.services.listener.Listener, as you