incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cziege...@apache.org
Subject svn commit: r1365497 - in /sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource: ModifiableValueMap.java ModifyingResourceProvider.java PersistableValueMap.java PersistenceException.java ResourceResolver.java
Date Wed, 25 Jul 2012 09:14:07 GMT
Author: cziegeler
Date: Wed Jul 25 09:14:07 2012
New Revision: 1365497

URL: http://svn.apache.org/viewvc?rev=1365497&view=rev
Log:
SLING-2530 : Implement CRUD based on resources

Modified:
    sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ModifiableValueMap.java
    sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ModifyingResourceProvider.java
    sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/PersistableValueMap.java
    sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/PersistenceException.java
    sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java

Modified: sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ModifiableValueMap.java
URL: http://svn.apache.org/viewvc/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ModifiableValueMap.java?rev=1365497&r1=1365496&r2=1365497&view=diff
==============================================================================
--- sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ModifiableValueMap.java
(original)
+++ sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ModifiableValueMap.java
Wed Jul 25 09:14:07 2012
@@ -21,27 +21,31 @@ package org.apache.sling.api.resource;
 /**
  * The <code>ModifiableValueMap</code> is an extension
  * of the {@link ValueMap} which allows to modify and
- * persist the properties.
+ * persist properties. All changes to this map are transient
+ * and only available through this map instance.
  *
- * Changes can be pushed into the persistence layer
- * with a call to {@link #update()}. The changes are then
- * stored in the persistence layer for committing. Once
+ * Changes can be pushed into the transient persistence layer
+ * with a call to {@link #update()}. This causes the changes
+ * to be stored in the persistence layer for committing. Once
  * {@link ResourceResolver#commit()} is called, the
- * changes get persisted.
+ * changes are finally persisted.
  *
  * Note, that each time you call {@link Resource#adaptTo(Class)}
  * you get a new map instance which does not share modified
- * properties with other representations.
- *
- * TODO - we can convert this to a plain marker interface and
- * directly set the changes properties in the persistence layer!
+ * properties with other representations until {@link #update()}
+ * is called. In general, to avoid confusion, it's better to use
+ * one modifiable value map for a resource per resource resolver.
  *
  * @since 2.2
  */
 public interface ModifiableValueMap extends ValueMap {
 
     /**
-     * Persists the changes.
+     * Persists the changes in the transient persistence layer.
+     * Once update is called this map has no temporary changes
+     * any more.
+     * A call to {@link ResourceResolver#commit()} is required
+     * to permanently persist the changes.
      * @throws PersistenceException If the changes can't be persisted.
      */
     void update() throws PersistenceException;
@@ -52,7 +56,7 @@ public interface ModifiableValueMap exte
     void revert();
 
     /**
-     * Are there any changes?
+     * Are there any temporary changes?
      */
     boolean hasChanges();
 }

Modified: sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ModifyingResourceProvider.java
URL: http://svn.apache.org/viewvc/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ModifyingResourceProvider.java?rev=1365497&r1=1365496&r2=1365497&view=diff
==============================================================================
--- sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ModifyingResourceProvider.java
(original)
+++ sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ModifyingResourceProvider.java
Wed Jul 25 09:14:07 2012
@@ -18,17 +18,13 @@
  */
 package org.apache.sling.api.resource;
 
-
-
 /**
  * A modifying resource provider is an extension of a resource provider which
  * is only supported if the resource provider has been created through
  * a {@link ResourceProviderFactory}.
  *
  * A modifying resource provider allows to create, update, and delete
- * resources.
- *
- * TODO - Exception handling, return values
+ * resources. Update is handled through {@link ModifiableValueMap}.
  *
  * @see ResourceProviderFactory#getResourceProvider(java.util.Map)
  * @see ResourceProviderFactory#getAdministrativeResourceProvider(java.util.Map)
@@ -37,17 +33,49 @@ package org.apache.sling.api.resource;
  */
 public interface ModifyingResourceProvider {
 
+    /**
+     * Create a new resource at the given path.
+     * The new resource is put into the transient space of this provider
+     * until {@link #commit()} is called.
+     *
+     * @param resolver The current resource resolver.
+     * @param path The resource path.
+     * @param properties Optional properties
+     * @return The new resource.
+     *
+     * @throws PersistenceException If anything fails
+     */
     Resource create(ResourceResolver resolver, String path, ValueMap properties)
     throws PersistenceException;
 
+    /**
+     * Delete the resource at the given path.
+     * This change is kept in the transient space of this provider
+     * until {@link #commit()} is called.
+     *
+     * @param resolver The current resource resolver.
+     * @param path The resource path.
+     *
+     * @throws PersistenceException If anything fails
+     */
     void delete(ResourceResolver resolver, String path)
     throws PersistenceException;
 
-    void revert()
-    throws PersistenceException;
-
+    /**
+     * Revert all transient changes: create, delete and updates.
+     */
+    void revert();
+
+    /**
+     * Commit all transient changes: create, delete and updates
+     *
+     * @throws PersistenceException If anything fails
+     */
     void commit()
     throws PersistenceException;
 
+    /**
+     * Are there any transient changes?
+     */
     boolean hasChanges();
 }

