Workspace Setup

You are reading the CRX 2.3 version of Workspace Setup.
This documentation is also available for the following versions: CRX 2.2 CRX 2.1 CRX 2.0 (for CQ 5.3)

CRX stores its configuration in the file workspace.xml in the workspace folder. You can find the workspace folders in the folder crx-quickstart/repository/workspaces.

A configuration file looks like the following:

<?xml version="1.0" encoding="UTF-8"?>
<Workspace name="crx.default">

    <FileSystem class="com.day.crx.core.fs.local.LocalFileSystem">
        <param name="path" value="${wsp.home}"/>
    </FileSystem>

    <PersistenceManager class="com.day.crx.persistence.tar.TarPersistenceManager"/>

    <SearchIndex class="com.day.crx.query.lucene.LuceneHandler">
        <param name="useCompoundFile" value="true"/>
        <param name="minMergeDocs" value="1000"/>
        <param name="maxMergeDocs" value="100000"/>
        <param name="mergeFactor" value="10"/>
        <param name="path" value="${wsp.home}/index"/>
        <param name="onWorkspaceInconsistency" value="fix"/>
        <param name="queryClass" value="com.day.crx.query.lucene.CRXQueryImpl"/>
        <param name="extractorPoolSize" value="2"/>
        <param name="extractorTimeout" value="100"/>
        <param name="extractorBackLogSize" value="100"/>
    </SearchIndex>

</Workspace>

Workspace	The name of the workspace.
FileSystem	The virtual file system in which CRX stores the repository content. By default, CRX uses the local file system of the server. path: The path where CRX stores the workspace files. By default, this is the workspace folder.
PersistenceManager	The persistence manager that CRX uses to store the data. By default, CRX uses the Tar persistence manager.
SearchIndex	The search index you use to index and searchdata in CRX. By default, CRX uses the Lucene search engine. Note that you must specify the file system that the search engine uses to store the index file. useCompoundFile: The indexer merges the index files into larger segments, which require less file system overhead. minMergeDocs: The minimum number of files (documents and segments) that are merged into a new segment. maxMergeDocs:The maximum number of documents in a segment. Large segments produce more efficient search, but may require a long time to compile. mergeFactor: The number of files that are compiled into a segment. onWorkspaceInconsistency:To work with workspace inconsistencies, you can set CRX to either fix,fail, or ignore inconsistencies. The "fix" option fixes workspace inconsistencies (see important note that follows). If CRX is set to"ignore" inconsistencies, when an inconsistency occurs, an error message is written to the log and the inconsistency is ignored. If CRXis set to "fail" when an inconsistency occurs, an error message iswritten to the log and an exception is thrown, which causes CRX to shutdown. extractorPoolSize defines the maximum number of background threads that are used to extract text from binary properties. If set to zero (default), no background threads areallocated and text extractors run in the current thread. extractorTimeout:A text extractor is executed using a background thread if it does not finish within this timeout, defined in milliseconds. This parameter has no effect if extractorPoolSize is zero. extractorBackLogSize:The size of the extractor pool back log. If all threads in the pool are busy then all incoming work is put into a wait queue. If the wait queue reaches the back log size then the incoming extractor jobs will not be queued anymore, but will be executed with the current thread.

Note

In onWorkspaceInconsistency, the "fix" option relies on the method void PersistenceManager.checkConsistency(String[] uuids, boolean recursive, boolean fix) This means the "fix" option does not work with all persistence managers. Currently, only the TarPM and BundleDbPersistenceManagers implement this method and can actually fix an inconsistency. If you set onWorkspaceInconsistency=fix in CRX and the persistence manager cannot fix the inconsistency, CRX ignores it and continues the re-indexing process. In any case, an error message is written to the log.

Note

Lucene indexes string properties of up to 16k in length. Strings in excess of this will not be searched.

The default CRX configuration file already contains configuration entries for all of the options that CRX supports, such as storing the repository content in a database. If you define your own configuration entry, you can use the following variables:

${wsp.home}	The workspace folder. Save all workspace information in this folder, or a sub folder of it.
${wsp.name}	The name of the workspace.
${rep.home}	The repository folder. You can save repository information in a sub folder of the repository folder.

Using a Virtual File System

In addition to the repository content, there are a number of files that CRX uses. By default, CRX stores these files in the file system of the server on which it runs.

You can store these files in a central repository (such as a database) as well. To set up the repository, you can use the following variables:

${wsp.home}	The workspace folder. Save all workspace information in this folder, or a sub folder of it.
${wsp.name}	The name of the workspace.
${rep.home}	The repository folder. You can save repository information in a sub folder of the repository folder.

Note

