Prerequisites

Before you can use Maven to build an application that uses ModeShape, you'll need to have JDK 6 and Maven 3 installed.

All ModeShape releases since 3.0.0.Final are now available directly from the Maven Central repository. It takes a few hours (at least) after the artifacts are in the JBoss repository before they appear in Maven Central. So if you don't see a recent release in Maven Central, just give it a bit of time - or use the JBoss Maven repository.

Add ModeShape Dependencies

The next step is to edit your application or library's POM file and add the dependencies to the JCR API and ModeShape. The easiest way to do that is to use one of our Maven BOMs that specifies the versions for all of the ModeShape components and all of its dependencies:

<dependencyManagement>
  <dependencies>
    <!-- Import the ModeShape BOM for embedded usage. This adds to the "dependenciesManagement" section
         defaults for all of the modules we might need, but we still have to include in the
         "dependencies" section the modules we DO need. The benefit is that we don't have to
         specify the versions of any of those modules.-->
    <dependency>
      <groupId>org.modeshape.bom</groupId>
      <artifactId>modeshape-bom-embedded</artifactId>
      <version>3.7.2.Final</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Then include in the POM "<dependencies>" section the ModeShape modules that you will directly use. Note that you don't need to specify any of the versions, since that's what the modeshape-bom-embedded provided. The one module that you need to include is the primary JCR implementation:

<dependency>
  ...
  <dependency>
    <groupId>org.modeshape</groupId>
    <artifactId>modeshape-jcr</artifactId>
  </dependency>
  ...
</dependencies>

But you should also include any other modules that you'll either directly use or optional modules that you want to use. For example, if you're going to use any of ModeShape's public API (instead of just the JCR API), then you should include this dependency:

<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-jcr-api</artifactId>
</dependency>

If you want to use one of Infinispan's cache stores, then pick from ONE of the following:

<dependency>
   <groupId>org.infinispan</groupId>
   <artifactId>infinispan-cachestore-bdbje</artifactId>
</dependency>
<dependency>
   <groupId>org.infinispan</groupId>
   <artifactId>infinispan-cachestore-jdbm</artifactId>
</dependency>
<dependency>
   <groupId>org.infinispan</groupId>
   <artifactId>infinispan-cachestore-jdbc</artifactId>
</dependency>
<dependency>
   <groupId>org.infinispan</groupId>
   <artifactId>infinispan-cachestore-cassandra</artifactId>
</dependency>
<dependency>
   <groupId>org.infinispan</groupId>
   <artifactId>infinispan-cachestore-cloud</artifactId>
</dependency>

If you're going to use the JDBC Cache Store (e.g., "infinispan-cachestore-jdbc"), then you'll also need to add a dependency on the JDBC driver or embeddable database. For example, here's the dependency required to use the embeddable H2 database:

<dependency>
   <groupId>com.h2database</groupId>
   <artifactId>h2</artifactId>
   <version>1.1.117</version>
</dependency>

<project>
  <!-- ... -->
  <properties>
    <infinispan.version>5.2.7.Final</infinispan.version>
    <jgroups.version>3.2.10.Final</jgroups.version>
  </properties>
  <dependencies>
    <dependency>
      <groupId>org.infinispan</groupId>
      <artifactId>infinispan-core</artifactId>
      <version>${infinispan.version}</version>
    </dependency>
    <dependency>
      <groupId>org.infinispan</groupId>
      <artifactId>infinispan-cachestore-jdbm</artifactId>
      <version>${infinispan.version}</version>
    </dependency>
    <dependency>
      <groupId>org.jgroups</groupId>
      <artifactId>jgroups</artifactId>
      <version>${jgroups.version}</version>
    </dependency>
    <dependency>
      <groupId>javax.jcr</groupId>
      <artifactId>jcr</artifactId>
    </dependency>
    <dependency>
      <groupId>org.modeshape</groupId>
      <artifactId>modeshape-jcr-api</artifactId>
    </dependency>
    <dependency>
      <groupId>org.modeshape</groupId>
      <artifactId>modeshape-jcr</artifactId>
    </dependency>

    <!-- Other dependencies ... -->

  </dependencies>
  <dependencyManagement>
    <dependencies>
      <!-- Import the ModeShape BOM for embedded usage. This adds to the "dependenciesManagement" section
           defaults for all of the modules we might need, but we still have to include in the
           "dependencies" section the modules we DO need. The benefit is that we don't have to
           specify the versions of any of those modules.-->
      <dependency>
        <groupId>org.modeshape.bom</groupId>
        <artifactId>modeshape-bom-embedded</artifactId>
        <version>3.7.2.Final</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>
