Chapter 18. Disk Connector

This connector stores content in a ModeShape-specific file format on disk. Although this may seem similar in concept to the File System Connector, this connector actually serves a much different purpose. While the File System Connector is designed to expose existing files and folders on the disk and allow ModeShape users to create content that can be read directly by other applications, the Disk Connector is designed for efficiency and stores content in a serialized representation that is not readily accessible to other applications. Conversely, the Disk Connector supports referenceable nodes and can efficiently access nodes by UUID, unlike the File System Connector.

The DiskSource class provides a number of JavaBean properties that control its behavior:

cachePolicy

Optional property that, if used, defines the cache policy for this repository source. When not used, this source will not define a specific duration for caching information.

creatingWorkspaceAllowed

Optional property that defines whether clients can create additional workspaces. The default value is "true".

defaultWorkspaceName

Optional property that is initialized to "default" and which defines the name for the workspace that will be used by default if none is specified.

largeValuePath

Optional, advanced property that, if specified, specifies the path to the large value area. This path is relative to the value of the repositoryRootPath property. The default value for this property is "largeValues" and it only needs to be changed if there will be a workspace named "largeValues".

largeValueSizeInBytes

Optional property that, if specified, sets the threshold for large values. Binary property values that exceed this size will be copied into the large value area for this repository, where they can be shared between nodes and lazily loaded to improve node retrieval time. The default value is "8192".

lockFileUsed

An advanced property that, if set to "true", indicates that repository read and write locks should be synchronized with file lock options on a file in the on-disk storage. This causes a performance penalty, but allows disk sources in different JVMS (e.g., clustered disk sources) to coordinate their locks as long as all cluster members share the same disk. This approach uses Java NIO file locking and is subject to the limitations of the Java NIO file locking for the current JVM implementation.

The default value is "false", but this should always be set to "true" when used in a clustered environment.

name

Required property that specifies the name of the repository source, which is used by the RepositoryService when obtaining a RepositoryConnection by name.

nodeCachePolicy

Optional property that, if used, defines the cache policy to use for caching nodes within the connector.

predefinedWorkspaceNames

Optional property that, if used, defines names of the workspaces that are predefined and need not be created before being used. This can be coupled with a "false" value for the "creatingWorkspaceAllowed" property to allow only the use of only predefined workspaces.

repositoryRootPath

Optional property that specifies a path on the local file system to the root of all workspaces. The connector will use this as the root for a file and folder structure for storing content. The default value is "/tmp", so setting this property to a more logical value is strongly recommended.

retryLimit

Optional property that, if used, defines the number of times that any single operation on a RepositoryConnection to this source should be retried following a communication failure. The default value is '0'.

rootNodeUuid

Optional property that, if used, specifies the UUID that should be used for the root node of each workspace. If no value is specified, a default UUID is used.

updatesAllowed

Optional property that determines whether the content in the file system can be updated ("true"), or if the content may only be read ("false"). The default value is "true".

One way to configure the file system connector is to create JcrConfiguration instance with a repository source that uses the DiskSource class. For example:



JcrConfiguration config = ...

config.repositorySource("Disk Store")

      .usingClass(DiskSource.class)

      .setDescription("The repository for our content")

      .setProperty("repositoryRootPath", "/home/content/someApp")

      .setProperty("defaultWorkspaceName", "prod")

      .setProperty("predefinedWorkspaceNames", new String[] { "staging", "dev"})

      .setProperty("rootNodeUuid", UUID.fromString("fd129c12-81a8-42ed-aa4b-820dba49e6f0")

      .setProperty("updatesAllowed", "true")

      .setProperty("creatingWorkspaceAllowed", "false");

Another way to configure the file system connector is to create JcrConfiguration instance and load an XML configuration file that contains a repository source that uses the DiskSource class. For example a file named configRepository.xml can be created with these contents:




<?xml version="1.0" encoding="UTF-8"?>

<configuration xmlns:mode="http://www.modeshape.org/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0">

    <!-- 

    Define the sources for the content.  These sources are directly accessible using the 

    ModeShape-specific Graph API. In fact, this is how the ModeShape JCR implementation works.  You can 

    think of these as being similar to JDBC DataSource objects, except that they expose graph 

    content via the Graph API instead of records via SQL or JDBC. 

    -->

    <mode:sources jcr:primaryType="nt:unstructured">

        <!-- 

        The 'Disk Store' repository is a disk source with a three predefined workspaces 

        ("prod", "staging", and "dev").

        -->

        <mode:source jcr:name="Disk Store" 

            mode:classname="org.modeshape.connector.disk.DiskSource"

            mode:description="The repository for our content"

            mode:repositoryRootPath="/home/content/someApp"

            mode:defaultWorkspaceName="prod"

            mode:creatingWorkspacesAllowed="false"

            mode:rootNodeUuid="fd129c12-81a8-42ed-aa4b-820dba49e6f0"

            mode:updatesAllowed="true" >

            <mode:predefinedWorkspaceNames>staging</mode:predefinedWorkspaceNames>

            <mode:predefinedWorkspaceNames>dev</mode:predefinedWorkspaceNames>

            <!-- 

            If desired, specify a cache policy that caches items in memory for 5 minutes (300 s).

            This fragment can be left out if the connector should not cache any content.

            -->

            <mode:cachePolicy jcr:name="nodeCachePolicy" 

              mode:classname="org.modeshape.graph.connector.base.cache.InMemoryNodeCache$MapCachePolicy"

              mode:timeToLive="300" />

        </mode:source>    

    </mode:sources>



    <!-- MIME type detectors and JCR repositories would be defined below --> 

</configuration>

The configuration can then be loaded from Java like this:



JcrConfiguration config = new JcrConfiguration().loadFrom("/configRepository.xml");