incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From fmesc...@apache.org
Subject svn commit: r1499258 - in /sling/whiteboard/fmeschbe/deprecate_login_administrative/api/src/main/java/org/apache/sling/api/resource: ResourceProviderFactory.java ResourceResolverFactory.java
Date Wed, 03 Jul 2013 08:36:21 GMT
Author: fmeschbe
Date: Wed Jul  3 08:36:21 2013
New Revision: 1499258

URL: http://svn.apache.org/r1499258
Log:
Implement support for service based ResourceResolver and Session access

- Update and complete JavaDoc
- Move service.info property to ResourceResolverFactory because
  consumers have to provide this property

Modified:
    sling/whiteboard/fmeschbe/deprecate_login_administrative/api/src/main/java/org/apache/sling/api/resource/ResourceProviderFactory.java
    sling/whiteboard/fmeschbe/deprecate_login_administrative/api/src/main/java/org/apache/sling/api/resource/ResourceResolverFactory.java

Modified: sling/whiteboard/fmeschbe/deprecate_login_administrative/api/src/main/java/org/apache/sling/api/resource/ResourceProviderFactory.java
URL: http://svn.apache.org/viewvc/sling/whiteboard/fmeschbe/deprecate_login_administrative/api/src/main/java/org/apache/sling/api/resource/ResourceProviderFactory.java?rev=1499258&r1=1499257&r2=1499258&view=diff
==============================================================================
--- sling/whiteboard/fmeschbe/deprecate_login_administrative/api/src/main/java/org/apache/sling/api/resource/ResourceProviderFactory.java
(original)
+++ sling/whiteboard/fmeschbe/deprecate_login_administrative/api/src/main/java/org/apache/sling/api/resource/ResourceProviderFactory.java
Wed Jul  3 08:36:21 2013
@@ -23,75 +23,98 @@ import java.util.Map;
 /**
  * The <code>ResourceProviderFactory</code> defines the service API to get and
  * create <code>ResourceProviders</code>s dynamically on a per usage base.
- *
  * Instead of sharing a resource provider between resource resolvers, the
  * factory allows to create an own instance of a resource provider per resource
- * resolver.
- * The factory also supports authentication.
+ * resolver. The factory also supports authentication.
  * <p>
- * If the resource provider is not used anymore and implements the {@link DynamicResourceProvider}
- * interface, the close method should be called.
+ * If the resource provider is not used anymore and implements the
+ * {@link DynamicResourceProvider} interface, the close method should be called.
  *
  * @since 2.2.0
  */
 public interface ResourceProviderFactory {
 
     /**
-     * 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 vaule is <code>false</true>
+     * 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 vaule
+     * is <code>false</true>
      */
     String PROPERTY_REQUIRED = "required";
 
+    /**
+     * The authentication information property referrring to the bundle
+     * providing a service for which a resource provider is to be retrieved. If
+     * this property is provided, the
+     * {@link ResourceResolverFactory#SERVICE_INFO} property may also be
+     * present.
+     * <p>
+     * {@link ResourceResolverFactory} implementations must provide this
+     * property if their implementation of the
+     * {@link ResourceResolverFactory#getServiceResourceResolver(Map)} method
+     * use a resource provider factory.
+     * <p>
+     * The type of this property, if present, is
+     * <code>org.osgi.framework.Bundle</code>.
+     *
+     * @since 2.4 (bundle version 2.4.0)
+     */
     String SERVICE_BUNDLE = "sling.service.bundle";
 
-    String SERVICE_INFO = "sling.service.info";
-
     /**
      * Returns a new {@link ResourceProvider} instance with further
      * configuration taken from the given <code>authenticationInfo</code> map.
      * Generally this map will contain a user name and password to authenticate.
      * <p>
+     * The <code>authenticationInfo</code> map will in general contain the same
+     * information as provided to the respective {@link ResourceResolver}
+     * method. For
+     * <p>
      * If the <code>authenticationInfo</code> map is <code>null</code>
the
-     * <code>ResourceProvider</code> returned will generally not be authenticated
-     * and only provide minimal privileges, if any at all.
+     * <code>ResourceProvider</code> returned will generally not be
+     * authenticated and only provide minimal privileges, if any at all.
      *
-     * @param authenticationInfo
-     *            A map of further credential information which may be used by
-     *            the implementation to parametrize how the resource provider is
-     *            created. This may be <code>null</code>.
-     * @return A {@link ResourceProvider} according to the <code>authenticationInfo</code>.
-     * @throws LoginException
-     *             If an error occurrs creating the new <code>ResourceProvider</code>
with the
-     *             provided credential data.
+     * @param authenticationInfo A map of further credential information which
+     *            may be used by the implementation to parametrize how the
+     *            resource provider is created. This may be <code>null</code>.
+     * @return A {@link ResourceProvider} according to the
+     *         <code>authenticationInfo</code>.
+     * @throws LoginException If an error occurrs creating the new
+     *             <code>ResourceProvider</code> with the provided credential
+     *             data.
      */
     ResourceProvider getResourceProvider(Map<String, Object> authenticationInfo) throws
LoginException;
 
     /**
      * Returns a new {@link ResourceProvider} instance with administrative
-     * privileges with further configuration taken from the given <code>authenticationInfo</code>
-     * map.
+     * privileges with further configuration taken from the given
+     * <code>authenticationInfo</code> map.
      * <p>
      * Note, that if the <code>authenticationInfo</code> map contains the
-     * {@link ResourceResolverFactory#USER_IMPERSONATION} attribute the <code>ResourceProvider</code>
returned will only
-     * have administrative privileges if the user identified by the property has administrative
+     * {@link ResourceResolverFactory#USER_IMPERSONATION} attribute the
+     * <code>ResourceProvider</code> returned will only have administrative
+     * privileges if the user identified by the property has administrative
      * privileges.
      * <p>
-     * <b><i>NOTE: This method is intended for use by infrastructure bundles
to access the
-     * resource tree and provide general services. This method MUST not be used to handle
client
-     * requests of whatever kinds. To handle client requests a regular authenticated resource
-     * provider retrieved through {@link #getResourceProvider(Map)} must be used.</i></b>
+     * Implementations of this method should throw {@code LoginException} if
+     * they don't support it.
      *
-     * @param authenticationInfo
-     *            A map of further credential information which may be used by
-     *            the implementation to parametrize how the resource provider is
-     *            created. This may be <code>null</code>.
+     * @param authenticationInfo A map of further credential information which
+     *            may be used by the implementation to parametrize how the
+     *            resource provider is created. This may be <code>null</code>.
      * @return A {@link ResourceProvider} with administrative privileges unless
-     *         the {@link ResourceResolverFactory#USER_IMPERSONATION} was set in the <code>authenticationInfo</code>.
-     * @throws LoginException
-     *             If an error occurrs creating the new <code>ResourceResolverFactory</code>
with the
-     *             provided credential data.
+     *         the {@link ResourceResolverFactory#USER_IMPERSONATION} was set in
+     *         the <code>authenticationInfo</code>.
+     * @throws LoginException If an error occurrs creating the new
+     *             <code>ResourceResolverFactory</code> with the provided
+     *             credential data.
+     * @deprecated as of 2.4 (bundle version 2.4.0) because of inherent security
+     *             issues. Implementations may implement this method at their
+     *             discretion but must support the new service based resource
+     *             provider generation in the {@link #getResourceProvider(Map)}
+     *             method honouring the {@link #SERVICE_BUNDLE} and
+     *             {@link ResourceResolverFactory#SERVICE_INFO} properties.
      */
     ResourceProvider getAdministrativeResourceProvider(Map<String, Object> authenticationInfo)
throws LoginException;
 }