</project>

<project>
  <!-- ... -->
  <dependencies>
    <!-- ... -->
    <dependency>
       <groupId>org.jboss.jbossts</groupId>
       <artifactId>jbossjta</artifactId>
    </dependency>
    <!-- ... -->

  </dependencies>
  <!-- ... -->
</project>

<transaction
      transactionManagerLookupClass="<specify your TransactionManagerLookup implementation class here>"
      transactionMode="TRANSACTIONAL"
      lockingMode="OPTIMISTIC"/>

Configuring a ModeShape repository

The ModeShape engine is capable of running (or "deploying") multiple JCR repositories. However, each repository is configured separately and is completely independent from all other repositories. To configure a repository, you'll need a configuration file. Starting with ModeShape 3.0, these configuration files use the JSON format (which is a lot easier to read and create). Here is the minimum configuration file for a repository:

{ }

That's not a mistake. An empty JSON document is a completely valid repository configuration. Everything has a default value except for the repository's name, and the filename is used if one is not specified in the file. In this case, the name of this repository will be "my_repository".

Of course, lots of other options can be specified in the configuration file, but typically only the non-default values are specified. Since most of the defaults are sensible, many configurations will be pretty small.

Here's a configuration file that uses most of the available fields, most of which happen to be set the same values as the defaults. (This time we'll show line numbers so we can more easily describe what's going on.)

{
    "name" : "Test Repository",
    "jndiName" : "jcr/Test Repository",
    "monitoring" : {
        "enabled" : true
    },
    "workspaces" : {
        "default" : "defaultWorkspace",
        "predefined" : ["otherWorkspace"],
        "allowCreation" : true
    },
    "storage" : {
        "cacheConfiguration" : "/path/to/infinispan/cache/configuration.xml",
        "cacheName" : "Test Repository",
        "transactionManagerLookup" : "org.infinispan.transaction.lookup.GenericTransactionManagerLookup",
        "binaryStorage" : {
            "minimumBinarySizeInBytes" : 4096,
            "minimumStringSize" : 4096,
            "type" : "file"
        }
    },
    "security" : {
        "jaas" : {
            "policyName" : "modeshape-jcr"
        }
        "anonymous" : {
            "roles" : ["readonly","readwrite","admin"],
            "username" : "<anonymous>",
            "useOnFailedLogin" : false
        },
        "providers" : [
            {
                "classname" : "org.example.MyAuthorizationProvider",
                "member1" : "value of instance member1"
            }
        ]
    },
    "query" : {
        "enabled" : true,
        "rebuildUponStartup" : "if_missing", //DEPRECATED use indexing/rebuildOnStartup,
        "indexStorage" : {
            "type" : "filesystem",
            "location" : "/path/on/filesystem",
            "lockingStrategy" : "simple",
            "fileSystemAccessType" : "auto"
        },
        "indexing" : {
            "rebuildOnStartup": {
                "when" : "if_missing",
                "includeSystemContent": true,
                "mode": async
            },
            "threadPool" : "modeshape-workers",
            "analyzer" : "org.apache.lucene.analysis.standard.StandardAnalyzer",
            "similarity" : "org.apache.lucene.search.DefaultSimilarity",
            "indexFormat" : "LUCENE_CURRENT",
            "readerStrategy" : "shared",
            "backend" : {
                "type" : "lucene"
            },
            "batchSize" : -1,
            "mode" : "sync",
            "asyncThreadPoolSize" : 1,
            "asyncMaxQueueSize" : 0
        },
        "extractors" : [MODE:ModeShape and JBoss AS7]
    },
    "sequencing" : {
        "removeDerivedContentWithOriginal" : true,
        "threadPool" : "modeshape-workers",
        "sequencers" : [MODE:ModeShape and JBoss AS7] => /ddl"
            },
            {
                "name" : "XSD sequencer",
                "classname" : "xsd",
                "pathExpressions" : [ "/(*.xsd)/jcr:content[@jcr:data]" ],
            }
        ]
    }
}

This configuration defines:

• The name of the repository (on line 2) to be "Test Repository", which will take precedence over the name of the file.

