[exo-jcr-commits] exo-jcr SVN: r2878 - in jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr: backup and 2 other directories.

Author: sergiykarpenko Date: 2010-08-05 04:52:15 -0400 (Thu, 05 Aug 2010) New Revision: 2878 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/data-container-howto.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/acl-ext.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/acl.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/binary-values-processing.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/jcr-organization-service.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/link-producer.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/protocols/webdav.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/statistics.xml Log: EXOJCR-869: link fixes 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-05 06:58:25 UTC (rev 2877) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/backup/exojcr-backup-service.xml 2010-08-05 08:52:15 UTC (rev 2878) @@ -1,480 +1,477 @@ -<?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>&lt;component&gt; - &lt;key&gt;org.exoplatform.services.jcr.ext.backup.BackupManager&lt;/key&gt; - &lt;type&gt;org.exoplatform.services.jcr.ext.backup.impl.BackupManagerImpl&lt;/type&gt; - &lt;init-params&gt; - &lt;properties-param&gt; - &lt;name&gt;backup-properties&lt;/name&gt; - &lt;property name="default-incremental-job-period" value="3600" /&gt; &lt;!-- set default incremental period = 60 minutes --&gt; - &lt;property name="full-backup-type" value="org.exoplatform.services.jcr.ext.backup.impl.fs.FullBackupJob" /&gt; - &lt;property name="incremental-backup-type" value="org.exoplatform.services.jcr.ext.backup.impl.fs.IncrementalBackupJob" /&gt; - &lt;property name="backup-dir" value="target/backup" /&gt; - &lt;/properties-param&gt; - &lt;/init-params&gt; -&lt;/component&gt;</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 &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>// 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&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> - <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>&lt;workspaces&gt; - &lt;workspace name="production" ... &gt; - &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"&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></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>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>&lt;component&gt; + &lt;key&gt;org.exoplatform.services.jcr.ext.backup.BackupManager&lt;/key&gt; + &lt;type&gt;org.exoplatform.services.jcr.ext.backup.impl.BackupManagerImpl&lt;/type&gt; + &lt;init-params&gt; + &lt;properties-param&gt; + &lt;name&gt;backup-properties&lt;/name&gt; + &lt;property name="default-incremental-job-period" value="3600" /&gt; &lt;!-- set default incremental period = 60 minutes --&gt; + &lt;property name="full-backup-type" value="org.exoplatform.services.jcr.ext.backup.impl.fs.FullBackupJob" /&gt; + &lt;property name="incremental-backup-type" value="org.exoplatform.services.jcr.ext.backup.impl.fs.IncrementalBackupJob" /&gt; + &lt;property name="backup-dir" value="target/backup" /&gt; + &lt;/properties-param&gt; + &lt;/init-params&gt; +&lt;/component&gt;</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 &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>// 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&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> + <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>&lt;workspaces&gt; + &lt;workspace name="production" ... &gt; + &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"&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></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> Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/data-container-howto.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/data-container-howto.xml 2010-08-05 06:58:25 UTC (rev 2877) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/data-container-howto.xml 2010-08-05 08:52:15 UTC (rev 2878) @@ -1,112 +1,159 @@ -<?xml version='1.0' ?><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> - <chapter id="JCR.HowToImplementWorkspaceDataContainer"> - <title>How-to implement Workspace Data Container</title> - <?dbhtml filename="ch-data-container-howto.html"?> - <section id="ShortintrointoWorkspacedatacontainerimplementationpractices"> - <title>Short intro into Workspace data container implementation practices:</title> - <orderedlist> - <listitem> - <para>Read a bit about the <link linkend="JCRWorkspaceDataContainerarchitecturecontract">contract</link>.</para> - </listitem> - <listitem> - <para>Start new implementation project pom.xml with org.exoplatform.jcr parent. (optional, but will makes the development easy)</para> - </listitem> - <listitem> - <para>Update sources of JCR Core and read JavaDoc on - <emphasis role="bold">org.exoplatform.services.jcr.storage.WorkspaceDataContainer</emphasis> and - <emphasis role="bold">org.exoplatform.services.jcr.storage.WorkspaceStorageConnection</emphasis> interfaces. This two are main part for the implemenation. - </para> - </listitem> - <listitem> - <para>Look at - <emphasis role="bold">org.exoplatform.services.jcr.impl.dataflow.persistent.WorkspacePersistentDataManager</emphasis> sourcecode, check how data meneger uses container and its connections (see in save() method) - </para> - </listitem> - <listitem> - <para>Create - <emphasis role="bold">WorkspaceStorageConnection</emphasis> dummy implementation class. It's freeform class, but to be close to the eXo JCR, check how implemented JDBC or SimpleDB containers ( - <emphasis role="bold">org.exoplatform.services.jcr.impl.storage.jdbc.JDBCStorageConnection</emphasis> and - <emphasis role="bold">org.exoplatform.services.jcr.aws.storage.sdb.SDBWorkspaceStorageConnection</emphasis>). Take in account usage of - <emphasis role="bold">ValueStoragePluginProvider</emphasis> in both implementations.Value storage is an useful option for production versions. But leave it to the end of implementation work. - </para> - </listitem> - <listitem> - <para>Create the connection implementation unit tests to play TTD. (optional, but takes many benefits for the process)</para> - </listitem> - <listitem> - <para>Implement CRUD starting from the read to write etc. Test the methods using external to the implementation ways of data read/write in your backend.</para> - </listitem> - <listitem> - <para>When all methods of the connection done start - <emphasis role="bold">WorkspaceDataContainer</emphasis>. Container class very simple, it's like a factory for the connections only. - </para> - </listitem> - <listitem> - <para>Care about container reuseConnection(WorkspaceStorageConnection) method logic. For some backends it cab be same as openConnection(), but for some others it's important to reuse physical backend connection, e.g. to be in same transaction - see JDBC container.</para> - </listitem> - <listitem> - <para>It's almost ready for use in data manager. Start another test and go on.</para> - </listitem> - </orderedlist> - <para>When the container will be ready for run as JCR persistence storage (e.g. for this level testing) it should be configured in Repository configuration.</para> - <para>Assuming that our new implementation class name is - <emphasis role="bold">org.project.jcr.impl.storage.MyWorkspaceDataContainer</emphasis>. - </para> - <programlisting> &lt;repository-service default-repository="repository"> - &lt;repositories> - &lt;repository name="repository" system-workspace="production" default-workspace="production"> - ............. - &lt;workspaces> - &lt;workspace name="production"> - &lt;container class="org.project.jcr.impl.storage.MyWorkspaceDataContainer"> - &lt;properties> - &lt;property name="propertyName1" value="propertyValue1" /> - &lt;property name="propertyName2" value="propertyValue2" /> - ....... - &lt;property name="propertyNameN" value="propertyValueN" /> - &lt;/properties> - &lt;value-storages> - ....... - &lt;/value-storages> - &lt;/container> - -</programlisting> - <para>Container can be configured using set properties.</para> - </section> - <section id="Valuestorageusagenotes"> - <title>Value storage usage notes:</title> - <para>Value storages pluggable to the container but if it used the container implementation should respect set of interfaces and external storage usage principles.</para> - <para>If the container have - <emphasis role="bold">ValueStoragePluginProvider</emphasis> (e.g. via constructor) it's just few methods to manipulate external Values data. - </para> - <programlisting>// get channel for ValueData write (add or update) -ValueIOChannel channel = valueStorageProvider.getApplicableChannel(data, i); -if (channel == null) { - // write - channel.write(data.getIdentifier(), vd); - // obtain storage id, id can be used for linkage of external ValueData and PropertyData in main backend - String storageId = channel.getStorageId(); -} - -.... - -// delete all Property Values in external storage -ValueIOChannel channel = valueStorageProvider.getChannel(storageId); -channel.delete(propertyData.getIdentifier()); - -.... - -// read ValueData from external storage -ValueIOChannel channel = valueStorageProvider.getChannel(storageId); -ValueData vdata = channel.read(propertyData.getIdentifier(), orderNumber, maxBufferSize); - -</programlisting> - <important> - <title>Important</title> - <para>After a sequence of write and/or delete operations on the storage channel, the channel should be committed (or rolled back on an error). See - <emphasis role="bold">ValueIOChannel.commit()</emphasis> and - <emphasis role="bold">ValueIOChannel.rollback()</emphasis> and how those methods used in JDBC container. - </para> - </important> - </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.HowToImplementWorkspaceDataContainer"> + <title>How-to implement Workspace Data Container</title> + + <?dbhtml filename="ch-data-container-howto.html"?> + + <section id="ShortintrointoWorkspacedatacontainerimplementationpractices"> + <title>Short intro into Workspace data container implementation + practices:</title> + + <orderedlist> + <listitem> + <para>Read a bit about the <link + linkend="JCR.WorkspaceDataContainer">contract</link>.</para> + </listitem> + + <listitem> + <para>Start new implementation project pom.xml with + org.exoplatform.jcr parent. (optional, but will makes the development + easy)</para> + </listitem> + + <listitem> + <para>Update sources of JCR Core and read JavaDoc on <emphasis + role="bold">org.exoplatform.services.jcr.storage.WorkspaceDataContainer</emphasis> + and <emphasis + role="bold">org.exoplatform.services.jcr.storage.WorkspaceStorageConnection</emphasis> + interfaces. This two are main part for the implemenation.</para> + </listitem> + + <listitem> + <para>Look at <emphasis + role="bold">org.exoplatform.services.jcr.impl.dataflow.persistent.WorkspacePersistentDataManager</emphasis> + sourcecode, check how data meneger uses container and its connections + (see in save() method)</para> + </listitem> + + <listitem> + <para>Create <emphasis + role="bold">WorkspaceStorageConnection</emphasis> dummy implementation + class. It's freeform class, but to be close to the eXo JCR, check how + implemented JDBC or SimpleDB containers ( <emphasis + role="bold">org.exoplatform.services.jcr.impl.storage.jdbc.JDBCStorageConnection</emphasis> + and <emphasis + role="bold">org.exoplatform.services.jcr.aws.storage.sdb.SDBWorkspaceStorageConnection</emphasis>). + Take in account usage of <emphasis + role="bold">ValueStoragePluginProvider</emphasis> in both + implementations.Value storage is an useful option for production + versions. But leave it to the end of implementation work.</para> + </listitem> + + <listitem> + <para>Create the connection implementation unit tests to play TTD. + (optional, but takes many benefits for the process)</para> + </listitem> + + <listitem> + <para>Implement CRUD starting from the read to write etc. Test the + methods using external to the implementation ways of data read/write + in your backend.</para> + </listitem> + + <listitem> + <para>When all methods of the connection done start <emphasis + role="bold">WorkspaceDataContainer</emphasis>. Container class very + simple, it's like a factory for the connections only.</para> + </listitem> + + <listitem> + <para>Care about container reuseConnection(WorkspaceStorageConnection) + method logic. For some backends it cab be same as openConnection(), + but for some others it's important to reuse physical backend + connection, e.g. to be in same transaction - see JDBC + container.</para> + </listitem> + + <listitem> + <para>It's almost ready for use in data manager. Start another test + and go on.</para> + </listitem> + </orderedlist> + + <para>When the container will be ready for run as JCR persistence storage + (e.g. for this level testing) it should be configured in Repository + configuration.</para> + + <para>Assuming that our new implementation class name is <emphasis + role="bold">org.project.jcr.impl.storage.MyWorkspaceDataContainer</emphasis>.</para> + + <programlisting> &lt;repository-service default-repository="repository"&gt; + &lt;repositories&gt; + &lt;repository name="repository" system-workspace="production" default-workspace="production"&gt; + ............. + &lt;workspaces&gt; + &lt;workspace name="production"&gt; + &lt;container class="org.project.jcr.impl.storage.MyWorkspaceDataContainer"&gt; + &lt;properties&gt; + &lt;property name="propertyName1" value="propertyValue1" /&gt; + &lt;property name="propertyName2" value="propertyValue2" /&gt; + ....... + &lt;property name="propertyNameN" value="propertyValueN" /&gt; + &lt;/properties&gt; + &lt;value-storages&gt; + ....... + &lt;/value-storages&gt; + &lt;/container&gt; + +</programlisting> + + <para>Container can be configured using set properties.</para> + </section> + + <section id="Valuestorageusagenotes"> + <title>Value storage usage notes:</title> + + <para>Value storages pluggable to the container but if it used the + container implementation should respect set of interfaces and external + storage usage principles.</para> + + <para>If the container have <emphasis + role="bold">ValueStoragePluginProvider</emphasis> (e.g. via constructor) + it's just few methods to manipulate external Values data.</para> + + <programlisting>// get channel for ValueData write (add or update) +ValueIOChannel channel = valueStorageProvider.getApplicableChannel(data, i); +if (channel == null) { + // write + channel.write(data.getIdentifier(), vd); + // obtain storage id, id can be used for linkage of external ValueData and PropertyData in main backend + String storageId = channel.getStorageId(); +} + +.... + +// delete all Property Values in external storage +ValueIOChannel channel = valueStorageProvider.getChannel(storageId); +channel.delete(propertyData.getIdentifier()); + +.... + +// read ValueData from external storage +ValueIOChannel channel = valueStorageProvider.getChannel(storageId); +ValueData vdata = channel.read(propertyData.getIdentifier(), orderNumber, maxBufferSize); + +</programlisting> + + <important> + <title>Important</title> + + <para>After a sequence of write and/or delete operations on the storage + channel, the channel should be committed (or rolled back on an error). + See <emphasis role="bold">ValueIOChannel.commit()</emphasis> and + <emphasis role="bold">ValueIOChannel.rollback()</emphasis> and how those + methods used in JDBC container.</para> + </important> + </section> +</chapter> Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/acl-ext.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/acl-ext.xml 2010-08-05 06:58:25 UTC (rev 2877) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/acl-ext.xml 2010-08-05 08:52:15 UTC (rev 2878) @@ -3,31 +3,46 @@ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> <chapter id="JCR.AccessControlExtension"> <?dbhtml filename="ch-acl-ext.html"?> + <title>Access Control Extension</title> <section> <title>Prerequisites</title> <para>This is an extension of eXo JCR Access Control features. Please read - <ulink url="Access Control">Access Control</ulink> and <ulink - url="JCR Extensions">JCR Extensions</ulink> topics before.</para> + <link linkend="JCR.AccessControl">Access Control</link> and <link + linkend="JCR.Extensions">JCR Extensions</link> topics before.</para> </section> <section> <title>Overview</title> - <para>An extended Access Control system consists of: * Specifically - configured custom <emphasis role="bold">Extended Access Manager</emphasis> - which is called by eXo JCR internals to check if some user's Session - (user) has some privilege to perform some operation * The <emphasis - role="bold">Action</emphasis> which sets the thread local <emphasis - role="bold">Invocation Context</emphasis> at runtime. This invocation - context is used by the Extended Access Manager to make a decision about - the current Session's permission * <emphasis role="bold">Invocation - Context</emphasis> is a collection of properties which reflect the state - of a current Session. For the time being it contains: the type of the - current operation on Session (event), current Item (javax.jcr.Item) on - which this operation is performed and the current eXo Container</para> + <para>An extended Access Control system consists of:</para> + + <itemizedlist> + <listitem> + <para>Specifically configured custom <emphasis role="bold">Extended + Access Manager</emphasis> which is called by eXo JCR internals to + check if some user's Session (user) has some privilege to perform some + operation</para> + </listitem> + + <listitem> + <para>The <emphasis role="bold">Action</emphasis> which sets the + thread local <emphasis role="bold">Invocation Context</emphasis> at + runtime. This invocation context is used by the Extended Access + Manager to make a decision about the current Session's + permission</para> + </listitem> + + <listitem> + <para><emphasis role="bold">Invocation Context</emphasis> is a + collection of properties which reflect the state of a current Session. + For the time being it contains: the type of the current operation on + Session (event), current Item (javax.jcr.Item) on which this operation + is performed and the current eXo Container</para> + </listitem> + </itemizedlist> </section> <section> @@ -148,7 +163,6 @@ return false; } } -} -</programlisting> +}</programlisting> </section> </chapter> Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/acl.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/acl.xml 2010-08-05 06:58:25 UTC (rev 2877) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/acl.xml 2010-08-05 08:52:15 UTC (rev 2878) @@ -3,13 +3,14 @@ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> <chapter id="JCR.AccessControl"> <?dbhtml filename="ch-acl.html"?> + <title>Access Control</title> <para>eXo JCR is a complete implementation of the standard JSR 170: <ulink - url="Content Repository for Java TM Technology API &gt; http://jcp.org/en/jsr/detail?id=170">Content - Repository for Java TM Technology API</ulink>, including <emphasis - role="bold">Level 1, Level 2 and Additional Features</emphasis> as is - specified in the JCR Specification.</para> + url="http://jcp.org/en/jsr/detail?id=170">Content Repository for Java TM + Technology API</ulink>, including <emphasis role="bold">Level 1, Level 2 and + Additional Features</emphasis> as is specified in the JCR + Specification.</para> <section> <title>Standard Action Permissions</title> @@ -282,8 +283,8 @@ repository to auto-create <emphasis role="bold">exo:privilegeable</emphasis> or/and <emphasis role="bold">exo:owneable</emphasis> thanks to eXo's JCR interceptors - extension (see <ulink - url="http://wiki.exoplatform.org/xwiki/bin/view/JCR/JCR+Extensions&q... + extension (see <link linkend="JCR.Extensions">JCR + Extensions</link>)</para> <para><emphasis role="bold">OR-based Privilege Inheritance</emphasis> Note, that eXo's Access Control implementation supports an privilege @@ -304,10 +305,12 @@ <para>In the following example, you see a node named "Politics" which contains two nodes named "Cats" and "Dogs".</para> - <para>#info("These examples are exported from eXo DMS using the - \"document view\" representation of JCR. Each value of a multivalue - property is separated by a whitespace, each whitespace is escaped by - <emphasis>x0020</emphasis>.")</para> + <note> + <para>These examples are exported from eXo DMS using the \"document + view\" representation of JCR. Each value of a multivalue property is + separated by a whitespace, each whitespace is escaped by + <emphasis>x0020</emphasis>.</para> + </note> <programlisting>&lt;Politics jcr:primaryType="nt:unstructured" jcr:mixinTypes="exo:owneable exo:datetime exo:privilegeable" exo:dateCreated="2009-10-08T18:02:43.687+02:00" exo:dateModified="2009-10-08T18:02:43.703+02:00" @@ -374,7 +377,7 @@ <mediaobject> <imageobject> - <imagedata fileref="images/other.acl.gif" /> + <imagedata fileref="images/other/acl.gif" /> </imageobject> </mediaobject> </section> @@ -387,19 +390,69 @@ interface provides additional methods for Access Control management.</para> - <para>{table} Method signature |Description void - setPermissions(Map\&lt;String, String\ <ulink url="\">\</ulink>\&gt; - permissions)| Assigns a set of Permissions to a node void - setPermission(String identity, String\ <ulink url="\">\</ulink> - permission)| Assigns some Identity's Permission to a node void - removePermission(String identity)| Remove Identity's Permission void - removePermission(String identity, String permission)|Remove the - specified permission for a particular identity void clearACL()| Clears - the current ACL so it becomes default AccessControlList getACL()| - Returns the current ACL void checkPermission(String actions)| Checks - Permission (AccessDeniedException will be thrown if denied) - {table}</para> + <table> + <title>Additional methods</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Method signature</entry> + + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry>void setPermissions(Map&lt;String, String[]&gt; + permissions)</entry> + + <entry>Assigns a set of Permissions to a node</entry> + </row> + + <row> + <entry>void setPermission(String identity, String[] + permission)</entry> + + <entry>Assigns some Identity's Permission to a node</entry> + </row> + + <row> + <entry>void removePermission(String identity)</entry> + + <entry>Remove Identity's Permission</entry> + </row> + + <row> + <entry>void removePermission(String identity, String + permission)</entry> + + <entry>Remove the specified permission for a particular + identity</entry> + </row> + + <row> + <entry>void clearACL()</entry> + + <entry>Clears the current ACL so it becomes default</entry> + </row> + + <row> + <entry>AccessControlList getACL()</entry> + + <entry>Returns the current ACL</entry> + </row> + + <row> + <entry>void checkPermission(String actions)</entry> + + <entry>Checks Permission (AccessDeniedException will be thrown + if denied)</entry> + </row> + </tbody> + </tgroup> + </table> + <para>The "identity" parameter is the user or group name. The permissions are the literal strings of the standard action permissions (add_node, set_property, remove, read.</para> Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/binary-values-processing.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/binary-values-processing.xml 2010-08-05 06:58:25 UTC (rev 2877) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/binary-values-processing.xml 2010-08-05 08:52:15 UTC (rev 2878) @@ -3,6 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> <chapter id="JCR.BinaryValuesProcessing"> <?dbhtml filename="ch-binary-values-processing.html"?> + <title>Binary Values Processing</title> <section> @@ -28,17 +29,15 @@ <note> <para>eXo JCR Repository service configuration basics is discussed in - <ulink - url="Configuration&gt;http://wiki.exoplatform.com/xwiki/bin/view... + <link linkend="JCR.eXoJCRconfiguration">Configuration</link></para> <para>Database and workspace persistence storage configuration is - discussed in <ulink - url="http://wiki.exoplatform.com/xwiki/bin/view/JCR/JDBC+Data+Contai... - Data Container config</ulink></para> + discussed in <link linkend="JCR.JDBCDataContainerConfig">JDBC Data + Container config</link></para> - <para>Configuration details for <ulink - url="http://wiki.exoplatform.com/xwiki/bin/view/JCR/External+Value+S... - Value Storages</ulink>.</para> + <para>Configuration details for <link + linkend="JCR.ExternalValueStorages">External Value + Storages</link>.</para> </note> </section> Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/jcr-organization-service.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/jcr-organization-service.xml 2010-08-05 06:58:25 UTC (rev 2877) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/jcr-organization-service.xml 2010-08-05 08:52:15 UTC (rev 2878) @@ -3,6 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> <chapter id="JCR.Organizationservice"> <?dbhtml filename="ch-jcr-organization-service.html"?> + <title>JCR Organization service</title> <para>This is an implementation of the exo.core.component.organization.api @@ -59,7 +60,7 @@ storage will be created&lt;br&gt; storage-path - the relative path to the stored data&lt;br&gt;</para> - <para>You should also read how to use the <ulink - url="Core.Organization Service Initializer">Core.Organization Service - Initializer</ulink>.</para> + <para>You should also read how to use the <link + linkend="Core.OrganizationServiceInitializer">Organization Service + Initializer</link>.</para> </chapter> Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/link-producer.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/link-producer.xml 2010-08-05 06:58:25 UTC (rev 2877) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/link-producer.xml 2010-08-05 08:52:15 UTC (rev 2878) @@ -3,6 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> <chapter id="JCR.LinkProducerService"> <?dbhtml filename="ch-link-producer.html"?> + <title>Link Producer Service</title> <para>Link Producer Service - a simple service, which generates an .lnk @@ -19,17 +20,15 @@ &lt;/component&gt;</programlisting> <para>When using JCR the resource can be addressed by WebDav reference - (href) like <emphasis role="bold"> <ulink - url="http://host:port/rest/jcr/repository/workspace/somenode/somefile.extention">http://host:port/rest/jcr/repository/workspace/somenode/somefile.extention</ulink> - </emphasis>, the link servlet must be called for this resource by several - hrefs, like <emphasis role="bold"> <ulink - url="http://localhost:8080/rest/lnkproducer/openit.lnk?path=/repository/workspace/somenode/somefile.extention">http://localhost:8080/rest/lnkproducer/openit.lnk?path=/repository/workspace/somenode/somefile.extention</ulink> - </emphasis></para> + (href) like + <uri>http://host:port/rest/jcr/repository/workspace/somenode/somefile.extention</uri> + , the link servlet must be called for this resource by several hrefs, like + <uri>http://localhost:8080/rest/lnkproducer/openit.lnk?path=/repository/workspace/somenode/somefile.extention</uri> + </para> <para>Please note, that when using the portal mode the REST servlet is - available using a reference (href) like <emphasis role="bold"> <ulink - url="http://localhost:8080/portal/rest/">http://localhost:8080/portal/rest/</ulink>... - </emphasis></para> + available using a reference (href) like + <uri>http://localhost:8080/portal/rest/...</uri></para> <para>The name of the .lnk file can be any. But for the best compatibility it must be the same as the name of the JCR resource.</para> Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/protocols/webdav.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/protocols/webdav.xml 2010-08-05 06:58:25 UTC (rev 2877) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/protocols/webdav.xml 2010-08-05 08:52:15 UTC (rev 2878) @@ -3,13 +3,18 @@ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> <chapter id="JCR.WebDAV"> <?dbhtml filename="ch-webdav.html"?> + <title>WebDAV</title> <section> <title>Related documents</title> - <para>* Link Producer * Microsoft Office plugin * Open Office Add-On * - WebDav Client Libraries</para> + <itemizedlist> + <listitem> + <para><link linkend="JCR.LinkProducerService">Link + Producer</link></para> + </listitem> + </itemizedlist> </section> <section> @@ -39,22 +44,20 @@ <para>Standalone mode:</para> - <para><ulink - url="http://host:port/rest/jcr/">http://host:port/rest/jcr/</ulink>{RepositoryName}/{WorkspaceName}/{Path}</para> + <para><uri>http://host:port/rest/jcr/{RepositoryName}/{WorkspaceName}/{Path}</uri></para> <para>Portal mode:</para> - <para><ulink - url="http://host:port/portal/rest/private/jcr/">http://host:port/portal/rest/private/jcr/</ulink>{RepositoryName}/{WorkspaceName}/{Path}</para> + <para><uri>http://host:port/portal/rest/private/jcr/{RepositoryName}/{WorkspaceName}/{Path}</uri></para> - <para>When accessing the WebDAV server - here URL is <ulink - url="http://localhost:8080/rest/jcr/repository/production">http://localhost:8080/rest/jcr/repository/production</ulink>, - you might also use "collaboration" (instead of "production") which is the - default workspace in eXo products - the user will be asked to enter his - login and password. Those will then be checked using the organization - service (that can be implemented thanks to an Inmemory(dummy) module or DB - module or LDAP one) and the JCR user session will be created with the - correct JCR Credentials.</para> + <para>When accessing the WebDAV server - here URL is + <uri>http://localhost:8080/rest/jcr/repository/production</uri>, you might + also use "collaboration" (instead of "production") which is the default + workspace in eXo products - the user will be asked to enter his login and + password. Those will then be checked using the organization service (that + can be implemented thanks to an Inmemory(dummy) module or DB module or + LDAP one) and the JCR user session will be created with the correct JCR + Credentials.</para> <para><emphasis role="bold">NOTE:</emphasis> If you try the "in ECM" option, add "@ecm" to the user's password. Alternatively, you may modify Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/statistics.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/statistics.xml 2010-08-05 06:58:25 UTC (rev 2877) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/statistics.xml 2010-08-05 08:52:15 UTC (rev 2878) @@ -229,24 +229,24 @@ <para><emphasis>exo.jcr.component.statistics-X.Y.Z</emphasis>.jar corresponding to your eXo JCR version that you can get from the jboss maven repository <ulink - url="???"><uri>http://repository.jboss.com/maven2/org/... + url="http://repository.jboss.com/maven2/org/exoplatform/jcr/exo.jcr.... </listitem> <listitem> <para>aspectjrt-1.6.8.jar that you can get from the main maven repository <ulink - url="???"><uri>http://repo2.maven.org/maven2/org/aspec... + url="http://repo2.maven.org/maven2/org/aspectj/aspectjrt">&l... </listitem> </itemizedlist> <para>You will also need to get aspectjweaver-1.6.8.jar from the main maven repository <ulink - url="???">http://repo2.maven.org/maven2/org/aspectj/aspectjw...;. + url="http://repo2.maven.org/maven2/org/aspectj/aspectjweaver"&g...;. At this stage, to enable the statistics on the JCR API accesses, you will need to add the JVM parameter <emphasis>-javaagent:${pathto}/aspectjweaver-1.6.8.jar</emphasis> to your command line, for more details please refer to <ulink - url="???">http://www.eclipse.org/aspectj/doc/released/devgui... + url="http://www.eclipse.org/aspectj/doc/released/devguide/ltw-config... <para>By default, the configuration will collect statistcs on all the methods of the internal interfaces