<?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 preface 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="configuration">
  <title>Configuration</title>
	<para>
		Using ModeShape within your application is actually quite straightforward, and with JCR 2.0 it is possible for your
		application to do everything using only the JCR 2.0 API. Your application will first obtain a <code>javax.jcr.Repository</code> instance,
		and will use that object to create sessions through which your application will read, modify, search,
		or monitor content in the repository.
	</para>
	<para>
		However, before you can use ModeShape, you need to configure it, and that's what this chapter covers.
	</para>
	<sect1 id="jcr_configuration">
		<title>Configuring ModeShape</title>
		<para>
		There really are three options:
		<itemizedlist>
			<listitem>
				<para><emphasis role="strong"><code>Load from a file</code></emphasis> is conceptually the most straightforward and requires the least amount
				of Java code, but it does requires having a configuration file. This is easy, allows one to manage configurations in version control,
				enables your application to use only the standard JCR API, and will likely be the best approach for most applications.
				If you're not sure, use this approach.</para>
			</listitem>
			<listitem>
				<para><emphasis role="strong"><code>Programmatic configuration</code></emphasis> allows an application to define and edit
				a configuration using Java code. This is useful when you cannot pre-define your configuration, or when you want to start
				with a baseline configuration, make programmatic changes based upon some inputs or preferences, and then save
				the configuration to a file. However, this requires that you write your application directly against ModeShape-specific
				interfaces and class.</para>
			</listitem>
			<listitem>
				<para><emphasis role="strong"><code>Load from a configuration repository</code></emphasis> is an advanced technique
				that allows multiple &JcrEngine; instances (usually in different processes perhaps on different machines)
				to easily access a (shared) configuration.</para>
			</listitem>
		</itemizedlist>
	</para>
	<para>
		Each of these approaches has their obvious advantages, so the choice of which one to use is entirely up to you.
	</para>
	<sect2 id="loading_from_file">
		<title>Configuration Files</title>
		<para>
			By far the easiest approach to defining your ModeShape configuration is to use a configuration file.
			As mentioned above, you'll want to do this if your application uses the standard and implementation-independent
			&RepositoryFactory; mechanism to obtain the JCR &Repository; reference.
		</para>
		<para>
			Here is an example configuration file used in the repository example covered in the &GettingStarted; document, 
			though it has been slightly simplified for clarity):
		</para>
   	<programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<configuration xmlns:mode="http://www.modeshape.org/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0">
  <!-- 
  Define the JCR repositories 
  -->
  <mode:repositories>
      <!-- 
      Define a JCR repository that accesses the 'Cars' source directly.
      This of course is optional, since we could access the same content through 'vehicles'.
      -->
      <mode:repository jcr:name="car repository" mode:source="Cars">
          <mode:options jcr:primaryType="mode:options">
              <mode:option jcr:name="jaasLoginConfigName" mode:value="modeshape-jcr"/>
          </mode:options>
          <mode:descriptors>
            <!-- 
            	This adds a JCR Repository descriptor named "myDescriptor" with a value of "foo".
            	So this code:
            	Repository repo = ...;
            	System.out.println(repo.getDescriptor("myDescriptor");

            	Will now print out "foo".
            -->
            <myDescriptor mode:value="foo" />
          </mode:descriptors>
          <!-- 
                Import the custom node types defined in the named files. The values
                can be an absolute path to a classpath resource, an absolute file system
                path, a relative path on the file system (relative to where the process was
                started from), or a resolvable URL. If more than one node type definition 
                file is needed, the files can be listed as a single comma-delimited string
                in the 'mode:resource' attribute of the 'jcr:nodeTypes' element, or listed 
                individually using multiple mode:resource child elements (as shown below).
            -->
          <jcr:nodeTypes>
	           <mode:resource>/org/example/my-node-types.cnd</mode:resource>
	           <mode:resource>/org/example/additional-node-types.cnd</mode:resource>
	        </jcr:nodeTypes>
      </mode:repository>
  </mode:repositories>
   <!-- 
   Define the sources for the content. These sources are directly accessible using the 
   ModeShape-specific Graph API.
   -->
   <mode:sources jcr:primaryType="nt:unstructured">
       <mode:source jcr:name="Cars" 
              mode:classname="org.modeshape.graph.connector.inmemory.InMemoryRepositorySource" 
              mode:retryLimit="3" mode:defaultWorkspaceName="workspace1">
	           <mode:predefinedWorkspaceNames>workspace2</mode:predefinedWorkspaceNames>
	           <mode:predefinedWorkspaceNames>workspace3</mode:predefinedWorkspaceNames>
       </mode:source>
   </mode:sources>
   <!-- 
   Define the sequencers. This is an optional section. For this example, we're not using any sequencers. 
   -->
   <mode:sequencers>
       <!--mode:sequencer jcr:name="Image Sequencer">
           <mode:classname>
           	org.modeshape.sequencer.image.ImageMetadataSequencer
           </mode:classname>
           <mode:description>Image metadata sequencer</mode:description>        
           <mode:pathExpression>/foo/source => /foo/target</mode:pathExpression>
           <mode:pathExpression>/bar/source => /bar/target</mode:pathExpression>
       </mode:sequencer-->
   </mode:sequencers>
   <mode:mimeTypeDetectors>
       <mode:mimeTypeDetector jcr:name="Detector" 
                             mode:description="Standard extension-based MIME type detector"/>
   </mode:mimeTypeDetectors>
</configuration>
]]></programlisting>
	</sect2>
	<sect2 id="programmatic_configuration">
		<title>Programmatic Configuration</title>
		<para>
			Most likely you'll define your configuration <link linkend="loading_from_file">in a file</link>.
			But there are some situations where it's far easier - even necessary - to programmatically configure ModeShape.
			For example, you may not be able to predefine a configuration, because it needs parameters and information
			known only at runtime.
		</para>
		<para>
			One obvious approach is to write code that takes this new information and generates a ModeShape configuration
			file. The challenge here is that a sizable amount of code may be required just to write out the XML file
			in the correct format.
		</para>
		<para>
			Perhaps an easier approach is to use the ModeShape &JcrConfiguration; class to programmatically construct
			the configuration, and then have it write the configuration out to a file. You can even load a starting
			configuration, programmatically modify it, and write it out to a file. From there, your application
			can use the standard and implementation-independent JCR API to find and use the &Repository; instances.
		</para>
		<para>
			The &JcrConfiguration; class is used by ModeShape to read in the configuration files, but it was also
			designed to have an easy-to-use API that makes it easy to configure each of the different kinds of
			components, especially when using an IDE with code completion. The next few sections describe
			how to configure the various parts of a ModeShape configuration.
		</para>
		<sect3 id="programmatically_configuring_sources">
			<title>Repository Sources</title>
			<para>Each repository source definition must include the name of the &RepositorySource; class as well as each bean property
				that should be set on the object:
			</para>
   		<programlisting language="JAVA" role="JAVA"><![CDATA[JcrConfiguration config = ...
config.repositorySource("source A")
     .usingClass(InMemoryRepositorySource.class)
     .setDescription("The repository for our content")
     .setProperty("defaultWorkspaceName", workspaceName);
]]></programlisting>
			<para>
				This example defines an in-memory source with the name "source A", a description, and a single "defaultWorkspaceName" bean property.
				Different &RepositorySource; implementations will the bean properties that are required and optional.
				Of course, the class can be specified as Class reference or a string (followed by whether the class should be loaded from
				the classpath or from a specific classpath).
			</para>
			<note>
				<para>Each time <code>repositorySource(String)</code> is called, it will either load the existing definition with the supplied
				name or will create a new definition if one does not already exist.  To remove a definition, simply call <code>remove()</code>
				on the result of <code>repositorySource(String)</code>.
				The set of existing definitions can be accessed with the <code>repositorySources()</code> method.
				</para>
			</note>
		</sect3>
		<sect3 id="programmatically_configuring_repositories">
			<title>Repositories</title>
			<para>Each repository must be defined to use a named repository source, but all other aspects (e.g., namespaces, node types, options) 
				are optional.</para> 
   		<programlisting language="JAVA" role="JAVA"><![CDATA[JcrConfiguration config = ...
config.repository("repository A")
     .addNodeTypes("myCustomNodeTypes.cnd")		// can be called multiple times
     .setSource("source 1")
     .registerNamespace("acme","http://www.example.com/acme")
     .setOption(JcrRepository.Option.JAAS_LOGIN_CONFIG_NAME, "modeshape-jcr");
]]></programlisting>
			<para>
				This example defines a repository that uses the "source 1" repository source (which could be a federated source, an in-memory source,
				a database store, or any other source).  Additionally, this example adds the node types in the "myCustomNodeTypes.cnd" file as those
				that will be made available when the repository is accessed.  It also defines the "http://www.example.com/acme" namespace,
				and finally sets the "JAAS_LOGIN_CONFIG_NAME" option to define the name	of the JAAS login configuration that should be used by 
				the ModeShape repository.
			</para>
			<note>
				<para>Each time <code>repository(String)</code> is called, it will either load the existing definition with the supplied
				name or will create a new definition if one does not already exist.  To remove a definition, simply call <code>remove()</code>
				on the result of <code>repository(String)</code>.
				The set of existing definitions can be accessed with the <code>repositories()</code> method.
				</para>
			</note>
		</sect3>
		<sect3 id="programmatically_configuring_sequencers">
			<title>Sequencers</title>
			<para>Each defined sequencer must specify the name of the &StreamSequencer; implementation class as well as the path expressions
				defining which nodes should be sequenced and the output paths defining where the sequencer output should be placed (often as a function
				of the input path expression).</para> 
   		<programlisting language="JAVA" role="JAVA"><![CDATA[JcrConfiguration config = ...
config.sequencer("Image Sequencer")
     .usingClass("org.modeshape.sequencer.image.ImageMetadataSequencer")
     .loadedFromClasspath()
     .setDescription("Sequences image files to extract the characteristics of the image")
     .sequencingFrom("//(*.(jpg|jpeg|gif|bmp|pcx|png|iff|ras|pbm|pgm|ppm|psd)[*])/jcr:content[@jcr:data]")
     .andOutputtingTo("/images/$1");
]]></programlisting>
			<para>
				This shows an example of a sequencer definition named "Image Sequencer" that uses the &ImageMetadataSequencer; class 
				(loaded from the classpath), that is to sequence the "jcr:data" property on any new or changed nodes that are named 
				"jcr:content" below a parent node	with a name ending in ".jpg", ".jpeg", ".gif", ".bmp", ".pcx", ".iff", ".ras", 
				".pbm", ".pgm", ".ppm" or ".psd".  The output of the sequencing operation should be placed at the "/images/$1" node,
				where the "$1" value is captured as the name of the parent node.  (The capture groups work the same way as regular expressions.)
				Of course, the class can be specified as Class reference or a string (followed by whether the class should be loaded from
				the classpath or from a specific classpath).
			</para>
			<note>
				<para>Each time <code>sequencer(String)</code> is called, it will either load the existing definition with the supplied
				name or will create a new definition if one does not already exist.  To remove a definition, simply call <code>remove()</code>
				on the result of <code>sequencer(String)</code>.
				The set of existing definitions can be accessed with the <code>sequencers()</code> method.
				</para>
			</note>
			<para>Note that in addition to including a description for the configuration, it is also possible to set sequencer-specific properties
				using the <code>setProperty(String,String[])</code> method. When ModeShape uses this configuration to set up a sequencing
				operation, it will instantiate the &StreamSequencer; class and will call a JavaBean-style setter method for each property.
				For example, calling <code>setProperty("foo","val1")</code> on the sequencer configuration will mean that ModeShape
				will instantiate the sequencer implementation and will look for a <code>setFoo(String)</code> method on the sequencer implementation
				class, and use that method (if found) to pass the "val1" value to the instance.
			</para>
		</sect3>
		<sect3 id="programmatically_configuring_mime_type_detectors">
			<title>MIME Type Detectors</title>
			<para>Each defined MIME type detector must specify the name of the &MimeTypeDetector; implementation class as well as any
				other bean properties required by the implementation.</para> 
   		<programlisting language="JAVA" role="JAVA"><![CDATA[JcrConfiguration config = ...
config.mimeTypeDetector("Extension Detector")
     .usingClass(org.modeshape.graph.mimetype.ExtensionBasedMimeTypeDetector.class);
]]></programlisting>
			<para>
				Of course, the class can be specified as Class reference or a string (followed by whether the class should be loaded from
				the classpath or from a specific classpath).
			</para>
			<note>
				<para>Each time <code>mimeTypeDetector(String)</code> is called, it will either load the existing definition with the supplied
				name or will create a new definition if one does not already exist.  To remove a definition, simply call <code>remove()</code>
				on the result of <code>mimeTypeDetector(String)</code>.  
				The set of existing definitions can be accessed with the <code>mimeTypeDetectors()</code> method.
				</para>
			</note>
	</sect3>
	<sect3 id="storing_configuration">
		<title>Storing Configuration</title>
		<para>
			Regardless of how the &JcrConfiguration; is loaded, it can also be stored to a file or stream in an XML format that can then be
			reloaded in the future to recreate the configuration. This makes it very easy to programmatically generate a configuration file
			once while being able to load that same configuration at a later time (or on a different instance).
		</para>
   		<programlisting language="JAVA" role="JAVA"><![CDATA[JcrConfiguration config = ...
String pathToFile = ...

// Save any changes before this point in the configuration repository ...
configuration.save();
// And now write out the configuration repository to a file ...
configuration.storeTo(pathToFile);
]]></programlisting>
		<para>
			This will create a file at <code>pathToFile</code> that contains the current configuration in XML format. Any changes made after 
			the most recent call to the <code>save()</code> method on the &JcrConfiguration; object will not be saved in the configuration
			repository, and thus will not be in the generated file. The generated XML will not be formatted, so it may be a bit
			hard to read. (Any good XML editor will be able to format it for readability.)
		</para>
	</sect3>
	</sect2>
	<sect2 id="loading_from_repository">
		<title>Loading from a Configuration Repository</title>
		<para>
			So far, we've seen how to load a configuration from a file, how to programmatically define a configuration 
			and write it out to a file. In this section, we'll see how ModeShape can load its configuration from
			another repository.
		</para>
		<note>
			<para>
			This really is a very advanced way to define your configuration, so this is recommended only for those
			that are already very comfortable with ModeShape and its lower-level <link linkend="graph-model">graph API</link> and 
			<link linkend="connector-framework">connector API</link>.
			</para>
		</note>
		<para>
			The first step is to create and configure the &RepositorySource; instance that we'll use to access the
			repository where the configuration is stored.  Then, create a &JcrConfiguration; instance and 
			load from this source:
		</para>
   	<programlisting language="JAVA" role="JAVA"><![CDATA[RepositorySource configSource = ...
JcrConfiguration config = new JcrConfiguration();
configuration.loadFrom(configSource);
]]></programlisting>
		<para>The <code>loadFrom(...)</code> method can be called any number of times, but each time it is called it completely wipes
		  out any current notion of the configuration and replaces it with the configuration found in the file.
		</para>
		<para>
			There is an optional second parameter that defines the name of the workspace in the supplied source where the configuration content
			can be found.  It is not needed if the workspace is the source's default workspace. 
			There is an optional third parameter that defines the &Path; within the configuration repository identifying the parent node of the various
			configuration nodes.  If not specified, it assumes "/".  This makes it possible for the configuration content to be
			located at a different location in the hierarchical structure.  (This is not often required, but it is very useful
			if you ModeShape configuration file is embedded within another XML file.)
		</para>
		<para>
			Once the &JcrConfiguration; has been loaded from a &RepositorySource;, the &JcrConfiguration; instance can be used
			to modify the configuration and then save those changes back to the repository. This technique can be used to
			place a configuration into a repository (such as a database) for the first time:
		</para>
   	<programlisting language="JAVA" role="JAVA"><![CDATA[RepositorySource configSource = ...	// a RepositorySource to an empty source
JcrConfiguration config = new JcrConfiguration();

// Bind the configuration to the repository source (which is initially empty)...
configuration.loadFrom(configSource);

// Now load a configuration from a file (or construct one programmatically) ...
String pathToFile = ... 
configuration.loadFrom(pathToFile);

// Now save the configuration into the source ...
configuration.save();
]]></programlisting>
		<para>
			Now you can load this configuration in multiple processes, using the approach mentioned above.
		</para>
	</sect2>
 </sect1>
 <sect1 id="jcr_repository_options">
	  <title>JCR Repository options</title>
	  <para>
		  ModeShape JCR repositories have a number of behaviors that can be controlled from within the configuration.
		  These are known as <emphasis>repository options</emphasis>, and all have sensible defaults. However, they
		  do allow you to better configure the JCR repository instances to best suit your needs. 
		</para>
		<para>
			As mentioned earlier, these options can be set programmatically or within the configuration file. When setting up the configuration programmatically, 
			the actual enum literal values must be used, and all values are String literals:
		</para>
 		<programlisting language="JAVA" role="JAVA"><![CDATA[JcrConfiguration config = ...
config.repository("repository A")
     .setOption(JcrRepository.Option.JAAS_LOGIN_CONFIG_NAME, "modeshape-jcr");
]]></programlisting>
		<para>
			When using a configuration file, you set the option within the "<code>mode:options</code>"
			fragment under the "<code>mode:repository</code>" section. Each option fragment typically looks
			something like this:
		</para>
   	<programlisting language="JAVA" role="JAVA"><![CDATA[<mode:option jcr:name="jaasLoginConfigName" mode:value="modeshape-jcr"/>
]]></programlisting>
		<para>
			where the "<code>jcr:name</code>" XML attribute value contains the lower-camel-case form of the option literal, and the "<code>mode:value</code>" 
			XML attribute value contains the repository option value. In the example above, the "jaasLoginConfigName" is the option name,
			and "modeshape-jcr" is the option value. An alternative representation is to set the name using the XML element name and set the primary type
			with an XML attribute. Thus, this fragment is equivalent to the previous listing:
		</para>
   	<programlisting language="JAVA" role="JAVA"><![CDATA[<jaasLoginConfigName jcr:primaryType="mode:option" mode:value="modeshape-jcr"/>
]]></programlisting>
		<para>
			The following table describes all of the current repository options.
		</para>
	<table frame='all'>
		<title>JCR Repository Options</title>
		<tgroup cols='2' align='left' colsep='1' rowsep='1'>
      <colspec colname='c1' colwidth="1*"/>
      <colspec colname='c2' colwidth="1*"/>
			<thead>
				<row>
		  		<entry>Option</entry>
		  		<entry>Description</entry>
				</row>
			</thead>
			<tbody>
				<row>
					<entry>jaasLoginConfigName</entry>
					<entry>
						The JAAS <ulink url='&Java;javax/security/auth/login/Configuration.html'>JAAS application configuration name</ulink>
						that specifies which login module should be used to validate credentials. By default, "modeshape-jcr" is used.
						Set the option with an empty (zero-length) value to completely turn off JAAS authentication (see the
						<link linkend="jcr-built-in-auth-providers">Built-In Providers section</link> for details).
						The enumeration literal is <ulink url='&API;jcr/JcrRepository.Option.html#JAAS_LOGIN_CONFIG_NAME'>Option.JAAS_LOGIN_CONFIG_NAME</ulink>
					</entry>
				</row>
				<row>
					<entry>systemSourceName</entry>
					<entry>
						<para>
						The name of the source (and optionally the workspace in the source) where the "/jcr:system" branch should be stored. 
						The format is "name of workspace@name of source", or simply "name of source" if the default workspace is to be used. 
						If this option is not used, a transient in-memory source will be used. Note that all leading and trailing whitespaces is removed 
						for both the source name and workspace name. Thus, a value of "@" implies a zero-length workspace name and zero-length source name.
						Also, any use of the '@' character in source and workspace names must be escaped with a preceding backslash.
						</para>
						<para>
						The enumeration literal is <ulink url='&API;jcr/JcrRepository.Option.html#SYSTEM_SOURCE_NAME'>Option.SYSTEM_SOURCE_NAME</ulink>
  					</para>
					</entry>
				</row>
				<row>
					<entry>anonymousUserRoles</entry>
					<entry>
						A comma-delimited list of default roles provided for anonymous access. A null or empty value for this option means that anonymous access is disabled.
						The enumeration literal is <ulink url='&API;jcr/JcrRepository.Option.html#ANONYMOUS_USER_ROLES'>Option.ANONYMOUS_USER_ROLES</ulink>
					</entry>
				</row>
				<row>
					<entry>exposeWorksapceNamesInDescription</entry>
					<entry>
						<para>
							A boolean flag that indicates whether a complete list of workspace names should be exposed in the custom repository descriptor 
							"<code>org.modeshape.jcr.api.Repository.REPOSITORY_WORKSPACES</code>". If this option is set to true, then any code that can access the 
							repository can retrieve a complete list of workspace names through the javax.jcr.Repository.getDescriptor(String) method without logging in.
							The default value is 'true', meaning that the descriptor is populated.
						</para>
						<para>
							Since some ModeShape installations may consider the list of workspace names to be restricted information and limit the ability of some or all 
							users to see a complete list of workspace names, this option can be set to "false" to disable this capability. If this option is set to "false", 
							the "<code>org.modeshape.jcr.api.Repository.REPOSITORY_WORKSPACES</code>" descriptor will not be set.
						</para>
						<para>
							The enumeration literal is <ulink url='&API;jcr/JcrRepository.Option.html#EXPOSE_WORKSPACE_NAMES_IN_DESCRIPTOR'>Option.EXPOSE_WORKSPACE_NAMES_IN_DESCRIPTOR</ulink>
						</para>
					</entry>
				</row>
				<row>
					<entry>repositoryJndiLocation</entry>
					<entry>
						A string property that when specified tells the &JcrEngine; where to put the &Repository; in JNDI. Assumes that you have write access to the JNDI tree. 
						If no value set, then the &Repository; will not be bound to JNDI.
						The enumeration literal is <ulink url='&API;jcr/JcrRepository.Option.html#REPOSITORY_JNDI_LOCATION'>Option.REPOSITORY_JNDI_LOCATION</ulink>
					</entry>
				</row>
				<row>
					<entry>queryExecutionEnabled</entry>
					<entry>
						A boolean flag that specifies whether this repository is expected to execute searches and queries. If client applications will never perform searches 
						or queries, then maintaining the query indexes is an unnecessary overhead, and can be disabled. Note that this is merely a hint, and that searches 
						and queries might still work when this is set to 'false'. The default is 'true', meaning that clients can execute searches and queries.
						The enumeration literal is <ulink url='&API;jcr/JcrRepository.Option.html#QUERY_EXECUTION_ENABLED'>Option.QUERY_EXECUTION_ENABLED</ulink>
					</entry>
				</row>
				<row>
					<entry>queryIndexDirectory</entry>
					<entry>
						<para>
							The system may maintain a set of indexes that improve the performance of searching and querying the content. These size of these indexes 
							depend upon the size of the content being stored, and thus may consume a significant amount of space. This option defines a location on 
							the file system where this repository may (if needed) store indexes so they don't consume large amounts of memory.
						</para>
						<para>
							If specified, the value must be a valid path to a writable directory on the file system. If the path specifies a non-existant location, 
							the repository may attempt to create the missing directories. The path may be absolute or relative to the location where this VM was started. 
							If the specified location is not a readable and writable directory (or cannot be created as such), then this will generate an exception when 
							the repository is created.
						</para>
						<para>
							The default value is null, meaning the search indexes may not be stored on the local file system and, if needed, will be stored within memory.
						</para>
						<para>
							The enumeration literal is <ulink url='&API;jcr/JcrRepository.Option.html#QUERY_INDEX_DIRECTORY'>Option.QUERY_INDEX_DIRECTORY</ulink>
  					</para>
					</entry>
				</row>
				<row>
					<entry>queryIndexesUpdatedSynchronously</entry>
					<entry>
						<para>
							An <emphasis>advanced</emphasis> boolean flag that specifies whether updates to the indexes (if used) should be made synchronously, meaning that a call to Session.save() 
							will not return until the search indexes have been completely updated. The benefit of synchronous updates is that a search or query 
							performed immediately after a save() will operate upon content that was just changed. The downside is that the save() operation will take longer.
						</para>
						<para>
							With asynchronous updates, however, the only work done during a save() invocation is that required to persist the changes in the underlying 
							repository source, while changes to the search indexes are made in a different thread that may not run immediately. In this case, there may 
							be an indeterminate lag before searching or querying after a save() will operate upon the changed content.
						</para>
						<para>
							The default is value '<emphasis>false</emphasis>', meaning the updates are performed asynchronously.
						</para>
						<para>
							The enumeration literal is <ulink url='&API;jcr/JcrRepository.Option.html#QUERY_INDEXES_UPDATED_SYNCHRONOUSLY'>Option.QUERY_INDEXES_UPDATED_SYNCHRONOUSLY</ulink>
						</para>
					</entry>
				</row>
				<row>
					<entry>queryIndexesRebuiltSynchronously</entry>
					<entry>
						<para>
							An <emphasis>advanced</emphasis> boolean flag that specifies whether the indexes should be rebuilt synchronously when the repository restarts.
							If this flag is set to '<emphasis>true</emphasis>', query indexes for each workspace in the repository will be rebuilt synchronously 
							the first time that the repository is accessed (e.g., at the first login).  If this flag is set to '<emphasis>false</emphasis>', the query
							indexes for each workspace in the repository will be rebuilt asynchronously.
						</para>
						<para>
						    Rebuilding the indexes synchronously can cause very significant latency in the initial repository access if the repository contains a significant amount of 
						    content that must be reindexed.  Updating the indexes asynchronously eliminates this latency, but repository queries may generate inconsistent results
						    while the indexes are being updated.  That is, query results may refer to content that is no longer in the repository or may fail to include appropriate
						    results for nodes that had been added to the repository.
						</para>
						<para>
							The default is value '<emphasis>true</emphasis>', meaning the rebuilds are performed synchronously.
						</para>
						<para>
							The enumeration literal is <ulink url='&API;jcr/JcrRepository.Option.html#QUERY_INDEXES_REBUILT_SYNCHRONOUSLY'>Option.QUERY_INDEXES_REBUILT_SYNCHRONOUSLY</ulink>
						</para>
					</entry>
				</row>
				<row>
					<entry>rebuildQueryIndexOnStartup</entry>
					<entry>
						<para>
							An <emphasis>advanced</emphasis> setting that specifies the strategy used to determine which query indexes need to be rebuilt when the repository restarts.
							ModeShape currently supports two strategies:
							<itemizedlist>
								<listitem>
									<para>A value of "always" dictates that the query index for every workspace in the repository will be rebuilt each time that the repository restarts.
									This can sharply increase the startup time for the repository, particularly if the <code>queryIndexesRebuiltSynchronously</code> option is set to 
									'<emphasis>true</emphasis>' (the default).  However, this strategy ensures that any repository content that was modified outside of the repository 
									(e.g., files in a &FileSystemSource; that were directly modified on the file system) are properly indexed.
									</para>
								</listitem>
								<listitem>
									<para>A value of "ifMissing" indicates that indexes should only be rebuilt if they do not currently exist or are obviously invalid.  This strategy is
									always the most appropriate strategy for non-clustered repositories with repository sources that provide exclusive control over content (e.g., 
									the &InfinispanSource;, the &JpaSource;) as it greatly reduces repository startup time for repositories with significant amounts of content.
									</para>
								</listitem>
							</itemizedlist>
							Note that repositories that do not configure the <code>queryIndexDirectory</code> option will always use an in-memory index.  This type of index
							will not be persisted across repository restarts and will require ModeShape to rebuild the indexes each time the repository starts up even if the 
							"ifMissing" strategy is specified.
						</para>	
						<para>	
							The "always" strategy is used by default and in cases where the option's value does not case-independently match the one of these two values.  This was the only
							strategy available prior to ModeShape 2.5.0.Beta3.
						</para>
						<para>
							The enumeration literal is <ulink url='&API;jcr/JcrRepository.Option.html#QUERY_INDEXES_REBUILT_SYNCHRONOUSLY'>Option.QUERY_INDEXES_REBUILT_SYNCHRONOUSLY</ulink>,
							and the values are <ulink url='&API;jcr/JcrRepository.RebuildQueryIndexOnStartupOption.html#ALWAYS'>RebuildQueryIndexOnStartupOption.ALWAYS</ulink> and
							<ulink url='&API;jcr/JcrRepository.RebuildQueryIndexOnStartupOption.html#IF_MISSING'>RebuildQueryIndexOnStartupOption.IF_MISSING</ulink>
					</para>
					</entry>
				</row>				
				<row>
					<entry>projectNodeTypes</entry>
					<entry>
						An <emphasis>advanced</emphasis> boolean flag that defines whether or not the node types should be exposed as content under the "/jcr:system/jcr:nodeTypes" node. 
						Value is either "true" or "false" (default).
						The enumeration literal is <ulink url='&API;jcr/JcrRepository.Option.html#PROJECT_NODE_TYPES'>Option.PROJECT_NODE_TYPES</ulink>
					</entry>
				</row>
				<row>
					<entry>readDepth</entry>
					<entry>
						An <emphasis>advanced</emphasis> integer flag that specifies the depth of the subgraphs that should be loaded from the connectors during normal 
						read operations. The default value is 1.
						The enumeration literal is <ulink url='&API;jcr/JcrRepository.Option.html#READ_DEPTH'>Option.READ_DEPTH</ulink>
					</entry>
				</row>
				<row>
					<entry>indexReadDepth</entry>
					<entry>
						An <emphasis>advanced</emphasis> integer flag that specifies the depth of the subgraphs that should be loaded from the connectors during indexing 
						operations. The default value is 4.
						The enumeration literal is <ulink url='&API;jcr/JcrRepository.Option.html#INDEX_READ_DEPTH'>Option.INDEX_READ_DEPTH</ulink>
					</entry>
				</row>
				<row>
					<entry>tablesIncludeColumnsForInheritedProperties</entry>
					<entry>
						<para>
							An <emphasis>advanced</emphasis> boolean flag that dictates whether the property definitions inherited from supertypes should be represented
							in the corresponding queryable table with columns. The JCR specification gives implementations some flexibility, so ModeShape allows this to be controlled.
						</para>
						<para>
							When this option is set to "false", then each table has only those columns representing the (single-valued) property definitions explicitly defined by the 
							node type. When this option is set to "true" (the default), each table will contain columns for each of the (single-valued) property definitions explicitly defined on
							the node type and inherited by the node type from all of the supertypes.
						</para>
						<para>
							The enumeration literal is <ulink url='&API;jcr/JcrRepository.Option.html#TABLES_INCLUDE_COLUMNS_FOR_INHERITED_PROPERTIES'>Option.TABLES_INCLUDE_COLUMNS_FOR_INHERITED_PROPERTIES</ulink>
						</para>
					</entry>
				</row>
				<row>
					<entry>performReferentialIntegrityChecks</entry>
					<entry>
						<para>
							An <emphasis>advanced</emphasis> boolean flag that specifies whether referential integrity checks should be performed upon Session.save(). 
							If set to "true" (the default), referential integrity checks are performed to ensure that nodes referenced by other nodes 
							cannot be removed. If the value is set to "false", then these referential integrity checks will not be performed when removing nodes.
						</para>
						<para>
							Many people generally discourage the use of REFERENCE properties because of the overhead and the need for referential integrity. These concerns are
							somewhat mitigated by the introduction in JCR 2.0 of the WEAKREFERENCE property type, which are excluded from referential integrity checks.
						</para>
						<para>
							This option is available for those cases where REFERENCE properties are <emphasis>not</emphasis> used within your content, and thus
							the referential integrity checks will never find violations. In these cases, you may disable these checks to slightly improve performance
							of delete operations.
						</para>
						<para>
							The enumeration literal is <ulink url='&API;jcr/JcrRepository.Option.html#PERFORM_REFERENTIAL_INTEGRITY_CHECKS'>Option.PERFORM_REFERENTIAL_INTEGRITY_CHECKS</ulink>
						</para>
					</entry>
				</row>
				<row>
					<entry>versionHistoryStructure</entry>
					<entry>
						<para>
							An <emphasis>advanced</emphasis> flag that specifies the structure used to store version histories under the "<code>/jcr:system/jcr:versionStorage</code>" branch. 
							The JCR 2.0 specification does not predefine any particular structure, but ModeShape supports two types:
							<itemizedlist>
								<listitem>
									<para>A value of "flat" dictates that all "<code>nt:versionHistory</code>" nodes are stored with a name matching the UUID of the versioned node and 
										directly under the "<code>/jcr:system/jcr:versionStorage</code>" node. For example, given a "<code>mix:versionable</code>" node with the UUID 
										<code>fae2b929-c5ef-4ce5-9fa1-514779ca0ae3</code>, the corresponding " <code>nt:versionHistory</code>" node will be at 
										"<code>/jcr:system/jcr:versionStorage/fae2b929-c5ef-4ce5-9fa1-514779ca0ae3</code>".
									</para>
								</listitem>
								<listitem>
									<para>A value of "hierarchical" dictates that all "<code>nt:versionHistory</code>" nodes are stored under a hierarchical structure created by the first 
										8 characters of the UUID string. For example, given a "<code>mix:versionable</code>" node with the UUID <code>fae2b929-c5ef-4ce5-9fa1-514779ca0ae3</code>, 
										the corresponding "<code>nt:versionHistory</code>" node will be at "<code>/jcr:system/jcr:versionStorage/fa/e2/b9/29/c5ef-4ce5-9fa1-514779ca0ae3</code>.
									</para>
								</listitem>
							</itemizedlist>
							The "hierarchical" structure is used by default and in cases where the option's value does not case-independently match the one of these two values.
						</para>
						<para>
							The enumeration literal is <ulink url='&API;jcr/JcrRepository.Option.html#VERSION_HISTORY_STRUCTURE'>Option.VERSION_HISTORY_STRUCTURE</ulink>,
							and the values are <ulink url='&API;jcr/JcrRepository.VersionHistoryOption.html#FLAT'>VersionHistoryOption.FLAT</ulink> and
							<ulink url='&API;jcr/JcrRepository.VersionHistoryOption.html#HIERARCHICAL'>VersionHistoryOption.HIERARCHICAL</ulink>
					</para>
					</entry>
				</row>
				<row>
					<entry>removeDerivedContentWithOriginal</entry>
					<entry>
						<para>
							An <emphasis>advanced</emphasis> boolean flag that dictates whether content derived from other content (e.g., that output by sequencers) should be 
							automatically (re)moved when the content from which it was derived is (re)moved from the repository. For example, consider that a file is uploaded and 
							sequenced, and that the content derived from the file is stored in the repository. When that file is (re)moved, this option dictates whether the 
							derived content should also be (re)moved automatically.
						</para>
						<para>
							By default this option has a value of "true", ensuring that all derived content is deleted whenever the original content is deleted.
							A value of "false" will leave the derived content.
						</para>
						<para>
							The enumeration literal is <ulink url='&API;jcr/JcrRepository.Option.html#REMOVE_DERIVED_CONTENT_WITH_ORIGINAL'>Option.REMOVE_DERIVED_CONTENT_WITH_ORIGINAL</ulink>
						</para>
					</entry>
				</row>
				<row>
					<entry>useAnonymousAccessOnFailedLogin</entry>
					<entry>
						<para>
							A boolean flag that indicates whether any failed, non-anonymous login attempts will automatically cause the &Session; to be created using the anonymous context.  If anonymous logins are not enabled
							(with the anonymousUserRoles option), then the login will still fail. 
						</para>
						<para>
							By default this option has a value of "false", ensuring that non-anonymous login attempts either succeed as the requested user or fail.
						</para>
						<para>
							The enumeration literal is <ulink url='&API;jcr/JcrRepository.Option.html#USE_ANONYMOUS_ACCESS_ON_FAILED_LOGIN'>Option.USE_ANONYMOUS_ACCESS_ON_FAILED_LOGIN</ulink>
						</para>
					</entry>
				</row>				
				<row>
					<entry>useSecurityContextCredentials</entry>
					<entry>
						Older versions of ModeShape allowed client applications to pass in &Credentials; implementations that had a <code>getSecurityContext()</code> method
						that returned a &SecurityContext; object, which ModeShape would then use for authorization. However, since ModeShape now provides support for
						customized authentication and authorization modules, this is no longer needed and has been deprecated. If, however, your applications were written
						to use this &SecurityContextCredentials; implementation, then you can enable this option to turn the old behavior back on. Note, however, that
						this option will be removed in the next major release.
						Value is either "true" or "false" (default).
						The enumeration literal is <ulink url='&API;jcr/JcrRepository.Option.html#USE_SECURITY_CONTEXT_CREDENTIALS'>Option.USE_SECURITY_CONTEXT_CREDENTIALS</ulink>
					</entry>
				</row>
			</tbody>
		</tgroup>
	</table>
		    <warning>
		    <para>
					Setting the useAnonymousAccessOnFailedLogin option to "true" and setting the anonymousUserRoles to a valid value means that all login attempts will succeed, but 
					named login attempts may actually succeed in an anonymous context.  You can programattically determine which context is being used by checking the value of &Session;.getUserID().
				</para>
		  </warning>
 </sect1>
 <sect1 id="system_workspace_configuration">
	  <title>Repository system content</title>
	  <para>
		  Each JCR repository contains information about the system in the "<code>/jcr:system</code>" area of the repository content.
		  All of this system content applies to the whole repository (e.g., namespaces, node types, locks, versions, etc.) and
		  therefore every session for each workspace sees the exact same "<code>/jcr:system</code>" content.
		</para>
		<para>
			ModeShape implements this behavior by storing all "<code>/jcr:system</code>" content in a separate workspace, and then
			using <link linkend="federation-connector">federation</link> to project that content into each workspace. This ensures
			that all workspaces see the same content, without having to duplicate the "<code>/jcr:system</code>" content in each workspace
			and ensure those copies stay in sync. Federation is better than duplication.
		</para>
		<para>
			By default, ModeShape creates this separate system workspace in a transient, in-memory store. This works great for some
			simplistic cases, but this doesn't work when using <link linkend="clustering">clustering</link>, 
			<link linkend="jcr2_versioning">versioning</link>, or dynamically registering namespaces or
			<link linkend="jcr2_node_type_management">adding or changing node types</link>. 
			This is because these features all rely upon changing or adding content in the "<code>/jcr:system</code>"
			area. For example, version histories are stored under "<code>/jcr:system/jcr:versionStorage</code>", node types
			under "<code>/jcr:system/jcr:versionStorage</code>", and namespaces under "<code>/jcr:system/mode:namespaces</code>".
		</para>
		<para>
			In these situations, it is necessary to persist the system content in a repository source, and if clustering is enabled
			this source needs to be accessible to all members of the cluster. Many times, the easiest approach is to simply define
			an extra workspace in your repository source where the system content can be stored. It's also possible to define
			a separate repository source with a separate workspace for each repository's system content. (Using a separate source is required
			when the repository is using a single repository source that can only store limited kinds of nodes, like the
			<link linkend="file-system-connector">file system connector</link> or <link linkend="subversion-connector">Subversion connector</link>
			that can only store <code>nt:file</code> and <code>nt:folder</code> nodes.)
		</para>
		<para>
			You should always configure each ModeShape repository with a source for its system workspace by using the
			<code>SYSTEM_SOURCE_NAME</code> repository option with a value that defines the name of source and name of the workspace
			in that source where the system content should be stored, in the format:
		</para>
   	<programlisting>  workspaceName@sourceName</programlisting>
		<para>
			This specifies the system content should be stored in the workspace named "<code>workspaceName</code>" in the 
			"<code>sourceName</code>" repository source.
		</para>
		<para>
			The system content can be stored in any repository source capable of storing any content and, in the case
			of clustering, that is accessible across multiple processes. For most people, this will mean a relational database.
			Here is an abbreviated example of an XML configuration that defines a source for the system storage (in a MySQL database)
			and a repository that uses it:
		</para>
   	<programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<configuration xmlns:mode="http://www.modeshape.org/1.0" 
	             xmlns:jcr="http://www.jcp.org/jcr/1.0">
  <mode:repositories>
    <mode:repository jcr:name="car repository" mode:source="Cars">
      <mode:options jcr:primaryType="mode:options">
        <!-- Explicitly specify the "system" workspace in the "SystemStore" source. -->
        <systemSourceName jcr:primaryType="mode:option" 
	                           mode:value="system@SystemStore"/>
        ...
      </mode:options>
      ...
    </mode:repository>
    ...
  </mode:repositories>
  <mode:sources jcr:primaryType="nt:unstructured">
    <!-- One source for the "/jcr:system" content ... -->
    <mode:source jcr:name="SystemStore" 
                 mode:classname="org.modeshape.connector.store.jpa.JpaSource"
                 mode:description="The database store for our system content"
                 mode:dialect="org.hibernate.dialect.MySQLDialect"
                 mode:dataSourceJndiName="java:/MyDataSource"
                 mode:defaultWorkspaceName="system"
                 mode:autoGenerateSchema="validate"/>    
    </mode:sources>
    <!-- An another source for the regular content ... -->
    <mode:source jcr:name="Cars" 
                 mode:classname="org.modeshape.connector.store.jpa.JpaSource"
                 mode:description="The database store for our system content"
                 mode:dialect="org.hibernate.dialect.MySQLDialect"
                 mode:dataSourceJndiName="java:/MyDataSource"
                 mode:defaultWorkspaceName="workspace1"
                 mode:autoGenerateSchema="validate">
      <mode:predefinedWorkspaceNames>workspace1</mode:predefinedWorkspaceNames>
      <mode:predefinedWorkspaceNames>workspace2</mode:predefinedWorkspaceNames>
      <mode:predefinedWorkspaceNames>workspace3</mode:predefinedWorkspaceNames>
    </mode:sources>
    ...
  </mode:sources>
  ...
