Prerequisites

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

All ModeShape releases 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>5.1.0.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're going to use the Relations Persistent Store 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>
</dependency>

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" : {
        "persistence" : {
            "type" : "file",
            "path": "target/test_repository"
        } ,
        "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"
            }
        ]
    },
    "indexProviders" : {
        "local" : {
            "classname" : "org.modeshape.jcr.index.local.LocalIndexProvider",
            "directory" : "target/local_index_test_repository/1"
        }
    },
    "indexes" : {
        "index" : {
            "kind" : "value",
            "nodeType" : "mix:title",
            "columns" : "jcr:title(STRING)",
            "provider" : "local",
            "synchronous" : true,
            "workspaces" : "*"
        }
    },
   "textExtraction": {
        "extractors" : {
            "tikaExtractor":{
                "name" : "Tika content-based extractor",
                "classname" : "tika"
            }
        }
    },
    "sequencing" : {
        "removeDerivedContentWithOriginal" : true,
        "threadPool" : "modeshape-workers",
        "sequencers" : { [
            {
                "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 store data on disk inside the target/test_repository folder relative to the runtime working directory of the JVM

• 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.

• Since 4.0.0.Final ModeShape supports defining indexes (lines 38-52) similar to the way you would in a RDBMS and index providers - the mechanism via which the index definition is maintained. If you omit these 2 sections, queries will still work but will not potentially perform as well since ModeShape will have to crawl the entire repository each time to find the nodes. If you decide to defined indexes, make sure both "indexes" and "indexProviders" are configured and each index has a defined index provider. See https://docs.jboss.org/author/display/MODE50/Query+and+search#Queryandsearch-Usingindexes for a more thorough explanation.

• Text extractors (lines 54-61) 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 62-74) 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.

  • "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.

{
    "name" : "repo",
}

{
    "name" : "test",
    "storage" : {
        "persistence": {
            "type": "mem"
        }
    }
}

{
    "name" : "Test Repository",
    "storage" : {
        "persistence": {
            "type": "file",
            "path" : "target/test_repository"
        },
    }
}

{
    "name" : "Test Repository",
    "storage" : {
      "persistence" : {
            "type" : "db",
            "connectionUrl": "jdbc:h2:file:./target/test_repo/db;AUTO_SERVER=TRUE"
        }
    }
}

Starting a ModeShape Repository

Now that we have a configuration for a ModeShape repository, 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.