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.
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 EAP, 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.
Each repository is configured separately with a file that conforms to the JSON format. (Note that when installed into JBoss EAP, configuring ModeShape is done through EAP'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. Additionally, the Infinispan cache(s) used in each repository should also be clustered, so that Infinispan can coordinate changes to the data stored in the cache(s).
There are two other important aspects of clustering: storage and indexing.
If the Infinispan caches use cache stores to persist content to the filesystem, a database, cloud storage, etc., then this storage must be compatible with clustering. For example, if the cache store content on the file system, then the cached used by each repository instance needs to have its own non-shared directory in which the cache can persist information. (Infinispan clustering will use network messaging to ensure that multiple instances that "own" a particular piece of data are all kept in sync.) Some of Infinispan's cache stores are sharable, which means that multiple instances can all share a single store.
Each repository instance uses 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). Note that even in the shared case, the index files might be local copies that are periodically cloned from a master set.
Local indexes are much easier to configure, 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 (they require the use and proper configuration of JMS and/or JGroups), but are generally more capable of handling large amounts of updates.
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:
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.
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 Infinispan, 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. ModeShape stores each node as a document inside Infinispan, and this library encapsultes all of the domain-indpendent logic for doing this. The module depends on several Infinispan artifacts.
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.
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.
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 EAP - A kit that can be unzipped on top of a JBoss EAP 6.1 installation to install a custom subsystem that will manage a ModeShape engine and that makes it possible to configure ModeShape, Infinispan, 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 EAP. See https://github.com/ModeShape/quickstart for details.