JBoss AS

When ModeShape is installed and deployed into a JBoss AS installation, the ModeShape will automatically register each deployed repository in JNDI, which by default is at "/jcr/repositoryName" (where "repositoryName" is the name of the repository). Simply use the JBoss AS administration tools to configure and deploy as many repositories as needed, including customizing the JNDI location of each repository.

Then in your application, simply look up each Repository instance from JNDI:

InitialContext initCtx = new InitialContext();
Context envCtx = (Context) initCtx.lookup("java:comp/env");
javax.jcr.Repository repository = (javax.jcr.Repository) envCtx.lookup("jcr/myrepo");

Tomcat and other web or app servers

There are several ways of deploying ModeShape and registering the Repository instances in JNDI. One is to simply create a web application that sets up ModeShape and its repositories, where each repository configuration file specifies the location in JNDI where ModeShape should register that repository:

{
    "name" : "My Repository",
    "jndiName" : "java:jcr/local/MyRepository",
}

However, many servlet containers and application servers provide a way to configure a JNDI ObjectFactory that will create the necessary objects as soon as a client uses JNDI to look up the object at a particular location; after that, the objects will be registered in JNDI and found. ModeShape provides an ObjectFactory implementation, so simply configure your server to use it, and deploy your applications to look in JNDI for ModeShape's Repository instances.

Although each server configures the ObjectFactory instances differently, they all basically define the following:

• The name of the ObjectFactory implementation class. For ModeShape, this is "org.modeshape.jcr.JndiRepositoryFactory".

• Custom properties. For ModeShape, there are two for each repository:

  • The "configFile" property that specifies the location for the JSON repository configuration file

  • The "repositoryName" property that specifies the name of the repository. This value must match the name in the configuration file.

Note that that although the "repositoryName" can be found in the configuration file, specifying it does allow the factory to quickly find the named repository if it were already deployed, without having to read the configuration file.

Here's an example of a fragment of the conf/context.xml for Tomcat that registers ModeShape's Repositories implementation in JNDI at "jcr", and deploys two repositories using a different JSON configuration file for each one:

<Resource name="jcr/myrepo"
          auth="Container"
          factory="org.modeshape.jcr.JndiRepositoryFactory"
          repositoryName="My Repository"
          configFile="/resource/path/to/repository-config.json" />

Simply provide a similar fragment for each repository that is to be registered in JNDI.

Then in your application, simply look up the Repository instance from the correct JNDI location:

InitialContext initCtx = new InitialContext();
Context envCtx = (Context) initCtx.lookup("java:comp/env");
javax.jcr.Repository repository = (javax.jcr.Repository) envCtx.lookup("jcr/myrepo");

You can also configure and access multiple repositories at once by binding a ModeShapeEngine instance in JNDI. To do this, you must omit the repositoryName attribute from the above configuration and optionally replace the confiFile attribute with configFiles (plural) attribute which contains a comma-separated list of configuration file paths. You can then access all the repositories using the Repositories interface

public interface Repositories {
    /**
     * Get the names of the available repositories.
     *
     * @return the immutable set of repository names provided by this server; never null
     */
    Set<String> getRepositoryNames();

    /**
     * Return the JCR Repository with the supplied name.
     *
     * @param repositoryName the name of the repository to return; may not be null
     * @return the repository with the given name; never null
     * @throws javax.jcr.RepositoryException if no repository exists with the given name or there is an error communicating with
     *         the repository
     */
    javax.jcr.Repository getRepository( String repositoryName ) throws javax.jcr.RepositoryException;
}

Here's an example of a fragment of the conf/context.xml for Tomcat that registers ModeShape's Repositories implementation in JNDI at "jcr", and deploys two repositories using a different JSON configuration file for each one:

<Resource name="jcr"
          auth="Container"
          factory="org.modeshape.jcr.JndiRepositoryFactory"
          configFiles="/resource/path/to/first/repository-config.json, /resource/path/to/second/repository-config.json" />

Then in your application, simply look up the Repositories instance from JNDI, and get the names of the available repositories and/or get a Repository with a particular name.

InitialContext initCtx = new InitialContext();
Context envCtx = (Context) initCtx.lookup("java:comp/env");
org.modeshape.jcr.api.Repositories repositories =
             (org.modeshape.jcr.api.Repositories) envCtx.lookup("jcr");

// Get the names of the available repositories ...
Set<String> repoNames = repositories.getRepositoryNames();

// Get the repository given a name ...
String repoName = //...
javax.jcr.Repository repo = repositories.getRepository(repoName);