svn commit: r1464342 - /sling/trunk/bundles/api/src/main/java/org/apache/sling/api/security/ResourceAccessSecurity.java

[bd...@apache.org]

Author: bdelacretaz
Date: Thu Apr  4 08:04:03 2013
New Revision: 1464342

URL: http://svn.apache.org/r1464342
Log:
tweak/complete javadocs

Modified:
    sling/trunk/bundles/api/src/main/java/org/apache/sling/api/security/ResourceAccessSecurity.java

Modified: sling/trunk/bundles/api/src/main/java/org/apache/sling/api/security/ResourceAccessSecurity.java
URL: http://svn.apache.org/viewvc/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/security/ResourceAccessSecurity.java?rev=1464342&r1=1464341&r2=1464342&view=diff
==============================================================================
--- sling/trunk/bundles/api/src/main/java/org/apache/sling/api/security/ResourceAccessSecurity.java (original)
+++ sling/trunk/bundles/api/src/main/java/org/apache/sling/api/security/ResourceAccessSecurity.java Thu Apr  4 08:04:03 2013
@@ -23,43 +23,59 @@ import org.apache.sling.api.resource.Res
 
 /**
  * The <code>ResourceAccessSecurity</code> defines a service API which might be
- * used in implementations of resource providers where the underlaying
- * persistence layer does not have any ACLs. The service should it make easy to
- * implement a lightweight access control in such sort of providers.
+ * used in implementations of resource providers where the underlying
+ * persistence layer does not implement access control. The goal is to make it 
+ * easy to implement a lightweight access control in such providers.
  * 
- * - Expected to only be implemented once in the framework/application (much
- * like the OSGi LogService or Configuration Admin Service) - ResourceProvider
+ * Expected to only be implemented once in the framework/application (much
+ * like the OSGi LogService or ConfigurationAdmin Service) - ResourceProvider
  * implementations are encouraged to use this service for access control unless
- * the underlying storage already has it.
+ * the underlying storage already provides it.
  * 
+ * JCR resource providers should *not* use this - in a JCR context, security is
+ * fully delegated to the underlying repository, and mixing security models would
+ * be a bad idea.
  */
 
 public interface ResourceAccessSecurity {
 
+    /** If supplied Resource can be read, return it (or a wrapped
+     *  variant of it). The returned Resource should then be used
+     *  instead of the one that was passed into the method.
+     *  @return null if {@link Resource} cannot be read
+     */
     public Resource getReadableResource(Resource resource);
 
+    /** @return true if a {@link Resource} can be created at the supplied 
+     *  absolute path. */
     public boolean canCreate(String absPathName, ResourceResolver resourceResolver);
 
+    /** @return true if supplied {@link Resource} can be updated */ 
     public boolean canUpdate(Resource resource);
 
+    /** @return true if supplied {@link Resource} can be deleted */ 
     public boolean canDelete(Resource resource);
 
+    /** @return true if supplied {@link Resource} can be executed as a script */ 
     public boolean canExecute(Resource resource);
 
+    /** @return true if the "valueName" value of supplied {@link Resource} can be read */ 
     public boolean canReadValue(Resource resource, String valueName);
 
+    /** @return true if the "valueName" value of supplied {@link Resource} can be set */ 
     public boolean canSetValue(Resource resource, String valueName);
 
+    /** @return true if the "valueName" value of supplied {@link Resource} can be deleted */ 
     public boolean canDeleteValue(Resource resource, String valueName);
 
     /**
-     * Allows to transform the query based on the current
+     * Optionally transform a query based on the current
      * user's credentials. Can be used to narrow down queries to omit results
-     * that the current user is not allowed to see anyway, speeding up
+     * that the current user is not allowed to see anyway, to speed up
      * downstream access control.
      * 
      * Query transformations are not critical with respect to access control as results
-     * are checked using the canRead.. methods anyway. 
+     * are filtered downstream using the canRead.. methods. 
      * 
      * @param query the query
      * @param language the language in which the query is expressed
@@ -70,4 +86,4 @@ public interface ResourceAccessSecurity 
     public String transformQuery(String query, String language, ResourceResolver resourceResolver)
             throws AccessSecurityException;
 
-}
+}
\ No newline at end of file