<?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">
<section id="JCR.BackupService">
  <title>eXo JCR Backup Service</title>

  <note>
    <para>Restore of system workspace is not supported only as part of
    restoring of whole repository.</para>
  </note>

  <section id="JCR.BackupService.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 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 points 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. Run 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. Run until it is stopped.</para>
      </listitem>
    </itemizedlist>
  </section>

  <section id="JCR.BackupService.HowItWorks">
    <title>How it works</title>

    <section id="JCR.BackupService.HowItWorks.ImplementationDetails">
      <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>Restoring 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>

      <note>
        <para>Incremental backup is an experimental feture and not supported,
        so it must be used with a lot of caution.</para>
      </note>
    </section>

    <section id="JCR.BackupService.HowItWorks.WorkBasics">
      <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 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>Finally, we may say that 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
      Repositor, you may use the same name as the Backup one.</para>
    </section>
  </section>

  <section id="JCR.BackupService.Configuration">
    <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>The following is an example configuration :</para>

    <programlisting language="xml">&lt;component&gt;
  &lt;key&gt;org.exoplatform.services.jcr.ext.backup.BackupManager&lt;/key&gt;
  &lt;type&gt;org.exoplatform.services.jcr.ext.backup.impl.BackupManagerImpl&lt;/type&gt;
  &lt;init-params&gt;
    &lt;properties-param&gt;
      &lt;name&gt;backup-properties&lt;/name&gt;
      &lt;property name="backup-dir" value="target/backup" /&gt;
    &lt;/properties-param&gt;
  &lt;/init-params&gt;
&lt;/component&gt;</programlisting>

    <para>Where mandatory paramet is:<itemizedlist>
        <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>

    <para>Also, there are optional parameters:<itemizedlist>
        <listitem>
          <para><emphasis role="bold">incremental-backup-type</emphasis> : The
          FQN of incremental job class. Must implement
          org.exoplatform.services.jcr.ext.backup.BackupJob. By default :
          org.exoplatform.services.jcr.ext.backup.impl.fs.FullBackupJob
          used.</para>
        </listitem>

        <listitem>
          <para><emphasis
          role="bold">default-incremental-job-period</emphasis> : The period
          between incremetal flushes (in seconds). Default is 3600
          seconds.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">full-backup-type</emphasis> : The FQN of
          the full backup job class; Must implement
          org.exoplatform.services.jcr.ext.backup.BackupJob. By default :
          org.exoplatform.services.jcr.ext.backup.impl.rdbms.FullBackupJob
          used. Please, notice that file-system based implementation
          org.exoplatform.services.jcr.ext.backup.impl.fs.FullBackupJob is
          deprecated and not recommended for use.</para>
        </listitem>
      </itemizedlist></para>
      <note>
        <para>The number of rows that should be fetched from the database during backup operation,
         can be changed thanks to the System property exo.jcr.component.ext.FullBackupJob.fetch-size.
         The default value of this parameter is 1000.</para>
      </note>
  </section>

  <section id="JCR.BackupService.RDBMSBackup">
    <title>RDBMS backup</title>

    <para>RDBMS backup It is the lastest, currently supportedm used by default
    and recommended implementation of full backup job for BackupManager
    service. It is useful in case when database is used to store data.</para>

    <para>Brings such advantages:</para>

    <para><itemizedlist>
        <listitem>
          <para>fast: backup takes only several minutes to perform full backup
          of repository with 1 million rows in tables;</para>
        </listitem>

        <listitem>
          <para>atomic restore: restore process into existing
          workspace/repository with same configuration is atomic, it means you
          don’t loose the data when restore failed, the original data
          remains;</para>
        </listitem>

        <listitem>
          <para>cluster aware: it is possible to make backup/restore in
          cluster environment into existing workspace/repository with same
          configuration;</para>
        </listitem>

        <listitem>
          <para>consistence backup: all threads make waiting until backup is
          finished and then continue to work, so, there are no data
          modification during backup process;</para>
        </listitem>
      </itemizedlist></para>
  </section>

  <section id="JCR.BackupService.Usage">
    <title>Usage</title>

    <section id="JCR.BackupService.Usage.PerformingBackup">
      <title>Performing a Backup</title>

      <para>In the following example, we create a BackupConfig bean for the
      Full + Incrementals mode, then we ask the BackupManager to start the
      backup process.</para>

      <programlisting language="java">// 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 &amp; 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 language="java">// stop backup
