<?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="infinispan-connector">
  <title>Infinispan Connector</title>
  <para>
  	The Infinispan repository connector allows a <ulink url="http://www.jboss.org/infinispan/">Infinispan</ulink> instance to be 
		used as a ModeShape (and thus JCR) repository.  This provides a way for the content in a repository to be stored in an
		effective, scalable, and distributed data grid,
		and can be <link linkend="federation-connector">federated</link> with other repository sources to provide a distributed repository.
  </para>
  <para>
	  There are two connectors that can be used. The &InfinispanSource; class, which was introduced in ModeShape 1.x, stores the content
	  in an Infinispan data grid that is running, at least in part, within the same process. The &RemoteInfinispanSource; class,
	  which was introduced in ModeShape 2.3.0.Final, is capable of storing content in a remote Infinispan data grid (where Infinispan
	  is running in remote processes). Because these two connectors communicate with Infinispan in different ways, they are configured
	  differently.
  </para>
	<para>
		The &InfinispanSource; class provides a number of JavaBean properties that control its behavior:
	</para>
  <variablelist>
    <varlistentry>
      <term>cacheContainerJndiName</term>
      <listitem>
        <para>
          Optional property that, if used, specifies the name in JNDI where an existing Infinispan Cache Manager instance can be found.
					That factory would then be used if needed to create an Infinispan Cache instance.  If no value is provided, then the
					Infinispan <code>DefaultCacheManager</code> class is used.
				</para>
				<para>
				  <emphasis>Note that the "<code>cacheManagerJndiName</code>" property is checked first as a pointer to the Infinispan <code>CacheManager</code>.
					If the JNDI name points to a CacheManager, the "<code>cacheConfigurationName</code>" property will not be considered.</emphasis>
				</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>cacheConfigurationName</term>
      <listitem>
				<para>
				  Optional property that, if used, specifies the name of the configuration resource or file that is supplied to the cache manager
					when creating a new Infinispan DefaultCacheManager instance.  The configuration name is first treated as a resource name and will be attempted
					to be loaded from the &ClassLoader;.  If that is unsuccessful, the configuration name is assumed to be a file name and will be loaded
					from the file system.  This initialization happens the first time that the source is used.
				</para>
				<para>
				  <emphasis>Note that the "<code>cacheManagerJndiName</code>" property is checked first as a pointer to the Infinispan <code>CacheManager</code>.
					If the JNDI name points to a CacheManager, the "<code>cacheConfigurationName</code>" property will not be considered.</emphasis>
				</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>defaultCachePolicy</term>
      <listitem>
        <para>
          Optional property that, if used, defines the default for how long this information provided by this source may to be 
					cached by other, higher-level components.  The default value is an empty string (or null) and implies that this source 
					does not define a specific duration for caching information provided by this repository source.
				</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>defaultWorkspaceName</term>
      <listitem>
        <para>
          Optional property that defines the name for the workspace that will be used in cases when clients do not explicitly specify
          the workspace name. If not specified, "<code>default</code>" will be used.
				</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>name</term>
      <listitem>
        <para>
          Required property that specifies the name of the repository source, which is used by the &RepositoryService; 
          when obtaining a &RepositoryConnection; by name.
				</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>predefinedWorkspaceNames</term>
      <listitem>
        <para>
          Optional property that defines the names of the workspaces that exist and that are available for use without having to create them.
				</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>rootNodeUuid</term>
      <listitem>
        <para>
          Optional property that, if used, specifies the UUID that should be used for the root node of each workspace.  If no value is
					specified, a pre-defined UUID constant is used. A custom value need only be supplied for Infinispan sources created prior to ModeShape 2.0,
					or if a specific UUID is desired or needed.
				</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>retryLimit</term>
      <listitem>
        <para>
          Optional property that, if used, defines the number of times that any single operation on a &RepositoryConnection; to this source should be retried
					following a communication failure. The default value is '0'.
				</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>updatesAllowed</term>
      <listitem>
        <para>
          Optional property that determines whether the content in the connector is can be updated ("true"), or if the content may only be read ("false").
					The default value is "true".
				</para>
      </listitem>
    </varlistentry>
  </variablelist>
	<para>
		The &RemoteInfinispanSource; class provides a number of JavaBean properties that control its behavior:
	</para>
  <variablelist>
    <varlistentry>
      <term>defaultCachePolicy</term>
      <listitem>
        <para>
          Optional property that, if used, defines the default for how long this information provided by this source may to be 
					cached by other, higher-level components.  The default value is an empty string (or null) and implies that this source 
					does not define a specific duration for caching information provided by this repository source.
				</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>defaultWorkspaceName</term>
      <listitem>
        <para>
          Optional property that defines the name for the workspace that will be used in cases when clients do not explicitly specify
          the workspace name. If not specified, "<code>default</code>" will be used.
				</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>name</term>
      <listitem>
        <para>
          Required property that specifies the name of the repository source, which is used by the &RepositoryService; 
          when obtaining a &RepositoryConnection; by name.
				</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>predefinedWorkspaceNames</term>
      <listitem>
        <para>
          Optional property that defines the names of the workspaces that exist and that are available for use without having to create them.
				</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>remoteInfinispanServerList</term>
      <listitem>
        <para>
          Optional property that defines the list of Infinispan HotRod servers.  The list must be in
					the appropriate format of "<code>host:port[;host:port...]</code>" that would be used when defining an Infinispan <code>RemoteCacheManager</code> 
					instance.  If the value is missing, "<code>localhost:11311</code>" is assumed.
				</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>rootNodeUuid</term>
      <listitem>
        <para>
          Optional property that, if used, specifies the UUID that should be used for the root node of each workspace.  If no value is
					specified, a pre-defined UUID constant is used. A custom value need only be supplied for Infinispan sources created prior to ModeShape 2.0,
					or if a specific UUID is desired or needed.
				</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>retryLimit</term>
      <listitem>
        <para>
          Optional property that, if used, defines the number of times that any single operation on a &RepositoryConnection; to this source should be retried
					following a communication failure. The default value is '0'.
				</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>updatesAllowed</term>
      <listitem>
        <para>
          Optional property that determines whether the content in the connector is can be updated ("true"), or if the content may only be read ("false").
					The default value is "true".
				</para>
      </listitem>
    </varlistentry>
  </variablelist>
 	<para>
		One way to configure the Infinispan connector is to create &JcrConfiguration; instance with a repository source that uses the &InfinispanSource; class.
		For example:
	</para>
  <programlisting language="JAVA" role="JAVA"><![CDATA[
JcrConfiguration config = ...
config.repositorySource("Infinispan Store")
      .usingClass(InfinispanSource.class)
      .setDescription("The repository for our content")
      .setProperty("defaultWorkspaceName", "prod")
      .setProperty("predefinedWorkspaceNames", new String[] { "staging", "dev"});
]]></programlisting>
	<para>
		Another way to configure the Infinispan connector is to create &JcrConfiguration; instance and load an XML configuration file that contains a repository source that 
		uses the &InfinispanSource; class.
		For example a file named configRepository.xml can be created with these contents:
	</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 sources for the content.  These sources are directly accessible using the 
    ModeShape-specific Graph API.  In fact, this is how the ModeShape JCR implementation works.  You 
    can think of these as being similar to JDBC DataSource objects, except that they expose 
    graph content via the Graph API instead of records via SQL or JDBC. 
    -->
    <mode:sources jcr:primaryType="nt:unstructured">
        <!-- 
        The 'Infinispan Store' repository is a Infinispan repository with a single default 
        workspace (though others could be created, too).
        -->
        <mode:source jcr:name="Infinispan Store" 
                    mode:classname="org.modeshape.connector.infinispan.InfinispanSource" 
                    mode:description="The repository for our content"
                    mode:defaultworkspaceName="prod">
           <mode:predefinedWorkspaceNames>staging</mode:predefinedWorkspaceNames>
           <mode:predefinedWorkspaceNames>dev</mode:predefinedWorkspaceNames>
        </mode:source>
    </mode:sources>
    
	<!-- MIME type detectors and JCR repositories would be defined below --> 
