SLING-6932 : [javadoc] Document transient nature of ResourceResolver operations
diff --git a/src/main/java/org/apache/sling/api/resource/ResourceResolver.java b/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
index 0e3cc65..36da95d 100644
--- a/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
+++ b/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
@@ -27,22 +27,23 @@
import javax.servlet.http.HttpServletRequest;
import org.apache.sling.api.adapter.Adaptable;
-
import org.osgi.annotation.versioning.ProviderType;
/**
- * The <code>ResourceResolver</code> defines the service API which may be used
- * to resolve {@link org.apache.sling.api.resource.Resource} objects. The resource resolver is available to
- * the request processing servlet through the
+ * The {@code ResourceResolver} defines the API which may be used
+ * to resolve {@link org.apache.sling.api.resource.Resource} objects and
+ * work with such resources like creating, editing or updating them.
+ * The resource resolver is available to 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}.
+ * method. A resource resolver can also be created through the
+ * {@link ResourceResolverFactory} service.
* <p>
- * The <code>ResourceResolver</code> is also an {@link Adaptable} to get
+ * The {@code ResourceResolver} is also an {@link Adaptable} to get
* adapters to other types. A JCR based resource resolver might support adapting
* to the JCR Session used by the resolver to access the JCR Repository.
* <p>
- * A <code>ResourceResolver</code> is generally not thread safe! As a
+ * A {@code ResourceResolver} is generally not thread safe! As a
* consequence, an application which uses the resolver, its returned resources
* and/or objects resulting from adapting either the resolver or a resource,
* must provide proper synchronization to ensure no more than one thread
@@ -78,6 +79,28 @@
* </tr>
* </table>
* <p>
+ * <b>Resource Handling</b>
+ * <p>
+ * A resource resolver provides various methods to manage resources. All changes
+ * are transient and require to commit them at the end.
+ * <ul>
+ * <li>{@link #create(Resource, String, Map)} for creating a new resource.
+ * <li>{@link #delete(Resource)} to delete a resource.
+ * <li>{@link #adaptTo(Class)} allows to adapt a resource to a {@link ModifiableValueMap}
+ * to update a resource.
+ * <li>{@link #move(String, String)} to move resources.
+ * <li>{@link #copy(String, String)} to copy resources.
+ * <li>{@link #commit()} commits all staged changes.
+ * <li>{@link #revert()} reverts all staged changes.
+ * </ul>
+ * <p>
+ * The resource tree accessible through the resource resolver is backed by one or
+ * more {@link org.apache.sling.spi.resource.provider.ResourceProvider}s. In
+ * general it is advisable to limit transient changes to a single resource provider.
+ * The {@link #commit()} is not using a two phase commit, therefore if there
+ * is more than one resource provider involved and one of them fails in persisting,
+ * changes already committed to other providers are not reverted.
+ * <p>
* <b>Lifecycle</b>
* <p>
* A Resource Resolver has a life cycle which begins with the creation of the
@@ -601,6 +624,8 @@
*
* Deleting a non existing resource leads to no operation nor exception.
*
+ * The changes are transient and require a call to {@link #commit()} for persisting.
+ *
* @param resource The resource to delete
*
* @throws NullPointerException if the resource parameter is null
@@ -616,6 +641,8 @@
/**
* Add a child resource to the given parent resource
+ * The changes are transient and require a call to {@link #commit()} for persisting.
+ *
* @param parent The parent resource
* @param name The name of the child resource - this is a plain name, not a path!
* @param properties Optional properties for the resource
@@ -698,9 +725,9 @@
/**
* Returns <code>true</code> if the resource type or any of the resource's
* super type(s) equals the given resource type.
- *
+ *
* In case the type of the given resource or the given resource type starts with one of the resource resolver's search paths
- * it is converted to a relative resource type by stripping off the resource resolver's search path
+ * it is converted to a relative resource type by stripping off the resource resolver's search path
* before doing the comparison.
*
* @param resource The resource to check
@@ -738,6 +765,8 @@
* a {@code PersistenceException} is thrown. If the resource at {@code srcAbsPath} does not exist,
* a {@code PersistenceException} is thrown.
*
+ * The changes are transient and require a call to {@link #commit()} for persisting.
+ *
* @param srcAbsPath the path of the resource to be copied.
* @param destAbsPath the location to which the resource at
* <code>srcAbsPath</code> is to be copied.
@@ -766,6 +795,8 @@
* a {@code PersistenceException} is thrown. If the resource at {@code srcAbsPath} does not exist,
* a {@code PersistenceException} is thrown.
*
+ * The changes are transient and require a call to {@link #commit()} for persisting.
+ *
* @param srcAbsPath the path of the resource to be copied.
* @param destAbsPath the location to which the resource at
* <code>srcAbsPath</code> is to be moved.