• The repository will be registered in JNDI (if JNDI is available in the environment) with the name "jcr/Test Repository" (line 3). By default, the JNDI name will follow the pattern "jcr/<name>", where "<name>" is the repository name.

• The repository will periodically collect performance and statistical metrics in the background (line 5). This is enabled by default, but can be set to false to turn off the collection.

• The "defaultWorkspace" workspace (on line 8) is used by default when the client a Repository.login(...) method that doesn't have the workspace name as a parameter or if the client provides a null reference for the workspace name. If not specified, the default workspace for the repository will be named "default".

• One other workspace named "otherWorkspace" (line 9) will exist upon startup. By default, only the default workspace will exist.

• Clients can use the "Workspace.createWorkspace(...)" methods to create new workspaces (line 10). This is the default.

• The repository will look for a Infinispan configuration file at "/path/to/infinispan/cache/configuration.xml" (line 13) to create a new Infinispan CacheContainer instance. The value can be a (absolute or relative) path on the file system, the path to a resource on the (application, system, or thread-context) classloader, or the JNDI name where the CacheContainer instance can be found in JNDI. If no configuration file is found at any of these locations, a default Infinispan configuration (a basic, local mode, non-clustered, in-memory cache) will be used.

• The repository will use the Infinispan cache named "Test Repository" (line 14). If not specified, the repository's name is used.

• The repository will attempt to find the JTA transaction manager using the "org.infinispan.transaction.lookup.GenericTransactionManagerLookup" class. This is the default, and will work for many environments. You can specify the name of any class that implements the "org.infinispan.transaction.lookup.TransactionManagerLookup" interface, including several provided by Infinispan.

• The repository will store all BINARY values equal to or larger than 4096 bytes (line 16) in the binary store that uses the file system (line 18). Smaller BINARY values are held in-memory or persisted with the node information. The default size is 4096 bytes, and the default type is "filesystem".

• The repository can also store all STRING values equal to or larger than a specified number of characters. In this case, all STRING values with 4096 or more characters (line 17) will be stored in the binary store that uses the file system (line 18). Smaller STRING values are held in-memory or persisted with the node information. By default, the maximumStringSize value will be set to the explicit or default value of maximumBinaryValueInBytes.

• The repository will use several security providers for authentication and authorization. By default, only the anonymous provider is used. The order of the providers is important: a caller will be authenticated or authorized if any of the providers succeed for the caller:

  • The JAAS policy named "modeshape-jcr" will be used (lines 23-24). If the "jaas" nested document is not specified, JAAS will not be used. If specified in this fashion, the JAAS security provider will always be used first. The "modeshape-jcr" policy is used by default if JAAS is enabled.

  • Any providers as configured by the "providers" nested array (lines 31-36), where each array value is a nested document specifying the provider's name, description, and type (or classname). Only the "type" (or "classname") field is required. The two built-in types are "jaas" and "servlet", but any implementation of the 'org.modeshape.jcr.security.AuthorizationProvider" interface can be specified instead. Any instance members on the implementation class can be set by specifying additional fields of the same name, as long as the member type is String, a primitive boolean or number, java.util.Map, or java.util.List.

  • The anonymous provider (lines 26-30) is enabled by default and (if enabled) always is the last provider to be consulted. It authenticates all users with read and write permission by default, although the exact roles (either "read", "readwrite", or "admin") can be configured with the "roles" field; specify an empty "roles" array to completely disable the anonymous provider. All sessions that are authenticated by this provider will be given the username given by the "username" field (line 30), which defaults to the literal "<anonymous>" value (including the angle brackets). Any user that fails to properly authenticate with another provider will not be given an anonymous session unless the "useOnFailedLogin" field is set to true.