</configuration>
]]></programlisting>
		<para>
			Of course, you can always use a separate workspace in your primary source, too:
		</para>
   	<programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<configuration xmlns:mode="http://www.modeshape.org/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0">
  <mode:repositories>
    <mode:repository jcr:name="car repository" mode:source="Cars">
      <mode:options jcr:primaryType="mode:options">
        <!-- Explicitly specify the "system" workspace in the "Cars" source. -->
        <systemSourceName jcr:primaryType="mode:option" mode:value="system@Cars"/>
        ...
      </mode:options>
      ...
    </mode:repository>
    ...
  </mode:repositories>
  <mode:sources jcr:primaryType="nt:unstructured">
    <!-- 
    Define one source for the regular content with a special workspace for the system content.
    -->
    <mode:source jcr:name="Cars" 
                 mode:classname="org.modeshape.connector.store.jpa.JpaSource"
                 mode:description="The database store for our system content"
                 mode:dialect="org.hibernate.dialect.MySQLDialect"
                 mode:dataSourceJndiName="java:/MyDataSource"
                 mode:defaultWorkspaceName="workspace1"
                 mode:autoGenerateSchema="validate">
      <mode:predefinedWorkspaceNames>workspace1</mode:predefinedWorkspaceNames>    
      <mode:predefinedWorkspaceNames>workspace2</mode:predefinedWorkspaceNames>    
      <mode:predefinedWorkspaceNames>workspace3</mode:predefinedWorkspaceNames>    
      <mode:predefinedWorkspaceNames>system</mode:predefinedWorkspaceNames>    
    </mode:sources>
    ...
  </mode:sources>
  ...
