Skip to main content

[identity-api-spec commits] [identity-api-spec~git:b9d1a90f] various editorial javadoc corrections/additions

  • From: monzillo@...
  • To: commits@...
  • Subject: [identity-api-spec commits] [identity-api-spec~git:b9d1a90f] various editorial javadoc corrections/additions
  • Date: Tue, 27 Aug 2013 19:25:58 +0000

Project:    identity-api-spec
Repository: git
Revision:   b9d1a90fb99e2017f1cc9605d5b340139196625e
Author:     monzillo
Date:       2013-08-27 19:25:20 UTC
Link:       

Log Message:
------------
renamed getPermissions to getRequiredPermissions
various editorial javadoc changes
various editorial javadoc corrections/additions


Revisions:
----------
5411339315d4bbe3eea65016451163256ccc3c2e
b9d1a90fb99e2017f1cc9605d5b340139196625e


Modified Paths:
---------------
IdentityApiGit/src/main/java/javax/security/identity/client/ProviderLookupContext.java
IdentityApiGit/src/main/java/javax/security/identity/client/ExpressionPredicateOperator.java
IdentityApiGit/src/main/java/javax/security/identity/client/IDPredicate.java
IdentityApiGit/src/main/java/javax/security/identity/client/PropertySelector.java
IdentityApiGit/src/main/java/javax/security/identity/client/ProviderLookupService.java
IdentityApiGit/src/main/java/javax/security/identity/permission/AttributeAction.java
IdentityApiGit/src/main/java/javax/security/identity/permission/AttributeRepositoryPermission.java
IdentityApiGit/src/main/java/javax/security/identity/permission/PermissionAction.java


Diffs:
------
--- 
a/IdentityApiGit/src/main/java/javax/security/identity/client/ProviderLookupContext.java
+++ 
b/IdentityApiGit/src/main/java/javax/security/identity/client/ProviderLookupContext.java
@@ -41,7 +41,7 @@ public class ProviderLookupContext implements 
Comparable<ProviderLookupContext>,
     NameExpression[] _expressions;
 
     /**
-     * Construct a ProviderLookupCOntext describing a leaf 
AttributeProvider. A
+     * Construct a ProviderLookupContext describing a leaf 
AttributeProvider. A
      * leaf attribute provider is described by a RepositoryDescriptor.
      *
      * @param repositoryDescriptor
@@ -51,9 +51,9 @@ public class ProviderLookupContext implements 
Comparable<ProviderLookupContext>,
     }
 
     /**
-     * Construct a ProviderLookupCOntext describing an AttributeProvider 
that is
+     * Construct a ProviderLookupContext describing an AttributeProvider 
that is
      * constructed by applying an EntitySelector to the AttributeProvider 
from
-     * which the EntitySelector was obtained
+     * which the EntitySelector was obtained.
      *
      * @param selector an AttributeSelector that is used to identify the 
entities that
      * are to be selected from initial AttributeProvider to yield the
@@ -64,9 +64,9 @@ public class ProviderLookupContext implements 
Comparable<ProviderLookupContext>,
     }
 
     /**
-     * Construct a ProviderLookupCOntext describing an AttributeProvider 
that is
-     * constructed by combining (via union) the argument AttributeProviders.
-     * from which the EntitySelector was obtained
+     * Construct a ProviderLookupContext describing an AttributeProvider 
that is
+     * constructed by combining (via union) the argument AttributeProviders
+     * from which the EntitySelector was obtained.
      *
      * @param providers a varying length array of 1 or more 
AttributeProviders.
      */