If you store the configuration files in a database, they are much harder to edit and manage. If problems arise, they may be much harder to locate and fix than if the repository files are in the file system.

The Local File System

This is the default option and saves the CRX files in the file system of the server on which CRX runs. Use the following code for the <FileSystem> tag:

<FileSystem class="com.day.crx.core.fs.local.LocalFileSystem">
   <param name="path" value="${wsp.home}"/>
   <!-- param name="enableHandleMonitor" value="true" / -->
</FileSystem>

Path	The path where CRX saves the repository files.
enableHandleMonitor	This option is used for debugging purposes.

The DB File System

The DB file system saves the repository files in a standard SQL database. The configuration varies for different types of database. The following properties are supported:

driver	The FQN name of the JDBC driver class.
url	The database URL in the form jdbc:subprotocol:subname
user	The database user
password	The password of the database user
schema	The type of schema you want to use
schemaObjectPrefix	The prefix used for schema objects

Note

If you use different virtual file systems on the same database, make sure they have different values of the parameter schemaObjectPrefix. This makes sure that each virtual file system uses its own, separate tables to store the files.

MySQL

<FileSystem class="com.day.crx.core.fs.db.DbFileSystem">
   <param name="driver" value="com.mysql.jdbc.Driver"/>
   <param name="url" value="jdbc:mysql:///test"/>
   <param name="schema" value="mysql"/>
   <param name="schemaObjectPrefix" value="rep_"/>
</FileSystem>

Microsoft SQL Server

<FileSystem class="com.day.crx.core.fs.db.DbFileSystem">
   <param name="driver" value="com.microsoft.jdbc.sqlserver.SQLServerDriver"/>
   <param name="url" value="jdbc:microsoft:sqlserver://localhost:1433;DatabaseName=test;SelectMethod=Cursor"/>
   <param name="schema" value="mssql"/>
   <param name="user" value="sa"/>
   <param name="password" value=""/>
   <param name="schemaObjectPrefix" value="rep_"/>
</FileSystem>

PostgreSQL

<FileSystem class="com.day.crx.core.fs.db.DbFileSystem">
   <param name="driver" value="org.postgresql.Driver"/>
   <param name="url" value="jdbc:postgresql://localhost/test"/>
   <param name="schema" value="postgresql"/>
   <param name="user" value="postgres"/>
   <param name="password" value="postgres"/>
   <param name="schemaObjectPrefix" value="rep_"/>
</FileSystem>

The Oracle File System

The Oracle file system has the same configuration options as the DB file system, but contains some changes that take into account how Oracle databases work. A sample configuration for the Oracle file system looks as follows:

<FileSystem class="com.day.crx.core.fs.db.OracleFileSystem">
  <param name="url" value="jdbc:oracle:thin:@127.0.0.1:1521:orcl"/>
  <param name="user" value="scott"/>
  <param name="password" value="tiger"/>
  <param name="schemaObjectPrefix" value="rep_"/>
</FileSystem>

The Derby File System

The Derby file system has the same configuration options as the DB file system, but contains some changes that take into account how Derby databases work. A sample configuration for the Derby file system looks as follows:

<FileSystem class="com.day.crx.core.fs.db.DerbyFileSystem">
   <param name="url" value="jdbc:derby:${rep.home}/db;create=true"/>
   <param name="schemaObjectPrefix" value="rep_"/>
<FileSystem>

The DB2 File System

The DB2 file system has the same configuration options as the DB file system, but contains some changes that take into account how DB2 databases work. A sample configuration for the DB2 file system looks as follows:

<FileSystem class="com.day.crx.core.fs.db.DB2FileSystem">
   <param name="url" value="jdbc:db2:test"/>
   <param name="schemaObjectPrefix" value="rep_"/>
<FileSystem>

Adding a Workspace

To add a workspace, you have to add the workspace folder and the workspace.xml configuration file to the repository folder.

CRX stores the workspace configuration and the workspace content in a folder in the installation folder. To create a new workspace folder, proceed as follows:

1. Open your CRX workspace folder. A typical location for the folder is <crx-installation-folder>\crx-quickstart\repository\workspaces. This folder contains one folder for each workspace.

2. In the workspaces folder, create a new folder for your workspace.

3. Copy an existing workspace.xml file from an existing workspace into the new workspace folder.

Adapting the workspace.xml File

Open the file workspace.xml in an editor and adapt it to your needs. If you want to use the same configuration as for the original workspace, all you have to do is change the workspace name.