backup.stopBackup(chain);</programlisting>
    </section>

    <section id="JCR.BackupService.Usage.PerformingRestore">
      <title>Performing a Restore</title>

      <para>Restoration involves 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 language="java">// 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&lt;WorkspaceEntry&gt; 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 id="JCR.BackupService.Usage.PerformingRestore.ExistingWorkspace">
        <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:</para>

        <itemizedlist>
          <listitem>
            <para>Remove workspace</para>
          </listitem>
        </itemizedlist>

        <programlisting language="java">ManageableRepository repo = repositoryService.getRepository(repository);
repo.removeWorkspace(workspace);</programlisting>

        <itemizedlist>
          <listitem>
            <para>Clean database, value storage, index</para>
          </listitem>

          <listitem>
            <para>Restore (see snippet above)</para>
          </listitem>
        </itemizedlist>
      </section>

      <section id="JCR.BackupService.Usage.PerformingRestore.SystemWorkspace">
        <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):</para>

        <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 refer to your backup.</para>
          </listitem>
        </itemizedlist>

        <para>For example:</para>

        <programlisting language="xml">&lt;workspaces&gt;
  &lt;workspace name="production" ... &gt;
    &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer"&gt;
      ...
    &lt;/container&gt;
    &lt;initializer class="org.exoplatform.services.jcr.impl.core.BackupWorkspaceInitializer"&gt;
      &lt;properties&gt;
         &lt;property name="restore-path" value="D:\java\exo-working\backup\repository_production-20090527_030434"/&gt;
      &lt;/properties&gt;
   &lt;/initializer&gt;
    ...
&lt;/workspace&gt;
</programlisting>

        <itemizedlist>
          <listitem>
            <para>Start repository (or portal).</para>
          </listitem>
        </itemizedlist>
      </section>
    </section>

    <section id="JCR.BackupService.Usage.RepositoryAndWorkspaceInitializationFromBackup">
      <title>Repository and Workspace initialization from backup</title>

      <para>Repository and Workspace initialization from backup can use the
      BackupWorkspaceInitializer.</para>

      <para>Will be configured BackupWorkspaceInitializer in configuration of
      workspace to restore the Workspace from backup over initializer.</para>

      <para>Will be configured BackupWorkspaceInitializer in all
      configurations workspaces of the Repository to restore the Repository
      from backup over initializer.</para>

      <para/>

      <para>Restoring the repository or workspace requires to shutdown the
      repository.</para>

      <para>Follow these steps: <itemizedlist>
          <listitem>
            <para>Stop repository (will be skipped this step if repository or
            workace is not exists)</para>
          </listitem>

          <listitem>
            <para>Clean database, value storage, index; (will be skipped this
            step if repository or worksace is new)</para>
          </listitem>

          <listitem>
            <para>In configuration, the workspace/-s set
            BackupWorkspaceInitializer to refer to your backup.</para>
          </listitem>

          <listitem>
            <para>Start repository</para>
          </listitem>
        </itemizedlist></para>

      <para/>

      <para>Example of configuration initializer to restore workspace "backup"
      over BackupWorkspaceInitializer:</para>

      <programlisting language="xml">&lt;workspaces&gt;
  &lt;workspace name="backup" ... &gt;
    &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer"&gt;
      ...
    &lt;/container&gt;
    &lt;initializer class="org.exoplatform.services.jcr.impl.core.BackupWorkspaceInitializer"&gt;
      &lt;properties&gt;
         &lt;property name="restore-path" value="D:\java\exo-working\backup\repository_backup-20110120_044734"/&gt;
      &lt;/properties&gt;
   &lt;/initializer&gt;
    ...
