You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by cz...@apache.org on 2015/05/05 14:42:03 UTC
svn commit: r1677803 -
/sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/provider/ResourceProvider.java
Author: cziegeler
Date: Tue May 5 12:42:02 2015
New Revision: 1677803
URL: http://svn.apache.org/r1677803
Log:
Update javadocs
Modified:
sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/provider/ResourceProvider.java
Modified: sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/provider/ResourceProvider.java
URL: http://svn.apache.org/viewvc/sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/provider/ResourceProvider.java?rev=1677803&r1=1677802&r2=1677803&view=diff
==============================================================================
--- sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/provider/ResourceProvider.java (original)
+++ sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/provider/ResourceProvider.java Tue May 5 12:42:02 2015
@@ -25,12 +25,14 @@ import java.util.Map;
import javax.annotation.CheckForNull;
import javax.annotation.Nonnull;
+import org.apache.sling.api.SlingException;
import org.apache.sling.api.resource.LoginException;
import org.apache.sling.api.resource.PersistenceException;
import org.apache.sling.api.resource.Resource;
import org.apache.sling.api.resource.ResourceResolver;
import org.apache.sling.api.resource.ResourceResolverFactory;
import org.apache.sling.api.resource.ResourceUtil;
+import org.apache.sling.api.resource.SyntheticResource;
import aQute.bnd.annotation.ConsumerType;
@@ -149,6 +151,8 @@ public abstract class ResourceProvider<T
* The provider is updated to reflect the latest state.
* Resources which have changes pending are not discarded.
* {@link #revert(ResolveContext)} can be called to discard changes.
+ *
+ * @param ctx The {@link ResolveContext} to which the returned {@link Resource} is attached.
*/
public void refresh(final @Nonnull ResolveContext<T> ctx) {
// nothing to do here
@@ -161,6 +165,7 @@ public abstract class ResourceProvider<T
* This method will never throw an exception
* even after the resource provider has been closed
*
+ * @param ctx The {@link ResolveContext} to which the returned {@link Resource} is attached.
* @return <code>true</code> if the resource provider has not been closed
* yet and is still active.. Once the resource provider has been closed
* or is not active anymore, this method returns <code>false</code>.
@@ -169,6 +174,23 @@ public abstract class ResourceProvider<T
return true;
}
+ /**
+ * Returns the parent resource from this resource provider or <code>null</code> if
+ * the resource provider cannot find it.
+ *
+ * The resource provider must not return cached instances for a resource as
+ * the resource resolver will update the resource metadata of the resource
+ * at the end of the resolution process and this metadata might be different
+ * depending on the full path of resource resolution passed into the
+ * resource resolver.
+ *
+ * @param ctx The {@link ResolveContext} to which the returned {@link Resource} is attached.
+ * @param child The child resource.
+ * @return <code>null</code> if this provider does not have a resource for
+ * the parent.
+ * @throws org.apache.sling.api.SlingException
+ * may be thrown in case of any problem creating the <code>Resource</code> instance.
+ */
public @CheckForNull Resource getParent(final @Nonnull ResolveContext<T> ctx,final @Nonnull Resource child) {
final String parentPath = ResourceUtil.getParent(child.getPath());
if (parentPath == null) {
@@ -177,14 +199,64 @@ public abstract class ResourceProvider<T
return this.getResource(ctx, parentPath);
}
+ /**
+ * Returns a resource from this resource provider or <code>null</code> if
+ * the resource provider cannot find it. The path must have the {@link #PROPERTY_ROOT}
+ * strings as its prefix.
+ *
+ * The resource provider must not return cached instances for a resource as
+ * the resource resolver will update the resource metadata of the resource
+ * at the end of the resolution process and this metadata might be different
+ * depending on the full path of resource resolution passed into the
+ * resource resolver.
+ *
+ * @param resourceResolver
+ * The {@link ResourceResolver} to which the returned {@link Resource} is attached.
+ * @param path The full path of the resource.
+ * @return <code>null</code> If this provider does not have a resource for
+ * the path.
+ * @throws org.apache.sling.api.SlingException
+ * may be thrown in case of any problem creating the <code>Resource</code> instance.
+ */
public abstract @CheckForNull Resource getResource(final @Nonnull ResolveContext<T> ctx, final @Nonnull String path);
+ /**
+ * Returns an <code>Iterator</code> of {@link Resource} objects loaded from
+ * the children of the given <code>Resource</code>. The returned {@link Resource} instances
+ * are attached to the same
+ * {@link ResourceResolver} as the given <code>parent</code> resource.
+ * <p>
+ * This method may be called for resource providers whose root path list contains a path such
+ * that the resource path is a
+ * prefix of the list entry. This allows for the enumeration of deeply nested provided resources
+ * for which no actual parent
+ * hierarchy exists.
+ * <p>
+ * The returned iterator may in turn contain resources which do not actually exist but are required
+ * to traverse the resource
+ * tree. Such resources SHOULD be {@link SyntheticResource} objects whose resource type MUST be set to
+ * {@link #RESOURCE_TYPE_SYNTHETIC}.
+ *
+ * As with {@link #getResource(ResourceResolver, String)} the returned Resource objects must
+ * not be cached objects.
+ *
+ * @param ctx The {@link ResolveContext} to which the returned {@link Resource} is attached.
+ * @param parent
+ * The {@link Resource Resource} whose children are requested.
+ * @return An <code>Iterator</code> of {@link Resource} objects or <code>null</code> if the resource
+ * provider has no children for the given resource.
+ * @throws NullPointerException
+ * If <code>parent</code> is <code>null</code>.
+ * @throws SlingException
+ * If any error occurs acquiring the child resource iterator.
+ */
public abstract @CheckForNull Iterator<Resource> listChildren(final @Nonnull ResolveContext<T> ctx, final @Nonnull Resource parent);
/**
* Returns a collection of attribute names whose value can be retrieved
* calling the {@link #getAttribute(ResourceResolver, String)} method.
*
+ * @param ctx The {@link ResolveContext} to which the returned {@link Resource} is attached.
* @return A collection of attribute names or <code>null</code>
* @throws IllegalStateException if this resource provider has already been
* closed.
@@ -198,6 +270,7 @@ public abstract class ResourceProvider<T
* if the attribute is not set or not visible (as e.g. security
* sensitive attributes).
*
+ * @param ctx The {@link ResolveContext} to which the returned {@link Resource} is attached.
* @param name
* The name of the attribute to access
* @return The value of the attribute or <code>null</code> if the attribute
@@ -217,7 +290,7 @@ public abstract class ResourceProvider<T
* A resource provider should value {@link ResourceResolver#PROPERTY_RESOURCE_TYPE}
* to set the resource type of a resource.
*
- * @param resolver The current resource resolver.
+ * @param ctx The {@link ResolveContext} to which the returned {@link Resource} is attached.
* @param path The resource path.
* @param properties Optional properties
* @return The new resource.
@@ -234,8 +307,8 @@ public abstract class ResourceProvider<T
* This change is kept in the transient space of this provider
* until {@link #commit(ResourceResolver)} is called.
*
- * @param resolver The current resource resolver.
- * @param path The resource path.
+ * @param ctx The {@link ResolveContext} to which the returned {@link Resource} is attached.
+ * @param resource The resource to delete.
*
* @throws PersistenceException If anything fails
*/
@@ -247,7 +320,7 @@ public abstract class ResourceProvider<T
/**
* Revert all transient changes: create, delete and updates.
*
- * @param resolver The current resource resolver.
+ * @param ctx The {@link ResolveContext} to which the returned {@link Resource} is attached.
*/
public void revert(final @Nonnull ResolveContext<T> ctx) {
// nothing to do here
@@ -256,7 +329,7 @@ public abstract class ResourceProvider<T
/**
* Commit all transient changes: create, delete and updates
*
- * @param resolver The current resource resolver.
+ * @param ctx The {@link ResolveContext} to which the returned {@link Resource} is attached.
*
* @throws PersistenceException If anything fails
*/
@@ -268,7 +341,7 @@ public abstract class ResourceProvider<T
/**
* Are there any transient changes?
*
- * @param resolver The current resource resolver.
+ * @param ctx The {@link ResolveContext} to which the returned {@link Resource} is attached.
*/
public boolean hasChanges(final @Nonnull ResolveContext<T> ctx) {
return false;
@@ -278,6 +351,12 @@ public abstract class ResourceProvider<T
return null;
}
+ /**
+ *
+ * @param ctx The {@link ResolveContext} to which the returned {@link Resource} is attached.
+ * @param type
+ * @return
+ */
public @CheckForNull <AdapterType> AdapterType adaptTo(final @Nonnull ResolveContext<T> ctx, final @Nonnull Class<AdapterType> type) {
return null;
}