</configuration>
]]></programlisting>
	</sect1>
  <sect1 id="query_index_directory">
	  <title>Query index directory</title>
	  <para>
		  ModeShape maintains a set of index files that are used to process <link linkend="jcr-query-and-search">queries and searches</link>,
		  using the Lucene search engine. By default, these indexes are kept in memory (primarily because it's easy to configure).
		  But most production configurations should not store them in-memory but should instead store these index files on the local
		  file system.
		</para>
	  <para>
	    Each ModeShape repository can be configured where the indexes should be stored, using the "QUERY_INDEX_DIRECTORY" repository
      option (see &JcrRepositoryOption;) when using the programmatic API or the "queryIndexDirectory" repository option in a
      ModeShape configuration file. The value of this setting should be the absolute or relative path to the folder where the 
      indexes should be stored. In this directory, ModeShape will store the index files for each workspace in a folder
      named similarly to the workspace. Note that ModeShape will dynamically create these workspace folders as required.
	  </para>
		<para>
			For example, here is part of a ModeShape configuration file that specifies these index files should be stored in the 
			"<code>data/car_repository/indexes</code>" folder, relative to the folder where the JVM process was started:
		</para>
   	<programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<configuration xmlns:mode="http://www.modeshape.org/1.0" 
	             xmlns:jcr="http://www.jcp.org/jcr/1.0">
  <mode:repositories>
    <mode:repository jcr:name="car repository" mode:source="Cars">
      <mode:options jcr:primaryType="mode:options">
        <!-- Explicitly specify the directory where the index files should be stored. -->
        <queryIndexDirectory jcr:primaryType="mode:option" 
	                           mode:value="data/car_repository/indexes"/>
        ...
      </mode:options>
      ...
    </mode:repository>
    ...
  </mode:repositories>
  ...
</configuration>
]]></programlisting>
  </sect1>
  <sect1 id="jcr-security">
	  <title>Authentication and Authorization</title>
	  <para>
	    ModeShape 2.6 introduced pluggable authentication and authorization modules. Several modules are included and configured out-of-the-box,
	    but it is now possible to implement and configure customized authentication and authorization logic. This section describes how
	    these modules work, what's there out-of-the-box, and how to implement and add your own modules.
	  </para>
	  <para>
	    The &AuthenticationProvider; interface defines a single method:
	  </para>
 		<programlisting language="JAVA" role="JAVA"><![CDATA[public interface AuthenticationProvider {

  /**
   * Authenticate the user that is using the supplied credentials. If the supplied
   * credentials are authenticated, this method should construct an ExecutionContext 
   * that reflects the authenticated environment, including the context's valid
   * SecurityContext that will be used for authorization throughout the Session.
   * <p>
   * Note that each provider is handed a map into which it can place name-value 
   * pairs that will be used in the Session attributes of the Session that results
   * from this authentication attempt. ModeShape will ignore any attributes if 
   * this provider does not authenticate the credentials.
   * </p>
   * 
   * @param credentials the user's JCR credentials, which may be an 
   *  AnonymousCredentials if authenticating as an anonymous user
   * @param repositoryName the name of the JCR repository; never null
   * @param workspaceName the name of the JCR workspace; never null
   * @param repositoryContext the execution context of the repository, which 
   * may be wrapped by this method
   * @param sessionAttributes the map of name-value pairs that will be placed 
   *  into the Session's attributes; never null
   * @return the execution context for the authenticated user, or null if 
   * this provider could not authenticate the user
   */
  ExecutionContext authenticate( Credentials credentials,
                                 String repositoryName,
                                 String workspaceName,
                                 ExecutionContext repositoryContext,
                                 Map<String,Object> sessionAttributes );

}]]></programlisting>
    <para>
      When a client calls one of the &Repository;'s <code>login</code> methods, ModeShape calls the <code>authenticate</code> method
      on each of the &AuthenticationProvider; implementations registered with the Repository. As soon as one provider returns a non-null
      &ExecutionContext;, the caller is authenticated and ModeShape uses that ExecutionContext within the resulting &Session;. 
    </para>
    <para>
      When the client uses the &Session; and attempts to perform actions on the content, ModeShape uses the ExecutionContext's
      &SecurityContext; to determine whether the user has the necessary privileges. If the &SecurityContext; object implements the
      &AuthorizationProvider; interface, then ModeShape will call the <code>hasPermission(...)</code> method, passing in the
      ExecutionContext, the repository name, the name of the source used for the repository, the workspace name, the path of
      the node upon which the actions are being applied, and the array of actions (see &ModeShapePermissions; for the possible values):
    </para>
 		<programlisting language="JAVA" role="JAVA"><![CDATA[public interface AuthorizationProvider {

  /**
   * Determine if the supplied execution context has permission for all of the 
   * named actions in the named workspace. If not all actions are allowed, the
   * method returns false.
   * 
   * @param context the context in which the subject is performing the 
   *        actions on the supplied workspace
   * @param repositoryName the name of the repository containing the 
   *        workspace content
   * @param repositorySourceName the name of the repository's source
   * @param workspaceName the name of the workspace in which the path exists
   * @param path the path on which the actions are occurring
   * @param actions the list of ModeShapePermissions actions to check
   * @return true if the subject has privilege to perform all of the named 
   *         actions on the content at the supplied path in the
   *         given workspace within the repository, or false otherwise
   */
  boolean hasPermission( ExecutionContext context,
                         String repositoryName,
                         String repositorySourceName,
                         String workspaceName,
                         Path path,
                         String... actions );
}]]></programlisting>
    <para>
      If the &SecurityContext; does not implement &AuthorizationProvider;, then ModeShape uses role-based authorization by
      <link linkend="modeshape_jcr_security">mapping the actions into roles</link> and then for each role calling the 
      <link linkend="security">hasRole(...) method</link> on &SecurityContext;. Only if all of these invocations returns <code>true</code>
      will the operation be allowed to continue.
    </para>
    <sect2 id="jcr-built-in-auth-providers">
	    <title>Built-in Providers</title>
	    <para>
	      ModeShape comes with several &AuthorizationProvider; implementations that are automatically configured with every Repository,
	      depending upon other settings and options. These providers are as follows:
				<itemizedlist>
					<listitem>
						<para>&JaasProvider; uses <link linkend="jaas_security">JAAS</link> for all authentication and role-based authorization. 
						 This provider authenticates clients that login to the &Repository; with a &SimpleCredentials; object, where the username and password match that
						 in the JAAS policy, or a &JaasCredentials; constructed with a specific and already-authenticated JAAS &LoginContext;.
						 This provider can be disabled by setting the <link linkend="jcr_repository_options">jaasLoginConfigName configuration option</link>
						 to an empty (i.e., zero-length) value; otherwise, the option defines the name of the JAAS login configuration and
						 will default to "modeshape-jcr" if not explicitly set. (This provider also works in some J2EE containers, in which 
						 the JAAS Subject is not available via the standard JAAS API and instead requires use of the JACC API, which many
						 J2EE containers support).</para>
					</listitem>
					<listitem>
						<para>&SeamSecurityProvider; delegates all authentication and role-based authorization to the Seam Security framework.
						 This provider authenticates clients that login to the &Repository; with no need to pass a &Credentials; object. 
						 Note this does require obtaining a session for each servlet request, which is actually how
						 the JCR API was intended to be used within web applications. This provider is automatically enabled when the
						 Seam Security Identity class is found on the classpath.</para>
					</listitem>
					<listitem>
						<para>&ServletProvider; delegates all authentication and role-based authorization to the servlet framework.
						 This provider authenticates clients that login to the &Repository; with a &ServletCredentials; object, which can be constructed with the
						 &HttpServletRequest;. Note this does require obtaining a session for each servlet request, which is actually how
						 the JCR API was intended to be used within web applications. This provider is automatically enabled when the
						 HttpServletSession class is found on the classpath.</para>
					</listitem>
					<listitem>
						<para>&AnonymousProvider; will allow clients without &Credentials; to operate upon the repository, and will
						 use role-based authorization based upon the roles defined by the 
						 <link linkend="jcr_repository_options">anonymousUserRoles configuration option</link>.
						 This provider authenticates clients that provide an &AnonymousCredentials; to the &Repository;'s <code>login(...)</code> methods or
						 use one of the <code>login(...)</code> methods that does not take a &Credentials; object.</para>
					</listitem>
				</itemizedlist>
				<note>
				  <para>
				    The &SecurityContextProvider; is also configured only when the
				    <link linkend="jcr_repository_options">useSecurityContextCredentials configuration option</link> is set to 'true'.
				    This provider authenticates clients that pass a &SecurityContextCredentials; object, and delegates all authentication to
				    the embedded SecurityContext. This deprecated approach is not enabled by default, and will be removed in the next major release of ModeShape.
				    It remains in place to enable applications that use this older and less attractive approach to upgrade to ModeShape 2.6 (or later) without breaking their
				    authentication mechanism.
				  </para>
				</note>
	    </para>
    </sect2>
    <sect2 id="jcr-custom-auth-providers">
	    <title>Custom Providers</title>
	    <para>
	      It is possible to provide your own authentication and authorization logic by providing one (or more) classes that implements
	      the &AuthorizationProvider; interface, specifying the names of these classes in the configuration (see below), and making the classes available on the
	      correct classpath.
	    </para>
	    <para>
	      Implementing the &AuthorizationProvider; interface is pretty straightforward. Your class needs a no-arg constructor, and the
	      <code>authenticate</code> method must simply authenticate the credentials for the named repository and workspace. If the
	      credentials are not authenticated, simply return null. Otherwise, simply create an &ExecutionContext; instance (from the
	      ExecutionContext supplied in the <code>repositoryContext</code> parameter) to contain an appropriate &SecurityContext; instance
	      for the authenticated user. As mentioned above, the &SecurityContext; should also implement the &AuthorizationProvider; interface
	      for non-role-based authorization.
	    </para>
	    <para>
	      For example, let's imagine that our JCR application has its own authentication and authorization system. We can integrate with
	      that by create a new &Credentials; implementation called <code>MyAppCredentials</code> to encapsulate any information needed by
	      the authentication/authorization system, which we'll assume is accessed by a singleton class <code>SecurityService</code>.
	      We can then implement &AuthenticationProvider; as follows:
	    </para>
 		<programlisting language="JAVA" role="JAVA"><![CDATA[public class MyAppAuthorizationProvider implements AuthorizationProvider {

  private String appName;
  
  /**
   * Any public JavaBean properties can be set in the configuration
   */
  public void setApplicationName( String appName ) {
    this.appName = appName;
  }

  /**
   * Authenticate the user that is using the supplied credentials. If the supplied
   * credentials are authenticated, this method should construct an ExecutionContext
   * that reflects the authenticated environment, including the context's valid
   * SecurityContext that will be used for authorization throughout the Session.
   * <p>
   * Note that each provider is handed a map into which it can place name-value 
   * pairs that will be used in the Session attributes of the Session that results
   * from this authentication attempt. ModeShape will ignore any attributes if 
   * this provider does not authenticate the credentials.
   * </p>
   * 
   * @param credentials the user's JCR credentials, which may be an 
   *  AnonymousCredentials if authenticating as an anonymous user
   * @param repositoryName the name of the JCR repository; never null
   * @param workspaceName the name of the JCR workspace; never null
   * @param repositoryContext the execution context of the repository, which 
   * may be wrapped by this method
   * @param sessionAttributes the map of name-value pairs that will be placed 
   *  into the Session's attributes; never null
   * @return the execution context for the authenticated user, or null if 
   * this provider could not authenticate the user
   */
  public ExecutionContext authenticate( Credentials credentials,
                                        String repositoryName,
                                        String workspaceName,
                                        ExecutionContext repositoryContext,
                                        Map<String,Object> sessionAttributes );
    if ( credentials instanceof MyAppCredentials ) {
      // Try to authenticate ...
      MyAppCredentials appCreds = (MyAppCredentials)credentials;
      String user = appCreds.getUser();
      Object token = appCreds.getToken();
      AppCreds creds = SecurityService.login(appName,user,token);
      if ( creds != null ) {
        // We're in ...
        SecurityContext securityContext = new MyAppSecurityContext(creds);
        return repositoryContext.with(securityContext);
      }
    }
    return null;    
  }
}]]></programlisting>
      <para>
        where the <code>MyAppSecurityContext</code> is as follows:
      </para>
 		<programlisting language="JAVA" role="JAVA"><![CDATA[public class MyAppSecurityContext 
            implements SecurityContext, AuthorizationProvider {
  private final AppCreds creds;
  public MyAppSecurityContext( AppCreds creds ) {
    this.creds = creds;
  }
 	
  /**
   * {@inheritDoc SecurityContext#getUserName()}
   * 
   * @see SecurityContext#getUserName()
   */
  public final String getUserName() {
      return creds.getUser();
  }

  /**
   * {@inheritDoc SecurityContext#hasRole(String)}
   * 
   * @see SecurityContext#hasRole(String)
   */
  public final boolean hasRole( String roleName ) {
      // shouldn't be called since we've implemented AuthorizationProvider
      return false;
  }

  /**
   * {@inheritDoc}
   * 
   * @see org.modeshape.graph.SecurityContext#logout()
   */
  public void logout() {
      creds.logout();
  }
  
  /**
   * {@inheritDoc}
   * 
   * @see org.modeshape.jcr.security.AuthorizationProvider.hasPermission
   */
  public boolean hasPermission( ExecutionContext context,
                           String repositoryName,
                           String repositorySourceName,
                           String workspaceName,
                           Path path,
                           String... actions ) {
    // This is imaginary and simplistic, but you'd implement any authorization logic here ...
    return this.creds.isAuthorized(repositoryName,workspaceName,path);
  }
}]]></programlisting>
      <para>
        Then we just need to configure the Repository to use this provider. In the ModeShape configuration files, there is an optional
        "<code>mode:authenticationProviders</code>" child element of "<code>mode:repository</code>", and within this fragment
        you can define zero or more authentication providers by specifying a name, the class, an optional description,
        and optionally any bean properties that should be called upon instantiation. (Note that the class will be instantiated
        only once per Repository instance). Here's an example configuration file:
      </para>
   	<programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<configuration xmlns:mode="http://www.modeshape.org/1.0" 
	             xmlns:jcr="http://www.jcp.org/jcr/1.0">
  <mode:repositories>
    <mode:repository jcr:name="MyApp Repository" mode:source="Store">
      ...
      <mode:authenticationProviders>
        <!-- Specify the providers in a manner similar to sequencer 
             definitions are defined -->
        <mode:authenticationProvider jcr:name="CustomProviderA" 
                    mode:classname="org.example.MyAppAuthorizationProvider">
          <mode:description>My authentication provider</mode:description>
          <!-- Set JavaBean properties on provider if needed -->
          <mode:appName>MyAppName</mode:appName>
        </mode:authenticationProvider>
        ...
      </mode:authenticationProviders>
      ...
    </mode:repository>
    ...
  </mode:repositories>
  ...
