<?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="in-memory-connector">
  <title>In-Memory Connector</title>
  <para>
  	The in-memory repository connector is a simple connector that creates a transient, in-memory repository.
		This repository is used as a very simple in-memory cache or as a standalone transient repository.
		This connector works well for a readable and writable repository source with small to moderate sized
		content that need not be permanently saved.
  </para>
	<para>
		The &InMemoryRepositorySource; 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>jndiName</term>
      <listitem>
        <para>
          Optional property that, if used, specifies the name in JNDI where an &InMemoryRepository; instance can be found.
					This is an advanced property that is infrequently 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>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 new UUID is generated.
				</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>
  </variablelist>
	<para>
		One way to configure the in-memory connector is to create &JcrConfiguration; instance with a repository source that uses the &InMemoryRepositorySource; class.
		For example:
	</para>
  <programlisting language="JAVA" role="JAVA"><![CDATA[
JcrConfiguration config = ...
config.repositorySource("IMR Store")
      .usingClass(InMemoryRepositorySource.class)
      .setDescription("The repository for our content")
      .setProperty("predefinedWorkspaceNames", new String[] { "staging", "dev"})
      .setProperty("defaultWorkspaceName", workspaceName);
 ]]></programlisting>
	<para>
		Another way to configure the in-memory connector is to create &JcrConfiguration; instance and load an XML configuration file that contains a repository source that 
		uses the &InMemoryRepositorySource; 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 'IMR Store' repository is an in-memory source with a single default workspace (though 
        others could be created, too).
        -->
        <mode:source jcr:name="IMR Store" 
                    mode:classname="org.modeshape.graph.connector.inmemory.InMemoryRepositorySource" 
                    mode:description="The repository for our content" 
                    mode:defaultWorkspaceName="default">
           <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>

</chapter>
