Author: fmeschbe
Date: Wed Aug 11 14:04:05 2010
New Revision: 984412
URL: http://svn.apache.org/viewvc?rev=984412&view=rev
Log:
SLING-1640 Add ResourceResolver.copy(Map) method to the API and add some
JavaDoc to the ResourceResolverFactory
Modified:
sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/LoginException.java
sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceResolverFactory.java
Modified:
sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/LoginException.java
URL:
http://svn.apache.org/viewvc/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/LoginException.java?rev=984412&r1=984411&r2=984412&view=diff
==============================================================================
---
sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/LoginException.java
(original)
+++
sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/LoginException.java
Wed Aug 11 14:04:05 2010
@@ -21,8 +21,11 @@ package org.apache.sling.api.resource;
/**
* Exception thrown by
* <code>{...@link
ResourceResolverFactory#getAdministrativeResourceResolver(java.util.Map)}</code>
- * and <code>{...@link
ResourceResolverFactory#getResourceResolver(java.util.Map)}</code> if
- * the specified credentials are invalid.
+ * ,
+ * <code>{...@link
ResourceResolverFactory#getResourceResolver(java.util.Map)}</code>
+ * , and <code>{...@link ResourceResolver#copy(java.util.Map)}</code> if a
resource
+ * resolver cannot be created because the credential data is not valid.
+ *
* @since 2.1
*/
public class LoginException extends Exception {
@@ -42,7 +45,7 @@ public class LoginException extends Exce
* message.
*
* @param message the detail message. The detail message is saved for later
- * retrieval by the {...@link #getMessage()} method.
+ * retrieval by the {...@link #getMessage()} method.
*/
public LoginException(String message) {
super(message);
@@ -52,8 +55,8 @@ public class LoginException extends Exce
* Constructs a new instance of this class with the specified detail
message
* and root cause.
*
- * @param message the detail message. The detail message is saved for
later
- * retrieval by the {...@link #getMessage()} method.
+ * @param message the detail message. The detail message is saved for later
+ * retrieval by the {...@link #getMessage()} method.
* @param rootCause root failure cause
*/
public LoginException(String message, Throwable rootCause) {
Modified:
sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
URL:
http://svn.apache.org/viewvc/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java?rev=984412&r1=984411&r2=984412&view=diff
==============================================================================
---
sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
(original)
+++
sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
Wed Aug 11 14:04:05 2010
@@ -71,12 +71,45 @@ import org.apache.sling.api.adapter.Adap
*/
public interface ResourceResolver extends Adaptable {
- /** A request attribute containing the workspace to use for
- * {...@link #resolve(HttpServletRequest)} and {...@link
#resolve(HttpServletRequest, String)}
- * if not the default workspace should be used to resolve the resource.
+ /**
+ * A request attribute containing the workspace to use for
+ * {...@link #resolve(HttpServletRequest)} and
+ * {...@link #resolve(HttpServletRequest, String)} if not the default
workspace
+ * should be used to resolve the resource.
+ *
* @since 2.1
*/
- String REQUEST_ATTR_WORKSPACE_INFO = ResourceResolver.class.getName() +
"/use.workspace";
+ String REQUEST_ATTR_WORKSPACE_INFO = ResourceResolver.class.getName()
+ + "/use.workspace";
+
+ /**
+ * Returns a new <code>ResourceResolver</code> instance based on the given
+ * <code>authenticationInfo</code> map and the original authentication info
+ * used to create this instance.
+ * <p>
+ * The new resource resolver is created according to the following
+ * algorithm:
+ *
+ * <pre>
+ * Map<String, Object> newAuthenticationInfo = new HashMap(
+ * authenticationInfoOfThisInstance);
+ * newAuthenticationInfo.addAll(authenticationInfo);
+ * return
resourceResolverFactory.getResourceResolver(newAuthenticationInfo);
+ * </pre>
+ *
+ * @param authenticationInfo The map or credential data to overlay the
+ * orignal credential data with for the creation of a new
+ * resource resolver. This may be <code>null</code> in which
case
+ * the same credential data is used as was used to create this
+ * instance.
+ * @return A new <code>ResourceResolver</code>
+ * @throws LoginException If an error occurrs creating the new
+ * <code>ResourceResolver</code> with the provided credential
+ * data.
+ * @since 2.1
+ */
+ ResourceResolver copy(Map<String, Object> authenticationInfo)
+ throws LoginException;
/**
* Resolves the resource from the given <code>absPath</code> optionally
@@ -88,10 +121,8 @@ public interface ResourceResolver extend
* The difference between this method and the {...@link #resolve(String)}
* method is, that this method may take request properties like the scheme,
* the host header or request parameters into account to resolve the
- * resource.
- *
- * If the {...@link #REQUEST_ATTR_WORKSPACE_INFO} attribute is set, the
- * given workspace is used to resolve the resource.
+ * resource. If the {...@link #REQUEST_ATTR_WORKSPACE_INFO} attribute is
set,
+ * the given workspace is used to resolve the resource.
*
* @param request The http servlet request object providing more hints at
* how to resolve the <code>absPath</code>. This parameter may
be
Modified:
sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceResolverFactory.java
URL:
http://svn.apache.org/viewvc/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceResolverFactory.java?rev=984412&r1=984411&r2=984412&view=diff
==============================================================================
---
sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceResolverFactory.java
(original)
+++
sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceResolverFactory.java
Wed Aug 11 14:04:05 2010
@@ -21,26 +21,65 @@ package org.apache.sling.api.resource;
import java.util.Map;
/**
- * The <code>ResourceResolverFactory</code> defines the service API to
- * get and create <code>ResourceResolver</code>s.
+ * The <code>ResourceResolverFactory</code> defines the service API to get and
+ * create <code>ResourceResolver</code>s.
* <p>
- * As soon as the resource resolver is not used anymore, {...@link
ResourceResolver#close()}
- * should be called.
+ * As soon as the resource resolver is not used anymore,
+ * {...@link ResourceResolver#close()} should be called.
*
* @since 2.1
*/
public interface ResourceResolverFactory {
- /** If this property is set in the authentication information which is
passed
- * into {...@link #getResourceResolver(Map)} or {...@link
#getAdministrativeResourceResolver(Map)}
- * then after a successful authentication attempt, a sudo to the provided
- * user id is tried.
+ /**
+ * If this property is set in the authentication information which is
passed
+ * into {...@link #getResourceResolver(Map)} or
+ * {...@link #getAdministrativeResourceResolver(Map)} then after a
successful
+ * authentication attempt, a sudo to the provided user id is tried.
*/
String SUDO_USER_ID = "sudo.user.id";
+ /**
+ * 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.
+ * <p>
+ * If the <code>authenticationInfo</code> map is <code>null</code> the
+ * <code>ResourceResolver</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 resolver is created. This may be <code>null</code>.
+ * @return A {...@link ResourceResolver} according to the
+ * <code>authenticationInfo</code>.
+ * @throws LoginException If an error occurrs creating the new
+ * <code>ResourceResolver</code> with the provided credential
+ * data.
+ */
ResourceResolver getResourceResolver(Map<String, Object>
authenticationInfo)
- throws LoginException;
+ throws LoginException;
- ResourceResolver getAdministrativeResourceResolver(Map<String, Object>
authenticationInfo)
- throws LoginException;
+ /**
+ * Returns a new {...@link ResourceResolver} instance with administrative
+ * privileges with further configuration taken from the given
+ * <code>authenticationInfo</code> map.
+ * <p>
+ * Note, that if the <code>authenticationInfo</code> map contains the
+ * {...@link #SUDO_USER_ID} attribute the <code>ResourceResolver</code>
+ * returned will only have administrative privileges if the user identified
+ * by the property has administrative privileges.
+ *
+ * @param authenticationInfo A map of further credential 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 administrative privileges
unless
+ * the {...@link #SUDO_USER_ID} was set in the
+ * <code>authenticationInfo</code>.
+ * @throws LoginException If an error occurrs creating the new
+ * <code>ResourceResolver</code> with the provided credential
+ * data.
+ */
+ ResourceResolver getAdministrativeResourceResolver(
+ Map<String, Object> authenticationInfo) throws LoginException;
}
