JBoss.orgCommunity Documentation

Chapter 4. Building the example applications

4.1. Downloading and compiling
4.2. What's next

This chapter provides instructions for downloading and compiling two sample applications that demonstrates how ModeShape works with a JCR repository to automatically sequence changing content to extract useful information. So read on to get the simple application running.

ModeShape uses Maven 2 for its build system, as do these examples. Using Maven 2 has several advantages, including the ability to manage dependencies. If a library is needed, Maven automatically finds and downloads that library, plus everything that library needs. This means that it's very easy to build the examples - or even create a maven project that depends on the ModeShape JARs.

To use Maven with ModeShape, you'll need to have JDK 6 and Maven 2.0.9 (or higher).

Note

Maven can be downloaded from http://maven.apache.org/, and is installed by unzipping the maven-2.0.9-bin.zip file to a convenient location on your local disk. Simply add $MAVEN_HOME/bin to your path.

The examples are already configured to use the new JBoss.org Maven repository, which provides a central location for the artifacts produced by the JBoss.org projects (well, at least those that use Maven) as well as proxying other repositories and caching artifacts for third party libraries. This simplifies the builds, helps ensure that developers have easy access to these artifacts (including sources) so that the project (and dependencies) can always be rebuilt when needed.

For more information about the JBoss Maven repository, see the announcement and documentation.

Previous versions of ModeShape made use of the older JBoss.org Maven repository, and required modifying your local ~/.m2/settings.xml file. This is no longer required.

The next step is to download the example for this Getting Started guide, and extract the contents to a convenient location on your local disk. You'll find the example contains the following files, which are organized according to the standard Maven directory structure:

examples/pom.xml
         sequencers/pom.xml
                   /src/main/assembly
                            /config
                            /java
                            /resources
                       /test/java
                            /resources
         repository/pom.xml
                   /src/main/assembly
                            /config
                            /java
                            /resources
                       /test/java
                            /resources

There are essentially three Maven projects: a sequencers project, a repository project, and a parent project. All of the source for the sequencing example is located in the sequencers subdirectory, while all of the source for the repository example is located in the repository subdirectory.

And you may have noticed that none of the ModeShape libraries are there. This is where Maven comes in. The two pom.xml files tell Maven everything it needs to know about what libraries are required and how to build the example.

In a terminal, go to the examples directory and run:

$ mvn install

This command downloads all of the JARs necessary to compile and build the example, including the ModeShape libraries, the libraries they depend on, and any missing Maven components. (These are downloaded from the JBoss repositories only once and saved on your machine. This means that the next time you run Maven, all the libraries will already be available locally, and the build will run much faster.) The command then continues by compiling the example's source code (and unit tests) and running the unit tests. The build is successful if you see the following:

$ mvn install
...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] ------------------------------------------------------------------------
[INFO] Getting Started examples .............................. SUCCESS [2.106s]
[INFO] Sequencer Examples .................................... SUCCESS [9.768s]
[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 12 seconds
[INFO] Finished at: Wed May 07 12:00:06 CDT 2008
[INFO] Final Memory: 14M/28M
[INFO] ------------------------------------------------------------------------
$ 

If there are errors, check whether you have the correct version of Maven installed and that you've correctly updated your Maven settings as described above.

If you've successfully built the examples, there will be a new examples/sequencers/target/ directory that contains all of the generated output for the sequencers example, including a modeshape-example-sequencers-basic.dir/ subdirectory that contains the following:

  • run.sh is the *nix shell script that will run the sequencer example application.

  • log4j.properties is the Log4J configuration file.

  • sample1.mp3 is a sample MP3 audio file you'll use later to upload into the repository.

  • caution.gif, caution.png, caution.jpg, and caution.pict are images that you'll use later and upload into the repository.

  • sequencing.cnd is a Compact Node Definition (CND) file that defines the node types used in the output from the sequencers.

  • security subdirectory containing several files related to the JAAS implementation used for authentication.

  • project1 subdirectory contains some Java source that can be loaded into the repository.

  • lib subdirectory contains the JARs for all of the ModeShape artifacts as well as those for other libraries required by ModeShape and the sequencer example.

Similarly, the examples/repository/target/ directory contains all of the generated output for the repository example, including a modeshape-example-repository-basic.dir/ subdirectory that contains the following:

  • run.sh is the *nix shell script that will run the repository example application.

  • run.cmd is the Windows command file that will run the repository example application.

  • log4j.properties is the Log4J configuration file.

  • configRepository.xml is an XML file containing the information that the example application loads as its configuration and which defines the sources, repositories, sequencers (if used), and other components that make up the ModeShape JCR engine.

  • aircraft.xml is an XML file containing the information that the example application imports into its "Aircraft" repository.

  • cars.xml is an XML file containing the information that the example application imports into its "Cars" repository.

  • ufoSource subdirectory containing several folders and files used by the file system connector for the "UFOs" repository.

  • aircraft.cnd, cars.cnd, and vehicles.cnd are the CND files used for the three different JCR Repositories set up in the example. The vehicles.cnd is just a combination of the other two (with duplicates removed). The UFO source doesn't need a CND file, since the file system connector uses the "nt:file" and "nt:folder" node types built into the JCR standard.

  • security subdirectory containing several files related to the JAAS implementation used for authentication and authorization.

  • lib subdirectory contains the JARs for all of the ModeShape artifacts as well as those for other libraries required by ModeShape and the repository example. There are a lot of libraries here, but almost all of them are from the JPA connector (which depends upon Hibernate), HSQLDB, Lucene, and the JAAS implementation.

In this chapter you downloaded, installed, and built the two example applications. In the next two chapters we'll run these examples and walk through the code.