jackrabbit-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ang...@apache.org
Subject svn commit: r555335 - in /jackrabbit/trunk/contrib/spi/spi/src/main/java/org/apache/jackrabbit/spi: Batch.java RepositoryService.java
Date Wed, 11 Jul 2007 16:48:36 GMT
Author: angela
Date: Wed Jul 11 09:48:35 2007
New Revision: 555335

URL: http://svn.apache.org/viewvc?view=rev&rev=555335
Log:
javadoc (added extended interface description modified after an original draft created by
Peeter Piegaze)

Modified:
    jackrabbit/trunk/contrib/spi/spi/src/main/java/org/apache/jackrabbit/spi/Batch.java
    jackrabbit/trunk/contrib/spi/spi/src/main/java/org/apache/jackrabbit/spi/RepositoryService.java

Modified: jackrabbit/trunk/contrib/spi/spi/src/main/java/org/apache/jackrabbit/spi/Batch.java
URL: http://svn.apache.org/viewvc/jackrabbit/trunk/contrib/spi/spi/src/main/java/org/apache/jackrabbit/spi/Batch.java?view=diff&rev=555335&r1=555334&r2=555335
==============================================================================
--- jackrabbit/trunk/contrib/spi/spi/src/main/java/org/apache/jackrabbit/spi/Batch.java (original)
+++ jackrabbit/trunk/contrib/spi/spi/src/main/java/org/apache/jackrabbit/spi/Batch.java Wed
Jul 11 09:48:35 2007
@@ -29,13 +29,51 @@
 import javax.jcr.version.VersionException;
 
 /**
- * <code>Batch</code> defines a set of modifications that must be executed and
- * persisted at once. If any of the modifications added to the batch fails, none
- * of the other changes must be persisted, thus leaving the persistent layer
- * unaffected by the given batch. The <code>Batch</code> object is obtained by
calling
- * {@link RepositoryService#createBatch(ItemId, SessionInfo)}. The modifications
- * collected in a Batch are persisted upon a sucessful call to
- * {@link RepositoryService#submit(Batch)}.
+ * The <code>Batch</code> defines an ordered list of of operations that must
be
+ * executed at once on the persistent layer. If any of the modifications added
+ * to the batch fails, none of the other changes must be persisted, thus leaving
+ * the persistent layer unaffected.<p/>
+ *
+ * The <code>Batch</code> object is obtained by calling
+ * {@link RepositoryService#createBatch(ItemId, SessionInfo)}. The following
+ * methods can then be called on the returned <code>Batch</code> object to queue
+ * the corresponding operations:
+ * <ul>
+ * <li>addNode,</li>
+ * <li>addProperty,</li>
+ * <li>setValue,</li>
+ * <li>remove,</li>
+ * <li>reorderNodes,</li>
+ * <li>setMixins,</li>
+ * <li>move</li>
+ * </ul>
+ * The operations collected in a Batch are persisted upon a sucessful call to
+ * {@link RepositoryService#submit(Batch)}. The operations queued in the batch
+ * must be validated as a single unit and (if validation succeeds) applied to
+ * the persistent layer. If validation fails submitting the <code>Batch</code>
+ * is aborted and an exception is thrown.<p/>
+ *
+ * The Batch mechanism is required because there are sets of operations for
+ * which the following are both true:
+ * <ul>
+ * <li>The set can only be validated and put into effect as a single logical unit.<br>
+ * For example, adding mutually referring reference properties.</li>
+ * <li>The set contains operations that can only be validated on the persistent
+ * layer.<br>For example, operations that require a referential integrity check.</li>
+ * </ul>
+ * In addition the <code>Batch</code> mechanism is desirable in order to
+ * minimize calls to the persistent layer, which enables client-server
+ * implementations to reduce the number of network roundtrips.<p/>
+ *
+ * Since the batch records the “delta” of pending changes within the scope of
+ * an {@link javax.jcr.Item#save()} (or a {@link javax.jcr.Session#save()} it is
+ * intended to be constructed upon save (not before) and then submitted to the
+ * persistent layer as a single logical operation (see above).<p/>
+ *
+ * Note however, that methods of the JCR API that have immediate effect on the
+ * persistent storage have to call that storage, validate and return. The batch
+ * does not play a role in these operations, instead they are covered by the
+ * {@link RepositoryService}.
  */
 public interface Batch {
 

Modified: jackrabbit/trunk/contrib/spi/spi/src/main/java/org/apache/jackrabbit/spi/RepositoryService.java
URL: http://svn.apache.org/viewvc/jackrabbit/trunk/contrib/spi/spi/src/main/java/org/apache/jackrabbit/spi/RepositoryService.java?view=diff&rev=555335&r1=555334&r2=555335
==============================================================================
--- jackrabbit/trunk/contrib/spi/spi/src/main/java/org/apache/jackrabbit/spi/RepositoryService.java
(original)
+++ jackrabbit/trunk/contrib/spi/spi/src/main/java/org/apache/jackrabbit/spi/RepositoryService.java
Wed Jul 11 09:48:35 2007
@@ -46,7 +46,36 @@
 import java.io.InputStream;
 
 /**
- * <code>RepositoryService</code>...
+ * The <code>RepositoryService</code> interface defines methods used to
+ * retrieve information from the persistent layer of the repository as well
+ * as the methods that modify its persistent state.
+ * The implementation of this interface is intended to hold only the state of
+ * the persistent layer, no session-related state should be held. Consequently,
+ * each method that alters persistent state always includes all the information
+ * necessary to fully specify and authorize a change.<p/>
+ * For example, consider the method
+ * <pre>
+ *    void RepositoryService.copy(SessionInfo sessionInfo,
+ *                                String srcWorkspaceName,
+ *                                NodeId srcNodeId, NodeId destParentNodeId,
+ *                                QName destName)
+ * </pre>
+ * This method performs an immediate persistent copy of the node identified by
+ * srcNodeId and that node's subtree to a position as child of the node
+ * identified by destParentNodeId and assigns the newly copied node the name
+ * destName.<br>
+ * The <code>SessionInfo</code> object provides user and workspace identification
+ * as well as eventual lock tokens required to execute the copy.<br>
+ * If <code>srcWorkspaceName</code> differs from the workspace name present with
+ * the SessionInfo, the copy is corresponds to a copy across workspaces.
+ * The source and destination of the copy operation are specified by
+ * {@link NodeId}s. The <code>QName</code> holds the new name in fully qualified
+ * form. Taken together, this information is sufficient to completely specify
+ * and authorize the copy operations.<p/>
+ *
+ * The RepositoryService in addition allows to create and submit {@link Batch}
+ * objects, that cover lists of operations that have to be applied to the
+ * persistent layer at once.
  */
 public interface RepositoryService {
 
@@ -440,7 +469,7 @@
 
     /**
      * Create a lock on the <code>Node</code> identified by the given id.
-     * 
+     *
      * @param sessionInfo
      * @param nodeId
      * @param deep



Mime
View raw message