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:28:38 UTC
svn commit: r1677799 - in
/sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/provider:
AbstractResourceProvider.java ResourceProvider.java
Author: cziegeler
Date: Tue May 5 12:28:38 2015
New Revision: 1677799
URL: http://svn.apache.org/r1677799
Log:
Make interface an abstract class
Removed:
sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/provider/AbstractResourceProvider.java
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=1677799&r1=1677798&r2=1677799&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:28:38 2015
@@ -28,36 +28,42 @@ import javax.annotation.Nonnull;
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.ResourceProviderFactory;
import org.apache.sling.api.resource.ResourceResolver;
import org.apache.sling.api.resource.ResourceResolverFactory;
+import org.apache.sling.api.resource.ResourceUtil;
import aQute.bnd.annotation.ConsumerType;
/**
* API for providers of resources. Used by the {@link ResourceResolver} to
* transparently access resources from different locations such as a JCR
- * repository (the default) or OSGi bundles.
+ * repository, a database, or bundle resources.
* <p>
- * This interface is intended to be implemented by providers of resource
+ * This extension point is defined by an abstract class (in contrast to
+ * an interface) as this will allow to add new functionality in new versions
+ * without breaking any implementation.
+ * <p>
+ * This service is intended to be implemented by providers of resource
* instances on behalf of the {@link ResourceResolver}. It
* is not intended to be used by client applications directly. A resource
- * provider can either directly implement this service interface, e.g.
- * when no user authentication is provided (like for bundle resources)
- * or a {@link ResourceProviderFactory} service can be implemented which
- * upon successful authentication returns a resource provider with the
- * given user credentials.
+ * provider implements this service by extending this class.
+ * <p>
+ * TODO - authentication / logout (Closeable)
+ * TODO - context support
+ * TODO - query
+ * TODO - observation
+ * TODO - service ranking
*/
@ConsumerType
-public interface ResourceProvider<T> {
+public abstract class ResourceProvider<T> {
/**
* The name of the service registration property containing the root path
- * of the resources provided by this provider (value is "provider.root").
+ * of the resources provided by this provider.
* If this property is missing, empty or invalid, the provider is ignored.
* (value is "provider.root")
*/
- String PROPERTY_ROOT = "provider.root";
+ public static final String PROPERTY_ROOT = "provider.root";
/**
* The name of the service registration property containing a boolean
@@ -68,16 +74,18 @@ public interface ResourceProvider<T> {
* The default for this value is <code>false</code>.
* (value is "provider.useResourceAccessSecurity")
*/
- String PROPERTY_USE_RESOURCE_ACCESS_SECURITY = "provider.useResourceAccessSecurity";
+ public static final String PROPERTY_USE_RESOURCE_ACCESS_SECURITY = "provider.useResourceAccessSecurity";
/**
- * A required resource provider factory is accessed directly when a new
- * resource resolver is created. Only if authentication against all required
- * resource provider factories is successful, a resource resolver is created
- * by the resource resolver factory. Boolean service property, default value
- * is <code>false</true>
+ * A required resource provider is accessed directly when a new
+ * resource resolver is created. The resource resolver implementation
+ * will call the {@link #authenticate(Map)}. Only if authentication against
+ * all required resource provider factories is successful, a resource resolver
+ * is created by the resource resolver factory. Boolean service property, default value
+ * is <code>false</true>.
+ * (value is "provider.required")
*/
- String PROPERTY_REQUIRED = "provider.required";
+ public static final String PROPERTY_REQUIRED = "provider.required";
/**
* The authentication information property referring to the bundle
@@ -94,22 +102,57 @@ public interface ResourceProvider<T> {
* The type of this property, if present, is
* <code>org.osgi.framework.Bundle</code>.
*/
- String AUTH_SERVICE_BUNDLE = "sling.service.bundle";
-
- @Nonnull T authenticate(Map<String, Object> authenticationInfo) throws LoginException;
+ public static final String AUTH_SERVICE_BUNDLE = "sling.service.bundle";
/**
- * Close the resource provider.
- * Once the resource provider is not used anymore, it should be closed with
- * this method.
- */
- void logout(@Nonnull ResolveContext<T> ctx);
+ * Authenticate against the resource provider.
+ * <p>
+ * Returns a provider context object if authentication is successful. The
+ * context object is passed to the resource provider in all messages through
+ * the {@link ResolveContext}. A valid implementation might return {@code null}
+ * as the context information.
+ * <p>
+ * If authentication fails a {@code LoginException} must be thrown.
+ * <p>
+ * The returned context object grants access to the provided resources with
+ * privileges assigned to the service provided by the calling bundle.
+ * <p>
+ * The provided {@code authenticationInfo} map may be used to provide
+ * additional information such as the {@value #AUTH_SERVICE_BUNDLE}.
+ * If this property is provided, additional information like
+ * {@link ResourceResolverFactory#SUBSERVICE} might be provided. In this case
+ * {@link #USER} and {@link #PASSWORD} properties provided in the map are
+ * ignored.
+ * <p>
+ * The {@link #USER_IMPERSONATION} property is obeyed but requires that the
+ * authenticated user has permission to impersonate as the requested user.
+ * If such permission is missing, a {@code LoginException} is thrown.
+ * <p>
+ * If the returned context data object implements {@link java.io.Closeable},
+ * the resource resolver implementation will call the close method once
+ * the resource resolver is closed.
+ *
+ * @param authenticationInfo A map of further credential information which
+ * may be used by the implementation to parameterize how the
+ * resource resolver is created.
+ * @return A context data object according to the
+ * <code>authenticationInfo</code>.
+ * @throws LoginException If an error occurs authenticating with the
+ * provided credential data.
+ */
+ @Nonnull T authenticate(final @Nonnull Map<String, Object> authenticationInfo)
+ throws LoginException {
+ return null;
+ }
/**
* 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.
*/
- void refresh();
+ public void refresh(final @Nonnull ResolveContext<T> ctx) {
+ // nothing to do here
+ }
/**
* Returns <code>true</code> if this resource provider has not been closed
@@ -122,13 +165,21 @@ public interface ResourceProvider<T> {
* yet and is still active.. Once the resource provider has been closed
* or is not active anymore, this method returns <code>false</code>.
*/
- boolean isLive(@Nonnull ResolveContext<T> ctx);
-
- @CheckForNull Resource getParent(@Nonnull ResolveContext<T> ctx, @Nonnull Resource child);
+ public boolean isLive(final @Nonnull ResolveContext<T> ctx) {
+ return true;
+ }
+
+ public @CheckForNull Resource getParent(final @Nonnull ResolveContext<T> ctx,final @Nonnull Resource child) {
+ final String parentPath = ResourceUtil.getParent(child.getPath());
+ if (parentPath == null) {
+ return null;
+ }
+ return this.getResource(ctx, parentPath);
+ }
- @CheckForNull Resource getResource(@Nonnull ResolveContext<T> ctx, @Nonnull String path);
+ public abstract @CheckForNull Resource getResource(final @Nonnull ResolveContext<T> ctx, final @Nonnull String path);
- @CheckForNull Iterator<Resource> listChildren(@Nonnull ResolveContext<T> ctx, @Nonnull Resource parent);
+ 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
@@ -138,7 +189,9 @@ public interface ResourceProvider<T> {
* @throws IllegalStateException if this resource provider has already been
* closed.
*/
- Collection<String> getAttributeNames(@Nonnull ResolveContext<T> ctx);
+ public Collection<String> getAttributeNames(final @Nonnull ResolveContext<T> ctx) {
+ return null;
+ }
/**
* Returns the value of the given resource provider attribute or <code>null</code>
@@ -152,7 +205,9 @@ public interface ResourceProvider<T> {
* @throws IllegalStateException
* if this resource provider has already been closed.
*/
- Object getAttribute(@Nonnull ResolveContext<T> ctx, @Nonnull String name);
+ public Object getAttribute(final @Nonnull ResolveContext<T> ctx, final @Nonnull String name) {
+ return null;
+ }
/**
* Create a new resource at the given path.
@@ -169,8 +224,10 @@ public interface ResourceProvider<T> {
*
* @throws PersistenceException If anything fails
*/
- Resource create(@Nonnull ResolveContext<T> ctx, String path, Map<String, Object> properties)
- throws PersistenceException;
+ public Resource create(final @Nonnull ResolveContext<T> ctx, final String path, final Map<String, Object> properties)
+ throws PersistenceException {
+ throw new PersistenceException("create is not supported.");
+ }
/**
* Delete the resource at the given path.
@@ -182,15 +239,19 @@ public interface ResourceProvider<T> {
*
* @throws PersistenceException If anything fails
*/
- void delete(@Nonnull ResolveContext<T> ctx, Resource resource)
- throws PersistenceException;
+ public void delete(final @Nonnull ResolveContext<T> ctx, final @Nonnull Resource resource)
+ throws PersistenceException {
+ throw new PersistenceException("delete is not supported.");
+ }
/**
* Revert all transient changes: create, delete and updates.
*
* @param resolver The current resource resolver.
*/
- void revert(@Nonnull ResolveContext<T> ctx);
+ public void revert(final @Nonnull ResolveContext<T> ctx) {
+ // nothing to do here
+ }
/**
* Commit all transient changes: create, delete and updates
@@ -199,18 +260,25 @@ public interface ResourceProvider<T> {
*
* @throws PersistenceException If anything fails
*/
- void commit(@Nonnull ResolveContext<T> ctx)
- throws PersistenceException;
+ public void commit(final @Nonnull ResolveContext<T> ctx)
+ throws PersistenceException {
+ // nothing to do here
+ }
/**
* Are there any transient changes?
*
* @param resolver The current resource resolver.
*/
- boolean hasChanges(@Nonnull ResolveContext<T> ctx);
-
- @CheckForNull QueryProvider<T> getQueryProvider();
-
- @CheckForNull <AdapterType> AdapterType adaptTo(@Nonnull ResolveContext<T> ctx, Class<AdapterType> type);
-
+ public boolean hasChanges(final @Nonnull ResolveContext<T> ctx) {
+ return false;
+ }
+
+ public @CheckForNull QueryProvider<T> getQueryProvider() {
+ return null;
+ }
+
+ public @CheckForNull <AdapterType> AdapterType adaptTo(final @Nonnull ResolveContext<T> ctx, final @Nonnull Class<AdapterType> type) {
+ return null;
+ }
}