&lt;/workspace&gt;</programlisting>

      <section id="JCR.BackupService.Usage.RepositoryAndWorkspaceInitializationFromBackup.WorkspaceOverBackupWorksaceInitializer">
        <title>Restore the Workspace over BackupWorksaceInitializer</title>

        <para>Example of configuration initializer to resore the workspace
        "backup" over BackupWorkspaceInitializer:</para>

        <itemizedlist>
          <listitem>
            <para>Stop repository (will be skipped this step if workspace is
            not exists)</para>
          </listitem>

          <listitem>
            <para>Clean database, value storage, index; (will be skipped this
            step if workspace is new)</para>
          </listitem>
        </itemizedlist>

        <para>In configuration, the workspace/-s set
        BackupWorkspaceInitializer to refer to your backup.</para>

        <programlisting language="xml">&lt;workspaces&gt;
  &lt;workspace name="backup" ... &gt;
    &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer"&gt;
      ...
    &lt;/container&gt;
    &lt;initializer class="org.exoplatform.services.jcr.impl.core.BackupWorkspaceInitializer"&gt;
      &lt;properties&gt;
         &lt;property name="restore-path" value="D:\java\exo-working\backup\repository_backup-20110120_044734"/&gt;
      &lt;/properties&gt;
   &lt;/initializer&gt;
    ...
&lt;/workspace&gt;</programlisting>

        <itemizedlist>
          <listitem>
            <para>Start repository</para>
          </listitem>
        </itemizedlist>
      </section>

      <section id="JCR.BackupService.Usage.RepositoryAndWorkspaceInitializationFromBackup.RepositoryOverBackupWorksaceInitializer">
        <title>Restore the Repository over BackupWorksaceInitializer</title>

        <para>Example of configuration initializers to restore the repository
        "repository" over BackupWorkspaceInitializer:</para>

        <itemizedlist>
          <listitem>
            <para>Stop repository (will be skipped this step if repository is
            not exists)</para>
          </listitem>

          <listitem>
            <para>Clean database, value storage, index; (will be skipped this
            step if repository is new)</para>
          </listitem>
        </itemizedlist>

        <para>In configuration of repository will be configured initializers
        of workspace to refer to your backup.</para>

        <para>For example:</para>

        <programlisting language="xml">...
&lt;workspaces&gt;
 &lt;workspace name="system" ... &gt;
  &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer"&gt;
  ...
  &lt;/container&gt;
  &lt;initializer class="org.exoplatform.services.jcr.impl.core.BackupWorkspaceInitializer"&gt;
   &lt;properties&gt;
    &lt;property name="restore-path" value="D:\java\exo-working\backup\repository_system-20110120_052334"/&gt;
   &lt;/properties&gt;
  &lt;/initializer&gt;
  ...
 &lt;/workspace&gt;

 &lt;workspace name="collaboration" ... &gt;
   &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer"&gt;
   ...
  &lt;/container&gt;
  &lt;initializer class="org.exoplatform.services.jcr.impl.core.BackupWorkspaceInitializer"&gt;
   &lt;properties&gt;
    &lt;property name="restore-path" value="D:\java\exo-working\backup\repository_collaboration-20110120_052341"/&gt;
   &lt;/properties&gt;
  &lt;/initializer&gt;
  ...
 &lt;/workspace&gt;

 &lt;workspace name="backup" ... &gt;
  &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer"&gt;
  ...
  &lt;/container&gt;

  &lt;initializer class="org.exoplatform.services.jcr.impl.core.BackupWorkspaceInitializer"&gt;
   &lt;properties&gt;
    &lt;property name="restore-path" value="D:\java\exo-working\backup\repository_backup-20110120_052417"/&gt;
   &lt;/properties&gt;
  &lt;/initializer&gt;
  ...
  &lt;/workspace&gt;