</configuration>
]]></programlisting>
    </sect2>
  </sect1>
  <sect1 id="clustering">
	  <title>Clustering</title>
	  <para>
	    ModeShape 2.1 introduced the ability to have a cluster of &JcrEngine; instances distributed across multiple processes while
	    behaving as though everything was happening in a single process. With clusters, the workload can be distributed across multiple
			machines, increasing tolerance against failure while allowing ModeShape to scale out to handle more workload.
	  </para>
		<para>
			ModeShape clustering uses the powerful, flexible and mature <ulink url="&JGroups;">JGroups</ulink> library to handle
			all network communication within the cluster. JGroups provides a wealth of capabilities, including automatically detecting
			new engines in the cluster (called discovery), reliable multicast communication, and automatic determination of the master 
			node in the cluster. JGroups has a flexible protocol stack, works across firewalls, WANs and LANs, and supports multiple 
			transport protocols, failure detection, reliable unicast and multicast message transmission, and encryption.
		</para>
		<para>
			By default, clustering is <emphasis>not</emphasis> enabled. This means that each &JcrEngine; instance is self-contained
			and will not be aware of changes made in other &JcrEngine; instances. This is perfect in many lightweight or embedded
			scenarios, because it does not introduce any overhead associated with network communication.
		</para>
		<para>
			However, clustering ModeShape is very easy and requires only a few simple steps:
			<orderedlist>
				<listitem>
					<para>
						Enable clustering in the ModeShape configuration (more on this in a bit).
					</para>
				</listitem>
				<listitem>
					<para>
						Include the <code>modeshape-clustering</code> module in your application, either by 
						<link linkend="using_modeshape_via_jars">JAR file</link> or <link linkend="using_modeshape_via_maven">Maven dependency</link>.
					</para>
				</listitem>
				<listitem>
					<para>
						Start (or deploy) multiple &JcrEngine; instances using the same configuration. For embedded scenarios, this means simply
						instantiating multiple &JcrEngine; instances in multiple processes. In other cases, this means deploying ModeShape
						to multiple servers (either using the <link linkend="webdav_server">WebDAV</link> server, <link linkend="rest_serve">REST server</link>,
						or <link linkend="modeshape_and_jndi">into JNDI</link> and using with your own applications).
					</para>
				</listitem>
			</orderedlist>
			Your JCR-based application doesn't need to change in any other ways. Any &EventListener; implementations registered in
			&Session;s on any of the engines will be notified of all events, regardless of whether those events were due to changes
			in the local or remote engines.
		</para>
		<para>
			It also doesn't matter how many &Repository; instances are defined in the configuration and managed by each &JcrEngine; instance:
			each engine in the cluster can manage multiple named repositories.
			ModeShape ensures that all &Session;s for a named repository see the changes made to that repository, regardless of where those
			sessions are located in the cluster. Likewise, those same changes will not be visible to the sessions for any other named repository.
		</para>
	  <sect2 id="clustering_configuration">
		  <title>Enabling Clustering in ModeShape</title>
		  <para>
			  A ModeShape configuration can have a "<code>clustering</code>" fragment that defines the name of the cluster and the
			  JGroups configuration:
			</para>
    	<programlisting language="XML" role="XML"><![CDATA[<mode:clustering clusterName="modeshape-cluster" configuration="jgroups-modeshape.xml" />]]></programlisting>
			<para>
				The "<code>clusterName</code>" is a string that is a logical name of the cluster; all engines connecting to the same name
				form a cluster. Any messages multicast from one engine in the cluster will be received by all other members of the cluster.
				Again, the cluster name is <emphasis>independent</emphasis> of the repositories managed by th
			</para>
			<para>
				The "<code>configuration</code>" value is a string that is one of:
				<itemizedlist>
					<listitem>
						<para>the absolute file system path to the file containing the JGroups XML configuration;</para>
					</listitem>
					<listitem>
						<para>the relative file system path to the file containing the JGroups XML configuration, relative to the current working directory of the Java process;</para>
					</listitem>
					<listitem>
						<para>the name of a resource on the classpath containing the JGroups XML configuration;</para>
					</listitem>
					<listitem>
						<para>the URL that can be resolved to the JGroups XML configuration; or</para>
					</listitem>
					<listitem>
						<para>the string representation of JGroups configuration, either in XML format or the older string format.</para>
					</listitem>
				</itemizedlist>
				The format of this JGroups configuration will be described in the <link linkend="jgroups_clustering_configuration">next section</link>.
				If the "<code>configuration</code>" property is not given, ModeShape will use the default JGroups configuration (as defined by the specific
				JGroups version).
			</para>
			<note>
				<para>
					Note that all engines in the cluster must have the same JGroups configuration. In fact, all engines in the cluster will
					almost always have exactly the same ModeShape configuration.
				</para>
			</note>
			<para>
				Here is an example of a "<code>clustering</code>" fragment defining a cluster named "modeshape-cluster" using the JGroups
				configuration defined in the "jgroups-modeshape.xml" file at the supplied URL:
			</para>
    	<programlisting language="XML" role="XML"><![CDATA[<clustering clusterName="modeshape-cluster" 
	  configuration="file://some/path/jgroups-modeshape.xml" />]]></programlisting>
			<para>
				This next example uses the JGroups configuration defined in the "jgroups-modeshape.xml" resource file on the classpath
				(or as an absolute path on a *nix system):
			</para>
    	<programlisting language="XML" role="XML"><![CDATA[<clustering clusterName="modeshape-cluster" 
	  configuration="/some/path/jgroups-modeshape.xml" />]]></programlisting>
			<para>
				Next is an example that specifies the JGroups configuration using the older string representation of the form:
			</para>
    	<programlisting language="XML" role="XML"><![CDATA[<clustering clusterName="modeshape-cluster" 
	  configuration="PROTOCOL(param=value;param=value):PROTOCOL:PROTOCOL" />]]></programlisting>
			<para>
				Of course, the "<code>configuration</code>" property can be specified as a child element, too (line breaks added for readability):
			</para>
    	<programlisting language="XML" role="XML"><![CDATA[<clustering clusterName="modeshape-cluster">
	     <configuration>UDP(max_bundle_size="60000":max_bundle_timeout="30"):
		                  PING(timeout="2000"):...</configuration>
</clustering>]]></programlisting>
			<para>
				And finally an example that specifies the JGroups configuration using the newer XML representation (line breaks added for readability):
			</para>
    	<programlisting language="XML" role="XML">&lt;clustering clusterName="modeshape-cluster">
	 &lt;configuration>&lt;![CDATA[&lt;config>&lt;UDP max_bundle_size="60000" 
	      max_bundle_timeout="30".../>&lt;PING timeout="2000"/>...&lt;/config>]]&gt;
	 &lt;/configuration>