Modified: sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/PersistableValueMap.java
URL: http://svn.apache.org/viewvc/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/PersistableValueMap.java?rev=1365497&r1=1365496&r2=1365497&view=diff
==============================================================================
--- sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/PersistableValueMap.java
(original)
+++ sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/PersistableValueMap.java
Wed Jul 25 09:14:07 2012
@@ -26,7 +26,10 @@ package org.apache.sling.api.resource;
  * Note, that each time you call {@link Resource#adaptTo(Class)}
  * you get a new map instance which does not share modified
  * properties with other representations.
+ *
+ * @deprecated Use the {@äink ModifiableValueMap} instead.
  */
+@Deprecated
 public interface PersistableValueMap extends ValueMap {
 
     /**

Modified: sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/PersistenceException.java
URL: http://svn.apache.org/viewvc/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/PersistenceException.java?rev=1365497&r1=1365496&r2=1365497&view=diff
==============================================================================
--- sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/PersistenceException.java
(original)
+++ sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/PersistenceException.java
Wed Jul 25 09:14:07 2012
@@ -21,23 +21,75 @@ package org.apache.sling.api.resource;
 import java.io.IOException;
 
 /**
- * This exception will be thrown during the try to persists
- * changes to a {@link PersistableValueMap}.
+ * This exception will be thrown during the try to persist
+ * changes to a {@link PersistableValueMap}, a
+ * {@link ModifiableValueMap#update()} or
+ * the {@link ResourceResolver}.
  */
 public class PersistenceException extends IOException {
 
-    private static final long serialVersionUID = -147631829162481787L;
+    private static final long serialVersionUID = 2454225989618227698L;
 
+    /** Optional resource path. */
+    private final String resourcePath;
+
+    /** Optional property name. */
+    private final String propertyName;
+
+    /**
+     * Create a new persistence exception.
+     */
     public PersistenceException() {
-        super();
+        this(null, null, null, null);
+    }
+
+    /**
+     * Create a new persistence exception.
+     * @param msg Exception message.
+     */
+    public PersistenceException(final String msg) {
+        this(msg, null, null, null);
+    }
+
+    /**
+     * Create a new persistence exception.
+     * @param msg Exception message.
+     * @param cause Exception cause.
+     */
+    public PersistenceException(final String msg, final Throwable cause) {
+        this(msg, cause, null, null);
+    }
+
+    /**
+     * Create a new persistence exception.
+     * @param msg Exception message.
+     * @param cause Exception cause.
+     */
+    public PersistenceException(final String msg,
+                    final Throwable cause,
+                    final String resourcePath,
+                    final String propertyName) {
+        super(msg);
+        initCause(cause);
+        this.resourcePath = resourcePath;
+        this.propertyName = propertyName;
     }
 
-    public PersistenceException(String s) {
-        super(s);
+    /**
+     * Get the resource path related to this exception.
+     * @return The resource path or <code>null</code>
+     * @since 2.2
+     */
+    public String getResourcePath() {
+        return this.resourcePath;
     }
 
-    public PersistenceException(String s, Throwable t) {
-        super(s);
-        initCause(t);
+    /**
+     * Get the property name related to this exception.
+     * @return The property name or <code>null</code>
+     * @since 2.2
+     */
+    public String getPropertyName() {
+        return this.propertyName;
     }
 }

Modified: sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
URL: http://svn.apache.org/viewvc/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java?rev=1365497&r1=1365496&r2=1365497&view=diff
==============================================================================
--- sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
(original)
+++ sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
Wed Jul 25 09:14:07 2012
@@ -31,6 +31,7 @@ import org.apache.sling.api.adapter.Adap
  * the request processing servlet through the
  * {@link org.apache.sling.api.SlingHttpServletRequest#getResourceResolver()}
  * method.
+ * A resource resolver can also be created through the {@link ResourceResolverFactory}.
  * <p>
  * The <code>ResourceResolver</code> is also an {@link Adaptable} to get
  * adapters to other types. A JCR based resource resolver might support adapting
@@ -78,7 +79,7 @@ import org.apache.sling.api.adapter.Adap
  * Resource Resolver using any of the factory methods and ends with calling the
  * {@link #close()} method. It is very important to call the {@link #close()}
  * method once the resource resolver is not used any more to ensure any system
- * resources are properly clean up.
+ * resources are properly cleaned up.
  * <p>
  * To check whether a Resource Resolver can still be used, the {@link #isLive()}
  * method can be called.
@@ -525,7 +526,7 @@ public interface ResourceResolver extend
     /**
      * Revert all pending changes.
      */
-    void revert() throws PersistenceException;
+    void revert();
 
     /**
      * Persist all pending changes.



Mime
View raw message