1:27 a.m.
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><component>
+
<key>org.exoplatform.services.jcr.ext.backup.BackupManager</key>
+
<type>org.exoplatform.services.jcr.ext.backup.impl.BackupManagerImpl</type>
+ <init-params>
+ <properties-param>
+ <name>backup-properties</name>
+ <property name="default-incremental-job-period"
value="3600" /><!-- set default incremental periond = 60 minutes
-->
+ <property name="full-backup-type"
value="org.exoplatform.services.jcr.ext.backup.impl.fs.FullBackupJob" />
+ <property name="incremental-backup-type"
value="org.exoplatform.services.jcr.ext.backup.impl.fs.IncrementalBackupJob"
/>
+ <property name="backup-dir" value="target/backup"
/>
+ </properties-param>
+ </init-params>
+</component>
+
+<component>
+
<key>org.exoplatform.services.database.creator.DBCreator</key>
+
<type>org.exoplatform.services.database.creator.DBCreator</type>
+ <init-params>
+ <properties-param>
+ <name>db-connection</name>
+ <description>database connection
properties</description>
+ <property name="driverClassName"
value="org.hsqldb.jdbcDriver" />
+ <property name="url"
value="jdbc:hsqldb:file:target/temp/data/" />
+ <property name="username" value="sa" />
+ <property name="password" value="" />
+ </properties-param>
+ <properties-param>
+ <name>db-creation</name>
+ <description>database creation
properties</description>
+ <property name="scriptPath"
value="src/test/resources/test.sql" />
+ <property name="username" value="sa" />
+ <property name="password" value="" />
+ </properties-param>
+ </init-params>
+</component>
+
+<component>
+ <key>org.exoplatform.services.rpc.RPCService</key>
+
<type>org.exoplatform.services.rpc.impl.RPCServiceImpl</type>
+ <init-params>
+ <value-param>
+ <name>jgroups-configuration</name>
+ <value>jar:/conf/standalone/udp-mux.xml</value>
+ </value-param>
+ <value-param>
+ <name>jgroups-cluster-name</name>
+ <value>RPCService-Cluster</value>
+ </value-param>
+ <value-param>
+ <name>jgroups-default-timeout</name>
+ <value>0</value>
+ </value-param>
+ </init-params>
+</component>
+
+<component>
+
<key>org.exoplatform.services.jcr.ext.repository.creation.RepositoryCreationService</key>
+ <type>
+ org.exoplatform.services.jcr.ext.repository.creation.RepositoryCreationServiceImpl
+ </type>
+</component></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"