Using with Maven

By far the easiest way to use ModeShape is to use Maven, because with just a few lines of code, Maven will automatically pull all the JARs and source for all of the ModeShape libraries as well as everything those libraries need. All of ModeShape's artifacts for each release are published in the new JBoss Maven repository under the "org.modeshape" group ID.

Use the JBoss Maven repository

If you're using Maven (or Ivy), first make sure your project knows about the new JBoss Maven repository. One way to do this is to add the following to your project POM (you'll still likely want to use other Maven repositories for third-party artifacts):

  <repositories>
    <repository>
      <id>jboss</id>
      <url>https://repository.jboss.org/nexus/content/repositories/releases/</url>
    </repository>
  </repositories>

Or, you can add this information to your ~/.m2/settings.xml file. See the JBoss wiki for more details about this last option.

Add dependency to ModeShape

Then, simply add dependencies on the JBoss DNA JCR library:

  <dependency>
    <groupId>org.modeshape</groupId>
    <artifactId>modeshape-jcr</artifactId>
    <version>2.7.0.Final</version>
  </dependency>

This adds only the minimal libraries required to use ModeShape, so you need to add dependencies for each of the connectors, sequencers, and text extractors you want to use. Here is the list of available sequencers:

  <dependency>
    <groupId>org.modeshape</groupId>
    <artifactId>modeshape-sequencer-ddl</artifactId>
    <version>2.7.0.Final</version>
  </dependency>
  <dependency>
    <groupId>org.modeshapce</groupId>
    <artifactId>modeshape-sequencer-images</artifactId>
    <version>2.7.0.Final</version>
  </dependency>
  <dependency>
    <groupId>org.modeshape</groupId>
    <artifactId>modeshape-sequencer-java</artifactId>
    <version>2.7.0.Final</version>
  </dependency>
  <dependency>
    <groupId>org.modeshape</groupId>
    <artifactId>modeshape-sequencer-mp3</artifactId>
    <version>2.7.0.Final</version>
  </dependency>
  <dependency>
    <groupId>org.modeshape</groupId>
    <artifactId>modeshape-sequencer-msoffice</artifactId>
    <version>2.7.0.Final</version>
  </dependency>
  <dependency>
    <groupId>org.modeshape</groupId>
    <artifactId>modeshape-sequencer-xml</artifactId>
    <version>2.7.0.Final</version>
  </dependency>
  <dependency>
    <groupId>org.modeshape</groupId>
    <artifactId>modeshape-sequencer-xsd</artifactId>
    <version>2.7.0.Final</version>
  </dependency>
  <dependency>
    <groupId>org.modeshape</groupId>
    <artifactId>modeshape-sequencer-wsdl</artifactId>
    <version>2.7.0.Final</version>
  </dependency>
  <dependency>
    <groupId>org.modeshape</groupId>
    <artifactId>modeshape-sequencer-teiid</artifactId>
    <version>2.7.0.Final</version>
  </dependency>
  <dependency>
    <groupId>org.modeshape</groupId>
    <artifactId>modeshape-sequencer-text</artifactId>
    <version>2.7.0.Final</version>
  </dependency>
  <dependency>
    <groupId>org.modeshape</groupId>
    <artifactId>modeshape-sequencer-zip</artifactId>
    <version>2.7.0.Final</version>
  </dependency>

and the list of available connectors:

  <dependency>
    <groupId>org.modeshape</groupId>
    <artifactId>modeshape-connector-disk</artifactId>
    <version>2.7.0.Final</version>
  </dependency>
  <dependency>
    <groupId>org.modeshape</groupId>
    <artifactId>modeshape-connector-filesystem</artifactId>
    <version>2.7.0.Final</version>
  </dependency>
  <dependency>
    <groupId>org.modeshape</groupId>
    <artifactId>modeshape-connector-infinispan</artifactId>
    <version>2.7.0.Final</version>
  </dependency>
  <dependency>
    <groupId>org.modeshape</groupId>
    <artifactId>modeshape-connector-jcr</artifactId>
    <version>2.7.0.Final</version>
  </dependency>
  <dependency>
    <groupId>org.modeshape</groupId>
    <artifactId>modeshape-connector-inmemory</artifactId>
    <version>2.7.0.Final</version>
  </dependency>
  <dependency>
    <groupId>org.modeshape</groupId>
    <artifactId>modeshape-connector-jbosscache</artifactId>
    <version>2.7.0.Final</version>
  </dependency>
  <dependency>
    <groupId>org.modeshape</groupId>
    <artifactId>modeshape-connector-jdbc-metadata</artifactId>
    <version>2.7.0.Final</version>
  </dependency>
  <dependency>
    <groupId>org.modeshape</groupId>
    <artifactId>modeshape-connector-store-jpa</artifactId>
    <version>2.7.0.Final</version>
  </dependency>
  <dependency>
    <groupId>org.modeshape</groupId>
    <artifactId>modeshape-connector-svn</artifactId>
    <version>2.7.0.Final</version>
  </dependency>

and the list of available text extractors:

  <dependency>
    <groupId>org.modeshape</groupId>
    <artifactId>modeshape-extractor-tika</artifactId>
    <version>2.7.0.Final</version>
  </dependency>

These libraries and everything they need will be pulled in automatically into your project by Maven.

Add dependencies for logging

ModeShape is designed to use the same logging framework as your application, and it uses SLF4J to accomplish this. In other words, ModeShape depends upon the SLF4J API library, but requires you to provide provide a logging implementation as well as the appropriate SLF4J binding JAR.

For example, if your application is using Log4J, your application will already have a dependency for it, and to use ModeShape you need to add a dependency to the SLF4J-to-Log4J binding JAR:

  <dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-log4j12</artifactId>
    <version>1.6.1</version>
  </dependency>
  <dependency>
    <groupId>log4j</groupId>
    <artifactId>log4j</artifactId>
    <version>1.2.16</version>
  </dependency>

Of course, SLF4J works with other logging frameworks, too. Some logging implementations (such as LogBack) implement the SLF4J API natively, meaning they require no binding JAR. For details on the options and how to configure them, see the SLF4J manual.

And, ModeShape can use the JDK logging facility, too. ModeShape falls back to the JDK log when don't provide any SLF4J binding JAR.

Looking for JBoss DNA?

The ModeShape project used to be called "JBoss DNA", and all of the releases prior to ModeShape 1.0.0.Beta1 were released under that name and under the org.jboss.dna" group ID. All these artifacts are still available in the JBoss.org Maven repository.

We highly recommend migrating to ModeShape. We won't be issuing any more releases of JBoss DNA - but that's not a problem because ModeShape is the same stuff (just with a new name)!