<?xml version="1.0" encoding="UTF-8"?>
<!--
  ~ ModeShape (http://www.modeshape.org)
  ~
  ~ See the COPYRIGHT.txt file distributed with this work for information
  ~ regarding copyright ownership.  Some portions may be licensed
  ~ to Red Hat, Inc. under one or more contributor license agreements.
  ~ See the AUTHORS.txt file in the distribution for a full listing of 
  ~ individual contributors.
  ~
  ~ ModeShape is free software. Unless otherwise indicated, all code in ModeShape
  ~ is licensed to you under the terms of the GNU Lesser General Public License as
  ~ published by the Free Software Foundation; either version 2.1 of
  ~ the License, or (at your option) any later version.
  ~
  ~ ModeShape is distributed in the hope that it will be useful,
  ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  ~ or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
  ~ for more details.
  ~
  ~ You should have received a copy of the GNU Lesser General Public License
  ~ along with this distribution; if not, write to:
  ~ Free Software Foundation, Inc.
  ~ 51 Franklin Street, Fifth Floor
  ~ Boston, MA  02110-1301  USA
  -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % CustomDTD SYSTEM "../custom.dtd">
%CustomDTD;
]>
<chapter id="downloading_and_building">
	<title>Building the example applications</title>
	<para>
    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.
  </para>
	<para>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.</para>
	<para>
     To use Maven with ModeShape, you'll need to have <ulink url="http://java.sun.com/javase/downloads/index_jdk5.jsp">JDK 6</ulink>
     and Maven 2.0.9 (or higher).</para>
  <note>
		<para>
	     Maven can be downloaded from <ulink url="http://maven.apache.org/">http://maven.apache.org/</ulink>, and is installed by unzipping the
	     <code>maven-2.0.9-bin.zip</code> file to a convenient location on your local disk. Simply add <code>$MAVEN_HOME/bin</code>
	     to your path.
    </para>
		<para>
			The examples are already configured to use the new <ulink url="https://repository.jboss.org/nexus">JBoss.org Maven repository</ulink>, 
			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.
		</para>
		<para>
			For more information about the JBoss Maven repository, see the 
			<ulink url="http://community.jboss.org/en/build/blog/2010/04/20/announcement--new-maven-repository-infrastructure">announcement</ulink>
			and <ulink url="http://community.jboss.org/wiki/MavenRepository">documentation</ulink>.
		</para>
	  <para>
		  Previous versions of ModeShape made use of the older JBoss.org Maven repository, and required modifying your local
		  <code>~/.m2/settings.xml</code> file.  This is no longer required.
	  </para>
  </note>
	<sect1 id="downloading">
		<title>Downloading and compiling</title>
		<para>The next step is to <ulink url="&DownloadHome;/modeshape-&versionNumber;-gettingstarted-examples.zip">download</ulink>
      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:</para>
		<programlisting><![CDATA[
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
]]></programlisting>
		<para>
			There are essentially three Maven projects: a <code>sequencers</code> project, a <code>repository</code> project, 
		  and a parent project.  All of the source for the sequencing example is located in the <code>sequencers</code> subdirectory,
		  while all of the source for the repository example is located in the <code>repository</code> subdirectory.
		</para>
		<para>
			And you may have noticed that none of the ModeShape libraries are there.  This is where Maven comes in.  
			The two <code>pom.xml</code> files tell Maven everything it needs to know about what libraries are required and 
			how to build the example.
		</para>
		<para>
			In a terminal, go to the <code>examples</code> directory and run:
		</para>
		<programlisting>$ mvn install</programlisting>
		<para>  
      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:
		</para>
		<programlisting><![CDATA[
$ 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] ------------------------------------------------------------------------
$ ]]></programlisting>
		<para>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.</para>
		<para>If you've successfully built the examples, there will be a new <code>examples/sequencers/target/</code> directory that contains
			all of the generated output for the sequencers example, including a <code>modeshape-example-sequencers-basic.dir/</code> subdirectory 
			that contains the following:
			<itemizedlist>
				<listitem>
					<para><emphasis role="strong"><code>run.sh</code></emphasis> is the *nix shell script that will run the sequencer example application.</para>
				</listitem>
				<listitem>
					<para><emphasis role="strong"><code>log4j.properties</code></emphasis>
			        is the Log4J configuration file.
			      </para>
				</listitem>
				<listitem>
					<para><emphasis role="strong"><code>sample1.mp3</code></emphasis>
			        is a sample MP3 audio file you'll use later to upload into the repository.
			      </para>
				</listitem>
				<listitem>
					<para><emphasis role="strong"><code>caution.gif</code></emphasis>, <emphasis role="strong"><code>caution.png</code></emphasis>, 
					<emphasis role="strong"><code>caution.jpg</code></emphasis>, and <emphasis role="strong"><code>caution.pict</code></emphasis>
			        are images that you'll use later and upload into the repository.
			      </para>
				</listitem>
				<listitem>
					<para><emphasis role="strong"><code>sequencing.cnd</code></emphasis>
			        is a Compact Node Definition (CND) file that defines the node types used in the output from the sequencers.
			      </para>
				</listitem>
				<listitem>
					<para><emphasis role="strong"><code>security</code></emphasis> subdirectory containing several files related to the
				  JAAS implementation used for authentication.
				  </para>
				</listitem>
				<listitem>
					<para><emphasis role="strong"><code>project1</code></emphasis> subdirectory contains some Java source that can be loaded
					  into the repository.
				  </para>
				</listitem>
				<listitem>
					<para><emphasis role="strong"><code>lib</code></emphasis> subdirectory contains the JARs for all of the ModeShape artifacts 
					  as well as those for other libraries required by ModeShape and the sequencer example.
			      </para>
				</listitem>
			</itemizedlist>
		</para>
		<para>Similarly, the <code>examples/repository/target/</code> directory contains all of the generated output for the repository example, including
			a <code>modeshape-example-repository-basic.dir/</code> subdirectory that contains the following:
			<itemizedlist>
				<listitem>
					<para><emphasis role="strong"><code>run.sh</code></emphasis> is the *nix shell script that will run the repository example application.</para>
				</listitem>
				<listitem>
					<para><emphasis role="strong"><code>run.cmd</code></emphasis> is the Windows command file that will run the repository example application.</para>
				</listitem>
				<listitem>
					<para><emphasis role="strong"><code>log4j.properties</code></emphasis> is the Log4J configuration file.</para>
				</listitem>
				<listitem>
					<para><emphasis role="strong"><code>configRepository.xml</code></emphasis> 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.
					</para>
				</listitem>
				<listitem>
					<para><emphasis role="strong"><code>aircraft.xml</code></emphasis> is an XML file containing the information that the
					  example application imports into its "Aircraft" repository.
					</para>
				</listitem>
				<listitem>
					<para><emphasis role="strong"><code>cars.xml</code></emphasis> is an XML file containing the information that the
					  example application imports into its "Cars" repository.
					</para>
				</listitem>
				<listitem>
					<para><emphasis role="strong"><code>ufoSource</code></emphasis> subdirectory containing several folders and files used by the
					 file system connector for the "UFOs" repository.
				  </para>
				</listitem>
				<listitem>
					<para><emphasis role="strong"><code>aircraft.cnd</code></emphasis>, <emphasis role="strong"><code>cars.cnd</code></emphasis>,
					and <emphasis role="strong"><code>vehicles.cnd</code></emphasis> are the CND files used for the three different JCR Repositories
					set up in the example.  The <emphasis role="strong"><code>vehicles.cnd</code></emphasis> 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.
					</para>
				</listitem>
				<listitem>
					<para><emphasis role="strong"><code>security</code></emphasis> subdirectory containing several files related to the
				  JAAS implementation used for authentication and authorization.
				  </para>
				</listitem>
				<listitem>
					<para><emphasis role="strong"><code>lib</code></emphasis> 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.
			      </para>
				</listitem>
			</itemizedlist>
    </para>
	</sect1>
	<sect1 id="downloading_and_building_whats_next">
		<title>What's next</title>
		<para>In this chapter you downloaded, installed, and built the two example applications.  In the next <link linkend="sequencer_example">two</link>
		  <link linkend="repository_example">chapters</link> we'll run these examples and walk through the code.
		</para>
	</sect1>
</chapter>