&lt;/workspaces&gt;
</programlisting>

        <itemizedlist>
          <listitem>
            <para>Start repository.</para>
          </listitem>
        </itemizedlist>
      </section>
    </section>
  </section>

  <section id="JCR.BackupService.RestoreExistingWorkspaceOrReposistory">
    <title>Restore existing workspace or repository</title>

    <para>The resore of existing workspace or repositry is available.</para>

    <para>For restore will be used spacial methods:</para>

    <programlisting language="java"> /**
    * Restore existing workspace. Previous data will be deleted.
    * For getting status of workspace restore can use 
    * BackupManager.getLastRestore(String repositoryName, String workspaceName) method 
    * 
    * @param workspaceBackupIdentifier
    *          backup identifier
    * @param workspaceEntry
    *          new workspace configuration
    * @param asynchronous
    *          if 'true' restore will be in asynchronous mode (i.e. in separated thread)
    * @throws BackupOperationException
    *           if backup operation exception occurred 
    * @throws BackupConfigurationException
    *           if configuration exception occurred
    */
   void restoreExistingWorkspace(String workspaceBackupIdentifier, String repositoryName, WorkspaceEntry workspaceEntry,
      boolean asynchronous) throws BackupOperationException, BackupConfigurationException;

   /**
    * Restore existing workspace. Previous data will be deleted.
    * For getting status of workspace restore use can use 
    * BackupManager.getLastRestore(String repositoryName, String workspaceName) method 
    * 
    * @param log
    *          workspace backup log
    * @param workspaceEntry
    *          new workspace configuration
    * @param asynchronous
    *          if 'true' restore will be in asynchronous mode (i.e. in separated thread)
    * @throws BackupOperationException
    *           if backup operation exception occurred 
    * @throws BackupConfigurationException
    *           if configuration exception occurred
    */
   void restoreExistingWorkspace(BackupChainLog log, String repositoryName, WorkspaceEntry workspaceEntry, boolean asynchronous)  throws BackupOperationException, BackupConfigurationException;

   /**
    * Restore existing repository. Previous data will be deleted.
    * For getting status of repository restore can use 
    * BackupManager.getLastRestore(String repositoryName) method 
    * 
    * @param repositoryBackupIdentifier
    *          backup identifier
    * @param repositoryEntry
    *          new repository configuration
    * @param asynchronous
    *          if 'true' restore will be in asynchronous mode (i.e. in separated thread)
    * @throws BackupOperationException
    *           if backup operation exception occurred 
    * @throws BackupConfigurationException
    *           if configuration exception occurred
    */
   void restoreExistingRepository(String  repositoryBackupIdentifier, RepositoryEntry repositoryEntry, boolean asynchronous)  throws BackupOperationException, BackupConfigurationException;

   /**
    * Restore existing repository. Previous data will be deleted.
    * For getting status of repository restore can use 
    * BackupManager.getLastRestore(String repositoryName) method 
    * 
    * @param log
    *          repository backup log
    * @param repositoryEntry
    *          new repository configuration
    * @param asynchronous
    *          if 'true' restore will be in asynchronous mode (i.e. in separated thread)
    * @throws BackupOperationException
    *           if backup operation exception occurred 
    * @throws BackupConfigurationException
    *           if configuration exception occurred
    */
   void restoreExistingRepository(RepositoryBackupChainLog log, RepositoryEntry repositoryEntry, boolean asynchronous)
      throws BackupOperationException, BackupConfigurationException;</programlisting>

    <para>These methods for restore will do:</para>

    <itemizedlist>
      <listitem>
        <para>remove existed workspace or repository;</para>
      </listitem>

      <listitem>
        <para>clean database;</para>
      </listitem>

      <listitem>
        <para>clean index data;</para>
      </listitem>

      <listitem>
        <para>clean value storage;</para>
      </listitem>

      <listitem>
        <para>restore from backup.</para>
      </listitem>
    </itemizedlist>
  </section>

  <section id="JCR.BackupService.RestoreWorkspaceOrRepositoryUsingOriginalConfiguration">
    <title>Restore a workspace or a repository using original
    configuration</title>

    <para>The Backup manager allows you to restore a repository or a workspace
    using the original configuration stored into the backup log:</para>

    <programlisting language="java">/**
    * Restore existing workspace. Previous data will be deleted.
    * For getting status of workspace restore can use 
    * BackupManager.getLastRestore(String repositoryName, String workspaceName) method
    * WorkspaceEntry for restore should be contains in BackupChainLog. 
    * 
    * @param workspaceBackupIdentifier
    *          identifier to workspace backup. 
    * @param asynchronous
    *          if 'true' restore will be in asynchronous mode (i.e. in separated thread) 
    * @throws BackupOperationException
    *           if backup operation exception occurred 
    * @throws BackupConfigurationException
    *           if configuration exception occurred 
    */
   void restoreExistingWorkspace(String workspaceBackupIdentifier, boolean asynchronous)
            throws BackupOperationException,
            BackupConfigurationException;

   /**
    * Restore existing repository. Previous data will be deleted.
    * For getting status of repository restore can use 
    * BackupManager.getLastRestore(String repositoryName) method.
    * ReprositoryEntry for restore should be contains in BackupChainLog. 
    * 
    * @param repositoryBackupIdentifier
    *          identifier to repository backup.   
    * @param asynchronous
    *          if 'true' restore will be in asynchronous mode (i.e. in separated thread)
    * @throws BackupOperationException
    *           if backup operation exception occurred 
    * @throws BackupConfigurationException
    *           if configuration exception occurred
    */
   void restoreExistingRepository(String repositoryBackupIdentifier, boolean asynchronous)
            throws BackupOperationException,
            BackupConfigurationException;

   /**
    * WorkspaceEntry for restore should be contains in BackupChainLog. 
    * 
    * @param workspaceBackupIdentifier
    *          identifier to workspace backup. 
    * @param asynchronous
    *          if 'true' restore will be in asynchronous mode (i.e. in separated thread) 
    * @throws BackupOperationException
    *           if backup operation exception occurred 
    * @throws BackupConfigurationException
    *           if configuration exception occurred 
    */
   void restoreWorkspace(String workspaceBackupIdentifier, boolean asynchronous) throws BackupOperationException,
            BackupConfigurationException;

   /**
    * ReprositoryEntry for restore should be contains in BackupChainLog. 
    * 
    * @param repositoryBackupIdentifier
    *          identifier to repository backup.   
    * @param asynchronous
    *          if 'true' restore will be in asynchronous mode (i.e. in separated thread)
    * @throws BackupOperationException
    *           if backup operation exception occurred 
    * @throws BackupConfigurationException
    *           if configuration exception occurred
    */
   void restoreRepository(String repositoryBackupIdentifier, boolean asynchronous) throws BackupOperationException,
            BackupConfigurationException;

    /**
    * Restore existing workspace. Previous data will be deleted.
    * For getting status of workspace restore can use 
    * BackupManager.getLastRestore(String repositoryName, String workspaceName) method
    * WorkspaceEntry for restore should be contains in BackupChainLog. 
    * 
    * @param workspaceBackupSetDir
    *          the directory with backup set  
    * @param asynchronous
    *          if 'true' restore will be in asynchronous mode (i.e. in separated thread) 
    * @throws BackupOperationException
    *           if backup operation exception occurred 
    * @throws BackupConfigurationException
    *           if configuration exception occurred 
    */
   void restoreExistingWorkspace(File workspaceBackupSetDir, boolean asynchronous)
            throws BackupOperationException, BackupConfigurationException;

   /**
    * Restore existing repository. Previous data will be deleted.
    * For getting status of repository restore can use 
    * BackupManager.getLastRestore(String repositoryName) method.
    * ReprositoryEntry for restore should be contains in BackupChainLog. 
    * 
    * @param repositoryBackupSetDir
    *          the directory with backup set     
    * @param asynchronous
    *          if 'true' restore will be in asynchronous mode (i.e. in separated thread)
    * @throws BackupOperationException
    *           if backup operation exception occurred 
    * @throws BackupConfigurationException
    *           if configuration exception occurred
    */
   void restoreExistingRepository(File repositoryBackupSetDir, boolean asynchronous)
            throws BackupOperationException, BackupConfigurationException;

   /**
    * WorkspaceEntry for restore should be contains in BackupChainLog. 
    * 
    * @param workspaceBackupSetDir
    *          the directory with backup set 
    * @param asynchronous
    *          if 'true' restore will be in asynchronous mode (i.e. in separated thread) 
    * @throws BackupOperationException
    *           if backup operation exception occurred 
    * @throws BackupConfigurationException
    *           if configuration exception occurred 
    */
   void restoreWorkspace(File workspaceBackupSetDir, boolean asynchronous) throws BackupOperationException,
            BackupConfigurationException;

   /**
    * ReprositoryEntry for restore should be contains in BackupChainLog. 
    * 
    * @param repositoryBackupSetDir
    *          the directory with backup set   
    * @param asynchronous
    *          if 'true' restore will be in asynchronous mode (i.e. in separated thread)
    * @throws BackupOperationException
    *           if backup operation exception occurred 
    * @throws BackupConfigurationException
    *           if configuration exception occurred
    */
   void restoreRepository(File repositoryBackupSetDir, boolean asynchronous) throws BackupOperationException,
            BackupConfigurationException;</programlisting>
  </section>

  <section id="JCR.BackupService.BackupSetPortability">
    <title>Backup set portability</title>

    <para>The Backup log is stored during the Backup operation into two
    different locations: backup-dir directory of BackupService to support
    interactive operations via Backup API (e.g. console) and backup set files
    for portability (e.g. on another server).</para>
  </section>

  <section>
    <title>DB type migration</title>

    <para>You can use backup/restore mechanism to migrate between different DB
    types configuration. Currently three DB types supported (single, multi,
    isolated) and you can migrate between each of them.</para>

    <para>To accomplish migration you simply need to set desired DB type in
    the repository configuration file of backup set. It is highly recommended
    to make backup at the DB level before starting the migration process.
    <note>
        <para>After migration process, due to different DB structures, there
        can remain some unnecessary DB tables, which can be removed
        safetly.</para>
      </note></para>
      <para>Before starting migrating the data of your JCR from single/multi data format to isolated data format, you need to have the backupconsole.</para>
      <para>See the <link
              linkend="JCR.BackupClient.BackupClientUsage.BuildingApplication">Building application</link> section for more details.</para>
      <para>Or you can download it from <ulink url="http://forge.ow2.org/project/showfiles.php?group_id=151">ow2</ulink> directly.</para>
      <section>
          <title>Migrate JCR from single data format to isolated data format</title>
          <itemizedlist>
              <listitem>
                  <para>Enable the Backup service</para>
              </listitem>
          </itemizedlist>
          <para>See the <link
                  linkend="JCR.BackupClient.HTTPBackupAgent.HTTPBackupAgentConfiguration"> Configuration Backup service</link> section for details.</para>
          <itemizedlist>
              <listitem>
                  <para>Create a full backup</para>
              </listitem>
          </itemizedlist>
          <para>For example:</para>
          <programlisting>
              jcrbackup.cmd http://root:exo@localhost:8080/rest start /repository
          </programlisting>
          <para>Return</para>
          <programlisting>
              Successful :
              status code = 200
          </programlisting>
          <itemizedlist>
              <listitem>
                  <para>Get the backup id</para>
              </listitem>
          </itemizedlist>
          <para>You need get the backup id used in restore action.</para>
          <para>For example:</para>
          <programlisting>
              jcrbackup http://root:exo@localhost:8080 list completed
          </programlisting>
          <para>Return</para>
          <programlisting>
              The completed (ready to restore) backups information :
              1) Repository backup with id 5dcbc851c0a801c9545eb434947dbe87 :
              repository name           : repository
              backup type               : full only
              started time              : lun., 21 janv. 2013 16:48:21 GMT+01:00
              finished time             : lun., 21 janv. 2013 16:48:25 GMT+01:00
          </programlisting>
          <para>The backup id: 5dcbc851c0a801c9545eb434947dbe87</para>
          <para>See the <link
                  linkend="JCR.BackupClient.BackupClientUsage"> Backup Client Usage</link> section for more details.</para>
          <itemizedlist>
              <listitem>
                  <para>Set desired DB type in the repository configuration file of backup</para>
              </listitem>
          </itemizedlist>
          <para>Change  db-structure-type to isolated.</para>
          <para>For example:
              In original-repository-config :</para>
          <programlisting>
              exo-tomcat\temp\backup\repository_repository_backup_1358783301705\original-repository-config
          </programlisting>
          <para>replace</para>
          <programlisting>
              &lt;property name="db-structure-type" value="single"/&gt;
          </programlisting>
          <para>by</para>
          <programlisting>
              &lt;property name="db-structure-type" value="isolated"/&gt;
          </programlisting>
          <para>This change must be done for all workspaces.</para>
          <itemizedlist>
              <listitem>
                  <para>Activate the persister config</para>
              </listitem>
          </itemizedlist>
          <para>Before starting the restore operation, ensure that the persister is configured to save the changes of the repository configuration.</para>

          <para>If it's not activated, it should be configured, See the<link
                  linkend="JCR.ConfigurationPersister.Usage"> JCR Configuration persister</link> section for more details.</para>
          <itemizedlist>
              <listitem>
                  <para>Restore repository with original configuation and remove exists</para>
              </listitem>
          </itemizedlist>
          <para>For example:</para>
          <programlisting>
              jcrbackup.cmd http://root:exo@localhost:8080/rest restore remove-exists 5dcbc851c0a801c9545eb434947dbe87
          </programlisting>
          <para>Return</para>
          <programlisting>
              Successful :
              status code = 200
          </programlisting>
          <itemizedlist>
              <listitem>
                  <para>Drop the old tables with the old data format</para>
              </listitem>
          </itemizedlist>
          <programlisting>
              drop table JCR_SREF;
              drop table JCR_SVALUE;
              drop table JCR_SITEM;
          </programlisting>
      </section>
      <section>
          <title>Migrate JCR from multi data format to isolated data format</title>
          <itemizedlist>
              <listitem>
                  <para>Enable the Backup service</para>
              </listitem>
          </itemizedlist>
          <para>See the <link
                  linkend="JCR.BackupClient.HTTPBackupAgent.HTTPBackupAgentConfiguration"> Configuration Backup service</link> section for details.</para>
          <itemizedlist>
              <listitem>
                  <para>Create a full backup</para>
              </listitem>
          </itemizedlist>
          <para>For example:</para>
          <programlisting>
              jcrbackup.cmd http://root:exo@localhost:8080/rest start /repository
          </programlisting>
          <para>Return</para>
          <programlisting>
              Successful :
              status code = 200
          </programlisting>
          <itemizedlist>
              <listitem>
                  <para>Get the backup id</para>
              </listitem>
          </itemizedlist>
          <para>You need get the backup id to launch the restore action.</para>
          <para>For example:</para>
          <programlisting>
              jcrbackup http://root:exo@localhost:8080 list completed
          </programlisting>
          <para>Return</para>
          <programlisting>
              The completed (ready to restore) backups information :
              1) Repository backup with id 5dcbc851c0a801c9545eb434947dbe87 :
              repository name           : repository
              backup type               : full only
              started time              : lun., 21 janv. 2013 16:48:21 GMT+01:00
              finished time             : lun., 21 janv. 2013 16:48:25 GMT+01:00
          </programlisting>
          <para>The backup id: 5dcbc851c0a801c9545eb434947dbe87</para>
          <para>See the <link
                  linkend="JCR.BackupClient.BackupClientUsage"> Backup Client Usage</link> section for more details.</para>
          <itemizedlist>
              <listitem>
                  <para>Set desired DB type in the repository configuration file of backup</para>
              </listitem>
          </itemizedlist>
          <para>Change  db-structure-type to isolated.</para>
          <para>For example:
              In original-repository-config :</para>
          <programlisting>
              exo-tomcat\temp\backup\repository_repository_backup_1358783301705\original-repository-config
          </programlisting>
          <para>replace</para>
          <programlisting>
              &lt;property name="db-structure-type" value="multi"/&gt;
          </programlisting>
          <para>by</para>
          <programlisting>
              &lt;property name="db-structure-type" value="isolated"/&gt;
          </programlisting>
          <para>This change must be done for all workspaces.</para>
          <itemizedlist>
              <listitem>
                  <para>Configure the datasource name used for the isolated mode</para>
              </listitem>
          </itemizedlist>
          <para>Make sure that in your repository configuration all the workspaces of a same repository share the same datasource.</para>
          <itemizedlist>
              <listitem>
                  <para>Activate the persister config</para>
              </listitem>
          </itemizedlist>
          <para>Before starting the restore operation, ensure that the persister is configured to save the changes of the repository configuration.</para>

          <para>If it's not activated, it should be configured, See the<link
                  linkend="JCR.ConfigurationPersister.Usage"> JCR Configuration persister</link> section for more details.</para>
          <itemizedlist>
              <listitem>
                  <para>Restore repository with original configuation and remove exists</para>
              </listitem>
          </itemizedlist>
          <para>For example:</para>
          <programlisting>
              jcrbackup.cmd http://root:exo@localhost:8080/rest restore remove-exists 5dcbc851c0a801c9545eb434947dbe87
          </programlisting>
          <para>Return</para>
          <programlisting>
              Successful :
              status code = 200
          </programlisting>
          <itemizedlist>
              <listitem>
                  <para>Drop the old tables with the old data format</para>
              </listitem>
          </itemizedlist>
          <programlisting>
              drop table JCR_MREF;
              drop table JCR_MVALUE;
              drop table JCR_MITEM;
          </programlisting>
      </section>
  </section>
</section>
