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;
}
