<?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="subversion-connector">
  <title>Subversion Connector</title>
  <para>
		This connector provides read and write access to the directories and folders within a Subversion repository, providing that content in
		the form of <code>nt:file</code> and <code>nt:folder</code> nodes.
		This source considers a workspace name to be the path to the directory on the repository's root directory location
		that represents the root of that workspace (e.g., "trunk" or "branches"). 
		New workspaces can be created, as long as the names represent valid existing directories within the SVN repository.
  </para>
	<para>
		The &SVNRepositorySource; class provides a number of JavaBean properties that control its behavior:
	</para>
  <variablelist>
    <varlistentry>
      <term>cachePolicy</term>
      <listitem>
        <para>
          Optional property that, if used, defines the cache policy for this repository source.  When not used, this source will not define a specific
			    duration for caching information.
				</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>creatingWorkspaceAllowed</term>
      <listitem>
        <para>
          Optional property that defines whether clients can create additional workspaces.  The default value is "true".
        </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>defaultWorkspaceName</term>
      <listitem>
        <para>
          Optional property that, if used, specifies the name of the workspace to use when no workspace name is specified in an operation.
          If not specified, "<code>trunk</code>" is used.
        </para>
        <para>
					Each workspace name is treated as a path relative to the SVN repository being exposed. For example, given a repository root URL
					of "http://acme.com/repo/", a workspace name of "<code>trunk</code>" will map to "http://acme.com/repo/trunk".
				</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>nodeCachePolicy</term>
      <listitem>
        <para>
          Optional property that, if used, defines the cache policy to use for caching nodes within the connector.
        </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>password</term>
      <listitem>
        <para>
          The password that should be used to establish a connection to the repository. This is not required if the URL represents an
					anonymous SVN repository address.
				</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>predefinedWorkspaceNames</term>
      <listitem>
        <para>
          Optional property that, if used, defines names of the workspaces that are predefined and need not be created before being used.
					This can be coupled with a "false" value for the "creatingWorkspaceAllowed" property to allow only the use of only predefined workspaces.
        </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>repositoryRootURL</term>
      <listitem>
        <para>
          Required property that should be set with the URL to the Subversion repository.
				</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>username</term>
      <listitem>
        <para>
          The username that should be used to establish a connection to the repository. This is not required if the URL represents an
					anonymous SVN repository address.
				</para>
      </listitem>
    </varlistentry>
  </variablelist>
 	<para>
		One way to configure the Subversion connector is to create &JcrConfiguration; instance with a repository source that uses the &SVNRepositorySource; class.
		For example:
	</para>
  <programlisting language="JAVA" role="JAVA"><![CDATA[
JcrConfiguration config = ...
config.repositorySource("SVN Store")
      .usingClass(SVNRepositorySource.class)
      .setDescription("The ModeShape SVN repository (anonymous access)")
      .setProperty("repositoryRootUrl", "http://anonsvn.jboss.org/repos/modeshape");
      .setProperty("defaultWorkspaceName", "trunk");
      .setProperty("predefinedWorkspaceNames", new String[] {"trunk","tags" });
 ]]></programlisting>
	<para>
		Another way to configure the Subversion connector is to create &JcrConfiguration; instance and load an XML configuration file that contains a repository source that 
		uses the &SVNRepositorySource; 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 'SVN Store' repository is an Subversion source with one workspace (although others could 
        be defined).
        -->
        <mode:source jcr:name="SVN Store" 
                    mode:classname="org.modeshape.connector.svn.SVNRepositorySource" 
                    mode:description="The ModeShape SVN repository (anonymous access)"
                    mode:repositoryRootUrl="http://anonsvn.jboss.org/repos/modeshape"
                    mode:defaultWorkspaceName="trunk"
                    mode:defaultWorkspaceName="default" >
          <mode:predefinedWorkspaceNames>tags</mode:predefinedWorkspaceNames>
          <mode:predefinedWorkspaceNames>trunk</mode:predefinedWorkspaceNames>
      	    <!-- 
      	    If desired, specify a cache policy that caches items in memory for 5 minutes (300 s).
      	    This fragment can be left out if the connector should not cache any content.
      	    -->
      	    <mode:cachePolicy jcr:name="nodeCachePolicy" 
      	      mode:classname="org.modeshape.graph.connector.base.cache.InMemoryNodeCache$PathCachePolicy"
      	      mode:timeToLive="300" />
        </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>