&lt;/clustering></programlisting>
      <para>
	      Note that the this example uses a child XML element for the "<code>configuration</code>", along with
	      a CDATA section, so that the XML configuration can be nested within the ModeShape configuration.
	    </para>
	    <warning>
		    <para>
					Remember to specify the <link linkend="system_workspace_configuration">system workspace name</link>
					for each repository that is clustered.
				</para>
		  </warning>
		</sect2>
	  <sect2 id="jgroups_clustering_configuration">
		  <title>JGroups configuration</title>
		  <para>
			  The JGroups configuration defines a protocol stack that is used for messaging, starting with the bottom-most protocol
			  and ending with the top-most protocol.
			</para>
		  <para>
				An example of the newer-style JGroups XML format is:
			</para>
    	<programlisting language="XML" role="XML"><![CDATA[<config>
   <UDP
        mcast_addr="${jgroups.udp.mcast_addr:228.10.10.10}"
        mcast_port="${jgroups.udp.mcast_port:45588}"
        discard_incompatible_packets="true"
        max_bundle_size="60000"
        max_bundle_timeout="30"
        ip_ttl="${jgroups.udp.ip_ttl:2}"
        enable_bundling="true"
        thread_pool.enabled="true"
        thread_pool.min_threads="1"
        thread_pool.max_threads="25"
        thread_pool.keep_alive_time="5000"
        thread_pool.queue_enabled="false"
        thread_pool.queue_max_size="100"
        thread_pool.rejection_policy="Run"
        oob_thread_pool.enabled="true"
        oob_thread_pool.min_threads="1"
        oob_thread_pool.max_threads="8"
        oob_thread_pool.keep_alive_time="5000"
        oob_thread_pool.queue_enabled="false"
        oob_thread_pool.queue_max_size="100"
        oob_thread_pool.rejection_policy="Run"/>
   <PING timeout="2000"
           num_initial_members="3"/>
   <MERGE2 max_interval="30000"
           min_interval="10000"/>
   <FD_SOCK/>
   <FD timeout="10000" max_tries="5" />
   <VERIFY_SUSPECT timeout="1500"  />
   <BARRIER />
   <pbcast.NAKACK
                  use_mcast_xmit="false" gc_lag="0"
                  retransmit_timeout="300,600,1200,2400,4800"
                  discard_delivered_msgs="true"/>
   <UNICAST timeout="300,600,1200,2400,3600"/>
   <pbcast.STABLE stability_delay="1000" desired_avg_gossip="50000"
                  max_bytes="400000"/>
   <VIEW_SYNC avg_send_interval="60000"   />
   <pbcast.GMS print_local_addr="true" join_timeout="3000"
               view_bundling="true"/>
   <FC max_credits="20000000"
                   min_threshold="0.10"/>
   <FRAG2 frag_size="60000"  />
   <pbcast.STATE_TRANSFER  />
</config>]]></programlisting>
		  <para>
				The older-style JGroups string format is of the form:
			</para>
			<programlisting>PROTOCOL(param1=value1:param2=value2):PROTOCOL:PROTOCOL</programlisting>
		  <para>
				This format is generally harder to read and generally discouraged.
				Nevertheless, here's an example of the older string format defining the same stack as the previous XML example 
				(line breaks have been added for readability):
			</para>
			<programlisting>UDP(
        mcast_addr="${jgroups.udp.mcast_addr:228.10.10.10}":
        mcast_port="${jgroups.udp.mcast_port:45588}":
        discard_incompatible_packets="true":
        max_bundle_size="60000":
        max_bundle_timeout="30":
        ip_ttl="${jgroups.udp.ip_ttl:2}":
        enable_bundling="true":
        thread_pool.enabled="true":
        thread_pool.min_threads="1":
        thread_pool.max_threads="25":
        thread_pool.keep_alive_time="5000":
        thread_pool.queue_enabled="false":
        thread_pool.queue_max_size="100":
        thread_pool.rejection_policy="Run":
        oob_thread_pool.enabled="true":
        oob_thread_pool.min_threads="1":
        oob_thread_pool.max_threads="8":
        oob_thread_pool.keep_alive_time="5000":
        oob_thread_pool.queue_enabled="false":
        oob_thread_pool.queue_max_size="100":
        oob_thread_pool.rejection_policy="Run"):
   PING(timeout="2000":
        num_initial_members="3"):
   MERGE2(max_interval="30000":
          min_interval="10000"):
   FD_SOCK:
   FD(timeout="10000":max_tries="5"):
   VERIFY_SUSPECT(timeout="1500"):
   BARRIER:
   pbcast.NAKACK(use_mcast_xmit="false":gc_lag="0":
                 retransmit_timeout="300,600,1200,2400,4800":
                 discard_delivered_msgs="true"):
   UNICAST(timeout="300,600,1200,2400,3600"):
   pbcast.STABLE(stability_delay="1000":desired_avg_gossip="50000":
                 max_bytes="400000"):
   VIEW_SYNC(avg_send_interval="60000"):
   pbcast.GMS(print_local_addr="true":join_timeout="3000"
              view_bundling="true"):
   FC(max_credits="20000000":
      min_threshold="0.10"):
   FRAG2(frag_size="60000"):
   pbcast.STATE_TRANSFER</programlisting>
		  <para>
				For more details on how to configure the JGroups stack, see the <ulink url="&JGroupsManual;">JGroups Manual</ulink>.
			</para>
			<note>
			  <para>
				  JGroups is also used in Infinispan, JBoss AS, and other open source projects, and many of the JGroups configurations 
				  will work with ModeShape deployed in those same environments. For example, 
				  <ulink url="http://infinispan.blogspot.com/2010/05/infinispan-ec2-demo.html">this blog post</ulink>
				  describes how to configure JGroups with three autodiscovery options available on Amazon EC2.
				</para>
			</note>
		</sect2>
 </sect1>
	<sect1 id="modeshape_in_web_applications">
		<title>Using ModeShape in Web Applications</title>
		<para>
			Sometimes your applications can simply define a configuration file and use the &RepositoryFactory; to access its
			repositories. This is very straightforward, and this is useful for many simple applications because the application
			will then own the ModeShape instance(s).
		</para>
		<para>
			Web applications are a different story. Often, you would rather your web application not contain the code that initializes
			the JCR repository, but instead configure ModeShape as a central, shared service that all of your web applications
			can simply reference and use.
		</para>
		<para>
			Unfortunately, there's not single way to deploy ModeShape into any web or application server, since they all have
			slightly different deployment and configuration techniques. The remainder of this section will talk about
			how to deploy ModeShape to two popular open source servers.
		</para>
		<sect2 id="deloying_modeshape_to_jbossas">
			<title>Deploying ModeShape to JBoss AS</title>
			<para>
				The <ulink url="http://jboss.org/jbossas">JBoss Application Server</ulink> (or JBoss AS) is a very popular
				open source Java application server, with an extremely healthy and active community. 
				ModeShape offers a way to deploy ModeShape into JBoss AS as as a central, shared service
				that can be monitored and administered using the embedded console.
			</para>
			<para>
				ModeShape provides a downloadable ZIP file that can be unzipped into any JBoss AS profile. When you do this,
				that profile will contain all the files necessary for ModeShape to run when the server is started.
				The default configuration is for a single, in-memory repository with two users. However,
				other than basic playing, you will want to edit the configuration files to define a more robust,
				persistent and secure configuration.
			</para>
			<para>
				This JBoss AS distribution ZIP file contains several components:
				<itemizedlist>
					<listitem>
						<para>
							JAR files for the JCR 2.0 API and ModeShape's small extensions to the JCR API on the global classpath
							(that is, in the "<code>lib/</code>" directory).
							These APIs are available to all deployed applications, services and components. The JCR API contains
							the "<code>javax.jcr</code>" packages and has no other dependencies. ModeShape's extensions
							define interfaces in the "<code>org.modeshape.jcr.api</code>" packages; these extend a few of the standard
							JCR API interfaces and add several methods to make them more useful.
						</para>
					</listitem>
					<listitem>
						<para>The ModeShape Service, represented as an exploded JAR file in the "<code>deploy</code>" directory.
							This is where the &JcrEngine; is running, though any application (or other JBoss service)
							can access its JCR Repository instances using the standard &RepositoryFactory; approach (covered in the
							<link linkend="obtaining_jcr_repository">next chapter</link>) with JNDI URLs:
						</para>
				    <programlisting> jndi:jcr/local?repositoryName=&defaultJBossASRepository;</programlisting>
						<para>
							By default, there is a single in-memory repository named "&defaultJBossASRepository;", but this 
							can be changed by simply editing the "<code>deploy/modeshape-services.jar/managedConfigRepository.xml</code>" 
							configuration file. All of ModeShape's standard sequencers and connectors (and JARs for their dependencies)
							are included, meaning they can be configured for use without worrying about adding JARs to the classpath.
							Feel free to remove any of the JARs are not needed for your custom configuration.
						</para>
					</listitem>
					<listitem>
						<para>A pair of JAAS properties files, located in the "<code>conf/props/</code>" directory, that come
							out of the box with an "admin" user (with password "admin") that has full read, write, and
							administration privileges, and a "guest" user (with password "guest") that has only
							read and write privileges. Simply edit these files to change users, passwords, and roles,
							or to configure JAAS differently.
						</para>
					</listitem>
					<listitem>
						<para>The ModeShape RESTful API, represented as an exploded WAR file in the "<code>deploy</code>" directory.
							This allows remote applications to interact with ModeShape to access and manipulate repository content
							using a RESTful API that uses JSON in the requests and responses. All ModeShape repositories
							can be accessed, and authentication is done using the ModeShape JAAS configuration.
						</para>
					</listitem>
					<listitem>
						<para>The ModeShape WebDAV API, represented as an exploded WAR file in the "<code>deploy</code>" directory.
							This web application allows external clients to access and manipulate the content in the 
							ModeShape repositories using the standard WebDAV protocol. For example, you can mount
							a repository (or parts of it) as a network drive on most operating systems, and then upload
							or download files and folders using standard OS operations and graphical tools. All ModeShape repositories
							can be accessed, and authentication is done using the ModeShape JAAS configuration.
						</para>
					</listitem>
					<listitem>
						<para>A plugin for the embedded JBoss AS console, represented as a WAR file in the "<code>deploy</code>" directory.
							This plugin also works with <ulink url="http://support.rhq-project.org/display/RHQ/Home">RHQ</ulink>
							administration, monitoring, alerting, operational
							control and configuration system.  <emphasis>(We plan to add more metrics and operations over the 
							next few releases, as we gain more experience using the ModeShape RHQ plugin.)</emphasis>
						</para>
					</listitem>
					<listitem>
						<para>
							A JDBC driver that allows applications also deployed on the same JBoss AS instance to query
							the repositories through JDBC. This driver is on the global
							classpath so it can be used in any deployed component. A single JDBC DataSource is
							also configured in the "<code>deploy/modeshape-services.jar/modeshape-jdbc-ds.xml</code>" 
							file to use the single default in-memory repository available out of the box. Simply edit
							this file to add or change the DataSource definitions. The driver can also be used
							in a separate JVM to issue queries and access database metadata.
						</para>
					</listitem>
					<listitem>
						<para>
							A remote client JAR that can be used by Java applications to use JDBC or the RESTful API to
							remotely access a ModeShape repository deployed on JBoss AS. This JAR includes ModeShape's
							full JDBC driver.
						</para>
					</listitem>
				</itemizedlist>
				Here are the contents of this file:
			</para>
