JBoss Community Archive (Read Only)

ModeShape 5


ModeShape is intended to be an embeddable hierarchical data store, and as such we try to ensure that it makes judicious use of third party dependencies and is packaged in such a way as to have a relatively small number of separate artifacts but also enough artifacts to bring in only the necessary dependencies.

See also the descriptions of the concepts in ModeShape.

ModeShape engine

Perhaps the most important component in ModeShape is the engine, which is responsible for managing and making available all of the configured repositories. When ModeShape is embedded into an application, the application is better of manually instantiating the org.modeshape.jcr.ModeShapeEngine class and explicitly invoking the start(), deployRepository(...) and shutdown() methods in appropriate places within the application's own lifecycle. Note that repository configurations can be updated even when the repository is running and in use. ModeShape can also be deployed to a server (e.g., JBoss AS, Tomcat, etc.) so that the server manages the lifecycle of the engine.

Every repository in a ModeShapeEngine instance has a unique name, and applications can easily use the engine to get a particular repository by name. If used within an environment that has JNDI, ModeShape will also register each repository into JNDI so that applications can easily look it up. See the documentation for all the ways to find a repository.

Repository configuration

Each repository is configured separately with a file that conforms to the JSON format. (Note that when installed into JBoss AS, configuring ModeShape is done through AS's configuration system.) The configuration files can be read with the org.modeshape.jcr.RepositoryConfiguration class, and the resulting RepositoryConfiguration instances can be passed to the ModeShapeEngine.deployRepository(...) and ModeShapeEngine.updateRepository(...) methods.


ModeShape can be clustered at the repository level. This means that a repository with the same name is deployed to multiple engines (typically in separate processes), and those repository instances are aware of each other so that events that originate in one repository instance will be forwarded to all other repository instances in the cluster.

There are two other important aspects of clustering: storage and indexing.


ModeShape 5 comes with its own set of persistent stores, however not all of those are capable of handling clustered configurations. More specifically, only the database persistence store is able of handling clustering, meaning that ModeShape can only cluster with a shared persistent store.


Each repository instance can use indexes to help answer queries. When clustering a repository, the repository needs to know whether it owns the indexes (in which case the repository will update the indexes to reflect all changes that originate from the local or remote repository instances) or whether indexes are shared (in which case the repository will update the indexes only when changes that are made with that repository instance).

Local indexes are much easier to configured, but the disadvantage is that every repository is essentially updating its own indexes for every change (so there is duplicate work). This might cause a write-heavy system to become inundated with changes.

Shareable indexes are more difficult to configure but are generally more capable of handling large amounts of updates.

Whether indexes are local or shareable depends on each type of index provider


The ModeShape software is in the form of JAR files, and these JAR files are published in the Maven Central Repository for simpler application development. They are also available as a ZIP distribution from our downloads area.

Please see our Getting Started page for more detail on how to use ModeShape in your Maven-based application.

There are separate ModeShape JARs (or Maven artifacts) for each major component:

Public APIs

  • javax.jcr - This is the standard JCR 2.0 API, and it actually is not in our codebase but is available in Maven. It has no dependencies.

  • modeshape-jcr-api - ModeShape's small extension to the standard JCR 2.0 API. This public API was meant to be used by client applications that already use the JCR API, but it is entirely optional. Many of the interfaces here extend standard interfaces and add just one or a few useful methods, so most of the time clients can cast standard JCR instances to these ModeShape interfaces only when they need a ModeShape-specific method. A few interfaces are new concepts that clients might need to access. It only depends on the JCR API JAR. Note that the ModeShape team will only modify the public API in a backward-compatible fashion: while some methods might be deprecated at any time (though we don't anticipate doing so), changes that are not backward compatible (e.g., removal of deprecated methods) will only occur on major releases. This module also defines the Sequencer SPI, since sequencer implementations only need the JCR API and this public API.