Modified: sling/whiteboard/fmeschbe/deprecate_login_administrative/api/src/main/java/org/apache/sling/api/resource/ResourceResolverFactory.java
URL: http://svn.apache.org/viewvc/sling/whiteboard/fmeschbe/deprecate_login_administrative/api/src/main/java/org/apache/sling/api/resource/ResourceResolverFactory.java?rev=1499258&r1=1499257&r2=1499258&view=diff
==============================================================================
--- sling/whiteboard/fmeschbe/deprecate_login_administrative/api/src/main/java/org/apache/sling/api/resource/ResourceResolverFactory.java
(original)
+++ sling/whiteboard/fmeschbe/deprecate_login_administrative/api/src/main/java/org/apache/sling/api/resource/ResourceResolverFactory.java
Wed Jul  3 08:36:21 2013
@@ -33,11 +33,9 @@ public interface ResourceResolverFactory
 
     /**
      * Name of the authentication information property providing the name of the
-     * user for which the {@link #getResourceResolver(Map)} and
-     * {@link #getAdministrativeResourceResolver(Map)} create resource
-     * resolvers. on whose behalf the request is being handled. This property
-     * may be missing in which case an anonymous (unauthenticated) resource
-     * resolver is returned if possible.
+     * user for which the {@link #getResourceResolver(Map)} method creates
+     * resource resolvers. This property may be missing in which case an
+     * anonymous (unauthenticated) resource resolver is returned if possible.
      * <p>
      * The type of this property, if present, is <code>String</code>.
      */