• The query system (lines 38-67) is enabled by default but is explicitly enabled on line 39

  • When the repository starts up, only the missing indexes will be rebuilt (lines 48-51) (which is also the default), the system content area (under /jcr:system) will be indexed as well(by default the system area isn't re-indexed) and all of the re-indexing will be done asynchronously (by default however, it is done synchronously).

  • The indexes will be stored on the file system under the directory "/path/on/filesystem" and will use simple locking and automatically choose the kind of file system storage based upon the operating system (lines 42-45). By default the indexes are stored in memory (with a "type" value of "ram" and no other fields), so be sure to configure this carefully for your application/environment.

  • The indexing system will use the "modeshape-workers" thread pool for re-indexing the workspace content in the background (line 48), and will use the "StandardAnalyzer" for tokenizing terms (line 49) and the "DefaultSimilarity" class for scoring (line 50). By default the indexes will be stored using the current format (line 51), though it's recommended to explicitly set the value matching the Lucene version you've started using (e.g., "LUCENE_34"). The readers will be shared (line 52) until index changes are discovered. The "backend" nested document (lines 53-55) specifies how ModeShape is to handle changes to the indexes; the default of "lucene" (line 54) means the changes will be written directly to the local Lucene indexes, while other options allow using a JMS queue, JGroups, a "blackhole" option for testing, or even a custom implementation. The other advanced properties (lines 56-59) specify the maximum node updates per transaction, whether the indexes are to be written synchronously, and the thread pool size and queue size for asynchronous writes.

  • Text extractors (lines 61-70) are used to find the search terms from BINARY values. No text extractors are used by default, but specifying the name, description, and type (or classname) for one or more text extractor implementation classes enables this feature. Two text extractor types are provided out of the box, and both are configured here with the required "type" fields (e.g., "tika" and "vdb") and an optional description (useful for documentation and during administration).

• The configured sequencers (lines 72-87) specify the types of sequencers that should be run. Each sequencer is configured with one or more path expressions that are matched against the paths of changed nodes; when any changed path matches the expression, the sequencer is called on the changed property/node and the generated output of the sequencer invocation is written to the location specified in the path expression. Each sequencer is configured by specifying the required "type" field, and an optional name and description. Custom implementations of "org.modeshape.jcr.api.sequencer.Sequencer" interface can be specified using the "classname" field (instead of the "type" field), and any instance members on the implementation class can be set by specifying additional fields of the same name, as long as the member type is String, a primitive boolean or number, java.util.Map, or java.util.List. Several types of sequencers are available out of the box:

  • "cnd" parses JCR CND files to generate a node structure describing the namespaces, node types, property definitions, and child node definitions

  • "class" and "java" parse Java class files and source files (respectively) and generates a node structure describing the encoded types, fields, methods, parameters, etc.

  • "ddl" parses the more important DDL statements from SQL-92, Oracle, Derby, and PostgreSQL, and constructing a graph structure containing a structured representation of these statements. The resulting graph structure is largely the same for all dialects, though some dialects have non-standard additions to their grammar, and thus require dialect-specific additions to the graph structure.

  • "image" extracts metadata from JPEG, GIF, BMP, PCX, PNG, IFF, RAS, PBM, PGM, PPM and PSD image files. This sequencer extracts the file format, image resolution, number of bits per pixel and optionally number of images, comments and physical resolution.

  • "model" parses the model files produced by the Teiid Designer to extract the structured relational data model described by the XMI file, and outputs a node structure that represents this model.

  • "vdb" parses the VDB archive files produced by the Teiid Designer to extract the virtual database information and the structured relational data model described in each of the contained XMI model files, and outputs a node structure that represents the VDB and these models.

  • "wsdl" parses WSDL files that adhere to the W3C's Web Service Definition Language (WSDL) 1.1 specification, and output a representation of the WSDL file's messages, port types, bindings, services, types (including embedded XML Schemas), documentation, and extension elements (including HTTP, SOAP and MIME bindings). This derived information is intended to mirror the structure and semantics of the actual WSDL files while also making it possible for ModeShape users to easily navigate, query and search over this derived information. This sequencer captures the namespace and names of all referenced components, and will resolve references to components appearing within the same file.

  • "xsd" parses XML Schema Documents that adhere to the W3C's XML Schema Part 1 and Part 2 specifications, and output a representation of the XSD's attribute declarations, element declarations, simple type definitions, complex type definitions, import statements, include statements, attribute group declarations, annotations, other components, and even attributes with a non-schema namespace. This derived information is intended to accurately reflect the structure and semantics of the XSD files while also making it possible for ModeShape users to easily navigate, query and search over this derived information. This sequencer captures the namespace and names of all referenced components, and will resolve references to components appearing within the same files.

  • "xml" parses XML files and extracts the element, attribute, namespace, DTD, entity, comments and other information in the file, producing a node structure representative of this information.

  • "zip" extracts the files and folders contained in the ZIP archive file, extracting the files and folders into the repository using JCR's nt:file and nt:folder built-in node types. The structure of the output thus matches the logical structure of the contents of the ZIP file. Note that the resulting files may then be sequenced.

  • "mp3" processes MP3 audio files added to a repository and extracts the ID3 metadata for the file, including the track's title, author, album name, year, and comment, and then writes a node structure representing this information

  • "fixedwidth" extracts rows and fixed-width columns from text streams and generates a node structure representative of the rows and column values in each row.

  • "delimited" extracts rows and delimited columns from text streams and generates a node structure representative of the rows and column values in each row.

Configuring the Infinispan Cache

As noted in the previous section, the repository configuration can specify the configuration file for the Infinispan CacheContainer (see line 13 in the previous example). If a configuration or an existing CacheContainer instance can be found, a basic Infinispan configuration (a basic, local mode, non-clustered in-memory cache) will be used.

The rest of this section describes some basic ways to configure Infinispan. However, please see the Infinispan documentation for much more detailed information about how to properly configure Infinispan and its cache loaders using its XML configuration file format.

<infinispan />

<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 settings shared by all caches managed by this cache container. -->
  <global>
  </global>
  <!-- The default configuration template for caches. -->
  <default>
  </default>
  <!-- Individually named caches. -->
  <namedCache name="Test Repository">
      <loaders
         passivation="false"
         shared="false"
         preload="false">

         <loader
            class="org.infinispan.loaders.bdbje.BdbjeCacheStore"
            fetchPersistentState="false"
            purgeOnStartup="false">

            <properties>
               <property name="location" value="/path/to/bdb"/>
            </properties>

         </loader>
      </loaders>
   </namedCache>
</infinispan>

Starting a ModeShape Repository

Now that we have a configuration for a ModeShape repository and a configuration for our Infinispan cache, we can start writing the code to start up ModeShape, deploy our repository, and start using JCR.

// Create and start the engine ...
ModeShapeEngine engine = new ModeShapeEngine();
engine.start();

RepositoryConfiguration config = RepositoryConfiguration.read("my-repository-config.json");

config = config.withName("My Repository");

// Verify the configuration for the repository ...
Problems problems = config.validate();
if (problems.hasErrors()) {
    System.err.println("Problems with the configuration.");
    System.err.println(problems);
    System.exit(-1);
}

javax.jcr.Repository repository = engine.deploy(config);

Problems problems = repository.getStartupProblems();
if (problems.hasErrors() || problems.hasWarnings()) {
    System.err.println("Problems deploying the repository.");
    System.err.println(problems);
    System.exit(-1);
}

javax.jcr.Repository repository = engine.getRepository("My Repository");

javax.jcr.Session session = repository.login("default");

// Get the root node ...
Node root = session.getRootNode();
assert root != null;

System.out.println("Found the root node in the \"" + session.getWorkspace().getName() + "\" workspace");

session.logout();

Future<Boolean> future = engine.shutdown();
if ( future.get() ) {  // blocks until the engine is shutdown
   System.out.println("Shutdown successful");
}

Using JCR's RepositoryFactory

The JCR 2.0 specification introduced the javax.jcr.RepositoryFactory interface that can be used with the Java SE Service Locator pattern to find a Repository instance without using any implementation-specific APIs. The basic process is as follows:

Map<String,String> parameters = ...
Repository repository = null;
for (RepositoryFactory factory : ServiceLoader.load(RepositoryFactory.class)) {
    repository = factory.getRepository(parameters);
    if (repository != null) break;
}
Session session = repository.login("default");
...

Note how simple this is, while under the covers it is doing exactly the same process we described above.

Here, the parameters contain implementation-specific properties, but your application can easily read them from a file to keep all implementation-specific details out of your application code.

ModeShape requires one parameter:

org.modeshape.jcr.URL = file:path/to/my_repository.json

where the value of the property is the URL that can be resolved to the JSON configuration file. Other URLs might be to a file on the file system using an absolute path (e.g., "file:///abs/path/to/my_repository.json") or even a URL to a web server (or governance repository!) and the configuration file (e.g., "http://www.example.com/repos/my_repository.json").

At this point using ModeShape just requires using the standard JCR API.

Oh, and if you want to shut down the ModeShape engine, you can (try to) cast the javax.jcr.RepositoryFactory instance to a org.modeshape.jcr.api.RepositoryFactory instance. If successful, you can call the "shutdown()" method that returns a Future<Boolean> like the ModeShapeEngine's shutdown() method.