<programlisting>
conf/
conf/props/
conf/props/modeshape-roles.properties  
conf/props/modeshape-users.properties  
lib/
lib/jcr-2.0.jar         
lib/modeshape-jcr-api-&versionNumber;.jar  
lib/modeshape-jdbc-local-&versionNumber;.jar  
deploy/
deploy/modeshape-jboss-beans.xml  
deploy/modeshape-services.jar/
deploy/modeshape-services.jar/META-INF/
deploy/modeshape-services.jar/aperture-1.1.0.Beta1.jar 
deploy/modeshape-services.jar/joda-time-1.6.jar  
deploy/modeshape-services.jar/lucene-analyzers-3.0.2.jar  
deploy/modeshape-services.jar/lucene-core-3.0.2.jar  
deploy/modeshape-services.jar/lucene-regex-3.0.2.jar  
deploy/modeshape-services.jar/lucene-snowball-3.0.2.jar  
deploy/modeshape-services.jar/lucene-misc-3.0.2.jar  
deploy/modeshape-services.jar/poi-3.6.jar  
deploy/modeshape-services.jar/poi-scratchpad-3.6.jar  
deploy/modeshape-services.jar/managedConfigRepository.xml  
deploy/modeshape-services.jar/rdf2go.api-4.6.2.jar
deploy/modeshape-services.jar/META-INF/jboss-beans.xml  
deploy/modeshape-services.jar/modeshape-cnd-&versionNumber;.jar  
deploy/modeshape-services.jar/modeshape-common-&versionNumber;.jar  
deploy/modeshape-services.jar/modeshape-connector-filesystem-&versionNumber;.jar  
deploy/modeshape-services.jar/modeshape-connector-infinispan-&versionNumber;.jar  
deploy/modeshape-services.jar/modeshape-connector-jbosscache-&versionNumber;.jar  
deploy/modeshape-services.jar/modeshape-connector-jcr-&versionNumber;.jar  
deploy/modeshape-services.jar/modeshape-connector-jdbc-metadata-&versionNumber;.jar  
deploy/modeshape-services.jar/modeshape-connector-store-jpa-&versionNumber;.jar  
deploy/modeshape-services.jar/modeshape-connector-svn-&versionNumber;.jar  
deploy/modeshape-services.jar/modeshape-graph-&versionNumber;.jar  
deploy/modeshape-services.jar/modeshape-jbossas-service-&versionNumber;.jar  
deploy/modeshape-services.jar/modeshape-jcr-&versionNumber;.jar  
deploy/modeshape-services.jar/modeshape-jdbc-ds.xml  
deploy/modeshape-services.jar/modeshape-mimetype-detector-aperture-&versionNumber;.jar  
deploy/modeshape-services.jar/modeshape-repository-&versionNumber;.jar  
deploy/modeshape-services.jar/modeshape-search-lucene-&versionNumber;.jar  
deploy/modeshape-services.jar/modeshape-sequencer-classfile-&versionNumber;.jar  
deploy/modeshape-services.jar/modeshape-sequencer-cnd-&versionNumber;.jar  
deploy/modeshape-services.jar/modeshape-sequencer-ddl-&versionNumber;.jar  
deploy/modeshape-services.jar/modeshape-sequencer-java-&versionNumber;.jar  
deploy/modeshape-services.jar/modeshape-sequencer-jbpm-jpdl-&versionNumber;.jar  
deploy/modeshape-services.jar/modeshape-sequencer-msoffice-&versionNumber;.jar  
deploy/modeshape-services.jar/modeshape-sequencer-teiid-&versionNumber;.jar  
deploy/modeshape-services.jar/modeshape-sequencer-text-&versionNumber;.jar  
deploy/modeshape-services.jar/modeshape-sequencer-xml-&versionNumber;.jar  
deploy/modeshape-services.jar/modeshape-sequencer-zip-&versionNumber;.jar  
deploy/modeshape-rest.war/
deploy/modeshape-rest.war/META-INF/
deploy/modeshape-rest.war/WEB-INF/
deploy/modeshape-rest.war/WEB-INF/lib/
deploy/modeshape-rest.war/META-INF/MANIFEST.MF  
deploy/modeshape-rest.war/WEB-INF/jboss-web.xml  
deploy/modeshape-rest.war/WEB-INF/lib/jaxrs-api-1.2.1.GA.jar  
deploy/modeshape-rest.war/WEB-INF/lib/jettison-1.1.jar  
deploy/modeshape-rest.war/WEB-INF/lib/modeshape-jcr-&versionNumber;.jar  
deploy/modeshape-rest.war/WEB-INF/lib/modeshape-web-jcr-&versionNumber;.jar  
deploy/modeshape-rest.war/WEB-INF/lib/modeshape-web-jcr-rest-&versionNumber;.jar  
deploy/modeshape-rest.war/WEB-INF/lib/resteasy-jaxb-provider-1.2.1.GA.jar  
deploy/modeshape-rest.war/WEB-INF/lib/resteasy-jaxrs-1.2.1.GA.jar  
deploy/modeshape-rest.war/WEB-INF/lib/resteasy-jettison-provider-1.2.1.GA.jar  
deploy/modeshape-rest.war/WEB-INF/lib/scannotation-1.0.2.jar  
deploy/modeshape-rest.war/WEB-INF/web.xml  
deploy/modeshape-webdav.war/
deploy/modeshape-webdav.war/WEB-INF/
deploy/modeshape-webdav.war/WEB-INF/lib/
deploy/modeshape-webdav.war/WEB-INF/jboss-web.xml  
deploy/modeshape-webdav.war/WEB-INF/lib/aperture-1.1.0.Beta1.jar  
deploy/modeshape-webdav.war/WEB-INF/lib/modeshape-jcr-&versionNumber;.jar  
deploy/modeshape-webdav.war/WEB-INF/lib/modeshape-mimetype-detector-aperture-&versionNumber;.jar  
deploy/modeshape-webdav.war/WEB-INF/lib/modeshape-web-jcr-&versionNumber;.jar  
deploy/modeshape-webdav.war/WEB-INF/lib/modeshape-web-jcr-webdav-&versionNumber;.jar  
deploy/modeshape-webdav.war/WEB-INF/lib/webdav-servlet-2.0.1.jar  
deploy/modeshape-webdav.war/WEB-INF/web.xml  
deploy/admin-console.war/
deploy/admin-console.war/plugins/
deploy/admin-console.war/plugins/modeshape-jbossas-console-&versionNumber;.jar  
</programlisting>
    <para>
	    Your web application or JBoss service can use one of the JCR &Repository; instances running inside the ModeShape service
	    by simply using the &RepositoryFactory; technique described <link linkend="repository_factory">earlier</link>, with a
	    URL such as:
		</para>
    <programlisting> jndi:jcr/local?repositoryName=&defaultJBossASRepository;</programlisting>
    <para>
	    Be sure to use the correct repository name.
	  </para>
	  <para>
		  Since the JCR API JAR is on the global classpath, your web application can use the JCR API without
		  having to include the JAR file in your application's WAR file. In fact, your application will likely
		  get ClassCastExceptions if it does include the JCR API in its WAR file.
		  Plus, if needed, your application can use ModeShape's "<code>org.modeshape.jcr.api</code>" extensions to the JCR API
		  (again, on the global classpath), and should not need or use any of the classes or interfaces in the ModeShape implementation.
	  </para>
    </sect2>
		<sect2 id="deloying_modeshape_to_tomcat">
			<title>Deploying ModeShape to Tomcat</title>
			<para>
				Each kind of web server or application server is different, but all servlet containers do provide a way of configuring
				objects and placing them into JNDI.  ModeShape provides a &JndiRepositoryFactory; class that implements &ObjectFactory;
				and that can be used in the server's configuration. The &JndiRepositoryFactory; requires two properties:
				<itemizedlist>
					<listitem>
						<para>
							<emphasis role="strong"><code>configFile</code></emphasis> is required and specifies the path to the 
							<link linkend="loading_from_file">configuration file</link> resource, which must be available on the classpath
						</para>
					</listitem>
					<listitem>
						<para>
							<emphasis role="strong"><code>repositoryName</code></emphasis> is optional and specifies the name of a JCR repository that exists
							in the JCR configuration that should be registered in JNDI; if not provided, then the
							ModeShape engine will be registered in JDNI at the specified location.
						</para>
					</listitem>
				</itemizedlist>
			</para>
			<para>
				Here's an example of a fragment of the <code>conf/context.xml</code> for Tomcat that registers the ModeShape engine 
				in JNDI at "jcr/local":
			</para>
