Skip to main content

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

  • From: monzillo@...
  • To: commits@...
  • Subject: [identity-api-spec commits] [identity-api-spec~git:174e079f] various editorial javadoc corrections/additions
  • Date: Thu, 29 Aug 2013 17:44:53 +0000

Project:    identity-api-spec
Repository: git
Revision:   174e079fa2ec2b3701363dc9bbce4687ed64b3ae
Author:     monzillo
Date:       2013-08-29 17:44:14 UTC
Link:       

Log Message:
------------
various editorial javadoc corrections/additions
included added description of various enum values
improved descriprion of expressions, and of predicate operators.


Revisions:
----------
174e079fa2ec2b3701363dc9bbce4687ed64b3ae


Modified Paths:
---------------
IdentityApiGit/src/main/java/javax/security/identity/IDAttributeValue.java
IdentityApiGit/src/main/java/javax/security/identity/client/ExpressionPredicateOperator.java
IdentityApiGit/src/main/java/javax/security/identity/client/IDBooleanOperator.java
IdentityApiGit/src/main/java/javax/security/identity/client/IDOperator.java
IdentityApiGit/src/main/java/javax/security/identity/client/expression/IDExpression.java
IdentityApiGit/src/main/java/javax/security/identity/permission/AttributeAction.java
IdentityApiGit/src/main/java/javax/security/identity/permission/ServiceAction.java


