Author: sergiykarpenko Date: 2010-11-29 02:27:57 -0500 (Mon, 29 Nov 2010) New Revision: 3575 Added: jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/jcr/repository-creation-service.xml Modified: jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/jcr.xml Log: EXOJCR-929: RepositoryCreationService documentation added Added: jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/jcr/repository-creation-service.xml =================================================================== --- jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/jcr/repository-creation-service.xml (rev 0) +++ jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/jcr/repository-creation-service.xml 2010-11-29 07:27:57 UTC (rev 3575) @@ -0,0 +1,209 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="JCR.RepositoryCreationService"> + <?dbhtml filename="ch-repository-creation-service.html"?> + + <title>RepositoryCreationService</title> + + <section> + <title>Intro</title> + + <para>RepositoryCreationService is the service for creation repositories + in runtime. The service can be used in standalone or cluster + environment.</para> + </section> + + <section> + <title>Dependencies</title> + + <para>RepositoryConfigurationService depends to next components:</para> + + <itemizedlist> + <listitem> + <para><link linkend="Core.DBCreatorService">DBCreator</link> - + DBCreator used to create new database for each unbinded datasource. + </para> + </listitem> + + <listitem> + <para><link linkend="JCR.BackupService">BackupManager</link> - + BackupManager used to created repository from backup.</para> + </listitem> + + <listitem> + <para><link linkend="Kernel.RPCService">RPCService</link> - RPCService + used for communication between cluster-nodes </para> + + <note> + <para>RPCService may not be configured - in this case, + RepositoryService will work as standalone service.</para> + </note> + </listitem> + </itemizedlist> + </section> + + <section> + <title>How it works</title> + + <itemizedlist> + <listitem> + <para> User executes reserveRepositoryName(String repositoryName) - + client-node calls coordinator-node to reserve repositoryName. If this + name is already reserved or repository with this name exist, + client-node will fetch RepositoryCreationException. If not Client will + get token string. </para> + </listitem> + + <listitem> + <para>than user executes createRepository(String backupId, + RepositoryEntry rEntry, String token). Coordinator-node checks the + token, and creates Repository. </para> + </listitem> + + <listitem> + <para> whan repository become created - user-node broadcast message to + all clusterNodes with RepositoryEntry, so each cluster node starts new + Repository. </para> + </listitem> + </itemizedlist> + + <para>There is two ways to create repositry: make it in single step - just + call createRepository(String backupId, RepositoryEntry); or reserve + repositoryName at first (reserveRepositoryName(String repositoryName)), + than create reserved repository (createRepository(String backupId, + RepositoryEntry rEntry, String token)). </para> + </section> + + <section> + <title>Configuration</title> + + <para>RepositoryCreationService configuration</para> + + <programlisting>&lt;component&gt; + &lt;key&gt;org.exoplatform.services.jcr.ext.backup.BackupManager&lt;/key&gt; + &lt;type&gt;org.exoplatform.services.jcr.ext.backup.impl.BackupManagerImpl&lt;/type&gt; + &lt;init-params&gt; + &lt;properties-param&gt; + &lt;name&gt;backup-properties&lt;/name&gt; + &lt;property name="default-incremental-job-period" value="3600" /&gt;&lt;!-- set default incremental periond = 60 minutes --&gt; + &lt;property name="full-backup-type" value="org.exoplatform.services.jcr.ext.backup.impl.fs.FullBackupJob" /&gt; + &lt;property name="incremental-backup-type" value="org.exoplatform.services.jcr.ext.backup.impl.fs.IncrementalBackupJob" /&gt; + &lt;property name="backup-dir" value="target/backup" /&gt; + &lt;/properties-param&gt; + &lt;/init-params&gt; +&lt;/component&gt; + +&lt;component&gt; + &lt;key&gt;org.exoplatform.services.database.creator.DBCreator&lt;/key&gt; + &lt;type&gt;org.exoplatform.services.database.creator.DBCreator&lt;/type&gt; + &lt;init-params&gt; + &lt;properties-param&gt; + &lt;name&gt;db-connection&lt;/name&gt; + &lt;description&gt;database connection properties&lt;/description&gt; + &lt;property name="driverClassName" value="org.hsqldb.jdbcDriver" /&gt; + &lt;property name="url" value="jdbc:hsqldb:file:target/temp/data/" /&gt; + &lt;property name="username" value="sa" /&gt; + &lt;property name="password" value="" /&gt; + &lt;/properties-param&gt; + &lt;properties-param&gt; + &lt;name&gt;db-creation&lt;/name&gt; + &lt;description&gt;database creation properties&lt;/description&gt; + &lt;property name="scriptPath" value="src/test/resources/test.sql" /&gt; + &lt;property name="username" value="sa" /&gt; + &lt;property name="password" value="" /&gt; + &lt;/properties-param&gt; + &lt;/init-params&gt; +&lt;/component&gt; + +&lt;component&gt; + &lt;key&gt;org.exoplatform.services.rpc.RPCService&lt;/key&gt; + &lt;type&gt;org.exoplatform.services.rpc.impl.RPCServiceImpl&lt;/type&gt; + &lt;init-params&gt; + &lt;value-param&gt; + &lt;name&gt;jgroups-configuration&lt;/name&gt; + &lt;value&gt;jar:/conf/standalone/udp-mux.xml&lt;/value&gt; + &lt;/value-param&gt; + &lt;value-param&gt; + &lt;name&gt;jgroups-cluster-name&lt;/name&gt; + &lt;value&gt;RPCService-Cluster&lt;/value&gt; + &lt;/value-param&gt; + &lt;value-param&gt; + &lt;name&gt;jgroups-default-timeout&lt;/name&gt; + &lt;value&gt;0&lt;/value&gt; + &lt;/value-param&gt; + &lt;/init-params&gt; +&lt;/component&gt; + +&lt;component&gt; + &lt;key&gt;org.exoplatform.services.jcr.ext.repository.creation.RepositoryCreationService&lt;/key&gt; + &lt;type&gt; + org.exoplatform.services.jcr.ext.repository.creation.RepositoryCreationServiceImpl + &lt;/type&gt; +&lt;/component&gt;</programlisting> + </section> + + <section> + <title>Repsitory Interface</title> + + <programlisting>public interface RepositoryCreationService +{ + /** + * Reserves, validates and creates repository in a simplified form. + * + * @param rEntry - repository Entry - note that datasource must not exist. + * @param backupId - backup id + * @throws RepositoryConfigurationException + * if some exception occurred during repository creation or repository name is absent in reserved list + * @throws RepositoryCreationServiceException + * if some exception occurred during repository creation or repository name is absent in reserved list + */ + void createRepository(String backupId, RepositoryEntry rEntry) throws RepositoryConfigurationException, + RepositoryCreationException; + + /** + * Reserve repository name to prevent repository creation with same name from other place in same time + * via this service. + * + * @param repositoryName - repositoryName + * @return repository token. Anyone obtaining a token can later create a repository of reserved name. + * @throws RepositoryCreationServiceException if can't reserve name + */ + String reserveRepositoryName(String repositoryName) throws RepositoryCreationException; + + /** + * Creates repository, using token of already reserved repository name. Good for cases, when repository creation should be delayed or + * made asynchronously in dedicated thread. + * + * @param rEntry - repository entry - note, that datasource must not exist + * @param backupId - backup id + * @param rToken - token + * @throws RepositoryConfigurationException + * if some exception occurred during repository creation or repository name is absent in reserved list + * @throws RepositoryCreationServiceException + * if some exception occurred during repository creation or repository name is absent in reserved list + */ + void createRepository(String backupId, RepositoryEntry rEntry, String rToken) + throws RepositoryConfigurationException, RepositoryCreationException; +}</programlisting> + </section> + + <section> + <title>Conclusions and restrictions</title> + + <itemizedlist> + <listitem> + <para>Each datasource in RepositoryEntry of new Repository must have + unbinded datasources. Thats mean, such datasource must have not + databases behind them. This restriction exists to avoid corruption of + existing repositories data. </para> + </listitem> + + <listitem> + <para>RPCService is optional component, but without it, + RepositoryCreatorService can not communicate with other cluster-nodes + and works as standalone.</para> + </listitem> + </itemizedlist> + </section> +</chapter> Modified: jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/jcr.xml =================================================================== --- jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/jcr.xml 2010-11-26 15:02:32 UTC (rev 3574) +++ jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/jcr.xml 2010-11-29 07:27:57 UTC (rev 3575) @@ -89,7 +89,11 @@ <xi:include href="jcr/transaction-manager-lookup.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/repository-creation-service.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <!-- search --> <xi:include href="jcr/searching/jcr-query-usecases.xml"