[exo-jcr-commits] exo-jcr SVN: r2859 - in jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules: jcr/backup and 1 other directories.
do-not-reply at jboss.org
do-not-reply at jboss.org
Tue Aug 3 05:43:47 EDT 2010
Author: sergiykarpenko
Date: 2010-08-03 05:43:46 -0400 (Tue, 03 Aug 2010)
New Revision: 2859
Added:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/backup/backup-client.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/backup/search-index-backup.xml
Modified:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/backup/exojcr-backup-service.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/exo-jcr-configuration.xml
Log:
EXOJCR-869: backup documents ported
Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/backup/backup-client.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/backup/backup-client.xml (rev 0)
+++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/backup/backup-client.xml 2010-08-03 09:43:46 UTC (rev 2859)
@@ -0,0 +1,1321 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="JCR.BackupClient">
+ <?dbhtml filename="ch-backup-client.html"?>
+
+ <title>HTTPBackupAgent and backup client</title>
+
+ <warning>
+ <para>For this service you should configure the <emphasis
+ role="bold">org.exoplatform.services.jcr.impl.config.JDBCConfigurationPersister</emphasis>
+ in order to save the changes of the repository configuration. See the
+ <link
+ linkend="JCR.eXoJCRconfiguration.PortalAndStandaloneConfiguration">eXo JCR
+ Configuration article at chapter '2 Portal and Standalone
+ configuration'</link> .</para>
+ </warning>
+
+ <section>
+ <title>Introduction</title>
+
+ <para>The service
+ org.exoplatform.services.jcr.ext.backup.server.HTTPBackupAgent is
+ REST-based front-end to service
+ org.exoplatform.services.jcr.ext.backup.BackupManager. HTTPBackupAgent is
+ representation BackupManager to creation backup, restore, getting status
+ of current or completed backup/restore, etc.</para>
+
+ <para>The backup client is http client for HTTPBackupAgent.</para>
+ </section>
+
+ <section>
+ <title>HTTPBackupAgent</title>
+
+ <para>The HTTPBackupAgent is based on REST (see details about the <link
+ linkend="WS.RestFramework">REST Framework</link>).</para>
+
+ <para>HTTPBackupAgent is using POST and GET methods for request.</para>
+
+ <para>The HTTPBackupAgent allows :<itemizedlist>
+ <listitem>
+ <para>start backup</para>
+ </listitem>
+
+ <listitem>
+ <para>stop backup</para>
+ </listitem>
+
+ <listitem>
+ <para>restore from backup</para>
+ </listitem>
+
+ <listitem>
+ <para>delete the workspace</para>
+ </listitem>
+
+ <listitem>
+ <para>getting information about backup service
+ (BackupManager)</para>
+ </listitem>
+
+ <listitem>
+ <para>getting information about current backup / restores /
+ completed backups</para>
+ </listitem>
+ </itemizedlist></para>
+
+ <section>
+ <title>HTTPBackupAgent methods</title>
+
+ <section>
+ <title>Start Backup Service</title>
+
+ <para><emphasis
+ role="bold">/rest/jcr-backup/start/{repo}/{ws}</emphasis></para>
+
+ <para>Start backup on specific workspace</para>
+
+ <para><emphasis role="bold">URL:</emphasis>
+ <uri>http://host:port/rest/jcr-backup/start/{repo}/{ws}</uri></para>
+
+ <para><emphasis role="bold">Formats:</emphasis> json.</para>
+
+ <para><emphasis role="bold">Method</emphasis>: POST</para>
+
+ <para><emphasis role="bold">Parameters:</emphasis><itemizedlist>
+ <listitem>
+ <para>{repo} - the repository name;</para>
+ </listitem>
+
+ <listitem>
+ <para>{ws} - the workspace name;</para>
+ </listitem>
+
+ <listitem>
+ <para>BackupConfigBean - the JSON to BackupConfigBean.</para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>The BackupConfigBean:</para>
+
+ <programlisting>header :
+"Content-Type" = "application/json; charset=UTF-8"
+
+body:
+<JSON to BackupConfigBean></programlisting>
+
+ <para>The JSON bean of
+ org.exoplatform.services.jcr.ext.backup.server.bean.BackupConfigBean
+ :</para>
+
+ <programlisting>{"incrementalRepetitionNumber":<Integer>,"incrementalBackupJobConfig":<JSON to BackupJobConfig>,
+"backupType":<Integer>,"fullBackupJobConfig":<JSON to BackupJobConfig>,
+"incrementalJobPeriod":<Long>,"backupDir":"<String>"}</programlisting>
+
+ <para>Where :</para>
+
+ <programlisting>backupType - the type of backup:
+ 0 - full backup only;
+ 1 - full and incremental backup.
+backupDir - the path to backup folder;
+incrementalJobPeriod - the incremental job period;
+incrementalRepetitionNumber - the incremental repetition number;
+fullBackupJobConfig - the configuration to full backup, JSON to BackupJobConfig;
+incrementalJobPeriod - the configuration to incremental backup, JSON to BackupJobConfig.</programlisting>
+
+ <para>The JSON bean of
+ org.exoplatform.services.jcr.ext.backup.server.bean.response.BackupJobConfig
+ :</para>
+
+ <programlisting>{"parameters":[<JSON to Pair>, ..., <JSON to pair> ],"backupJob":"<String>"}</programlisting>
+
+ <para>Where:</para>
+
+ <programlisting>backupJob - the FQN (fully qualified name) to BackupJob class;
+parameters - the list of JSON of Pair.</programlisting>
+
+ <para>The JSON bean of
+ org.exoplatform.services.jcr.ext.backup.server.bean.response.Pair
+ :</para>
+
+ <programlisting>{"name":"<String>","value":"<String>"}</programlisting>
+
+ <para>Where:</para>
+
+ <programlisting>name - the name of parameter;
+value - the value of parameter.</programlisting>
+
+ <para><emphasis role="bold">Returns:</emphasis><itemizedlist>
+ <listitem>
+ <para>return when successful<programlisting>status code = 200</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>return when failure<programlisting>status code = 404 - the not found repositry '{repo}' or workspace '{ws}'
+status code = 500 - the other unknown errors
+failure message in response - the description of failure</programlisting></para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+
+ <section>
+ <title>Stop Backup Service</title>
+
+ <para><emphasis
+ role="bold">/rest/jcr-backup/stop/{id}</emphasis></para>
+
+ <para>Stop backup with identifier {id}.</para>
+
+ <para><emphasis role="bold">URL:</emphasis>
+ <uri>http://host:port/rest/jcr-backup/stop/{id}</uri></para>
+
+ <para><emphasis role="bold">Formats:</emphasis> plain text</para>
+
+ <para><emphasis role="bold">Method</emphasis>: GET</para>
+
+ <para><emphasis role="bold">Parameters:</emphasis><itemizedlist>
+ <listitem>
+ <para>{id} - the identifier of backup</para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para><emphasis role="bold">Returns:</emphasis><itemizedlist>
+ <listitem>
+ <para>return when successful<programlisting>status code = 200</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>return when failure<programlisting>status code = 404 - the no active backup with identifier {id}
+status code = 500 - the other unknown errors
+failure message in response - the description of failure</programlisting></para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+
+ <section>
+ <title>Backup Info Service</title>
+
+ <para><emphasis role="bold">/rest/jcr-backup/info</emphasis></para>
+
+ <para>Information about the backup service.</para>
+
+ <para><emphasis role="bold">URL:</emphasis>
+ <uri>http://host:port/rest/jcr-backup/info</uri></para>
+
+ <para><emphasis role="bold">Formats:</emphasis> json</para>
+
+ <para><emphasis role="bold">Method</emphasis>: GET</para>
+
+ <para><emphasis role="bold">Parameters:</emphasis> no</para>
+
+ <para><emphasis role="bold">Returns:</emphasis><itemizedlist>
+ <listitem>
+ <para>return when successful</para>
+
+ <para>Return the JSON bean of
+ org.exoplatform.services.jcr.ext.backup.server.bean.response.BackupServiceInfoBean
+ :<programlisting>{"backupLogDir":"<String>","defaultIncrementalJobPeriod":<Long>,"fullBackupType":"<String>","incrementalBackupType":"<String>"}</programlisting>Where:<programlisting>fullBackupType - the FQN (fully qualified name) of BackupJob class for full backup type;
+incrementalBackupType - the FQN (fully qualified name) of BackupJob class for incremental backup type;
+backupLogDir - path to backup folder;
+defaultIncrementalJobPeriod - the default incremental job period.</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>return when failure<programlisting>status code = 500 - the unknown error
+failure message in response - the description of failure</programlisting></para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+
+ <section>
+ <title>Drop Workspace Service</title>
+
+ <para><emphasis
+ role="bold">/rest/jcr-backup/drop-workspace/{repo}/{ws}/{force-session-close}</emphasis></para>
+
+ <para>Delete the workspace from repository /{repo}/{ws}. With this
+ service you can delete any workspace, completly independant of the
+ fact if the workspace is a backup or has been copied to a
+ backup.</para>
+
+ <para><emphasis role="bold">URL:</emphasis>
+ <uri>http://host:port/rest/jcr-backup/drop-workspace/{repo}/{ws}/{force-session-close}</uri></para>
+
+ <para><emphasis role="bold">Formats:</emphasis> plain text</para>
+
+ <para><emphasis role="bold">Method</emphasis>: GET</para>
+
+ <para><emphasis role="bold">Parameters:</emphasis><itemizedlist>
+ <listitem>
+ <para>{repo} - the repository name;</para>
+ </listitem>
+
+ <listitem>
+ <para>{ws} - the workspace name;</para>
+ </listitem>
+
+ <listitem>
+ <para> {force-session-close} - the boolean value : <emphasis
+ role="bold">true</emphasis> - the open sessions on workspace
+ will be closed; <emphasis role="bold">false</emphasis> - will
+ not close open sessions.</para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para><emphasis role="bold">Returns:</emphasis><itemizedlist>
+ <listitem>
+ <para>return when successful<programlisting>status code = 200</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>return when failure<programlisting>status code = 500 - the other unknown errors;
+ - not found repositry '{repo}' or workspace '{ws}'
+failure message in response - the description of failure</programlisting></para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+
+ <section>
+ <title>Backup Info</title>
+
+ <para><emphasis
+ role="bold">/rest/jcr-backup/info/backup</emphasis></para>
+
+ <para>Information about the current and completed backups</para>
+
+ <para><emphasis role="bold">URL:</emphasis>
+ <uri>http://host:port/rest/jcr-backup/info/backup</uri></para>
+
+ <para><emphasis role="bold">Formats:</emphasis> json</para>
+
+ <para><emphasis role="bold">Method</emphasis>: GET</para>
+
+ <para><emphasis role="bold">Parameters:</emphasis> no</para>
+
+ <para><emphasis role="bold">Returns:</emphasis><itemizedlist>
+ <listitem>
+ <para>return when successful</para>
+
+ <para>The JSON bean of
+ org.exoplatform.services.jcr.ext.backup.server.bean.response.ShortInfoList
+ :<programlisting>{"backups":[<JSON to ShortInfo>,<JSON to ShortInfo>,...,<JSON to ShortInfo>]}</programlisting>The
+ JSON bean of
+ org.exoplatform.services.jcr.ext.backup.server.bean.response.ShortInfo
+ :<programlisting>{"startedTime":"<String>","backupId":"<String>","type":<Integer>,"state":<Integer>,"backupType":<Integer>,
+"workspaceName":"<String>","finishedTime":"<String>","repositoryName":"<String>"}</programlisting></para>
+
+ <para>Where:<programlisting>type - the type of ShortInfo :
+ 0 - the ShorInfo to completed backup;
+ -1 - the ShorInfo to current (active) backup.
+ 1 - the ShorInfo to current restore.
+backupType - the type of backup:
+ 0 - full backup only;
+ 1 - full and incremental backup.
+backupId - the identifier of backup;
+workspaceName - the name of workspace;
+repositoryName - the name of repository.
+startedTime - the date of started backup. The date in format RFC 1123 (for examle "Thu, 16 Apr 2009 14:56:49 EEST").
+
+The ShorInfo to current (active) backup :
+ finishedTime - no applicable, always an empty string ("");
+ state - the state of full backup :
+ 0 - starting;
+ 1 - waiting;
+ 2 - working;
+ 4 - finished.
+
+The ShorInfo to completed backup :
+ finishedTime - the date of finished backup. The date in format RFC 1123;
+ state - no applicable, always zero (0).
+
+The ShorInfo to current restore :
+ finishedTime - the date of finished backup. The date in format RFC 1123;
+ state - the state of restore :
+ 1 - started;
+ 2 - successful;
+ 3 - failure;
+ 4 - initialized.</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>return when failure<programlisting>status code = 500 - the unknown error
+failure message in response - the description of failure</programlisting></para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+
+ <section>
+ <title>Current Backups Information</title>
+
+ <para><emphasis
+ role="bold">/rest/jcr-backup/info/backup/current</emphasis>
+ Information about the current backups</para>
+
+ <para><emphasis role="bold">URL:</emphasis>
+ <uri>http://host:port/rest/jcr-backup/info/backup/current</uri></para>
+
+ <para><emphasis role="bold">Formats:</emphasis> json</para>
+
+ <para><emphasis role="bold">Method</emphasis>: GET</para>
+
+ <para><emphasis role="bold">Parameters:</emphasis> no</para>
+
+ <para><emphasis role="bold">Returns:</emphasis><itemizedlist>
+ <listitem>
+ <para>return when successful</para>
+
+ <para>The JSON bean of
+ org.exoplatform.services.jcr.ext.backup.server.bean.response.ShortInfoList
+ (see item <emphasis
+ role="bold">/rest/jcr-backup/info/backup</emphasis>)</para>
+ </listitem>
+
+ <listitem>
+ <para>return when failure</para>
+
+ <programlisting>status code = 500 - the unknown error
+failure message in response - the description of failure</programlisting>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+
+ <section>
+ <title>Completed Backups Information</title>
+
+ <para><emphasis
+ role="bold">/rest/jcr-backup/info/backup/completed</emphasis>
+ Information about the completed backups.</para>
+
+ <para><emphasis role="bold">URL:</emphasis>
+ <uri>http://host:port/rest/jcr-backup/info/backup/completed</uri></para>
+
+ <para><emphasis role="bold">Formats:</emphasis> json</para>
+
+ <para><emphasis role="bold">Method</emphasis>: GET</para>
+
+ <para><emphasis role="bold">Parameters:</emphasis> no</para>
+
+ <para><emphasis role="bold">Returns:</emphasis><itemizedlist>
+ <listitem>
+ <para>return when successful</para>
+
+ <para>The JSON bean of
+ org.exoplatform.services.jcr.ext.backup.server.bean.response.ShortInfoList
+ (see item <emphasis
+ role="bold">/rest/jcr-backup/info/backup</emphasis>)</para>
+ </listitem>
+
+ <listitem>
+ <para>return when failure</para>
+
+ <programlisting>status code = 500 - the unknown error
+failure message in response - the description of failure</programlisting>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+
+ <section>
+ <title>Workspace-specific Backup Information</title>
+
+ <para><emphasis
+ role="bold">/rest/jcr-backup/info/backup/{repo}/{ws}</emphasis>
+ Information about the current and completed backups for specific
+ workspace.</para>
+
+ <para><emphasis role="bold">URL:</emphasis>
+ <uri>http://host:port/rest/jcr-backup/info/backup/{repo}/{ws}</uri></para>
+
+ <para><emphasis role="bold">Formats:</emphasis> json</para>
+
+ <para><emphasis role="bold">Method</emphasis>: GET</para>
+
+ <para><emphasis role="bold">Parameters:</emphasis><itemizedlist>
+ <listitem>
+ <para>{repo} - the repository name</para>
+ </listitem>
+
+ <listitem>
+ <para>{ws} - the workspace name</para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para><emphasis role="bold">Returns:</emphasis><itemizedlist>
+ <listitem>
+ <para>return when successful</para>
+
+ <para>The JSON bean of
+ org.exoplatform.services.jcr.ext.backup.server.bean.response.ShortInfoList
+ (see item <emphasis
+ role="bold">/rest/jcr-backup/info/backup</emphasis>)</para>
+ </listitem>
+
+ <listitem>
+ <para>return when failure</para>
+
+ <programlisting>status code = 500 - the unknown error
+failure message in response - the description of failure</programlisting>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+
+ <section>
+ <title>Single Backup Information</title>
+
+ <para><emphasis
+ role="bold">/rest/jcr-backup/info/backup/{id}</emphasis> Detailed
+ information about a current or completed backup with identifier
+ '{id}'.</para>
+
+ <para><emphasis role="bold">URL:</emphasis>
+ <uri>http://host:port/rest/jcr-backup/info/backup/{id}</uri></para>
+
+ <para><emphasis role="bold">Formats:</emphasis> json</para>
+
+ <para><emphasis role="bold">Method</emphasis>: GET</para>
+
+ <para><emphasis role="bold">Parameters:</emphasis><itemizedlist>
+ <listitem>
+ <para>{id} - the identifier of backup</para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para><emphasis role="bold">Returns:</emphasis><itemizedlist>
+ <listitem>
+ <para>return when successful</para>
+
+ <para>The JSON bean of
+ org.exoplatform.services.jcr.ext.backup.server.bean.response.DetailedInfo
+ :<programlisting>{"backupConfig":<JSON to BackupConfigBean>,"startedTime":"<String>","backupId":"<String>","type":<Integer>,
+"state":<Integer>,"backupType":<Integer>,"workspaceName":"<String>","finishedTime":"<String>",
+"repositoryName":"<String>"}</programlisting></para>
+
+ <para>Where:<programlisting>type - the type of DetailedInfo :
+ 0 - the DetailedInfo to completed backup;
+ -1 - the DetailedInfo to current (active) backup;
+ 1 - the DetailedInfo to restore.
+backupType - the type of backup:
+ 0 - full backup only;
+ 1 - full and incremental backup.
+backupId - the identifier of backup;
+workspaceName - the name of workspace;
+repositoryName - the name of repository;
+backupConfig - the JSON to BackupConfigBean.
+
+The DetailedInfo to current (active) backup :
+ startedTime - the date of started backup. The date in format RFC 1123 (for examle "Thu, 16 Apr 2009 14:56:49 EEST");
+ finishedTime - no applicable, always an empty string ("");
+ state - the state of full backup :
+ 0 - starting;
+ 1 - waiting;
+ 2 - working;
+ 4 - finished.
+The DetailedInfo to completed backup :
+ startedTime - the date of started backup. The date in format RFC 1123 (for examle "Thu, 16 Apr 2009 14:56:49 EEST");
+ finishedTime - the date of finished backup. The date in format RFC 1123;
+ state - no applicable, always zero (0).
+
+The DetailedInfo to restore :
+ startedTime - the date of started restore. The date in format RFC 1123 (for examle "Thu, 16 Apr 2009 14:56:49 EEST");
+ finishedTime - the date of finished restore;
+ state - the state of restore :
+ 1 - started;
+ 2 - successful;
+ 3 - failure;
+ 4 - initialized.</programlisting></para>
+
+ <para>The JSON bean of
+ org.exoplatform.services.jcr.ext.backup.server.bean.BackupConfigBean
+ (see item <emphasis
+ role="bold">/rest/jcr-backup/start/{repo}/{ws}</emphasis>).</para>
+ </listitem>
+
+ <listitem>
+ <para>return when failure</para>
+
+ <programlisting>status code = 404 - not found the backup with {id}
+status code = 500 - the unknown error
+failure message in response - the description of failure</programlisting>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+
+ <section>
+ <title>Restores on a Workspace Information</title>
+
+ <para><emphasis
+ role="bold">/rest/jcr-backup/info/restore/{repo}/{ws}</emphasis> The
+ information about the last restore on a specific workspace
+ /{repo}/{ws}.</para>
+
+ <para><emphasis role="bold">URL:</emphasis>
+ <uri>http://host:port/rest/jcr-backup/info/restore/{repo}/{ws}</uri></para>
+
+ <para><emphasis role="bold">Formats:</emphasis> json</para>
+
+ <para><emphasis role="bold">Method</emphasis>: GET</para>
+
+ <para><emphasis role="bold">Parameters:</emphasis><itemizedlist>
+ <listitem>
+ <para>{repo} - the repository name</para>
+ </listitem>
+
+ <listitem>
+ <para>{ws} - the workspace name</para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para><emphasis role="bold">Returns:</emphasis><itemizedlist>
+ <listitem>
+ <para>return when successful</para>
+
+ <para>The JSON bean of
+ org.exoplatform.services.jcr.ext.backup.server.bean.response.DetailedInfo
+ (see item <emphasis
+ role="bold">/rest/jcr-backup/info/backup/{id}</emphasis>)</para>
+ </listitem>
+
+ <listitem>
+ <para>return when failure</para>
+
+ <programlisting>status code = 404 - the not found the restore for workspace /{repo}/{ws}
+status code = 500 - the unknown error
+failure message in response - the description of failure</programlisting>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+
+ <section>
+ <title>Restores Information</title>
+
+ <para><emphasis
+ role="bold">/rest/jcr-backup/info/restores</emphasis></para>
+
+ <para>The information about the last restores.</para>
+
+ <para><emphasis role="bold">URL:</emphasis>
+ <uri>http://host:port/rest/jcr-backup/info/restores</uri></para>
+
+ <para><emphasis role="bold">Formats:</emphasis> json</para>
+
+ <para><emphasis role="bold">Method</emphasis>: GET</para>
+
+ <para><emphasis role="bold">Parameters:</emphasis> no</para>
+
+ <para><emphasis role="bold">Returns:</emphasis><itemizedlist>
+ <listitem>
+ <para>return when successful</para>
+
+ <para>The JSON bean of
+ org.exoplatform.services.jcr.ext.backup.server.bean.response.ShortInfoList
+ (see item <emphasis
+ role="bold">/rest/jcr-backup/info/backup</emphasis>)</para>
+ </listitem>
+
+ <listitem>
+ <para>return when failure</para>
+
+ <programlisting>status code = 500 - the unknown error
+failure message in response - the description of failure</programlisting>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+
+ <section>
+ <title>Restore Service</title>
+
+ <para><emphasis
+ role="bold">/rest/jcr-backup/restore/{repo}/{id}</emphasis></para>
+
+ <para>Restore the workspace from specific backup.</para>
+
+ <para><emphasis role="bold">URL:</emphasis>
+ <uri>http://host:port/rest/jcr-backup/restore/{repo}/{id}</uri></para>
+
+ <para><emphasis role="bold">Formats:</emphasis> json.</para>
+
+ <para><emphasis role="bold">Method</emphasis>: POST</para>
+
+ <para><emphasis role="bold">Parameters:</emphasis><itemizedlist>
+ <listitem>
+ <para>{repo} - the repository name;</para>
+ </listitem>
+
+ <listitem>
+ <para>{id} - the identifier to backup; * WorkspaceEntry - the
+ JSON to WorkspaceEntry.</para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>The RestoreBean:</para>
+
+ <programlisting>header :
+"Content-Type" = "application/json; charset=UTF-8"
+
+body:
+<JSON to WorkspaceEntry></programlisting>
+
+ <para>The example of JSON bean to
+ org.exoplatform.services.jcr.config.WorkspaceEntry :</para>
+
+ <programlisting>{ "accessManager" : null,
+ "autoInitPermissions" : null,
+ "autoInitializedRootNt" : null,
+ "cache" : { "parameters" : [ { "name" : "max-size",
+ "value" : "10k"
+ },
+ { "name" : "live-time",
+ "value" : "1h"
+ }
+ ],
+ "type" : "org.exoplatform.services.jcr.impl.dataflow.persistent.LinkedWorkspaceStorageCacheImpl"
+ },
+ "container" : { "parameters" : [ { "name" : "source-name",
+ "value" : "jdbcjcr"
+ },
+ { "name" : "dialect",
+ "value" : "hsqldb"
+ },
+ { "name" : "multi-db",
+ "value" : "false"
+ },
+ { "name" : "update-storage",
+ "value" : "false"
+ },
+ { "name" : "max-buffer-size",
+ "value" : "200k"
+ },
+ { "name" : "swap-directory",
+ "value" : "../temp/swap/production"
+ }
+ ],
+ "type" : "org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer",
+ "valueStorages" : [ { "filters" : [ { "ancestorPath" : null,
+ "minValueSize" : 0,
+ "propertyName" : null,
+ "propertyType" : "Binary"
+ } ],
+ "id" : "system",
+ "parameters" : [ { "name" : "path",
+ "value" : "../temp/values/production"
+ } ],
+ "type" : "org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage"
+ } ]
+ },
+ "initializer" : { "parameters" : [ { "name" : "root-nodetype",
+ "value" : "nt:unstructured"
+ } ],
+ "type" : "org.exoplatform.services.jcr.impl.core.ScratchWorkspaceInitializer"
+ },
+ "lockManager" : { "persister" : { "parameters" : [ { "name" : "path",
+ "value" : "../temp/lock/system"
+ } ],
+ "type" : "org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister"
+ },
+ "timeout" : 15728640
+ },
+ "name" : "production",
+ "queryHandler" : { "analyzer" : { },
+ "autoRepair" : true,
+ "bufferSize" : 10,
+ "cacheSize" : 1000,
+ "documentOrder" : true,
+ "errorLogSize" : 50,
+ "excerptProviderClass" : "org.exoplatform.services.jcr.impl.core.query.lucene.DefaultHTMLExcerpt",
+ "excludedNodeIdentifers" : null,
+ "extractorBackLogSize" : 100,
+ "extractorPoolSize" : 0,
+ "extractorTimeout" : 100,
+ "indexDir" : "../temp/jcrlucenedb/production",
+ "indexingConfigurationClass" : "org.exoplatform.services.jcr.impl.core.query.lucene.IndexingConfigurationImpl",
+ "indexingConfigurationPath" : null,
+ "maxFieldLength" : 10000,
+ "maxMergeDocs" : 2147483647,
+ "mergeFactor" : 10,
+ "minMergeDocs" : 100,
+ "parameters" : [ { "name" : "index-dir",
+ "value" : "../temp/jcrlucenedb/production"
+ } ],
+ "queryClass" : "org.exoplatform.services.jcr.impl.core.query.QueryImpl",
+ "queryHandler" : null,
+ "resultFetchSize" : 2147483647,
+ "rootNodeIdentifer" : "00exo0jcr0root0uuid0000000000000",
+ "spellCheckerClass" : null,
+ "supportHighlighting" : false,
+ "synonymProviderClass" : null,
+ "synonymProviderConfigPath" : null,
+ "type" : "org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex",
+ "useCompoundFile" : false,
+ "volatileIdleTime" : 3
+ },
+ "uniqueName" : "repository_production"
+}</programlisting>
+
+ <para><emphasis role="bold">Returns:</emphasis><itemizedlist>
+ <listitem>
+ <para>return when successful</para>
+
+ <programlisting>status code = 200</programlisting>
+
+ <para>Return the JSON bean
+ org.exoplatform.services.jcr.ext.backup.server.bean.response.ShortInfo
+ of just started restore. For JSON description see item <emphasis
+ role="bold">/rest/jcr-backup/info/backup</emphasis></para>
+ </listitem>
+
+ <listitem>
+ <para>return when failure</para>
+
+ <programlisting>status code = 403 - the already was restore to workspace /{repo}/{ws}
+status code = 404 - the not found repositry '{repo}' or unsupported encoding to workspaceConfig
+status code = 500 - the other unknown errors
+failure message in response - the description of failure</programlisting>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+
+ <section>
+ <title>Default Workspace Information</title>
+
+ <para><emphasis
+ role="bold">/rest/jcr-backup/info/default-ws-config</emphasis> Will be
+ returned the JSON bean to WorkspaceEntry for default workspace.</para>
+
+ <para><emphasis role="bold">URL:</emphasis>
+ <uri>http://host:port/rest/jcr-backup/info/default-ws-config</uri></para>
+
+ <para><emphasis role="bold">Formats:</emphasis> json</para>
+
+ <para><emphasis role="bold">Method</emphasis>: GET</para>
+
+ <para><emphasis role="bold">Parameters:</emphasis> no</para>
+
+ <para><emphasis role="bold">Returns:</emphasis><itemizedlist>
+ <listitem>
+ <para>return when successful</para>
+
+ <para>The JSON bean to
+ org.exoplatform.services.jcr.config.WorkspaceEntry
+ :<programlisting>{ "accessManager" : null,
+ "autoInitPermissions" : null,
+ "autoInitializedRootNt" : null,
+ "cache" : { "parameters" : [ { "name" : "max-size",
+ "value" : "10k"
+ },
+ { "name" : "live-time",
+ "value" : "1h"
+ }
+ ],
+ "type" : "org.exoplatform.services.jcr.impl.dataflow.persistent.LinkedWorkspaceStorageCacheImpl"
+ },
+ "container" : { "parameters" : [ { "name" : "source-name",
+ "value" : "jdbcjcr"
+ },
+ { "name" : "dialect",
+ "value" : "hsqldb"
+ },
+ { "name" : "multi-db",
+ "value" : "false"
+ },
+ { "name" : "update-storage",
+ "value" : "false"
+ },
+ { "name" : "max-buffer-size",
+ "value" : "200k"
+ },
+ { "name" : "swap-directory",
+ "value" : "../temp/swap/production"
+ }
+ ],
+ "type" : "org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer",
+ "valueStorages" : [ { "filters" : [ { "ancestorPath" : null,
+ "minValueSize" : 0,
+ "propertyName" : null,
+ "propertyType" : "Binary"
+ } ],
+ "id" : "system",
+ "parameters" : [ { "name" : "path",
+ "value" : "../temp/values/production"
+ } ],
+ "type" : "org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage"
+ } ]
+ },
+ "initializer" : { "parameters" : [ { "name" : "root-nodetype",
+ "value" : "nt:unstructured"
+ } ],
+ "type" : "org.exoplatform.services.jcr.impl.core.ScratchWorkspaceInitializer"
+ },
+ "lockManager" : { "persister" : { "parameters" : [ { "name" : "path",
+ "value" : "../temp/lock/system"
+ } ],
+ "type" : "org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister"
+ },
+ "timeout" : 15728640
+ },
+ "name" : "production",
+ "queryHandler" : { "analyzer" : { },
+ "autoRepair" : true,
+ "bufferSize" : 10,
+ "cacheSize" : 1000,
+ "documentOrder" : true,
+ "errorLogSize" : 50,
+ "excerptProviderClass" : "org.exoplatform.services.jcr.impl.core.query.lucene.DefaultHTMLExcerpt",
+ "excludedNodeIdentifers" : null,
+ "extractorBackLogSize" : 100,
+ "extractorPoolSize" : 0,
+ "extractorTimeout" : 100,
+ "indexDir" : "../temp/jcrlucenedb/production",
+ "indexingConfigurationClass" : "org.exoplatform.services.jcr.impl.core.query.lucene.IndexingConfigurationImpl",
+ "indexingConfigurationPath" : null,
+ "maxFieldLength" : 10000,
+ "maxMergeDocs" : 2147483647,
+ "mergeFactor" : 10,
+ "minMergeDocs" : 100,
+ "parameters" : [ { "name" : "index-dir",
+ "value" : "../temp/jcrlucenedb/production"
+ } ],
+ "queryClass" : "org.exoplatform.services.jcr.impl.core.query.QueryImpl",
+ "queryHandler" : null,
+ "resultFetchSize" : 2147483647,
+ "rootNodeIdentifer" : "00exo0jcr0root0uuid0000000000000",
+ "spellCheckerClass" : null,
+ "supportHighlighting" : false,
+ "synonymProviderClass" : null,
+ "synonymProviderConfigPath" : null,
+ "type" : "org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex",
+ "useCompoundFile" : false,
+ "volatileIdleTime" : 3
+ },
+ "uniqueName" : "repository_production"
+}</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>return when failure</para>
+
+ <programlisting>status code = 500 - the unknown error
+failure message in response - the description of failure</programlisting>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+ </section>
+
+ <section>
+ <title>HTTPBackupAgent Configuration</title>
+
+ <para>Add the components
+ org.exoplatform.services.jcr.ext.backup.server.HTTPBackupAgent and
+ org.exoplatform.services.jcr.ext.backup.BackupManager to services
+ configuration :</para>
+
+ <programlisting><component>
+ <type>org.exoplatform.services.jcr.ext.backup.server.HTTPBackupAgent</type>
+</component>
+
+<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="../temp/backup" />
+ </properties-param>
+ </init-params>
+</component></programlisting>
+ </section>
+ </section>
+
+ <section>
+ <title>Backup Client</title>
+
+ <para>Backup client is console application.</para>
+
+ <para>The backup client is http client for HTTPBackupAgent.</para>
+
+ <para>Command signature:</para>
+
+ <programlisting>Help info:
+ <url> <cmd>
+ <url> : http(s)//login:password at host:port/<context>
+ <cmd> : start <repo/ws> <backup_dir> [<incr>]
+ stop <backup_id>
+ status <backup_id>
+ restores <repo/ws>
+ restore <repo/ws> <backup_id> <pathToConfigFile>
+ list [completed]
+ info
+ drop [force-close-session] <repo/ws>
+ help
+
+ start - start backup
+ stop - stop backup
+ status - information about the current or completed backup by 'backup_id'
+ restores - information about the last restore on specific workspace
+ restore - restore the workspace from specific backup
+ list - information about the current backups (in progress)
+ list completed - information about the completed (ready to restore) backups
+ info - information about the service backup
+ drop - delete the workspace
+ help - print help information about backup console
+
+ <repo/ws> - /<reponsitory-name>/<workspace-name> the workspace
+ <backup_dir> - path to folder for backup on remote server
+ <backup_id> - the identifier for backup
+ <incr> - incemental job period
+ <pathToConfigFile> - path (local) to workspace configuration
+ force-close-session - close opened sessions on workspace.</programlisting>
+ </section>
+
+ <section>
+ <title>Backup Client Usage</title>
+
+ <section>
+ <title>Build application</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>go to folder of "backup client" <emphasis
+ role="bold">../jcr/trunk/applications/java/standalone/backupconsole</emphasis>
+ . - build the application :<programlisting>
+ mvn clean install
+
+</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>go to <emphasis
+ role="bold">../jcr/trunk/applications/java/standalone/backupconsole/target/backupconsole-binary</emphasis>
+ and use it.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Run application</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>run jar<programlisting>java -jar exo.jcr.applications.backupconsole-1.11.1-SNAPSHOT.jar <command>
+</programlisting>or use jcrbackup.cmd (or .sh);</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Get information about backup service</title>
+
+ <programlisting>jcrbackup http://root:exo@127.0.0.1:8080 info</programlisting>
+
+ <para>return :</para>
+
+ <programlisting>The backup service information :
+ full backup type : org.exoplatform.services.jcr.ext.backup.impl.fs.FullBackupJob
+ incremetal backup type : org.exoplatform.services.jcr.ext.backup.impl.fs.IncrementalBackupJob
+ backup log folder : /home/rainf0x/java/exo-working/JCR-839/new_JCR/exo-tomcat/bin/../temp/backup
+ default incremental job period : 3600</programlisting>
+ </section>
+
+ <section>
+ <title>Start full backup</title>
+
+ <para>Start full backup only on workspace "backup", the parameter
+ <bakcup_dir> (../temp/backup) should be exists:</para>
+
+ <programlisting>jcrbackup http://root:exo@127.0.0.1:8080 start /repository/backup ../temp/backup</programlisting>
+
+ <para>return :</para>
+
+ <programlisting>Successful :
+ status code = 200</programlisting>
+ </section>
+
+ <section>
+ <title>Start full and incremental backup on a single workspace</title>
+
+ <para>Start full and incremental backup on workspace
+ "production":</para>
+
+ <programlisting>jcrbackup http://root:exo@127.0.0.1:8080 start /repository/production ../temp/backup 10000</programlisting>
+
+ <para>return :</para>
+
+ <programlisting>Successful :
+ tatus code = 200</programlisting>
+ </section>
+
+ <section>
+ <title>Get information about the current backups (in progress)</title>
+
+ <programlisting>jcrbackup http://root:exo@127.0.0.1:8080 list</programlisting>
+
+ <para>return :</para>
+
+ <programlisting>The current backups information :
+ 1) Backup with id b46370107f000101014b03ea5fbe8d54 :
+ repository name : repository
+ workspace name : production
+ backup type : full + incremetal
+ full backup state : finished
+ incremental backup state : working
+ started time : Fri, 17 Apr 2009 17:03:16 EEST
+ 2) Backup with id b462e4427f00010101cf243b4c6015bb :
+ repository name : repository
+ workspace name : backup
+ backup type : full only
+ full backup state : finished
+ started time : Fri, 17 Apr 2009 17:02:41 EEST</programlisting>
+ </section>
+
+ <section>
+ <title>Get information about the current backup by 'backup_id'</title>
+
+ <programlisting>jcrbackup http://root:exo@127.0.0.1:8080 status b46370107f000101014b03ea5fbe8d54</programlisting>
+
+ <para>return:</para>
+
+ <programlisting>The current backup information :
+ backup id : b46370107f000101014b03ea5fbe8d54
+ backup folder : /home/rainf0x/java/exo-working/JCR-839/new_JCR/exo-tomcat/bin/../temp/backup
+ repository name : repository
+ workspace name : production
+ backup type : full + incremetal
+ full backup state : finished
+ incremental backup state : working
+ started time : Fri, 17 Apr 2009 17:03:16 EEST</programlisting>
+ </section>
+
+ <section>
+ <title>Stop backup by "backup_id"</title>
+
+ <programlisting>jcrbackup http://root:exo@127.0.0.1:8080 stop 6c302adc7f00010100df88d29535c6ee</programlisting>
+
+ <para>return:</para>
+
+ <programlisting>Successful :
+ status code = 200</programlisting>
+ </section>
+
+ <section>
+ <title>Get information about the completed (ready to restore)
+ backups</title>
+
+ <programlisting>jcrbackup http://root:exo@127.0.0.1:8080 list completed</programlisting>
+
+ <para>return:</para>
+
+ <programlisting>The completed (ready to restore) backups information :
+ 1) Backup with id adf6fadc7f00010100053b2cba43513c :
+ repository name : repository
+ workspace name : backup
+ backup type : full only
+ started time : Thu, 16 Apr 2009 11:07:05 EEST
+
+ 2) Backup with id b46370107f000101014b03ea5fbe8d54 :
+ repository name : repository
+ workspace name : production
+ backup type : full + incremetal
+ started time : Fri, 17 Apr 2009 17:03:16 EEST
+
+ 3) Backup with id aec419cc7f000101004aca277b2b4e9f :
+ repository name : repository
+ workspace name : backup8
+ backup type : full only
+ started time : Thu, 16 Apr 2009 14:51:08 EEST</programlisting>
+ </section>
+
+ <section>
+ <title>Restore to workspace</title>
+
+ <para>Restore to workspace "backup3", for restore need the
+ <backup_id> of completed backup and path to file with workspace
+ configuration:</para>
+
+ <programlisting>jcrbackup http://root:exo@127.0.0.1:8080 restore /repository/backup3 6c302adc7f00010100df88d29535c6ee /home/rainf0x/java/exo-working/JCR-839/exo-jcr-config_backup3.xml</programlisting>
+
+ <para>return:</para>
+
+ <programlisting>Successful :
+ status code = 200</programlisting>
+ </section>
+
+ <section>
+ <title>Get information about the current restore</title>
+
+ <para>Get information about the current restore for workspace
+ /repository/backup3:</para>
+
+ <programlisting>jcrbackup http://root:exo@127.0.0.1:8080 restores</programlisting>
+
+ <para>return:</para>
+
+ <programlisting>The current restores information :
+1) Restore with id 6c302adc7f00010100df88d29535c6ee:
+ full backup date : 2009-04-03T16:34:37.394+03:00
+ backup log file : /home/rainf0x/java/exo-working/JCR-839/exo-tomcat/bin/../temp/backup/backup-6c302adc7f00010100df88d29535c6ee.xml
+ repository name : repository
+ workspace name : backup3
+ backup type : full only
+ path to backup folder : /home/rainf0x/java/exo-working/JCR-839/exo-tomcat/bin/../temp/backup
+ restore state : successful</programlisting>
+ </section>
+ </section>
+
+ <section>
+ <title>Full Example for create backup and restore it for workspace
+ 'backup'</title>
+
+ <section>
+ <title>Create backup</title>
+
+ <programlisting>jcrbackup http://root:exo@127.0.0.1:8080 start /repository/backup ../temp/backup 10000</programlisting>
+
+ <para>return :</para>
+
+ <programlisting>Successful :
+ status code = 200</programlisting>
+ </section>
+
+ <section>
+ <title>Get information about current backups</title>
+
+ <programlisting>jcrbackup http://root:exo@127.0.0.1:8080 list</programlisting>
+
+ <para>return :</para>
+
+ <programlisting>The current backups information :
+ 1) Backup with id b469ba957f0001010178febaedf20eb7 :
+ repository name : repository
+ workspace name : backup
+ backup type : full + incremetal
+ full backup state : finished
+ incremental backup state : working
+ started time : Fri, 17 Apr 2009 17:10:09 EEST</programlisting>
+ </section>
+
+ <section>
+ <title>Stop backup by id</title>
+
+ <para>Stop backup with id b469ba957f0001010178febaedf20eb7 :</para>
+
+ <programlisting>jcrbackup http://root:exo@127.0.0.1:8080 stop b469ba957f0001010178febaedf20eb7</programlisting>
+
+ <para>return :</para>
+
+ <programlisting>Successful :
+ status code = 200</programlisting>
+ </section>
+
+ <section>
+ <title>Delete the workspace "backup" and close opened sessions on this
+ workspace</title>
+
+ <programlisting>jcrbackup http://root:exo@127.0.0.1:8080 drop force-close-session /repository/backup</programlisting>
+
+ <para>return :</para>
+
+ <programlisting>Successful :
+ status code = 200</programlisting>
+ </section>
+
+ <section>
+ <title>Restore the workspace "backup"</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>delete/clean the database for workspace <emphasis
+ role="bold">"backup"</emphasis> : When we use "single-db", then we
+ will run the SQL queries for clean database :<programlisting>
+ delete from JCR_SREF where NODE_ID in (select ID from JCR_SITEM where CONTAINER_NAME = 'backup')
+ delete from JCR_SVALUE where PROPERTY_ID in (select ID from JCR_SITEM where CONTAINER_NAME = 'backup')
+ delete from JCR_SITEM where CONTAINER_NAME='backup'
+
+</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>delete the value storage for workspace <emphasis
+ role="bold">"backup"</emphasis>; - delete the index data for
+ workspace <emphasis role="bold">"backup"</emphasis>; - restore
+ :<programlisting>jcrbackup http://root:exo@127.0.0.1:8080 restore /repository/backup b469ba957f0001010178febaedf20eb7 /home/rainf0x/java/exo-working/JCR-839/exo-jcr-config_backup.xml
+</programlisting>return :<programlisting>Successful :
+ status code = 200</programlisting>The
+ /home/rainf0x/java/exo-working/JCR-839/exo-jcr-config_backup.xml
+ content the configuration for restored workspace <emphasis
+ role="bold">"backup"</emphasis> :<programlisting>
+<repository-service default-repository="repository">
+ <repositories>
+ <repository name="repository" system-workspace="production" default-workspace="production">
+ <security-domain>exo-domain</security-domain>
+ <access-control>optional</access-control>
+ <authentication-policy>org.exoplatform.services.jcr.impl.core.access.JAASAuthenticator</authentication-policy>
+ <workspaces>
+
+ <workspace name="backup">
+ <container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer">
+ <properties>
+ <property name="source-name" value="jdbcjcr" />
+ <property name="dialect" value="pgsql" />
+ <property name="multi-db" value="false" />
+ <property name="update-storage" value="false" />
+ <property name="max-buffer-size" value="200k" />
+ <property name="swap-directory" value="../temp/swap/backup" />
+ </properties>
+ <value-storages>
+ <value-storage id="draft" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage">
+ <properties>
+ <property name="path" value="../temp/values/backup" />
+ </properties>
+ <filters>
+ <filter property-type="Binary"/>
+ </filters>
+ </value-storage>
+ </value-storages>
+ </container>
+ <initializer class="org.exoplatform.services.jcr.impl.core.ScratchWorkspaceInitializer">
+ <properties>
+ <property name="root-nodetype" value="nt:unstructured" />
+ </properties>
+ </initializer>
+ <cache enabled="true" class="org.exoplatform.services.jcr.impl.dataflow.persistent.LinkedWorkspaceStorageCacheImpl">
+ <properties>
+ <property name="max-size" value="10k" />
+ <property name="live-time" value="1h" />
+ </properties>
+ </cache>
+ <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex">
+ <properties>
+ <property name="index-dir" value="../temp/jcrlucenedb/backup" />
+ </properties>
+ </query-handler>
+ </workspace>
+ </workspaces>
+ </repository>
+ </repositories>
+</repository-service></programlisting></para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Get information about restore for workspace
+ /repository/backup</title>
+
+ <programlisting>jcrbackup http://root:exo@127.0.0.1:8080 restores /repository/backup</programlisting>
+
+ <para>return:</para>
+
+ <programlisting>The current restores information :
+ Restore with id b469ba957f0001010178febaedf20eb7:
+ backup folder : /home/rainf0x/java/exo-working/JCR-839/new_JCR/exo-tomcat/bin/../temp/backup
+ repository name : repository
+ workspace name : backup
+ backup type : full + incremetal
+ restore state : successful
+ started time : Fri, 17 Apr 2009 16:38:00 EEST
+ finished time : Fri, 17 Apr 2009 16:38:00 EEST</programlisting>
+ </section>
+ </section>
+</chapter>
Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/backup/exojcr-backup-service.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/backup/exojcr-backup-service.xml 2010-08-03 08:22:26 UTC (rev 2858)
+++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/backup/exojcr-backup-service.xml 2010-08-03 09:43:46 UTC (rev 2859)
@@ -1,480 +1,480 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="JCR.eXoJCRBackupService">
- <?dbhtml filename="ch-exojcr-backup-service.html"?>
-
- <title>eXo JCR Backup Service</title>
-
- <section id="Concept">
- <title>Concept</title>
-
- <para>The main purpose of that feature is to restore data in case of
- system faults and repository crashes. Also the backup results may be used
- as a content history.</para>
-
- <para>The eXo JCR backup service was developed from the JCR 1.8
- implementation. It's an independent service available as an eXo JCR
- Extensions project.</para>
-
- <para>The concept is based on the export of a workspace unit in the Full,
- or Full + Incrementals model. A repository workspace can be backup and
- restored using a combination of these modes. In all cases, at least one
- Full (initial) backup must be executed to mark a starting point of the
- backup history. An Incremental backup is not a complete image of the
- workspace. It contains only changes for some period. So it is not possible
- to perform an Incremental backup without an initial Full backup.</para>
-
- <para>The Backup service may operate as a hot-backup process at runtime on
- an in-use workspace. It's a case when the Full + Incrementals model should
- be used to have a guaranty of data consistency during restoration. An
- Incremental will be run starting from the start point of the Full backup
- and will contain changes that have occured during the Full backup
- too.</para>
-
- <para>A <emphasis role="bold">restore</emphasis> operation is a mirror of
- a backup one. At least one Full backup should be restored to obtain a
- workspace corresponding to some point in time. On the other hand,
- Incrementals may be restored in the order of creation to reach a required
- state of a content. If the Incremental contains the same data as the Full
- backup (hot-backup), the changes will be applied again as if they were
- made in a normal way via API calls.</para>
-
- <para>According to the model there are several modes for backup
- logic:</para>
-
- <itemizedlist>
- <listitem>
- <para><emphasis role="bold">Full backup only</emphasis> : single
- operation, runs once</para>
- </listitem>
-
- <listitem>
- <para><emphasis role="bold">Full + Incrementals</emphasis> : Start
- with an initial Full backup and then keep incrementals changes in one
- file. Runs until it is stopped.</para>
- </listitem>
-
- <listitem>
- <para><emphasis role="bold">Full + Incrementals(periodic)</emphasis> :
- Start with an initial Full backup and then keep incrementals with
- periodic result file rotation. Runs until it is stopped.</para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>How it works</title>
-
- <section>
- <title>Implementation details</title>
-
- <para>Full backup/restore is implemented using the JCR SysView
- Export/Import. Workspace data will be exported into Sysview XML data
- from root node.</para>
-
- <para>Restore is implemented using the special eXo JCR API feature: a
- dynamic workspace creation. Restoring of the workspace Full backup will
- create one new workspace in the repository. Then the SysView XML data
- will be imported as the root node.</para>
-
- <para>Incremental backup is implemented using the eXo JCR ChangesLog
- API. This API allows to record each JCR API call as atomic entries in a
- changelog. Hence, the Incremental backup uses a listener that collects
- these logs and stores them in a file.</para>
-
- <para>Restoring an incremental backup consists in applying the collected
- set of ChangesLogs to a workspace in the correct order.</para>
- </section>
-
- <section>
- <title>Work basics</title>
-
- <para>The work of Backup is based on the BackupConfig configuration and
- the BackupChain logical unit.</para>
-
- <para>BackupConfig describes the backup operation chain that will be
- performed by the service. When you intend to work with it, the
- configuration should be prepared before the backup is started.</para>
-
- <para>The configuration contains such values as:</para>
-
- <itemizedlist>
- <listitem>
- <para><emphasis role="bold">types of full and incremental
- backup</emphasis> ? (fullBackupType, incrementalBackupType) Strings
- with full names of classes which will cover the type
- functional.</para>
- </listitem>
-
- <listitem>
- <para><emphasis role="bold">incremental period</emphasis> - a period
- after that a current backup will be stopped and a new one will be
- started, in seconds (long).</para>
- </listitem>
-
- <listitem>
- <para><emphasis role="bold">target repository and workspace
- names</emphasis> ? Strings with described names</para>
- </listitem>
-
- <listitem>
- <para><emphasis role="bold">destination directory</emphasis> for
- result files ? String with a path to a folder where operation result
- files will be stored.</para>
- </listitem>
- </itemizedlist>
-
- <para>BackupChain is a unit performing the backup process and it covers
- the principle of initial Full backup execution and manages Incrementals
- operations. BackupChain is used as a key object for accessing current
- backups during runtime via BackupManager. Each BackupJob performs a
- single atomic operation ? a Full or Incremental process. The result of
- that operation is data for a Restore. BackupChain can contain one or
- more BackupJobs. But at least the initial Full job is always there. Each
- BackupJobs has its own unique number which means its Job order in the
- chain, the initial Full job always has the number 0.</para>
-
- <para><emphasis role="bold">Backup process, result data and file
- location</emphasis></para>
-
- <para>To start the backup process it's necessary to create the
- BackupConfig and call the BackupManager.startBackup(BackupConfig)
- method. This method will return BackupChain created according to the
- configuration. At the same time the chain creates a BackupChainLog which
- persists BackupConfig content and BackupChain operation states to the
- file in the service working directory (see Configuration).</para>
-
- <para>When the chain starts the work and the initial BackupJob starts,
- the job will create a result data file using the destination directory
- path from BackupConfig. The destination directory will contain a
- directory with an automatically created name using the pattern
- repository_workspace-timestamp where timestamp is current time in the
- format of yyyyMMdd_hhmmss (E.g. db1_ws1-20080306_055404). The directory
- will contain the results of all Jobs configured for execution. Each Job
- stores the backup result in its own file with the name
- repository_workspace-timestamp.jobNumber. BackupChain saves each state
- (STARTING, WAITING, WORKING, FINISHED) of its Jobs in the
- BackupChainLog, which has a current result full file path.</para>
-
- <para>BackupChain log file and job result files are a whole and
- consistent unit, that is a source for a Restore.</para>
-
- <note>
- <para>BackupChain log contains absolute paths to job result files.
- Don't move these files to another location.</para>
- </note>
-
- <para><emphasis role="bold">Restore requirements</emphasis></para>
-
- <para>As mentioned before a Restore operation is a mirror of a Backup.
- The process is a Full restore of a root node with restoring an
- additional Incremental backup to reach a desired workspace state.
- Restoring of the workspace Full backup will create a new workspace in
- the repository using given RepositoyEntry of existing repository and
- given (preconfigured) WorkspaceEntry for a new target workspace. A
- Restore process will restore a root node there from the SysView XML
- data.</para>
-
- <note>
- <para>The target workspace should not be in the repository. Otherwise
- a BackupConfigurationException exception will be thrown.</para>
- </note>
-
- <para>For creation and manipulation with Workspaces check the article
- <link linkend="TODO">Repository and Workspace management</link>.</para>
-
- <para>Finally we may say that a Restore is a process of a new Workspace
- creation and filling it with a Backup content. In case you already have
- a target Workspace (with the same name) in a Repository, you have to
- configure a new name for it. If no target workspace exists in the
- Repository you may use the same name as the Backup one.</para>
- </section>
- </section>
-
- <section>
- <title>Configuration</title>
-
- <para>As an optional extension, the Backup service is not enabled by
- default. <emphasis role="bold">You need to enable it via
- configuration</emphasis>.</para>
-
- <para>Below is an example configuration compatible with JCR 1.9.3 and
- later :</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 period = 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></programlisting>
-
- <para>Where:<itemizedlist>
- <listitem>
- <para><emphasis role="bold">incremental-backup-type</emphasis>
- (since 1.9.3) : the FQN of incremental job class. Must implement
- org.exoplatform.services.jcr.ext.backup.BackupJob</para>
- </listitem>
-
- <listitem>
- <para><emphasis role="bold">full-backup-type</emphasis> (since
- 1.9.3) : the FQN of the full backup job class; Must implement
- org.exoplatform.services.jcr.ext.backup.BackupJob</para>
- </listitem>
-
- <listitem>
- <para><emphasis
- role="bold">default-incremental-job-period</emphasis> (since 1.9.3)
- :the period between incremetal flushes (in seconds)</para>
- </listitem>
-
- <listitem>
- <para><emphasis role="bold">backup-dir</emphasis> : the path to a
- working directory where the service will store internal files and
- chain logs.</para>
- </listitem>
- </itemizedlist></para>
- </section>
-
- <section>
- <title>Usage</title>
-
- <section>
- <title>Perform a Backup</title>
-
- <para>In following example we create a BackupConfig bean for the Full +
- Incrementals mode, then we ask the BackupManager to start the backup
- process.</para>
-
- <programlisting>// Obtaining the backup service from the eXo container.
-BackupManager backup = (BackupManager) container.getComponentInstanceOfType(BackupManager.class);
-
-// And prepare the BackupConfig instance with custom parameters.
-// full backup & incremental
-File backDir = new File("/backup/ws1"); // the destination path for result files
-backDir.mkdirs();
-
-BackupConfig config = new BackupConfig();
-config.setRepository(repository.getName());
-config.setWorkspace("ws1");
-config.setBackupDir(backDir);
-
-// Before 1.9.3, you also need to indicate the backupjobs class FDNs
-// config.setFullBackupType("org.exoplatform.services.jcr.ext.backup.impl.fs.FullBackupJob");
-// config.setIncrementalBackupType("org.exoplatform.services.jcr.ext.backup.impl.fs.IncrementalBackupJob");
-
-// start backup using the service manager
-BackupChain chain = backup.startBackup(config);</programlisting>
-
- <para>To stop the backup operation you have to use the BackupChain
- instance.</para>
-
- <programlisting>// stop backup
-backup.stopBackup(chain);</programlisting>
- </section>
-
- <section>
- <title>Perform a Restore</title>
-
- <para>Restoration involves the reloading the backup file into a
- BackupChainLog and applying appropriate workspace initialization. The
- following snippet shows the typical sequence for restoring a workspace
- :</para>
-
- <programlisting>// find BackupChain using the repository and workspace names (return null if not found)
-BackupChain chain = backup.findBackup("db1", "ws1");
-
-// Get the RepositoryEntry and WorkspaceEntry
-ManageableRepository repo = repositoryService.getRepository(repository);
-RepositoryEntry repoconf = repo.getConfiguration();
-List<WorkspaceEntry> entries = repoconf.getWorkspaceEntries();
-WorkspaceEntry = getNewEntry(entries, workspace); // create a copy entry from an existing one
-
-// restore backup log using ready RepositoryEntry and WorkspaceEntry
-File backLog = new File(chain.getLogFilePath());
-BackupChainLog bchLog = new BackupChainLog(backLog);
-
-// initialize the workspace
-repository.configWorkspace(workspaceEntry);
-
-// run restoration
-backup.restore(bchLog, repositoryEntry, workspaceEntry);</programlisting>
-
- <section>
- <title>Restoring into an existing workspace</title>
-
- <note>
- <para>These instructions only applies to regular workspace. Special
- instructions are provided for System workspace below.</para>
- </note>
-
- <para>To restore a backup over an existing workspace, you are required
- to clear its data. Your backup process should follow these steps :
- <itemizedlist>
- <listitem>
- <para>remove workspace<programlisting>ManageableRepository repo = repositoryService.getRepository(repository);
-repo.removeWorkspace(workspace);</programlisting></para>
- </listitem>
-
- <listitem>
- <para>clean database, value storage, index</para>
- </listitem>
-
- <listitem>
- <para>restore (see snippet above)</para>
- </listitem>
- </itemizedlist></para>
- </section>
-
- <section>
- <title>System workspace</title>
-
- <note>
- <para>The BackupWorkspaceInitializer is available in JCR 1.9 and
- later.</para>
- </note>
-
- <para>Restoring the JCR System workspace requires to shutdown the
- system and use of a special initializer.</para>
-
- <para>Follow these steps (this will also work for normal workspaces) :
- <itemizedlist>
- <listitem>
- <para>Stop repository (or portal)</para>
- </listitem>
-
- <listitem>
- <para>clean database, value storage, index; </para>
- </listitem>
-
- <listitem>
- <para>In configuration the workspace set
- BackupWorkspaceInitializer to reference your backup.</para>
-
- <para>For example :<programlisting><workspaces>
- <workspace name="production" ... >
- <container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer">
- ...
- </container>
- <initializer class="org.exoplatform.services.jcr.impl.core.BackupWorkspaceInitializer">
- <properties>
- <property name="restore-path" value="D:\java\exo-working\backup\repository_production-20090527_030434"/>
- </properties>
- </initializer>
- ...
-</workspace></programlisting></para>
- </listitem>
-
- <listitem>
- <para>Start repository (or portal).</para>
- </listitem>
- </itemizedlist></para>
- </section>
- </section>
- </section>
-
- <section>
- <title>Scheduling (experimental)</title>
-
- <para>The Backup service has an additional feature that can be useful for
- a production level backup implementation. When you need to organize a
- backup of a repository it's necessary to have a tool which will be able to
- create and manage a cycle of Full and Incremental backups in periodic
- manner.</para>
-
- <para>The service has internal BackupScheduler which can run a
- configurable cycle of BackupChains as if they have been executed by a user
- during some period of time. I.e. BackupScheduler is a user-like daemon
- which asks the BackupManager to start or stop backup operations.</para>
-
- <para>For that purpose BackupScheduler has the method</para>
-
- <para>BackupScheduler.schedule(backupConfig, startDate, stopDate,
- chainPeriod, incrementalPeriod)</para>
-
- <para>where</para>
-
- <itemizedlist>
- <listitem>
- <para>backupConfig - a ready configuration which will be given to the
- BackupManager.startBackup() method</para>
- </listitem>
-
- <listitem>
- <para>startDate - a date and time of the backup start</para>
- </listitem>
-
- <listitem>
- <para>stopDate - a date and time of the backup stop</para>
- </listitem>
-
- <listitem>
- <para>chainPeriod - a period after which a current BackupChain will be
- stopped and a new one will be started, in seconds</para>
- </listitem>
-
- <listitem>
- <para>incrementalPeriod - if it is greater than 0 it will be used to
- override the same value in backupConfig.</para>
- </listitem>
- </itemizedlist>
-
- <programlisting>// geting the scheduler from the BackupManager
- BackupScheduler scheduler = backup.getScheduler();
-
-// schedule backup using a ready configuration (Full + Incrementals) to run from startTime
-// to stopTime. Full backuop will be performed every 24 hours (BackupChain lifecycle),
-// incremental will rotate result files every 3 hours.
- scheduler.schedule(config, startTime, stopTime, 3600 * 24, 3600 * 3);
-
-// it's possible to run the scheduler for an uncertain period of time (i.e. without stop time).
-// schedule backup to run from startTime till it will be stopped manually
-// also there, the incremental will rotate result files as it configured in BackupConfig
- scheduler.schedule(config, startTime, null, 3600 * 24, 0);
-
-// to unschedule backup simply call the scheduler with the configuration describing the
-// already planned backup cycle.
-// the scheduler will search in internal tasks list for task with repository and
-// workspace name from the configuration and will stop that task.
- scheduler.unschedule(config);</programlisting>
-
- <para>When the BackupScheduler starts the scheduling, it uses the internal
- Timer with startDate for the first (or just once) execution. If
- chainPeriod is greater than 0 then the task is repeated with this value
- used as a period starting from startDate. Otherwise the task will be
- executed once at startDate time. If the scheduler has stopDate it will
- stop the task ( the chain cycle) after stopDate. And the last parameter
- incrementalPeriod will be used instead of the same from BackupConfig if
- its values are greater than 0.</para>
-
- <para>Starting each task (BackupScheduler.schedule(...)), the scheduler
- creates a task file in the service working directory (see <emphasis
- role="bold">Configuration</emphasis>, backup-dir) which describes the task
- backup configuration and periodic values. These files will be used at the
- backup service start (JVM start) to reinitialize BackupScheduler for
- continuous task scheduling. Only tasks that don't have a stopDate or a
- stopDate not expired will be reinitialized.</para>
-
- <para>There is one notice about BackupScheduler task reinitialization in
- the current implementation. It comes from the BackupScheduler nature and
- its implemented behaviour. As the scheduler is just a virtual user which
- asks the BackupManager to start or stop backup operations, it isn't able
- to reinitialize each existing BackupChain before the service (JVM) is
- stopped. But it's possible to start a new operation with the same
- configuration via BackupManager (that was configured before and stored in
- a task file).</para>
-
- <para>This is a main detail of the BackupScheduler which should be taken
- into suggestion of a backup operation design now. In case of
- reinitialization the task will have new time values for the backup
- operation cycle as the chainPeriod and incrementalPeriod will be applied
- again. That behaviour may be changed in the future.</para>
- </section>
-</chapter>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="JCR.BackupService">
+ <?dbhtml filename="ch-exojcr-backup-service.html"?>
+
+ <title>eXo JCR Backup Service</title>
+
+ <section id="Concept">
+ <title>Concept</title>
+
+ <para>The main purpose of that feature is to restore data in case of
+ system faults and repository crashes. Also the backup results may be used
+ as a content history.</para>
+
+ <para>The eXo JCR backup service was developed from the JCR 1.8
+ implementation. It's an independent service available as an eXo JCR
+ Extensions project.</para>
+
+ <para>The concept is based on the export of a workspace unit in the Full,
+ or Full + Incrementals model. A repository workspace can be backup and
+ restored using a combination of these modes. In all cases, at least one
+ Full (initial) backup must be executed to mark a starting point of the
+ backup history. An Incremental backup is not a complete image of the
+ workspace. It contains only changes for some period. So it is not possible
+ to perform an Incremental backup without an initial Full backup.</para>
+
+ <para>The Backup service may operate as a hot-backup process at runtime on
+ an in-use workspace. It's a case when the Full + Incrementals model should
+ be used to have a guaranty of data consistency during restoration. An
+ Incremental will be run starting from the start point of the Full backup
+ and will contain changes that have occured during the Full backup
+ too.</para>
+
+ <para>A <emphasis role="bold">restore</emphasis> operation is a mirror of
+ a backup one. At least one Full backup should be restored to obtain a
+ workspace corresponding to some point in time. On the other hand,
+ Incrementals may be restored in the order of creation to reach a required
+ state of a content. If the Incremental contains the same data as the Full
+ backup (hot-backup), the changes will be applied again as if they were
+ made in a normal way via API calls.</para>
+
+ <para>According to the model there are several modes for backup
+ logic:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">Full backup only</emphasis> : single
+ operation, runs once</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">Full + Incrementals</emphasis> : Start
+ with an initial Full backup and then keep incrementals changes in one
+ file. Runs until it is stopped.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">Full + Incrementals(periodic)</emphasis> :
+ Start with an initial Full backup and then keep incrementals with
+ periodic result file rotation. Runs until it is stopped.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>How it works</title>
+
+ <section>
+ <title>Implementation details</title>
+
+ <para>Full backup/restore is implemented using the JCR SysView
+ Export/Import. Workspace data will be exported into Sysview XML data
+ from root node.</para>
+
+ <para>Restore is implemented using the special eXo JCR API feature: a
+ dynamic workspace creation. Restoring of the workspace Full backup will
+ create one new workspace in the repository. Then the SysView XML data
+ will be imported as the root node.</para>
+
+ <para>Incremental backup is implemented using the eXo JCR ChangesLog
+ API. This API allows to record each JCR API call as atomic entries in a
+ changelog. Hence, the Incremental backup uses a listener that collects
+ these logs and stores them in a file.</para>
+
+ <para>Restoring an incremental backup consists in applying the collected
+ set of ChangesLogs to a workspace in the correct order.</para>
+ </section>
+
+ <section>
+ <title>Work basics</title>
+
+ <para>The work of Backup is based on the BackupConfig configuration and
+ the BackupChain logical unit.</para>
+
+ <para>BackupConfig describes the backup operation chain that will be
+ performed by the service. When you intend to work with it, the
+ configuration should be prepared before the backup is started.</para>
+
+ <para>The configuration contains such values as:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">types of full and incremental
+ backup</emphasis> ? (fullBackupType, incrementalBackupType) Strings
+ with full names of classes which will cover the type
+ functional.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">incremental period</emphasis> - a period
+ after that a current backup will be stopped and a new one will be
+ started, in seconds (long).</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">target repository and workspace
+ names</emphasis> ? Strings with described names</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">destination directory</emphasis> for
+ result files ? String with a path to a folder where operation result
+ files will be stored.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>BackupChain is a unit performing the backup process and it covers
+ the principle of initial Full backup execution and manages Incrementals
+ operations. BackupChain is used as a key object for accessing current
+ backups during runtime via BackupManager. Each BackupJob performs a
+ single atomic operation ? a Full or Incremental process. The result of
+ that operation is data for a Restore. BackupChain can contain one or
+ more BackupJobs. But at least the initial Full job is always there. Each
+ BackupJobs has its own unique number which means its Job order in the
+ chain, the initial Full job always has the number 0.</para>
+
+ <para><emphasis role="bold">Backup process, result data and file
+ location</emphasis></para>
+
+ <para>To start the backup process it's necessary to create the
+ BackupConfig and call the BackupManager.startBackup(BackupConfig)
+ method. This method will return BackupChain created according to the
+ configuration. At the same time the chain creates a BackupChainLog which
+ persists BackupConfig content and BackupChain operation states to the
+ file in the service working directory (see Configuration).</para>
+
+ <para>When the chain starts the work and the initial BackupJob starts,
+ the job will create a result data file using the destination directory
+ path from BackupConfig. The destination directory will contain a
+ directory with an automatically created name using the pattern
+ repository_workspace-timestamp where timestamp is current time in the
+ format of yyyyMMdd_hhmmss (E.g. db1_ws1-20080306_055404). The directory
+ will contain the results of all Jobs configured for execution. Each Job
+ stores the backup result in its own file with the name
+ repository_workspace-timestamp.jobNumber. BackupChain saves each state
+ (STARTING, WAITING, WORKING, FINISHED) of its Jobs in the
+ BackupChainLog, which has a current result full file path.</para>
+
+ <para>BackupChain log file and job result files are a whole and
+ consistent unit, that is a source for a Restore.</para>
+
+ <note>
+ <para>BackupChain log contains absolute paths to job result files.
+ Don't move these files to another location.</para>
+ </note>
+
+ <para><emphasis role="bold">Restore requirements</emphasis></para>
+
+ <para>As mentioned before a Restore operation is a mirror of a Backup.
+ The process is a Full restore of a root node with restoring an
+ additional Incremental backup to reach a desired workspace state.
+ Restoring of the workspace Full backup will create a new workspace in
+ the repository using given RepositoyEntry of existing repository and
+ given (preconfigured) WorkspaceEntry for a new target workspace. A
+ Restore process will restore a root node there from the SysView XML
+ data.</para>
+
+ <note>
+ <para>The target workspace should not be in the repository. Otherwise
+ a BackupConfigurationException exception will be thrown.</para>
+ </note>
+
+ <para>For creation and manipulation with Workspaces check the article
+ <link linkend="TODO">Repository and Workspace management</link>.</para>
+
+ <para>Finally we may say that a Restore is a process of a new Workspace
+ creation and filling it with a Backup content. In case you already have
+ a target Workspace (with the same name) in a Repository, you have to
+ configure a new name for it. If no target workspace exists in the
+ Repository you may use the same name as the Backup one.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Configuration</title>
+
+ <para>As an optional extension, the Backup service is not enabled by
+ default. <emphasis role="bold">You need to enable it via
+ configuration</emphasis>.</para>
+
+ <para>Below is an example configuration compatible with JCR 1.9.3 and
+ later :</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 period = 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></programlisting>
+
+ <para>Where:<itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">incremental-backup-type</emphasis>
+ (since 1.9.3) : the FQN of incremental job class. Must implement
+ org.exoplatform.services.jcr.ext.backup.BackupJob</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">full-backup-type</emphasis> (since
+ 1.9.3) : the FQN of the full backup job class; Must implement
+ org.exoplatform.services.jcr.ext.backup.BackupJob</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis
+ role="bold">default-incremental-job-period</emphasis> (since 1.9.3)
+ :the period between incremetal flushes (in seconds)</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">backup-dir</emphasis> : the path to a
+ working directory where the service will store internal files and
+ chain logs.</para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+
+ <section>
+ <title>Usage</title>
+
+ <section>
+ <title>Perform a Backup</title>
+
+ <para>In following example we create a BackupConfig bean for the Full +
+ Incrementals mode, then we ask the BackupManager to start the backup
+ process.</para>
+
+ <programlisting>// Obtaining the backup service from the eXo container.
+BackupManager backup = (BackupManager) container.getComponentInstanceOfType(BackupManager.class);
+
+// And prepare the BackupConfig instance with custom parameters.
+// full backup & incremental
+File backDir = new File("/backup/ws1"); // the destination path for result files
+backDir.mkdirs();
+
+BackupConfig config = new BackupConfig();
+config.setRepository(repository.getName());
+config.setWorkspace("ws1");
+config.setBackupDir(backDir);
+
+// Before 1.9.3, you also need to indicate the backupjobs class FDNs
+// config.setFullBackupType("org.exoplatform.services.jcr.ext.backup.impl.fs.FullBackupJob");
+// config.setIncrementalBackupType("org.exoplatform.services.jcr.ext.backup.impl.fs.IncrementalBackupJob");
+
+// start backup using the service manager
+BackupChain chain = backup.startBackup(config);</programlisting>
+
+ <para>To stop the backup operation you have to use the BackupChain
+ instance.</para>
+
+ <programlisting>// stop backup
+backup.stopBackup(chain);</programlisting>
+ </section>
+
+ <section>
+ <title>Perform a Restore</title>
+
+ <para>Restoration involves the reloading the backup file into a
+ BackupChainLog and applying appropriate workspace initialization. The
+ following snippet shows the typical sequence for restoring a workspace
+ :</para>
+
+ <programlisting>// find BackupChain using the repository and workspace names (return null if not found)
+BackupChain chain = backup.findBackup("db1", "ws1");
+
+// Get the RepositoryEntry and WorkspaceEntry
+ManageableRepository repo = repositoryService.getRepository(repository);
+RepositoryEntry repoconf = repo.getConfiguration();
+List<WorkspaceEntry> entries = repoconf.getWorkspaceEntries();
+WorkspaceEntry = getNewEntry(entries, workspace); // create a copy entry from an existing one
+
+// restore backup log using ready RepositoryEntry and WorkspaceEntry
+File backLog = new File(chain.getLogFilePath());
+BackupChainLog bchLog = new BackupChainLog(backLog);
+
+// initialize the workspace
+repository.configWorkspace(workspaceEntry);
+
+// run restoration
+backup.restore(bchLog, repositoryEntry, workspaceEntry);</programlisting>
+
+ <section>
+ <title>Restoring into an existing workspace</title>
+
+ <note>
+ <para>These instructions only applies to regular workspace. Special
+ instructions are provided for System workspace below.</para>
+ </note>
+
+ <para>To restore a backup over an existing workspace, you are required
+ to clear its data. Your backup process should follow these steps :
+ <itemizedlist>
+ <listitem>
+ <para>remove workspace<programlisting>ManageableRepository repo = repositoryService.getRepository(repository);
+repo.removeWorkspace(workspace);</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>clean database, value storage, index</para>
+ </listitem>
+
+ <listitem>
+ <para>restore (see snippet above)</para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+
+ <section>
+ <title>System workspace</title>
+
+ <note>
+ <para>The BackupWorkspaceInitializer is available in JCR 1.9 and
+ later.</para>
+ </note>
+
+ <para>Restoring the JCR System workspace requires to shutdown the
+ system and use of a special initializer.</para>
+
+ <para>Follow these steps (this will also work for normal workspaces) :
+ <itemizedlist>
+ <listitem>
+ <para>Stop repository (or portal)</para>
+ </listitem>
+
+ <listitem>
+ <para>clean database, value storage, index; </para>
+ </listitem>
+
+ <listitem>
+ <para>In configuration the workspace set
+ BackupWorkspaceInitializer to reference your backup.</para>
+
+ <para>For example :<programlisting><workspaces>
+ <workspace name="production" ... >
+ <container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer">
+ ...
+ </container>
+ <initializer class="org.exoplatform.services.jcr.impl.core.BackupWorkspaceInitializer">
+ <properties>
+ <property name="restore-path" value="D:\java\exo-working\backup\repository_production-20090527_030434"/>
+ </properties>
+ </initializer>
+ ...
+</workspace></programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>Start repository (or portal).</para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+ </section>
+ </section>
+
+ <section>
+ <title>Scheduling (experimental)</title>
+
+ <para>The Backup service has an additional feature that can be useful for
+ a production level backup implementation. When you need to organize a
+ backup of a repository it's necessary to have a tool which will be able to
+ create and manage a cycle of Full and Incremental backups in periodic
+ manner.</para>
+
+ <para>The service has internal BackupScheduler which can run a
+ configurable cycle of BackupChains as if they have been executed by a user
+ during some period of time. I.e. BackupScheduler is a user-like daemon
+ which asks the BackupManager to start or stop backup operations.</para>
+
+ <para>For that purpose BackupScheduler has the method</para>
+
+ <para>BackupScheduler.schedule(backupConfig, startDate, stopDate,
+ chainPeriod, incrementalPeriod)</para>
+
+ <para>where</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>backupConfig - a ready configuration which will be given to the
+ BackupManager.startBackup() method</para>
+ </listitem>
+
+ <listitem>
+ <para>startDate - a date and time of the backup start</para>
+ </listitem>
+
+ <listitem>
+ <para>stopDate - a date and time of the backup stop</para>
+ </listitem>
+
+ <listitem>
+ <para>chainPeriod - a period after which a current BackupChain will be
+ stopped and a new one will be started, in seconds</para>
+ </listitem>
+
+ <listitem>
+ <para>incrementalPeriod - if it is greater than 0 it will be used to
+ override the same value in backupConfig.</para>
+ </listitem>
+ </itemizedlist>
+
+ <programlisting>// geting the scheduler from the BackupManager
+ BackupScheduler scheduler = backup.getScheduler();
+
+// schedule backup using a ready configuration (Full + Incrementals) to run from startTime
+// to stopTime. Full backuop will be performed every 24 hours (BackupChain lifecycle),
+// incremental will rotate result files every 3 hours.
+ scheduler.schedule(config, startTime, stopTime, 3600 * 24, 3600 * 3);
+
+// it's possible to run the scheduler for an uncertain period of time (i.e. without stop time).
+// schedule backup to run from startTime till it will be stopped manually
+// also there, the incremental will rotate result files as it configured in BackupConfig
+ scheduler.schedule(config, startTime, null, 3600 * 24, 0);
+
+// to unschedule backup simply call the scheduler with the configuration describing the
+// already planned backup cycle.
+// the scheduler will search in internal tasks list for task with repository and
+// workspace name from the configuration and will stop that task.
+ scheduler.unschedule(config);</programlisting>
+
+ <para>When the BackupScheduler starts the scheduling, it uses the internal
+ Timer with startDate for the first (or just once) execution. If
+ chainPeriod is greater than 0 then the task is repeated with this value
+ used as a period starting from startDate. Otherwise the task will be
+ executed once at startDate time. If the scheduler has stopDate it will
+ stop the task ( the chain cycle) after stopDate. And the last parameter
+ incrementalPeriod will be used instead of the same from BackupConfig if
+ its values are greater than 0.</para>
+
+ <para>Starting each task (BackupScheduler.schedule(...)), the scheduler
+ creates a task file in the service working directory (see <emphasis
+ role="bold">Configuration</emphasis>, backup-dir) which describes the task
+ backup configuration and periodic values. These files will be used at the
+ backup service start (JVM start) to reinitialize BackupScheduler for
+ continuous task scheduling. Only tasks that don't have a stopDate or a
+ stopDate not expired will be reinitialized.</para>
+
+ <para>There is one notice about BackupScheduler task reinitialization in
+ the current implementation. It comes from the BackupScheduler nature and
+ its implemented behaviour. As the scheduler is just a virtual user which
+ asks the BackupManager to start or stop backup operations, it isn't able
+ to reinitialize each existing BackupChain before the service (JVM) is
+ stopped. But it's possible to start a new operation with the same
+ configuration via BackupManager (that was configured before and stored in
+ a task file).</para>
+
+ <para>This is a main detail of the BackupScheduler which should be taken
+ into suggestion of a backup operation design now. In case of
+ reinitialization the task will have new time values for the backup
+ operation cycle as the chainPeriod and incrementalPeriod will be applied
+ again. That behaviour may be changed in the future.</para>
+ </section>
+</chapter>
Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/backup/search-index-backup.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/backup/search-index-backup.xml (rev 0)
+++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/backup/search-index-backup.xml 2010-08-03 09:43:46 UTC (rev 2859)
@@ -0,0 +1,84 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="JCR.SearchIndexBackup">
+ <?dbhtml filename="ch-search-index-backup.html"?>
+
+ <title>Search index backup</title>
+
+ <section>
+ <title>Manual backup (file copy)</title>
+
+ <para>It can be useful for some reason. The backup may be performed
+ manually or using third part software.</para>
+
+ <para>You can make a copy of the search index ($AS_HOME/temp/jcrlucenedb).
+ And use it to replace the current index by this copy in case of an index
+ damage or lost.</para>
+
+ <para>All repository changes that are applied between the index backup and
+ the point of time when the backup index is restored, are not in the index
+ and those modifications will not be found when searching. The
+ modifications exist in the repository, but do not exist in the search
+ index. <emphasis role="bold">And those changes will not be automatically
+ reindexed.</emphasis></para>
+
+ <para>For example: You have configured the workspace index to be in the
+ "/index/workspace" directory.<itemizedlist>
+ <listitem>
+ <para>make a backup of the search index - copy the content of the
+ "/index" directory;</para>
+ </listitem>
+
+ <listitem>
+ <para>add the node "/anynode" to the workspace. Now this node exists
+ in the workspace database and the search index has information about
+ this node, so you can find it using query <code>select * from
+ nt:base where jcr:path="/anynode"</code>;</para>
+ </listitem>
+
+ <listitem>
+ <para>rollback to the last backup - replace current
+ "/index/workspace" directory by the backup;</para>
+ </listitem>
+
+ <listitem>
+ <para>node "/anynode" still exists and is accessible in the
+ workspace (Session.getItem("/anynode")), but you can't find it via
+ the search query<code> select * from nt:base where
+ jcr:path="/anynode"</code>;</para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>If you want to find changes made after update you have to reindex
+ whole workspace content. One way to do this is to stop the repository
+ container and delete the "/index/workspace" folder. The workspace database
+ content will be reindexed on repository startup.</para>
+ </section>
+
+ <section>
+ <title>Consistency Requirements</title>
+
+ <para>To have the workspace content consistent with the search index, the
+ workspace database and the index directory should correspond to the same
+ state. In case of an external (manual) backup <emphasis>the database
+ backup and the index directory backup should be performed on a
+ stopped/unmodifiable repository</emphasis>.</para>
+
+ <para><emphasis role="bold">Only in that case the repository content and
+ the search index will be consistent.</emphasis></para>
+ </section>
+
+ <section>
+ <title>JCR Backup Service</title>
+
+ <para>To get a hot-backup, which is executed on the fly, it's possible to
+ use the <link linkend="JCR.BackupService">Backup service</link> which is
+ available as a JCR Extension.</para>
+
+ <note>
+ <para>Backup service supports full and incremental backup types. A
+ Scheduler is available.</para>
+ </note>
+ </section>
+</chapter>
Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/exo-jcr-configuration.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/exo-jcr-configuration.xml 2010-08-03 08:22:26 UTC (rev 2858)
+++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/exo-jcr-configuration.xml 2010-08-03 09:43:46 UTC (rev 2859)
@@ -38,7 +38,7 @@
</itemizedlist>
</section>
- <section>
+ <section id ="JCR.eXoJCRconfiguration.PortalAndStandaloneConfiguration">
<title>Portal and Standalone configuration</title>
<para>Like other eXo services eXo JCR can be configured and used in portal
Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr.xml 2010-08-03 08:22:26 UTC (rev 2858)
+++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr.xml 2010-08-03 09:43:46 UTC (rev 2859)
@@ -110,8 +110,10 @@
<!-- backup -->
<xi:include href="jcr/backup/exojcr-backup-service.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
- <!--xi:include href="jcr/backup/backup-client.xml"
- xmlns:xi="http://www.w3.org/2001/XInclude" /-->
+ <xi:include href="jcr/backup/backup-client.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="jcr/backup/search-index-backup.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
More information about the exo-jcr-commits
mailing list