@@ -78,7 +78,7 @@ public class ProviderLookupContext implements 
Comparable<ProviderLookupContext>,
     }
 
     /**
-     * Construct a ProviderLookupCOntext describing an AttributeProvider 
that is
+     * Construct a ProviderLookupContext describing an AttributeProvider 
that is
      * constructed by combining (via join) the entities from two
      * AttributeProviders; that have equivalent attribute values for the
      * attributes identified by the argument name expressions.
@@ -123,7 +123,7 @@ public class ProviderLookupContext implements 
Comparable<ProviderLookupContext>,
      * Get an Array of ProviderLookupContext describing the AttributeProvider
      * objects from which the described AttributeProvider is composed.
      * 
-     * @Return an array of ProviderLookupContext object or null if the
+     * @Return an array of ProviderLookupContext objects or null if the
      * ProviderLookupContext does not define an AttributeProvider that is
      * composed of other AttributeProviders.
      */
@@ -213,11 +213,11 @@ public class ProviderLookupContext implements 
Comparable<ProviderLookupContext>,
     }
 
     /**
-     * Get the Descriptors of all the distinct leaf attribute Repositories 
from
+     * Get the Descriptors of all the distinct leaf attribute repositories 
from
      * which the context has been composed.
      *
      * @return A Set of RepositoryDescriptor elements. One element for each
-     * distinct leaf attributeR repository.
+     * distinct leaf attribute repository.
      */
     public Set<RepositoryDescriptor> getRepositoryDescriptors() {
         Set<RepositoryDescriptor> rvalue = new 
HashSet<RepositoryDescriptor>();
@@ -236,17 +236,17 @@ public class ProviderLookupContext implements 
Comparable<ProviderLookupContext>,
     }
 
     /**
-     * Get The permissions that must be tested to perform the indicated 
action
+     * Get The permissions that are required to perform the indicated action
      * on an AttributeProvider obtained with the corresponding
-     * ProviderLookupContext
+     * ProviderLookupContext.
      *
      * @param <E>
      * @param action the action for which the permissions are requested
      * @return A Collection of AttributeServicePermission, with one 
permission 
      * for each distinct leaf AttributeProvider (i.e.,RepositoryDescriptor)
-     * within the ProviderLookupContext
+     * within the ProviderLookupContext.
      */
