JBoss.orgCommunity Documentation
This connector exposes an area of the local file system as a graph of "nt:file" and "nt:folder" nodes.
The connector can be configured so that the workspace name is either a path to the directory on the file system that represents the root of that
workspace or the name of subdirectory within a root directory (see the workspaceRootPath
property below). Each
connector can define whether it allows new workspaces to be created. If the directory for a workspace does not exist, this connector
will attempt to create the directory (and any missing parent directories).
By default, this connector is not capable of storing extra properties other than those defined on the nt:file
, nt:folder
and nt:resource
node types. This is because such properties cannot be represented natively on the file system.
When the connector is asked to store such properties, the default behavior is to log warnings and then to ignore these extra properties.
Obviously this is probably not sufficient for production (unless only the standard properties are to be used). To explicitly turn on this
behavior, set the "extraPropertiesBehavior" to "log".
However, the connector can be configured differently. If the "extraPropertiesBehavior" is set to "ignore", then these extra properties will simply be silently ignored and lost: none will be stored, none will be loaded, and no warnings will be logged. If the "extraPropertiesBehavior" is set to "error", the connector will throw an exception if any extra properties are used.
Perhaps the best setting for general use, however, is to set the "extraPropertiesBehavior" to "store". In this mode, any extra properties are written to files on the file system that are adjacent to the actual file or folder. For example, given a "nt:folder" node that represents the "folder1" directory, all extra properties will be stored in a text file named "folder1.modeshape" in the same parent directory as the "folder1" directory. Similarly, given a "nt:file" node that represents the "file1" file on the file system, all extra properties will be stored in a text file named "file1.modeshape" located next to the "file1" file. Note that the "nt:resource" node for our "nt:file" node also is stored in the same location, so we can't use the "file1.modeshape" file (it's already used for the "nt:file" node), so the connector uses the "file1.content.modeshape" file instead.
The "store" behavior may result in the creation of many "*.modeshape" files, and because of this the "store" behavior is not the default.
The FileSystemSource
class provides a number of JavaBean properties that control its behavior:
Table 13.1. FileSystemSource
properties
Property | Description |
---|---|
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". |
customPropertiesFactory |
Specifies the CustomPropertiesFactory implementation that should be used to augment the default properties
available on each node. This property can be set either from an object that implements the CustomPropertiesFactory
interface or from the name of a class with a public, no-argument constructor that implements the CustomPropertiesFactory
interface. In the latter case, a the named class will be instantiated and used as the custom properties factory implementation.
See also the "extraPropertiesBehavior" setting.
|
extraPropertiesBehavior | Optional setting that specifies how to handle the extra properties on "nt:file", "nt:folder", and "nt:resource" nodes that cannot be represented on the native files themselves. Set this to "log" if warnings are to be sent to the log (the default), or "error" if setting such properties should cause an error, or "store" if they should be stored in ancillary files next to the files and folders, or "ignore" if they should be silently ignored. The "log" value will be used by default or an invalid value is specified. This setting will be ignored if a "customPropertiesFactory" class name is specified. |
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. |
exclusionPattern |
Specifies a regular expression that is used to determine which files and folders in the underlying file system should be exposed through
this connector. Files and folders with a name that matches the provided regular expression will not be exposed by this source.
Setting this property to
This property is mutually incompatible with the |
filenameFilter |
Specifies the
This property can be set either from an object that implements the
This property is mutually incompatible with the |
name | The name of the repository source, which is used by the RepositoryService when obtaining a RepositoryConnection by name. |
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. |
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. |
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'. |
updatesAllowed | 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 "false" to avoid unintentional security vulnerabilities. |
workspaceRootPath |
Optional property that, if used, specifies a path on the local file system to the root of all workspaces. The source will will
use the name of the workspace as a relative path from the As an example for a workspace named |
One way to configure the file system connector is to create JcrConfiguration
instance with a repository source that uses the FileSystemSource
class.
For example:
JcrConfiguration config = ...
config.repositorySource("FS Store")
.usingClass(FileSystemSource.class)
.setDescription("The repository for our content")
.setProperty("workspaceRootPath", "/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 FileSystemSource
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 'FS Store' repository is a file system source with a three predefined workspaces
("prod", "staging", and "dev").
-->
<mode:source jcr:name="FS Store"
mode:classname="org.modeshape.connector.filesystem.FileSystemSource"
mode:description="The repository for our content"
mode:workspaceRootPath="/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 (300000 ms).
This fragment can be left out if the connector should not cache any content.
-->
<mode:cachePolicy jcr:name="cachePolicy"
mode:classname="org.modeshape.graph.connector.path.cache.InMemoryWorkspaceCache$InMemoryCachePolicy"
mode:timeToLiveInMilliseconds="300000" />
</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");