incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From fmesc...@apache.org
Subject svn commit: r984412 - in /sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource: LoginException.java ResourceResolver.java ResourceResolverFactory.java
Date Wed, 11 Aug 2010 14:04:06 GMT
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&lt;String, Object&gt; 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;
 }



Mime
View raw message