-    public <E extends Enum<E> & PermissionAction> 
Collection<AttributeRepositoryPermission<E>> getPermissions(E action) {
+    public <E extends Enum<E> & PermissionAction> 
Collection<AttributeRepositoryPermission<E>> getRequiredPermissions(E action) 
{
         Collection<AttributeRepositoryPermission<E>> rvalue = new 
HashSet<AttributeRepositoryPermission<E>>();
         for (RepositoryDescriptor descriptor : getRepositoryDescriptors()) {
             AttributeRepositoryPermission<E> p = new 
AttributeRepositoryPermission<E>(descriptor, action);
@@ -295,7 +295,7 @@ public class ProviderLookupContext implements 
Comparable<ProviderLookupContext>,
      * AttributeProvider. The determination is made based on the binding of 
the
      * IDExpression elements used to construct the predicate.
      *
-     * @param p an IDpredicate.
+     * @param p an IDPredicate.
      * @return true or false.
      */
     public boolean predicateInContext(IDPredicate p) {

--- 
a/IdentityApiGit/src/main/java/javax/security/identity/client/ExpressionPredicateOperator.java
+++ 
b/IdentityApiGit/src/main/java/javax/security/identity/client/ExpressionPredicateOperator.java
@@ -17,7 +17,7 @@ package javax.security.identity.client;
 
 /**
  * Interface to be implemented by all predicate operators except boolean 
- * predicate operators..
+ * predicate operators.
  * 
  * @author ronmonzillo
  */--- 
a/IdentityApiGit/src/main/java/javax/security/identity/client/IDPredicate.java
+++ 
b/IdentityApiGit/src/main/java/javax/security/identity/client/IDPredicate.java
@@ -29,26 +29,25 @@ import 
javax.security.identity.client.expression.IDExpression;
 public interface IDPredicate extends Serializable {
 
     /**
-     * Create a negation of this predicate
+     * Create a negation of this predicate.
      *
-     * @return a predicate that evaluates the negation of this predicate
+     * @return a predicate that evaluates the negation of this predicate.
      */
     IDPredicate not();
     
     /**
-     * return the IDExpression from which this predicate was created, if any
+     * return the IDExpression from which this predicate was created.
      * 
      * @return the IDExpression from which this predicate was created, or 
null if
-     * this predicate was created by conjunction, disjunction or negation.
+     * this predicate was created from other predicates by 
BooleanPredicateOperator.
      */
     IDExpression<? extends Serializable> getExpression();
     
     /**
-     * Return the top-level predicates from which this predicate was 
composed,
-     * by conjunction, disjunction, or negation (if any).
+     * Return the predicates from which this predicate was composed, if any.
      *
      * @return the list of component predicates or null if this predicate was
-     * created from an expression
+     * created from an expression by ExpressionPredicateOperator.
      */
     List<IDPredicate> getPredicates();
 
@@ -64,7 +63,7 @@ public interface IDPredicate extends Serializable {
      * obtained.
      * 
      * @return the AttributeLookupContext that may be used to obtain the
-     * AttributeProvider from which this predicate was obtained
+     * AttributeProvider from which this predicate was obtained.
      */
     ProviderLookupContext getProviderLookupContext();
 --- 
a/IdentityApiGit/src/main/java/javax/security/identity/client/PropertySelector.java
+++ 
b/IdentityApiGit/src/main/java/javax/security/identity/client/PropertySelector.java
@@ -62,7 +62,8 @@ public final class PropertySelector implements IDPredicate, 
Serializable {
      * Wraps an IDPredicate for use as a Property Selector. The constructor
      * ensures that the argument IDPredicate was constructed from an
      * IDExpression of ExpressionType.PropertyValue or
-     * ExpressionType.PropertyName, or by negation, conjuction, or 
disjunction,
+     * ExpressionType.PropertyName, or by boolean operation 
+     * (e.g., negation, conjuction, or disjunction), 
      * from one or more IDPredicate objects that satisfy this ExpressionType
      * criteria (recursively).
      *--- 
a/IdentityApiGit/src/main/java/javax/security/identity/client/ProviderLookupService.java
+++ 
b/IdentityApiGit/src/main/java/javax/security/identity/client/ProviderLookupService.java
@@ -29,7 +29,7 @@ public interface ProviderLookupService {
 
     /**
      * Register the source of an AttributeRepository (i.e, a RepositoryAgent)
-     * with the ProviderLookupService
+     * with the ProviderLookupService.
      *
      * @param agent an implementation of the RepositoryAgent Class that is 
able
      * to return the AttributeRepository named in repositoryName parameter.
@@ -51,7 +51,7 @@ public interface ProviderLookupService {
     ProviderLookupContext registerRepositoryAgent(RepositoryAgent agent, 
String repositoryName);
 
     /**
-     * Unregister an AttributeRepository from the ProviderLookupService
+     * Unregister an AttributeRepository from the ProviderLookupService.
      *
      * @param descriptor that identifies the AttributeProvider that is to be
      * unregistered by RepositoryAgent(name) and ProviderName.
@@ -74,10 +74,10 @@ public interface ProviderLookupService {
      * contained in the repository identified by the ProviderLookupContext.
      *
      * @param context identifies the entity provider or repository from which
-     * the entities are to be selected
+     * the entities are to be selected.
      *
      * @return a provider specific AttributeProvider that can be used to
-     * generate selectors for use with the LookpService
+     * generate selectors for use with the LookpService.
      *
      * Note that the AttributeProvider returns predicates that encapsulate
      * provider and repository specific details needed to convey queries to 
the--- 
a/IdentityApiGit/src/main/java/javax/security/identity/permission/AttributeAction.java
+++ 
b/IdentityApiGit/src/main/java/javax/security/identity/permission/AttributeAction.java
@@ -16,7 +16,7 @@
 package javax.security.identity.permission;
 
 /**
- * Actions used to protect the Service interfaces of the attributeProvider
+ * Actions used to protect the Service interfaces of the attributeProvider.
  *
  * @author ronmonzillo
  */--- 
a/IdentityApiGit/src/main/java/javax/security/identity/permission/AttributeRepositoryPermission.java
+++ 
b/IdentityApiGit/src/main/java/javax/security/identity/permission/AttributeRepositoryPermission.java
@@ -67,7 +67,7 @@ public class AttributeRepositoryPermission<E extends 
Enum<E> & PermissionAction>
     }
 
     /**
-     * return the type of an Enum class loaded by name
+     * return the type of an Enum class loaded by name.
      * ISSUE: need to be able to obtain the enumType from the loaded class
      * in a fashion that does not rely on suppressing warnings.
      * @param <E>
@@ -106,6 +106,7 @@ public class AttributeRepositoryPermission<E extends 
Enum<E> & PermissionAction>
     }
     
     /**
+     * Convert an action string into an EnumSet.
      *
      * @param <E>
      * @param enumType
@@ -114,11 +115,11 @@ public class AttributeRepositoryPermission<E extends 
Enum<E> & PermissionAction>
      * name.
      * @param delimiter
      * @return an EnumSet containing the Enum<E> values corresponding to the
-     * argument names
+     * argument names.
      * @throws PatternSyntaxException if delimiter is not a valid regular
-     * expression
+     * expression.
      * @throws IllegalArgumentException if the specified enumType has no
-     * constant with a specified name
+     * constant with a specified name.
      */
     private static <E extends Enum<E> & PermissionAction> EnumSet<E> 
getEnumSet(Class<E> enumType, String actions, String delimiter) {
 
@@ -129,15 +130,15 @@ public class AttributeRepositoryPermission<E extends 
Enum<E> & PermissionAction>
     }
 
     /**
-     * Convert an array of enum names into an EnumSet
+     * Convert an array of enum names into an EnumSet.
      *
      * @param <E>
      * @param enumType
-     * @param names an array of Enum<E> names
+     * @param names an array of Enum<E> names.
      * @return an EnumSet containing the Enum<E> values corresponding to the
-     * argument names
+     * argument names.
      * @throws IllegalArgumentException if the specified enumType has no
-     * constant with a specified name
+     * constant with a specified name.
      */
     private static <E extends Enum<E> & PermissionAction> EnumSet<E> 
getEnumSet(Class<E> enumType, String[] names) {
         ArrayList<E> enumList = new ArrayList<E>();
@@ -156,21 +157,21 @@ public class AttributeRepositoryPermission<E extends 
Enum<E> & PermissionAction>
      *
      * @param <E>
      * @param enumType
-     * @param elements an array of Enum<E> values
-     * @return an EnumSet containing the Enum<E> values
+     * @param elements an array of Enum<E> values.
+     * @return an EnumSet containing the Enum<E> values.
      */
     private static <E extends Enum<E> & PermissionAction> EnumSet<E> 
getEnumSet(Class<E> enumType, E... elements) {
         return getEnumSet(enumType, Arrays.asList(elements));
     }
 
     /**
-     * Create an EnumSet from a List of Enum<E> values
+     * Create an EnumSet from a List of Enum<E> values.
      *
      * @param <E>
      * @param enumType
-     * @param elements a List of Enum<E> values
+     * @param elements a List of Enum<E> values.
      * @return an EnumSet containing the Enum<E> values. If the List was 
empty,
-     * the returned set contains all possible values for the Enum<E> 
+     * the returned set contains all possible values for the Enum<E> .
      */
     private static <E extends Enum<E> & PermissionAction> EnumSet<E> 
getEnumSet(Class<E> enumType, List<E> elements) {
         EnumSet<E> set = EnumSet.noneOf(enumType);
@@ -184,8 +185,8 @@ public class AttributeRepositoryPermission<E extends 
Enum<E> & PermissionAction>
 
     /**
      * Determine if this permission implies the argument permission (P). 
-     * 
-     * for the argument permission to be implied by this permission:
+     * <p>
+     * For the argument permission to be implied by this permission:
      * <p><ul>
      * <li> the argument permission must an instanceof 
      *      AttributeRepositoryPermission
@@ -248,13 +249,18 @@ public class AttributeRepositoryPermission<E extends 
Enum<E> & PermissionAction>
     }
 
     /**
-     * 2 String constructor for use by policy systems employing the default 
Java
+     * Two String constructor for use by policy systems employing the 
default Java
      * Policy syntax.
      *
-     * @param name
-     * @param actions a string identifying the PermissionAction type 
followed by
+     * @param name a String formed by concatenating the repository agent 
class name
+     * a colon, and the provider name.
+     * 
+     * @param actions a String identifying the PermissionAction type 
followed by
      * a colon and then a comma separated list of the names of the actions 
to be
-     * represented in the permission.
+     * represented in the permission. The actions String must not be null, 
and
+     * must minimally define the PermissionActionType. If no actions are 
specified
+     * after the type, the permission is constructed with all actions defined
+     * for the type.
      */
     public AttributeRepositoryPermission(String name, String actions) throws 
ClassNotFoundException {
         super(getPermissionName(getRepositoryDescriptor(name)));
@@ -265,6 +271,16 @@ public class AttributeRepositoryPermission<E extends 
Enum<E> & PermissionAction>
         this._enumType = getEnumType(actions);
     }
 
+    /**
+     * Construct a single action permission from a RepositoryDescriptor
+     * and PermissionAction.
+     * 
+     * @param descriptor a RepositoryDescriptor from which the name of the 
Permission
+     * is derived by concatenating descriptor.getAgentClassName() a colon and
+     * descriptor.getProviderName();
+     * 
+     * @param action a PermissionAction, which may not be null.
+     */
     public AttributeRepositoryPermission(RepositoryDescriptor descriptor, E 
action) {
         super(getPermissionName(descriptor));
         this._descriptor = descriptor;
@@ -272,6 +288,22 @@ public class AttributeRepositoryPermission<E extends 
Enum<E> & PermissionAction>
         this._enumType = action.getDeclaringClass();
     }
 
+    /**
+     * Construct permission from a RepositoryDescriptor, a PermissionAction 
type,
+     * and 0 or more PermissionActions of the specified type.
+     * 
+     * @param descriptor a RepositoryDescriptor from which the name of the 
Permission
+     * is derived by concatenating descriptor.getAgentClassName() a colon and
+     * descriptor.getProviderName();
+     *
+     * @param enumType identifies the enum type of the specified 
PermissionActions.
+     * if no actions are specified, the enumType will be used to obtain all 
the
+     * actions defined for the type.
+     * 
+     * @param actions 0 or more PermissionActions of the specified
+     * enumType. If no actions are specified, the permission is constructed 
+     * with all actions defined for the enumType.
+     */
     public AttributeRepositoryPermission(RepositoryDescriptor descriptor, 
Class<E> enumType, E... actions) {
         super(getPermissionName(descriptor));
         this._descriptor = descriptor;--- 
a/IdentityApiGit/src/main/java/javax/security/identity/permission/PermissionAction.java
+++ 
b/IdentityApiGit/src/main/java/javax/security/identity/permission/PermissionAction.java
@@ -19,7 +19,7 @@ package javax.security.identity.permission;
  * Base interface implemented by the action values of the 
  * AttributeServicePermission. 
  * 
- * A type T must be defined <T extends Enum<T> & PermissionAction> to be 
used as
+ * A type T must be an enum that implements PermissionAction<T> in order to 
be used as
  * an action in an AttributeServicePermission.
  * 
  * @author ronmonzillo





[identity-api-spec commits] [identity-api-spec~git:b9d1a90f] various editorial javadoc corrections/additions

monzillo 08/27/2013
 
 
Close
loading
Please Confirm
Close