<programlisting language="XML" role="XML"><![CDATA[<Resource name="jcr/local" 
          auth="Container"
          type="org.modeshape.jcr.api.Repository"
          factory="org.modeshape.jcr.JndiRepositoryFactory"
          configFile="/resource/path/to/configuration.xml" />]]></programlisting>
			<para>
				The web application can then use the newer pattern specified by the JCR 2.0 specification to use the &ServiceLoader; and
				&RepositoryFactory;:
			</para>	
<programlisting language="JAVA" role="JAVA"><![CDATA[String configUrl = "jndi:jcr/local?repositoryName=Cars";
Map<String, String> parameters = Collections.singletonMap("org.modeshape.jcr.URL", configUrl);
for (RepositoryFactory factory : ServiceLoader.load(RepositoryFactory.class)) {
    repository = factory.getRepository(parameters);
    if (repository != null) break;
}]]></programlisting>
			<para>
				Alternatively, it's possible to use this JndiRepositoryFactory class to start up ModeShape and register an individual
				JCR &Repository; instance. Here's an example of a fragment of the <code>conf/context.xml</code> for Tomcat that registers the "Cars" repository
				in JNDI at "jcr/local/Cars":
			</para>
<programlisting language="XML" role="XML"><![CDATA[<Resource name="jcr/local/Cars" 
          auth="Container"
          type="javax.jcr.Repository"
          factory="org.modeshape.jcr.JndiRepositoryFactory"
          configFile="/resource/path/to/configuration.xml"
          repositoryName="Cars" />]]></programlisting>
			<para>
				The web application can then directly lookup the &Repository; instance in JNDI, as recommended in the older JCR 1.0 specification:
			</para>