</configuration>
 ]]></programlisting>
	<para>
		The configuration can then be loaded from Java like this:
	</para>
	
	<programlisting language="JAVA" role="JAVA"><![CDATA[
JcrConfiguration config = new JcrConfiguration().loadFrom("/configRepository.xml");
 ]]></programlisting>
 	<sect1>
 		<title>Considerations for Distributed Sources</title>
 		<para>
		The &InfinispanSource; can be used to provide access to an Infinispan cluster, but be sure to use the DIST_SYNC
		cache mode.  Using other modes will likely lead to data inconsistency.  The &RemoteInfinispanSource; can be used to connect
		to an Infinispan HotRod cache server.
 		</para>
 		<para>
 		Additionally, some operating systems (e.g., OS X) require you to set either the <code>java.net.preferIPv4Stack</code>
 		or the <code>java.net.preferIPv6Addresses</code> system property to <code>true</code>.  These properties are used by
 		JGroups, the communications library that underlies Infinispan, to help determine which address type to use.
 		</para>
 		<note>
	 		<para>The <code>rootNodeUuid</code> property <emphasis>must</emphasis> be set to the same value for all Infinispan sources in the cluster.</para>
 		</note>
 	</sect1>
	<sect2>
		<title>Considerations for using the HotRod Server</title>
		<para>
		The Infinispan HotRod Server must be made aware of the ModeShape classes that will be stored in it, since it will be running
		in a separate JVM.  The following jar files should be added to the classpath of the HotRod Server:
    <itemizedlist>
      <listitem><para>modeshape-common</para></listitem>
      <listitem><para>modeshape-graph</para></listitem>
      <listitem><para>modeshape-connector-infinispan</para></listitem>
      <listitem><para>joda-time</para></listitem>
    </itemizedlist>
    Only these libraries contain the classes that are used to store content within Infinispan.
		</para>
	</sect2>
 </chapter>

 