Diffs:
------
--- 
a/IdentityApiGit/src/main/java/javax/security/identity/IDAttributeValue.java
+++ 
b/IdentityApiGit/src/main/java/javax/security/identity/IDAttributeValue.java
@@ -29,15 +29,22 @@ public interface IDAttributeValue<T> {
      *
      * @return the singular value of the attribute if the attribute is not
      * multi-valued, or null otherwise.
+     * 
+     * A missing attribute value is represented by a return value of null 
from
+     * {@link javax.security.identity.IDAttribute#getAttributeValue()}.
      */
     T getValue();
 
     /**
      * get the value of the multi-valued attribute as a Collection.
      *
-     * @return The values of the attribute as a collection. Order, and
-     * uniqueness need to be appropriately handled by the returned collection
-     * type. An empty collection indicates an empty value.
+     * @return a Collection containing the values of the attribute, or null
+     * if the attribute is not multi-valued. Order, and uniqueness need to
+     * be appropriately handled by the returned collection type. An empty 
+     * collection indicates an empty (multi-valued) attribute value.
+     * 
+     * A missing attribute value is represented by a return value of null 
from
+     * {@link javax.security.identity.IDAttribute#getAttributeValue()}.
      */
     Collection<T> getValues();
 }--- 
a/IdentityApiGit/src/main/java/javax/security/identity/client/ExpressionPredicateOperator.java
+++ 
b/IdentityApiGit/src/main/java/javax/security/identity/client/ExpressionPredicateOperator.java
@@ -18,6 +18,35 @@ package javax.security.identity.client;
 /**
  * Interface to be implemented by all predicate operators except boolean 
  * predicate operators.
+ * <p>
+ * Expression Predicate Operators are combined with an IDExpression to define
+ * a predicate about an attribute as described in
+ * {@link javax.security.identity.client.expression.IDExpression}.
+ * The evaluation of predicate expressions to attribute aspects is dependent 
+ * on the predicate operator. The following list distinguishes the alternate
+ * expression evaluation behaviors that are used to characterize the 
required behavior
+ * of expression predicate operators such as in {@link 
javax.security.identity.client.IDOperator}.
+ * <p>
+ * Alternative expression predicate operator behaviors
+ * <ul>
+ * <li> value matched
+ * <p>can only be satisfied by an attribute instance where the aspect to 
which
+ * the expression applies matches the single valued or multi-valued nature of
+ * the expression; in which case, the corresponding value or values of the
+ * instance are evaluated against the expression.
+ * <li> single expression value
+ * <p>is only defined when used with in a single value expression, in which 
case
+ * the criteria defined by the operator and the expression must be satisfied 
by
+ * a value of the instance for the corresponding aspect. If the instance is
+ * single valued for the corresponding aspect, the criteria must be 
satisfied by
+ * the instance value. If the instance is multi-valued, the criteria must be
+ * satisfied by at least one of the instance values.
+ * <li> multi-attribute value
+ * <p> can only be satisfied by an attribute instance that is multi-valued 
for
+ * the corresponding aspect, and where for every value of the expression, at
+ * least one value of the aspect satisfies the operator with respect to the
+ * expression value.
+ * </ul>
  * 
  * @author ronmonzillo
  */--- 
a/IdentityApiGit/src/main/java/javax/security/identity/client/IDBooleanOperator.java
+++ 
b/IdentityApiGit/src/main/java/javax/security/identity/client/IDBooleanOperator.java
@@ -17,15 +17,27 @@ package javax.security.identity.client;
 
 /**
  * Enumeration of defined boolean predicate operators.
- * 
+ *
  * Additional boolean predicate operators may be defined by creating an 
another
  * enum that implements BooleanPredicateOperator.
- * 
+ *
  * @author ronmonzillo
  */
 public enum IDBooleanOperator implements 
BooleanPredicateOperator<IDBooleanOperator> {
-    
+
+    /**
+     * used to define a predicate that represents the conjunction (i.e., the
+     * logical AND) of 0 or more argument predicates.
+     */
     and,
+    /**
+     * used to define a predicate that represents the negation of an argument
+     * predicate.
+     */
     not,
+    /**
+     * used to define a predicate that represents the disjunction (i.e., the
+     * logical OR) of 0 or more argument predicates.
+     */
     or
 }--- 
a/IdentityApiGit/src/main/java/javax/security/identity/client/IDOperator.java
+++ 
b/IdentityApiGit/src/main/java/javax/security/identity/client/IDOperator.java
@@ -18,19 +18,65 @@ package javax.security.identity.client;
 /**
  *
  * Enumeration of defined expression predicate operators.
- * 
- * Additional expression predicate operators may be defined by creating an 
another
- * enum that implements ExpressionPredicateOperator.
- * 
+ *
+ * <p>
+ * The {@link javax.security.identity.client.BooleanPredicateOperator} 
interface
+ * provides additional information on the characterization and processing
+ * semantics of expression predicate operators.
+ *
  * @author ronmonzillo
  */
 public enum IDOperator implements ExpressionPredicateOperator<IDOperator> {
 
+    /**
+     * a value matched predicate operator
+     * used to define a predicate to test whether an attribute is equal to 
the
+     * value of an IDExpression in terms of the aspect represented by the 
type
+     * of the expression.
+     */
     equal,
+    /**
+     * a single expression value predicate operator 
+     * used to define a predicate to test whether an attribute is greater 
than
+     * the value of an IDExpression<C>, where C extends Serializable &
+     * Comparable<C>, in terms of the aspect represented by the type of the
+     * expression.
+     */
     greaterThan,
+    /**
+     * a single expression value predicate operator 
+     * used to define a predicate to test whether an attribute is less than 
the
+     * value of an IDExpression<C>, where C extends Serializable &
+     * Comparable<C>, in terms of the aspect represented by the type of the
+     * expression.
+     */
     lessThan,
+    /**
+     * a multi-attribute value predicate operator
+     * used to define a predicate to test whether an attribute contains the
+     * value of an IDExpression in terms of the aspect represented by the 
type
+     * of the expression.
+     */
     contains,
+    /**
+     * a single expression value predicate operator 
+     * used to define a predicate to test whether an attribute starts with 
the
+     * value of an IDExpression<String> in terms of the aspect represented by
+     * the type of the expression.
+     */
     startsWith,
+    /**
+     ** a single expression value predicate operator 
+     * used to define a predicate to test whether an attribute ends with the
+     * value of an IDExpression<String> in terms of the aspect represented by
+     * the type of the expression.
+     */
     endsWith,
+    /**
+     * a single expression value predicate operator 
+     * used to define a predicate to test whether an attribute is matched by 
the
+     * value of a RegualarExpression in terms of the attribute aspect
+     * represented by the type of the expression.
+     */
     matches
 }--- 
a/IdentityApiGit/src/main/java/javax/security/identity/client/expression/IDExpression.java
+++ 
b/IdentityApiGit/src/main/java/javax/security/identity/client/expression/IDExpression.java
@@ -25,17 +25,57 @@ import 
javax.security.identity.client.RepositoryDescriptor;
 /**
  * A statement about the value of an attribute or of a property of an 
attribute.
  *
+ * An Expression is combined with a predicate operator to define a 
predicate. 
+ * The attribute aspect to which a predicate applies is conveyed by its 
+ * ExpressionType. In the context of such predicates an attribute has four 
aspects:
+ * <ul>
+ * <li>
+ * its names (represented as a collection of names)
+ * <li>
+ * its value
+ * <li>
+ * the name of one of its properties
+ * <li>
+ * the value of one of its properties
+ * </ul>
+ * <li>
+ * Attribute names are represented as a collection (which must have at least 
one
+ * name), while the properties of attributes have exactly one name. The 
values
+ * of attributes and of the properties of attributes share a common
+ * representation in which a value may be any of missing (i.e, null), a 
singular
+ * non-null value, or a collection of zero or more values.
+ * <p>
+ * The expressions used in predicates share a common representation in which
+ * their value may be either a singular non-null value or a collection of 
zero
+ * or more values.
+ * <p>
+ * The evaluation of predicate expressions to attribute aspects is dependent 
on
+ * the predicate operator as described in 
+ * {@link javax.security.identity.client.ExpressionPredicateOperator}.
+ * 
  * @author ronmonzillo
  */
 public class IDExpression<T extends Serializable> extends IDValue<T> 
implements Serializable {
-
+        
     private static final long serialVersionUID = 1L;
 
     public static enum ExpressionType {
 
+        /*
+         * indicates that the expression applies to the name aspect of the 
attribute
+         */
         Name,
+        /*
+         * indicates that the expression applies to the value aspect of the 
attribute
+         */
         Value,
+        /*
+         * indicates that the expression applies to the property name aspect 
of the attribute
+         */
         PropertyName,
+        /*
+         * indicates that the expression applies to the property value 
aspect of the attribute
+         */
         PropertyValue
     };
     Collection<T> values;
@@ -143,8 +183,7 @@ public class IDExpression<T extends Serializable> extends 
IDValue<T> implements
      *
      */
 
-    public static <S extends Serializable> 
-    int compareTo(IDExpression<S> thisExpression, IDExpression<S> 
thatExpression) {
+    public static <S extends Serializable> int compareTo(IDExpression<S> 
thisExpression, IDExpression<S> thatExpression) {
         int rvalue = comparePointers(thisExpression, thatExpression);
         if (rvalue == 2) {
             rvalue = 
thisExpression.getExpressionType().compareTo(thatExpression.getExpressionType());
@@ -156,7 +195,7 @@ public class IDExpression<T extends Serializable> extends 
IDValue<T> implements
                 S thatValue = thatExpression.getValue();
                 rvalue = comparePointers(thisValue, thatValue);
                 if (rvalue == 2) {
-                    rvalue = IDValue.compareTo(thisValue,thatValue);
+                    rvalue = IDValue.compareTo(thisValue, thatValue);
                 } else if (rvalue == 0) {
                     Collection<S> thisValues = thisExpression.getValues();
                     Collection<S> thatValues = thatExpression.getValues();
@@ -169,7 +208,7 @@ public class IDExpression<T extends Serializable> extends 
IDValue<T> implements
                             Iterator<S> thisIt = thisValues.iterator();
                             Iterator<S> thatIt = thatValues.iterator();
                             while (rvalue == 0 && thisIt.hasNext()) {
-                                rvalue = 
IDValue.compareTo(thisIt.next(),thatIt.next());
+                                rvalue = IDValue.compareTo(thisIt.next(), 
thatIt.next());
                             }
                         }
                     }--- 
a/IdentityApiGit/src/main/java/javax/security/identity/permission/AttributeAction.java
+++ 
b/IdentityApiGit/src/main/java/javax/security/identity/permission/AttributeAction.java
@@ -22,19 +22,66 @@ package javax.security.identity.permission;
  */
 public enum AttributeAction implements PermissionAction<AttributeAction> {
 
+    /*
+     * action required to search an attribute provider for entities
+     */
     search,
+    /* 
+     * action required to seach an entity of an attribute provider for 
+     * attribute references 
+     */
     searchEntity,
+    /* 
+     * action required to get a reference for an attribute from an 
+     * attribute provider.
+     */
     getReference,
+    /* 
+     * action required to get an attribute (including by search) from an 
attribute provider
+     */
     getAttribute,
+    /* 
+     * action required to get a predicate from an attribute provider
+     */
     getPredicate,
+    /* 
+     * action required to add an entity to an attribute provider
+     */
     addEntity,
+    /* 
+     * action required to add an attribute to an entity in an attribute 
provider
+     */
     addAttribute,
+    /* 
+     * action required to add a property to an attribute in an attribute 
provider
+     */
     addProperty,
+    /* 
+     * action required to delete an entity from an attribute provider
+     */
     deleteEntity,
+    /* 
+     * action required to delete attributes from an attribute provider
+     */
     deleteAttribute,
+    /* 
+     * action required to delete a named property from attribute in an 
attribute provider
+     */
     deleteProperty,
+    /* 
+     * action required to replace all the attributes of an entity in an 
attribute provider
+     */
     replaceEntity,
+    /* 
+     * action required to replace the value of an attribute in an attribute 
provider
+     */
     replaceAttribute,
+    /* 
+     * action required to replace a named property of attributes in an 
attribute provider
+     */
     replaceProperty,
+    /* 
+     * action required to rename attributes in an attribute provider
+     */
     renameAttribute
 }--- 
a/IdentityApiGit/src/main/java/javax/security/identity/permission/ServiceAction.java
+++ 
b/IdentityApiGit/src/main/java/javax/security/identity/permission/ServiceAction.java
@@ -18,14 +18,29 @@ package javax.security.identity.permission;
 /**
  * Actions used to characterize protection of the service interfaces of the
  * attribute service.
- * 
+ *
  * @author ronmonzillo
  */
 public enum ServiceAction implements PermissionAction<ServiceAction> {
 
+    /*
+     * action required to register a repository agnet at the provider lookup 
service
+     */
     registerAgent,
+    /*
+     * action required to unregister a repository agent at the provider 
lookup service
+     */
     unregisterAgent,
+    /*
+     * action required to obtain an attribute provider from the provider 
lookup service
+     */
     getProvider,
+    /*
+     * action required to obtain the attribute loookup service for an 
attribute provider
+     */
     getLookupService,
+    /*
+     * action required to obtain the attribute update service for an 
attribute provider
+     */
     getUpdateService
 }





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

monzillo 08/29/2013
 
 
Close
loading
Please Confirm
Close