Core modules

  • modeshape-common - A simple set of domain-independent utilties and classes that are available for use in any other module. Some of these might be similar to those available in other third-party libraries, but were create and are maintained here to help minimize third-party dependencies (especially when small fractions of the third party libraries would be used). This includes ModeShape's framework for internationalization (I18n) and the logging framework that is a slight facade on top of several other logging systems, including SLF4J, Log4J, Logback, JDK logging. Sure, SLF4J is already a logging abstraction framework, but using our own abstraction makes it easier for developers to hook up ModeShape logging to their preferred framework (just include the appropriate logging JAR on the classpath, or fallback to JDK logging) and it also allows ModeShape to enforce using only internationalized logging messages (except for debug and trace, which just take string messages). Therefore, this module has no required dependencies, but will use one of the logging frameworks if they are available on the classpath.

  • modeshape-schematic - A library for working with JSON and BSON documents, for storing them inside a key-value store, and for editing them in a way that allows for the changes to be recorded as a set of changes to the documents and atomically apply them. (The latter is what distinguishes this library from other JSON or BSON libraries.) Supports reading a document from JSON and/or BSON, and writing a document to JSON and/or BSON. This module also contains the SPIs required for storing these types of documents into transactional key-value stores.

  • modeshape-jcr - The primary module that contains the ModeShape engine and implementations of the standard JCR API and ModeShape's public API. It also defines several SPIs, including the Connector SPI (for federation) and the BinaryStore SPI (for storing binary values). It contains the file system connector and CND sequencer (since neither is dependent upon any other libraries and thus are too simple to be distinct artifacts.


All of the sequencer artifacts are named in a similar way: modeshape-sequencer-name. For example, the DDL sequencer is in the modeshape-sequencer-ddl module, while the WSDL sequencer is in the modeshape-sequencer-wsdl module.

The use of sequencers in a repository is entirely optional. And because nearly all of the sequencers depend upon third-party libraries, we've put each sequencer into a separate artifact so that only the required dependencies are included.


All of the connector artifacts are named in a similar way: modeshape-connector-name. For example, the Git connector is in the modeshape-connector-git module, while the CMIS connector is in the modeshape-connector-cmis module.

The use of federation (and thus connectors) in a repository is entirely optional. And because nearly all of the connectors depend upon third-party libraries, we've put each connector into a separate artifact so that only the required dependencies are included.

Index Providers

All of the different index providers are named in a similar way: modeshape-name-index-provider. The use of index providers is entirely optional.

Web APIs

ModeShape has a number of web-based APIs that may optionally be used by remote clients to interact with one or more repositories.

  • REST Service - a RESTful service that enables navigating, searching, modifying and deleting nearly any content in the repositories (see the detailed API documentation). All representations are in JSON, XML or text form. Each operation creates a new session, fulfills the request, and then closes the session; sessions longer than a single request are not possible. Versioned content can be manipulated: if it is changed, it is checked out, modified, saved, and checked back in. However, the rest of the JCR functionality is not available. The WAR file is named modeshape-web-jcr-rest-war-<version>.war.

  • WebDAV Service - exposes content via WebDAV, enabling WebDAV clients and operating systems to mount the repositories as network disk drives. This service exposes a small amount of ModeShape functionality, and allows clients to basically navigate, download, and upload files and folders. The WAR file is named modeshape-web-jcr-webdav-war-<version>.war.

  • CMIS Service - exposes an API that conforms to CMIS. The CMIS functionality exposes the ability to navigate, download, and upload folders and CMIS documents. The WAR file is named modeshape-web-jcr-cmis-war-<version>.war.

Each of these services can be independently deployed to a web or application server and in which ModeShape must be running. Each service talks to a single (local) ModeShapeEngine instance (typically found via JNDI) and will work with all of the repositories deployed to that engine.

JDBC driver

ModeShape supports several query languages to allow client applications to find content independent of its hierarchical location. The JCR-SQL2 language is by far the most powerful, and ModeShape provides a JDBC driver that applications can use to query a repository (running in the same process or in a remote process where the REST service is available). The driver JAR is self-contained, making it pretty easy to incorporate into existing JDBC-aware applications. See this page for more detail.


In addition to embedding within a simple Java application, ModeShape can also be deployed to web or application servers, and there are a number of other modules that support this:

  • JCA Adapter - A JCA-compliant adapter that enables deploying a ModeShape engine into a JCA-compatible server. See this page for details.

  • JBoss AS - A kit that can be unzipped on top of a JBoss AS installation to install a custom subsystem that will manage a ModeShape engine and that makes it possible to configure ModeShape, JGroups, security, and JDBC data sources all from within the standard EAP configuration mechanism. Additionally, ModeShape can be used in any EJB or Java EE component, and can even participate in user-managed or container-managed transactions. See this page for details.


ModeShape provides a number of very simple examples that showcase how ModeShape can be used within Maven-based applications. Each of these applications is targeted to show a very specific piece of functionality (e.g., how to use Log4J logging). See https://github.com/ModeShape/modeshape-examples for more details.


ModeShape provides a Git repository of "quickstarts" that work with ModeShape installed on top of JBoss Wildfly. See https://github.com/ModeShape/quickstart for details.

JBoss.org Content Archive (Read Only), exported from JBoss Community Documentation Editor at 2020-03-11 12:12:24 UTC, last content change 2016-04-04 10:29:07 UTC.