@@ -54,10 +52,11 @@ public interface ResourceResolverFactory
 
     /**
      * Name of the authentication information property causing the
-     * {@link #getResourceResolver(Map)} and
-     * {@link #getAdministrativeResourceResolver(Map)} methods to try to
-     * impersonate the created resource resolver to the requested user and
-     * return the impersonated resource resolver.
+     * {@link #getResourceResolver(Map)},
+     * {@link #getAdministrativeResourceResolver(Map)}, and
+     * {@link #getServiceResourceResolver(Map)} methods to try to impersonate
+     * the created resource resolver to the requested user and return the
+     * impersonated resource resolver.
      * <p>
      * If this impersonation fails the actual creation of the resource resolver
      * fails.
@@ -71,6 +70,17 @@ public interface ResourceResolverFactory
     String USER_IMPERSONATION = "user.impersonation";
 
     /**
+     * Name of the authentication information property providing more
+     * information about the service requesting a resource resolver.
+     * <p>
+     * The type of this property, if present, is <code>String</code>.
+     *
+     * @see #getServiceResourceResolver(Map)
+     * @since 2.4 (bundle version 2.4.0)
+     */
+    String SERVICE_INFO = "sling.service.info";
+
+    /**
      * Returns a new {@link ResourceResolver} instance with further
      * configuration taken from the given <code>authenticationInfo</code> map.
      * Generally this map will contain a user name and password to authenticate.
@@ -88,8 +98,7 @@ public interface ResourceResolverFactory
      *             <code>ResourceResolver</code> with the provided credential
      *             data.
      */
-    ResourceResolver getResourceResolver(Map<String, Object> authenticationInfo)
-            throws LoginException;
+    ResourceResolver getResourceResolver(Map<String, Object> authenticationInfo) throws
LoginException;
 
     /**
      * Returns a new {@link ResourceResolver} instance with administrative
@@ -108,8 +117,9 @@ public interface ResourceResolverFactory
      * {@link #getResourceResolver(Map)} must be used.</i></b>
      * <p>
      * This method is deprecated. Services running in the Sling system should
-     * use the {@link #getServiceResourceResolver(String serviceInfo)} method
-     * instead.
+     * use the {@link #getServiceResourceResolver(Map)} method instead.
+     * Implementations of this method should throw {@code LoginException} if
+     * they don't support it.
      *
      * @param authenticationInfo A map of further credential information which
      *            may be used by the implementation to parametrize how the
@@ -122,20 +132,25 @@ public interface ResourceResolverFactory
      *             data.
      * @deprecated as of 2.4 (bundle version 2.4.0) because of inherent security
      *             issues. Services requiring specific permissions should use
-     *             the {@link #getServiceResourceResolver(String)} instead.
+     *             the {@link #getServiceResourceResolver(Map)} instead.
      */
     @Deprecated
-    ResourceResolver getAdministrativeResourceResolver(
-            Map<String, Object> authenticationInfo) throws LoginException;
+    ResourceResolver getAdministrativeResourceResolver(Map<String, Object> authenticationInfo)
throws LoginException;
 
     /**
      * Returns a new {@link ResourceResolver} instance with privileges assigned
-     * to the service provided by the calling bundle. The {@code serviceInfo}
-     * argument can be used to further specialize on the service account to be
-     * used.
+     * to the service provided by the calling bundle.
+     * <p>
+     * The provided {@code authenticationInfo} map may be used to provide
+     * addition information such as the {@link #SERVICE_INFO service
+     * information}. {@link #USER} and {@link #PASSWORD} properties provided in
+     * the map are ignored. The {@link #USER_IMPERSONATION} property is obeyed
+     * but requires that the actual service user has permission to impersonate
+     * as the requested user.
      *
-     * @param serviceInfo Optional service information to specialize account
-     *            selection for the service. This may be {@code null}.
+     * @param authenticationInfo A map of further service information which may
+     *            be used by the implementation to parametrize how the resource
+     *            resolver is created. This may be <code>null</code>.
      * @return A {@link ResourceResolver} with appropriate permissions to
      *         execute the service.
      * @throws LoginException If an error occurrs creating the new
@@ -144,5 +159,5 @@ public interface ResourceResolverFactory
      * @since 2.4 (bundle version 2.4.0) to replace
      *        {@link #getAdministrativeResourceResolver(Map)}
      */
-    ResourceResolver getServiceResourceResolver(String serviceInfo) throws LoginException;
+    ResourceResolver getServiceResourceResolver(Map<String, Object> authenticationInfo)
throws LoginException;
 }



Mime
View raw message