svn commit: r1242929 - /river/jtsk/trunk/src/net/jini/security/policy/DynamicPolicyProvider.java

[pe...@apache.org]

Author: peter_firmstone
Date: Fri Feb 10 21:17:30 2012
New Revision: 1242929

URL: http://svn.apache.org/viewvc?rev=1242929&view=rev
Log:
River-323 Minor javadoc changes

Modified:
    river/jtsk/trunk/src/net/jini/security/policy/DynamicPolicyProvider.java

Modified: river/jtsk/trunk/src/net/jini/security/policy/DynamicPolicyProvider.java
URL: http://svn.apache.org/viewvc/river/jtsk/trunk/src/net/jini/security/policy/DynamicPolicyProvider.java?rev=1242929&r1=1242928&r2=1242929&view=diff
==============================================================================
--- river/jtsk/trunk/src/net/jini/security/policy/DynamicPolicyProvider.java (original)
+++ river/jtsk/trunk/src/net/jini/security/policy/DynamicPolicyProvider.java Fri Feb 10 21:17:30 2012
@@ -80,66 +80,16 @@ import org.apache.river.impl.util.Collec
  * by granting additional permissions, this implementation adds an experimental 
  * feature for revoking permissions, however there are some caveats:</p>
  * 
- * <p>Background: if ProtectionDomain.toString(), is called a ProtectionDomain will
- * merge Permissions, from the policy with those in the ProtectionDomain,
- * in a new private instance of Permissions, thus a ProtectionDomain cannot have 
- * Permission's removed, only additional merged.  A ProtectionDomain must
+ * <p>Background: A ProtectionDomain must
  * be created with the dynamic constructor otherwise it will never consult
- * the policy.  The AccessController.checkPermission(Permission) method
- * consults the current AccessControlContext, which contains all
- * ProtectionDomain's on the current thread's stack, before consulting the
- * AccessControllContext.checkPermission(Permission), it calls
- * AccessControllContext.optimize() which  removes all duplicate ProtectionDomains
- * in the ProtectionDomain array[]'s from the
- * enclosing AccessContolContext for the execution domain and the nested
- * AccessControlContext for the privileged domain (the privileged domain is
- * an array of ProtectionDomain's on the stack since the last 
- * AccessController.doPriveleged() call).  The optimize() method also calls
- * the DomainCombiner, which, for example, gives the SubjectDomainCombiner the 
- * opportunity to manipulate the ProtectionDomain's in the privileged array, in the
- * SubjectDomainCombiner's case, it creates new copies of the ProtectionDomain's
- * with new Principal[]'s injected.  The optimize() method returns a new
- * optimized AccessControlContext.
- * </p><p>
- * Now the AccessController calls the new AccessControlContext.checkPermission(Permission),
- * at this stage, each ProtectionDomain, if created with the dynamic constructor
+ * the policy. Only a dynamic ProtectionDomain, created with the dynamic constructor
  * consults the Policy, calling Policy.implies(ProtectionDomain, Permission).
  * </p><p>
- * If any calls to the policy return false, the ProtectionDomain then checks its
+ * If any calls to the policy return false, a dynamic ProtectionDomain checks its
  * internal Permissions and if they return false, it returns false.  The first
  * ProtectionDomain in the AccessControlContext to return false causes the 
  * AccessController.checkPermission(Permission) to throw an AccessControlException
  * </p><p>
- * To optimise the time taken to check Permission's the ProtectionDomain's
- * should either be static, which excludes the Policy, or dynamic with
- * a null PermissionCollection in it's constructor, </p>
- * 
- * <p>So in order to prevent dynamic grants from finding
- * their way into a ProtectionDomain's private PermissionCollection,
- * one would have to ensure that no dynamically grantable permissions are 
- * returned via the method:</p>
- * <p>
- * getPermissions(ProtectionDomain domain) and
- * getPermissions(Codesource source) as a precaution.
- * </p>
- * <p>This is different to the behaviour of the existing Jini 2.0
- * DynamicPolicyProvider implementation where dynamically granted Permissions
- * are added and can escape into the ProtectionDomain's private PermissionCollection.
- * 
- * However when a Policy is checked via implies(ProtectionDomain d, Permission p)
- * this implementation checks the dynamic grants
- * 
- * This means that if a DynamicPolicy is utilised as the base Policy class
- * and if it returns dynamically granted permissions, then those permissions
- * cannot be revoked.</p>
- * <p>
- * It is thus recommended that Static policy files only be used for setting
- * up your privileged code and use UmbrellaGrantPermission's and grant 
- * all other Permission's using dynamic grants.  This minimises the double 
- * checking of Permission, that occurs when a ProtectionDomain is constructed
- * so it contains a default PermissionCollection that is not null.
- *
- * </p><p>
  * To make the best utilisation of this Policy provider, set the System property:
  * </p>,<p>
  * net.jini.security.policy.PolicyFileProvider.basePolicyClass =