<programlisting language="JAVA" role="JAVA"><![CDATA[InitialContext initCtx = new InitialContext();
Context envCtx = (Context) initCtx.lookup("java:comp/env");
Repository repository = (Repository) envCtx.lookup("jcr/local/Cars");]]></programlisting>
			<para>
				or via the newer pattern using the JCR 2.0 &RepositoryFactory;-style lookup approach:
			</para>	
<programlisting language="JAVA" role="JAVA"><![CDATA[String configUrl = "jndi:jcr/local/Cars";
Map<String, String> parameters = Collections.singletonMap("org.modeshape.jcr.URL", configUrl);
for (RepositoryFactory factory : ServiceLoader.load(RepositoryFactory.class)) {
    repository = factory.getRepository(parameters);
    if (repository != null) break;
}]]></programlisting>
			<para>
				Note that it is possible to have multiple <code>Resource</code> entries. The &JndiRepositoryFactory; ensures
				that only one &JcrEngine; is instantiated, but that a &Repository; instance is registered for each entry.
			</para>
			<para>
				Before the server can start, however, all of the ModeShape jars need to be placed on the classpath for the server.
				JAAS also needs to be configured, and this can be done using the application server's configuration or in your
				web application if you're using a simple servlet container. For more details, see the &ReferenceGuide;.
			</para>
			<para>
				Then, your web application needs to reference the <code>Resource</code> and state its requirements in its 
				<code>web.xml</code>:
			</para>
<programlisting language="XML" role="XML"><![CDATA[<resource-env-ref>
   <description>Repository</description>
   <resource-env-ref-name>jcr/local/Cars</resource-env-ref-name>
   <resource-env-ref-type>javax.jcr.Repository</resource-env-ref-type>
</resource-env-ref>]]></programlisting>
      <para>
        or
      </para>
<programlisting language="XML" role="XML"><![CDATA[<resource-env-ref>
   <description>ModeShape Engine</description>
   <resource-env-ref-name>jcr/local</resource-env-ref-name>
   <resource-env-ref-type>org.modeshape.jcr.api.Repositories</resource-env-ref-type>
</resource-env-ref>]]></programlisting>
			<para>
				Note that the value of <code>resource-env-ref-name</code> fields must matche the value of the name attribute on the 
				<code>&lt;Resource></code> tag in the <code>context.xml</code> described above.  This is a must.
			</para>
			<para>
				At this point, your web application can perform the lookup of the &Repository; object by using JNDI directly
				(or the more standard &RepositoryFactory; technique shown in the <link linkend="obtaining_jcr_repository">next chapter</link>), 
				create and use a &Session;, and then close the &Session;.  Here's an example of a JSP page that does this:
			</para>
<programlisting language="JAVA" role="JAVA"><![CDATA[
<%@ page import="javax.naming.*, javax.jcr.*, org.jboss.security.config.IDTrustConfiguration" %>
<%!

static {
	// Initialize IDTrust
	IDTrustConfiguration idtrustConfig = new IDTrustConfiguration();
	try {
	    idtrustConfig.config("security/jaas.conf.xml");
	} catch (Exception ex) {
	    throw new IllegalStateException(ex);
	}
}
%>
<%
Session sess = null;
try {
	InitialContext initCtx = new InitialContext();
	Context envCtx = (Context) initCtx.lookup("java:comp/env");
	Repository repo = (Repository) envCtx.lookup("jcr/local/Cars");
	sess = repo.login(new SimpleCredentials("readwrite", "readwrite".toCharArray()));

	// Do something interesting with the Session ...
	out.println(sess.getRootNode().getPrimaryNodeType().getName());
} catch (Exception ex) {
	ex.printStackTrace();
} finally {
	if (sess != null) sess.logout();
}
%>
]]></programlisting>			
			<para>
				Since this uses a servlet container, there is no JAAS implementation configured, so note the 
				loading of IDTrust to create the JAAS realm.  (To make this work in Tomcat, the security
				folder that contains the <code>jaas.conf.xml</code>, <code>users.properties</code>, and
				<code>roles.properties</code> needs to be moved into the <code>%CATALINA_HOME%</code> directory.)
			</para>
			<note>
				<para>
				If you deploy your application to JBoss AS or EAP and deploy 
				<link linkend="deploying-modeshape-to-jbossas">ModeShape as a service</link>, your application
				doesn't have to do anything with JAAS, since that's provided by the platform.
			  </para>
			</note>
		</sect2>
	</sect1>
	<sect1 id="modeshape_classpath">
		<title>Setting the Classpath</title>
		<para>
			Before you deploy ModeShape into your application or its environment, you need to make sure that all of the ModeShape
			JARs are on the appropriate classpath. Two different scenarios are covered in this section: Maven-based, and using
			JARs with the traditional classpath.
		</para>
		<sect2 id="using_modeshape_via_maven">
			<title>Building against ModeShape via Maven</title>
			<para>
				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 <ulink url="&JBossMaven;">JBoss Maven repository</ulink> 
				under the "<ulink url="&ModeShapeMaven;">org.modeshape</ulink>" group ID.
			</para>
			<sect3 id="using_jboss_maven_repository">
				<title>Using the JBoss Maven repository</title>
				<para>
					The JBoss Maven repository not only contains all of the artifacts for ModeShape and other open source projects
					hosted at <ulink url="http://www.jboss.org">JBoss.org</ulink>, but it also 
					<ulink url="&JBossMavenDoc;">proxies quite a few other repositories</ulink> that contain many other third-party
					libraries.
				</para>
				<para>
				  So if you're using Maven (or Ivy), first make sure your project knows about this 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):
				</para>
<programlisting language="XML" role="XML"><![CDATA[<repositories>
  <repository>
    <id>jboss</id>
    <url>http://repository.jboss.org/nexus/content/groups/public/</url>
  </repository>
</repositories>
]]></programlisting>
				<para>
					Or, you can add this information to your <code>~/.m2/settings.xml</code> file. For more information,
					see the <ulink url="&JBossMavenUsing;">JBoss wiki page</ulink>.
				</para>
			</sect3>
			<sect3 id="adding_modeshape_dependencies">
				<title>Add dependency to ModeShape</title>
				<para>
					Then, simply modify your project's POM by adding dependencies on the ModeShape JCR library:
			  </para>
<programlisting language="XML" role="XML"><![CDATA[<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-jcr</artifactId>
  <version>2.8.1.GA</version>
</dependency>
]]></programlisting>
				<para>
					This adds only the minimal libraries required to use ModeShape. If your application is going
					to use clustering, you'll need to also depend upon the clustering module:
				</para>
<programlisting language="XML" role="XML"><![CDATA[<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-clustering</artifactId>
  <version>2.8.1.GA</version>
</dependency>
]]></programlisting>
				<para>
					You also need to add dependencies for 
					each of the connectors and sequencers you want to use. Here is the list of available sequencers:
				</para>
<programlisting language="XML" role="XML"><![CDATA[<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-sequencer-cnd</artifactId>
  <version>2.8.1.GA</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-sequencer-ddl</artifactId>
  <version>2.8.1.GA</version>
</dependency>
<dependency>
  <groupId>org.modeshapce</groupId>
  <artifactId>modeshape-sequencer-images</artifactId>
  <version>2.8.1.GA</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-sequencer-classfile</artifactId>
  <version>2.8.1.GA</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-sequencer-java</artifactId>
  <version>2.8.1.GA</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-sequencer-mp3</artifactId>
  <version>2.8.1.GA</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-sequencer-msoffice</artifactId>
  <version>2.8.1.GA</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-sequencer-xml</artifactId>
  <version>2.8.1.GA</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-sequencer-teiid</artifactId>
  <version>2.8.1.GA</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-sequencer-text</artifactId>
  <version>2.8.1.GA</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-sequencer-zip</artifactId>
  <version>2.8.1.GA</version>
</dependency>
]]></programlisting>
			<para>
				Here is the list of available connectors:
			</para>
<programlisting language="XML" role="XML"><![CDATA[<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-connector-filesystem</artifactId>
  <version>2.8.1.GA</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-connector-infinispan</artifactId>
  <version>2.8.1.GA</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-connector-jcr</artifactId>
  <version>2.8.1.GA</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-connector-jbosscache</artifactId>
  <version>2.8.1.GA</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-connector-jdbc-metadata</artifactId>
  <version>2.8.1.GA</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-connector-store-jpa</artifactId>
  <version>2.8.1.GA</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-connector-svn</artifactId>
  <version>2.8.1.GA</version>
</dependency>]]></programlisting>
	      <para>
		      The sequencer and connector libraries you choose, plus every third-party library they need, will be pulled in automatically 
		      by Maven into your project.
		    </para>
			</sect3>
		</sect2>
			<sect2 id="adding_logging_dependencies">
				<title>Add dependencies for logging</title>
				<para>
					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.
				</para>
				<para>
					For example, if your application is using <ulink url="&Log4J;">Log4J</ulink>, your application will already have a dependency 
					for it, and so ModeShape log messages will be sent to the same logging system used in your application, you need to add a 
					dependency to the SLF4J-to-Log4J binding JAR:
				</para>
<programlisting language="XML" role="XML"><![CDATA[<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>
]]></programlisting>
        <para>
	        Of course, SLF4J works with other logging frameworks, too. Some logging implementations (such as <ulink url="&LogBack;">LogBack</ulink>) 
	        implement the SLF4J API natively, meaning they require no binding JAR. For details on the options and how to configure them, see the 
	        <ulink url="&SLF4JManual;">SLF4J manual</ulink>.
        </para>
		</sect2>
		<sect2 id="using_modeshape_via_jars">
			<title>Building against ModeShape via JARs</title>
			<para>
				If your application doesn't use Maven, you'll need to obtain the ModeShape JARs and place them onto your application's classpath. 
				ModeShape provides a <ulink url="&SingleDownload;">single download</ulink> with all of the JARs for all ModeShape components 
				and all dependencies. This file contains the following:
				<itemizedlist>
	        <listitem>
	          <para>
	            <emphasis role="strong"><code>modeshape-jcr-&versionNumber;-jar-with-dependencies.jar</code></emphasis> contains all of the
	 						classes (except those under <code>javax.jcr</code>) necessary to run the core ModeShape JCR repository engine using
							the in-memory connector and the federating connector;
	          </para>
	        </listitem>
	        <listitem>
	          <para>
	            one <emphasis role="strong"><code>modeshape-connector-&lt;type>-&versionNumber;-jar-with-dependencies.jar</code></emphasis> 
							for each type of connector, each containing all of the classes necessary for that connector, designed to be added to the classpath
							after the <code>modeshape-jcr-&versionNumber;-jar-with-dependencies.jar</code> file;
	          </para>
	        </listitem>
	        <listitem>
	          <para>
	            one <emphasis role="strong"><code>modeshape-sequencer-&lt;type>-&versionNumber;-jar-with-dependencies.jar</code></emphasis> 
							for each type of connector, each containing all of the classes necessary for that sequencer, designed to be added to the classpath
							after the <code>modeshape-jcr-&versionNumber;-jar-with-dependencies.jar</code> file;
	          </para>
	        </listitem>
	        <listitem>
	          <para>
	            <emphasis role="strong"><code>modeshape-mimetype-detector-aperture-&versionNumber;-jar-with-dependencies.jar</code></emphasis> 
							containing all of the classes necessary for detecting the MIME type of files based upon
							their name and/or content, designed to be added to the classpath
							after the <code>modeshape-jcr-&versionNumber;-jar-with-dependencies.jar</code> file;
	          </para>
	        </listitem>
	      </itemizedlist>
				Note that the core engine is required in all configurations. The <code>jcr-2.0.jar</code> file is not included and must be provided by you. 
				And, as mentioned in the <link linkend="adding_logging_dependencies">previous section</link>, ModeShape uses SLF4J for logging and you must provide 
				a logging implementation as well as the appropriate SLF4J binding JAR.
			</para>
		</sect2>
	</sect1>
	<sect1 id="using_modeshape_whats_next">
		<title>What's next</title>
		<para>
			This chapter outlines how you configure ModeShape, how to deploy ModeShape into your application, and how to set up your application's environment
			with the required ModeShape JARs.
			The <link linkend="jcr">next chapter</link> talks about how your application can use the JCR API to access ModeShape repositories.
		</para>
	</sect1>
</chapter>