<?xml version="1.0" encoding="UTF-8"?>
<Workspace name="myWorkspace" simpleLocking="true">
        <!--
        virtual file system of the workspace:
        class: FQN of class implementing FileSystem interface
        -->
        <FileSystem class="org.apache.jackrabbit.core.fs.local.LocalFileSystem">
            <param name="path" value="${wsp.home}"/>
        </FileSystem>

        <!--
        persistence manager of the workspace:
        class: FQN of class implementing PersistenceManager interface
        -->
        <PersistenceManager class="com.day.crx.persistence.tar.TarPersistenceManager"/>

        <!--
        Search index and the file system it uses.
        -->
        <SearchIndex class="com.day.crx.query.lucene.LuceneHandler">
            <param name="path" value="${wsp.home}/index"/>
            <param name="resultFetchSize" value="50"/>
        </SearchIndex>

        <!--
        Workspace security configuration
        -->
        <WorkspaceSecurity>
            <AccessControlProvider class="org.apache.jackrabbit.core.security.authorization.acl.ACLProvider">
                <param name="omit-default-permission" value="true"/>
            </AccessControlProvider>
        </WorkspaceSecurity>

        <!--
        XML Import configuration of the workspace
        -->
        <Import>
            <ProtectedItemImporter class="org.apache.jackrabbit.core.xml.AccessControlImporter"/>
            <ProtectedItemImporter class="org.apache.jackrabbit.core.security.user.UserImporter">
                <param name="importBehavior" value="besteffort"/>
            </ProtectedItemImporter>
        </Import>
    </Workspace>

Note

If you store the workspace content in the file system or if you use the default persistence manager, CRX uses the folder you have created. If you use an external database, you may have to specify a new database name, so the new workspace does not conflict with the existing workspace.

After you have created the folder and adapted the configuration file, restart CRX. CRX now creates additional files or database entries to store the workspace content.

Re-Initializing a Workspace

If you modify the locations of workspace files, you need to re-initialize the workspace because CRX loses access to the existing workspace files, which renders the workspace unusable.

To re-initialize a workspace, you have to delete all workspace files (except for the file workspace.xml). CRX then re-creates a new, empty workspace from the settings in the workspace.xml file.

If you want to keep the workspace content, you have to export it, and then re-import it into the new workspace.

Virtual Workspace Mapping

To help you simplify workspace management, you can map a workspace to a node of an existing workspace. This allows you to combine the data of two workspaces into one.

For example, you can use this to store a user’s personal data in one workspace, and the global application in another. Your application can then access these data seamlessly.

Note

For instructions on how to set up a more comprehensive solution called virtual repository, see the Virtual Repository section in this guide. Virtual repository is targeted towards content integration from various sources via Adobe JCR Connectors and provides more flexibility and control over workspace mapping.

Usage

To use the virtual workspace mapping, refer to the documentation of the CRX Java classes AutoMountRepository and AutoMountRepositoryStartupService.

Limitations

When you map a virtual workspace into an existing one, the following limitations exist:

You can only map one secondary workspace into an existing workspace.
Both workspaces must belong to the same repository.
Workspace operations only work for the primary workspace. You cannot move, copy, clone or restore nodes in the secondary workspace, or into the secondary workspace.

Your comments are welcome!

Did you notice a way we could improve the documentation on this page? Is something unclear or insufficiently explained? Please leave your comments below and we will make the appropriate changes. Comments that have been addressed, by improving the documentation accordingly, will then be removed.

COMMENTS

By gmetz - 5:37 PM on May 26, 2010 Reply
Please note that the mergeFactor should NOT be set too high (eg. 1000), otherwise the index is nearly never merged.
So only increase it if you have a valid reason, and ask Day to first validate such configuration change.
By marat - 2:37 PM on Jun 30, 2010 Reply
this class com.day.crx.core.fs.db.OracleFileSystem and another DB Classes are not present in the crx-core-2.0.0.jar
Only LocalFileSystem class and MemoryFileSystem are presented under the package com.day.crx.core.fs.*

For DB File systems use the package org.apache.jackrabbit.core.fs.db.* from jackrabbit-core-2.0.0.jar

org.apache.jackrabbit.core.fs.db.OracleFileSystem

regards,
Marat Saitov
By Anonymous - 7:48 PM on Dec 08, 2011 Reply
Is there a way to acces different workspaces via URLs? For example I have a workspace "abc" and I have all the content under root cloned into this abc workspace from crx.default workspace. I am able to change the repository.xml's default workspace and see content specific to the abc repository. But I have to change this everytime and reboot. Is there a way to do this via url? In other words can I call the URL with a repository parameter and it goes to the repository based on that.

Thanks

ADD A COMMENT

In order to post a comment, you need to sign-in.

Note: Customers with DayCare user accounts need to create a new account for use on day.com.