Skip to main content

[identity-api-spec commits] [identity-api-spec~git:128363be] aditorial change in comment

  • From: monzillo@...
  • To: commits@...
  • Subject: [identity-api-spec commits] [identity-api-spec~git:128363be] aditorial change in comment
  • Date: Thu, 12 Sep 2013 17:33:52 +0000

Project:    identity-api-spec
Repository: git
Revision:   128363beaff3a09f828c487afcd17e8ffe29ee73
Author:     monzillo
Date:       2013-09-12 16:25:27 UTC
Link:       

Log Message:
------------
refactored method of obtaining repository descriptor as a result of removal 
of getRepositoryDescriptor
method from AttributeRepository 
removed imp of getRepositoryDescriptor since method was removed from 
AttributeRepository interface
changed descriptor of RepositoryAgent to better describe the 
AttributeRepository that is returned by the agent,

changed inheritence hierarchy such that AttributeRepository no longer extends 
AttributeProvider by adding getRepositoryDescriptor method. No 
AttributeRepository is the base class that is extended by AttributeProvider.
AttributeProvider overides the interfaces of AttributeRepository by requiring 
that permissions be checked and that Security Exceptions be thrown. ALso 
removed getRepositoryDescriptor method as its effect could be achived by 
calling getRepositoryDescriptor on the associated ProviderLookupContext, and 
the inheritence change made it so that an AttributeRepository is no longer an 
AttributeProvider that has a non-null RepositoryDescriptor. 
changed inheritence hierarchy such that AttributeRepository no longer extends 
AttributeProvider .
Now AttributeRepository is the base class that is extended by 
AttributeProvider.
AttributeProvider overrides the interfaces of AttributeRepository by 
requiring that permissions be checked and that Security Exceptions be thrown. 
Added new interface unprotected AttributeLookupService to be returned by 
AttributeRepository
Added new interface unprotected AttributeUpdateService to be returned by 
AttributeRepository
changed AttributeUpdateService to extend unprotected RepositoryUpdateService 
returned by AttributeRepository.
As such AttributeProvider#getUpdateService now returns permission checking 
AttributeUpdateService
changed AttributeLookupService to extend unprotected RepositoryLookuoService 
returned by AttributeRepository.
As such AttributeProvider#getLookupService now returns permission checking 
AttributeLookupService
added getRepository action for use in RepositoryAgent#getAttributeRepository, 
as distinct from getProvider action that is used to protect interfaced of 
ProviderLookupService
aditorial change in comment


Revisions:
----------
bf24008c08e9c0145356b3b355e435839b19cef6
b11b46dbb63dc135685950c72c88c80dfcfce2fd
c8201992cf2eb7c4ecac86e5b0e7afe0d8341e09
a35ecef27309949f651d200e27d46255f7e89623
5e042df01b951265f28344f10e356720f048e6aa
25f0db03adb59e24415a927ee5e976103be0b39a
fe64d7e7b9bdb962bc87beb737c004253c207213
39ef4f6415a2d94f1aec8445414930eb76584bb5
347c20d4022dff058b3e332bace30615be9800e3
51a0c50260bbb48f8da3237ba7571bdeaeaadf0c
128363beaff3a09f828c487afcd17e8ffe29ee73


Modified Paths:
---------------
IdentityApiGit/src/test/java/security/identity/permission/TestAttributeRepositoryPermission.java
IdentityApiGit/src/test/java/security/identity/AttributeRepositoryForTesting.java
IdentityApiGit/src/main/java/javax/security/identity/provider/RepositoryAgent.java
IdentityApiGit/src/main/java/javax/security/identity/provider/AttributeRepository.java
IdentityApiGit/src/main/java/javax/security/identity/provider/AttributeProvider.java
IdentityApiGit/src/main/java/javax/security/identity/provider/AttributeUpdateService.java
IdentityApiGit/src/main/java/javax/security/identity/provider/AttributeLookupService.java
IdentityApiGit/src/main/java/javax/security/identity/permission/ServiceAction.java
IdentityApiGit/src/main/java/javax/security/identity/permission/AttributeRepositoryPermission.java


Added Paths:
------------
IdentityApiGit/src/main/java/javax/security/identity/provider/RepositoryLookupService.java
IdentityApiGit/src/main/java/javax/security/identity/provider/RepositoryUpdateService.java


Diffs:
------
--- 
a/IdentityApiGit/src/test/java/security/identity/permission/TestAttributeRepositoryPermission.java
+++ 
b/IdentityApiGit/src/test/java/security/identity/permission/TestAttributeRepositoryPermission.java
@@ -15,6 +15,7 @@
  */
 package security.identity.permission;
 
+import javax.security.identity.client.ProviderLookupContext;
 import javax.security.identity.client.RepositoryDescriptor;
 import javax.security.identity.permission.AttributeRepositoryPermission;
 import javax.security.identity.permission.AttributeAction;
@@ -43,7 +44,10 @@ public class TestAttributeRepositoryPermission {
     public void TestMixedActions() {
         RepositoryAgent agent = new RepositoryAgentForTesting();
         AttributeRepository repository = 
agent.getAttributeRepository("testRepository");
-        RepositoryDescriptor descriptor = 
repository.getRepositoryDescriptor();
+        ProviderLookupContext context = 
repository.getProviderLookupContext();
+        RepositoryDescriptor descriptor = context.getRepositoryDescriptor();
+        Assert.assertNotNull(descriptor);
+        
         AttributeRepositoryPermission p1, p2, p3;
 
         boolean shouldSucceed = false;
@@ -66,7 +70,9 @@ public class TestAttributeRepositoryPermission {
     public void TestMissingActions() {
         RepositoryAgent agent = new RepositoryAgentForTesting();
         AttributeRepository repository = 
agent.getAttributeRepository("testRepository");
-        RepositoryDescriptor descriptor = 
repository.getRepositoryDescriptor();
+        ProviderLookupContext context = 
repository.getProviderLookupContext();
+        RepositoryDescriptor descriptor = context.getRepositoryDescriptor();
+        Assert.assertNotNull(descriptor);
         AttributeRepositoryPermission p1, p2, p3, p4, p5;
         p1 = new AttributeRepositoryPermission<AttributeAction>(descriptor, 
AttributeAction.class);
         try {
@@ -103,7 +109,9 @@ public class TestAttributeRepositoryPermission {
     public void TestTwoStringConstructor() {
         RepositoryAgent agent = new RepositoryAgentForTesting();
         AttributeRepository repository = 
agent.getAttributeRepository("testRepository");
-        RepositoryDescriptor descriptor = 
repository.getRepositoryDescriptor();
+        ProviderLookupContext context = 
repository.getProviderLookupContext();
+        RepositoryDescriptor descriptor = context.getRepositoryDescriptor();
+        Assert.assertNotNull(descriptor);
         AttributeRepositoryPermission p1, p2, p3;
         p1 = new AttributeRepositoryPermission<AttributeAction>(descriptor, 
AttributeAction.addAttribute);
         try {

--- 
a/IdentityApiGit/src/test/java/security/identity/AttributeRepositoryForTesting.java
+++ 
b/IdentityApiGit/src/test/java/security/identity/AttributeRepositoryForTesting.java
@@ -47,11 +47,6 @@ public class AttributeRepositoryForTesting implements 
AttributeRepository {
     }
 
     @Override
-    public RepositoryDescriptor getRepositoryDescriptor() {
-        return this._descriptor;
-    }
-
-    @Override
     public ProviderLookupContext getProviderLookupContext() {
         return this._context;
     }

--- 
a/IdentityApiGit/src/main/java/javax/security/identity/provider/RepositoryAgent.java
+++ 
b/IdentityApiGit/src/main/java/javax/security/identity/provider/RepositoryAgent.java
@@ -33,9 +33,8 @@ public interface RepositoryAgent {
      * the caller has not been granted an 
      * {@link  
javax.security.identity.permission.AttributeRepositoryPermission}
      * with action 
-     * {@link  javax.security.identity.permission.ServiceAction#getProvider}
-     * for all the distinct RepositoryDescriptors occurring within 
-     * the ProviderLookupContext of the AttributeProvider. 
+     * {@link  
javax.security.identity.permission.ServiceAction#getRepository}
+     * for the RepositoryDescriptors describing the repository at the agent.
      */
     AttributeRepository getAttributeRepository(String repositoryName);
 }

--- 
a/IdentityApiGit/src/main/java/javax/security/identity/provider/AttributeRepository.java
+++ 
b/IdentityApiGit/src/main/java/javax/security/identity/provider/AttributeRepository.java
@@ -15,16 +15,245 @@
  */
 package javax.security.identity.provider;
 
-import javax.security.identity.client.RepositoryDescriptor;
+import java.io.Serializable;
+import javax.security.identity.client.BooleanPredicateOperator;
+import javax.security.identity.client.ExpressionPredicateOperator;
+import javax.security.identity.client.IDPredicate;
+import javax.security.identity.client.ProviderLookupContext;
+import javax.security.identity.client.expression.IDExpression;
+import javax.security.identity.client.expression.RegularExpression;
 
 /**
- * Extension of attribute provider interface as returned by 
+ * A provider of entity and attribute lookup and update interfaces and of a
+ * predicate builder service for use in acquiring predicates for use with the
+ * lookup interface as returned by 
  * {@link 
javax.security.identity.provider.RepositoryAgent#getAttributeRepository(java.lang.String)}.
  * 
  * @author ronmonzillo
  */
-public interface AttributeRepository extends AttributeProvider {
+public interface AttributeRepository {
 
-    RepositoryDescriptor getRepositoryDescriptor();
+    ProviderLookupContext getProviderLookupContext();
+
+    /**
+     * get the attribute lookup service associated with this Attribute 
provider
+     *
+     * @return an AttributeLookupService that is bound to the attribute 
provider
+     * and the predicate builder.
+     */
+    RepositoryLookupService getAttributeLookupService();
+
+    /**
+     * get the attribute update service associated with this Attribute 
provider
+     *
+     * @return an AttributeUpdateService that is bound to the attribute 
provider
+     * and the predicate builder or null if the provider does not support
+     * update.
+     */
+    RepositoryUpdateService getAttributeUpdateService();
+
+    /**
+     * Create a predicate that represents the conjunction of the argument
+     * predicates.
+     *
+     * @param predicates a variable length array of 0 or more IDPredicate
+     * objects.
+     * @return an IDpredicate to evaluate the logical AND of the argument
+     * predicates. When 0 predicates are passed as argument, the returned
+     * predicate evaluates to true.
+     *
+     * The returned predicate must be such that its getPredicates method 
returns
+     * the predicates passed as arguments to this method, and such that its
+     * getPredicateOperator method returns
+     * {@link javax.security.identity.client.IDBooleanOperator#and}.
+     *
+     * Note this method could have been put on IDPredicate, except then there
+     * would no way to create an empty true predicate.
+     */
+    IDPredicate and(IDPredicate... predicates);
+
+    /**
+     * Create a predicate that represents the disjunction of the argument
+     * predicates
+     *
+     * @param predicates a variable length array of 0 or more IDPredicate
+     * objects
+     * @return an IDpredicate to evaluate the logical OR of the argument
+     * predicates. When 0 predicates are passed as argument, the returned
+     * predicate evaluates to false.
+     *
+     * The returned predicate must be such that its getPredicates method 
returns
+     * the predicates passed as arguments to this method, and such that its
+     * getPredicateOperator method returns
+     * {@link javax.security.identity.client.IDBooleanOperator#or}.
+     *
+     * Note this method could have been put on IDPredicate, except then there
+     * would no way to create an empty false predicate.
+     */
+    IDPredicate or(IDPredicate... predicates);
+
+    /**
+     * Create a predicate for comparing the argument expression to the
+     * corresponding aspect of an attribute.
+     *
+     * <p><i>Note that a single value does not equal a collection with one
+     * equivalent value and collection comparison, including order dependency
+     * ,is dependent on the definition of the Collection returned by
+     * IDExpression.getValues()
+     * <i>
+     *
+     * @param x an expression of type ?
+     * @return an IDpredicate that evaluates whether an attribute is equal to
+     * the argument expression in terms of the aspects identified by the
+     * argument expression. The returned predicate must be such that its
+     * getExpression method returns the expression passed as argument to this
+     * method, and such that its getPredicateOperator method returns
+     * {@link javax.security.identity.client.IDOperator#equal}.
+     */
+    IDPredicate equal(IDExpression<? extends Serializable> x);
+
+    /**
+     * Create a predicate for testing whether an attribute is greater than 
the
+     * argument expression.
+     *
+     * @param x an expression of type Comparable
+     * @return an IDpredicate that evaluates whether an attribute is greater
+     * than the argument expression. The returned predicate must be such that
+     * its getExpression method returns the expression passed as argument to
+     * this method, and such that its getPredicateOperator method returns
+     * {@link javax.security.identity.client.IDOperator#greaterThan}.
+     */
+    <C extends Serializable & Comparable<C>> IDPredicate 
greaterThan(IDExpression<C> x);
+
+    /**
+     * Create a predicate for testing whether an attribute is less than the
+     * argument expression.
+     *
+     * @param x an expression of type Comparable
+     * @return an IDpredicate that evaluates whether an attribute is less 
than
+     * the argument expression. The returned predicate must be such that its
+     * getExpression method returns the expression passed as argument to this
+     * method, and such that its getPredicateOperator method returns
+     * {@link javax.security.identity.client.IDOperator#lessThan}.
+     */
+    <C extends Serializable & Comparable<C>> IDPredicate 
lessThan(IDExpression<C> x);
+
+    /**
+     * Create a predicate for testing whether an attribute contains the 
argument
+     * expression.
+     *
+     * The type of the argument expression establishes whether the 
attribute's
+     * names or values are tested for containment. The corresponding aspect 
of
+     * the attribute must be multi-valued in order for it to contain those in
+     * the expression, and for a multi-valued expression to be contained, the
+     * attribute's corresponding aspect must contain all those in the
+     * expression.
+     *
+     * @param x an expression
+     * @return an IDpredicate that tests whether an attribute contains the
+     * argument expression. The returned predicate must be such that its
+     * getExpression method returns the expression passed as argument to this
+     * method, and such that its getPredicateOperator method returns
+     * {@link javax.security.identity.client.IDOperator#contains}.
+     */
+    IDPredicate contains(IDExpression<? extends Serializable> x);
+
+    /**
+     * Create a predicate for testing whether an attribute starts with the
+     * argument String expression.
+     *
+     * @param x an expression of type String
+     * @return an IDpredicate that evaluates whether an attribute starts with
+     * the argument String expression. The returned predicate must be such 
that
+     * its getExpression method returns the expression passed as argument to
+     * this method, and such that its getPredicateOperator method returns
+     * {@link javax.security.identity.client.IDOperator#startsWith}.
+     */
+    IDPredicate startsWith(IDExpression<String> x);
+
+    /**
+     * Create a predicate for testing whether an attribute ends with the
+     * argument String expression.
+     *
+     * @param x an expression of type String
+     * @return an IDpredicate that evaluates whether an attribute ends with 
the
+     * argument String expression. The returned predicate must be such that 
its
+     * getExpression method returns the expression passed as argument to this
+     * method, and such that its getPredicateOperator method returns
+     * {@link javax.security.identity.client.IDOperator#endsWith}.
+     */
+    IDPredicate endsWith(IDExpression<String> x);
+
+    /**
+     * Create a predicate for testing whether the argument regular expression
+     * matches the attribute
+     *
+     * @param x a ReqularExpression
+     * @return an IDpredicate that evaluates whether an attribute is matched 
by
+     * the regular expression. The returned predicate must be such that its
+     * getExpression method returns the expression passed as argument to this
+     * method, and such that its getPredicateOperator method returns
+     * {@link javax.security.identity.client.IDOperator#matches}.
+     */
+    IDPredicate matches(RegularExpression x);
+
+    /**
+     * Extensibility point for the predicate builder aspect of the attribute
+     * provider interface. This method creates a predicate for testing 
whether
+     * an attribute corresponds, according to the argument operator to the
+     * expression passed as argument.
+     *
+     * @param operator an enum that extends the ExpressionPredicateOperator
+     * interface, and that identifies the function to be used in the 
evaluation
+     * of the correspondence between an attribute and the expression.
+     * @param x an IDExpression formed from value(s) that implement
+     * Serializable.
+     * @return an IDpredicate that evaluates whether an attribute 
corresponds to
+     * the expression according to the argument operator. The returned 
predicate
+     * must be such that its getExpression method returns the argument
+     * expression passed to this method, and such that its 
getPredicateOperator
+     * method returns the operator passed to this method.
+     *
+     * @throws UnsupportedOperationException if the argument operator is not
+     * supported by the attribute provider.
+     *
+     * @throws IllegalArgumentException if one or more of the argument
+     * predicates were not acquired from an attribute provider with an
+     * equivalent ProviderLookupContext to this attribute provider.
+     *
+     * @throws IllegalArgumentException if the argument expression is
+     * incompatible with the argument operation
+     */
+    IDPredicate getPredicate(ExpressionPredicateOperator<? extends Enum<?>> 
operator, IDExpression<? extends Serializable> x);
+
+    /**
+     * Extensibility point for the predicate builder aspect of the attribute
+     * provider interface. This method creates a predicate from 0 or more
+     * argument predicates.
+     *
+     * @param operator an enum that extends the BooleanPredicateOperator
+     * interface, and that identifies the boolean function to be used to 
create
+     * the predicate from the argument predicates.
+     *
+     * @param predicates an array of zero or more IDPredicates from which a
+     * predicate is to be created.
+     *
+     * @return an IDpredicate that performs the boolean operation over the
+     * argument predicates. The returned predicate must be such that its
+     * getPredicates method returns the argument predicates passed to this
+     * method, and such that its getPredicateOperator method returns argument
+     * operator passed to this method.
+     *
+     * @throws UnsupportedOperationException if the argument operator is not
+     * supported by the attribute provider.
+     *
+     * @throws IllegalArgumentException if one or more of the argument
+     * predicates were not acquired from an AttributeProvider with an 
equivalent
+     * ProviderLookupContext to this attribute provider.
+     *
+     * @throws IllegalArgumentException if one or more of the argument
+     * predicates are incompatible with the attribute provider.
+     */
+    IDPredicate getPredicate(BooleanPredicateOperator<? extends Enum<?>> 
operator, IDPredicate... predicates);
     
 }

--- 
a/IdentityApiGit/src/main/java/javax/security/identity/provider/AttributeProvider.java
+++ 
b/IdentityApiGit/src/main/java/javax/security/identity/provider/AttributeProvider.java
@@ -13,7 +13,6 @@
  *
  * http://www.apache.org/licenses/LICENSE-2.0
  */
-
 package javax.security.identity.provider;
 
 import java.io.Serializable;
@@ -25,351 +24,172 @@ import 
javax.security.identity.client.expression.IDExpression;
 import javax.security.identity.client.expression.RegularExpression;
 
 /**
- * The provider of entity and attribute lookup and update interfaces and
- * of a predicate builder service for use in acquiring predicates for use
- * with the lookup interface.
+ * The provider of entity and attribute lookup and update interfaces and of a
+ * predicate builder service for use in acquiring predicates for use with the
+ * lookup interface.
  *
  * @author ronmonzillo
  */
-public interface AttributeProvider {
+public interface AttributeProvider extends AttributeRepository {
 
-    /**
-     * get the context that may be used to lookup the provider from the
-     * ProviderLookupService of the attribute service.
-     *
-     * @return a ProviderLookupContext that can be used to obtain the
-     * AttributeProvider.
-     */
+    @Override
     ProviderLookupContext getProviderLookupContext();
 
     /**
-     * get the attribute lookup service associated with this Attribute 
provider
-     *
-     * @return an AttributeLookupService that is bound to the attribute
-     * provider and the predicate builder
-     *
-     * @throws SecurityException if a SecurityManager is enabled and
-     * the caller has not been granted an
+     * @throws SecurityException if a SecurityManager is enabled and the 
caller
+     * has not been granted an
      * {@link  
javax.security.identity.permission.AttributeRepositoryPermission}
      * with action
      * {@link  
javax.security.identity.permission.ServiceAction#getLookupService}
-     * for all the distinct RepositoryDescriptors occurring within
-     * the ProviderLookupContexts of the AttributeProvider.
+     * for all the distinct RepositoryDescriptors occurring within the
+     * ProviderLookupContexts of the AttributeProvider.
      */
+    @Override
     AttributeLookupService getAttributeLookupService();
 
     /**
-     * get the attribute update service associated with this Attribute 
provider
-     *
-     * @return an AttributeUpdateService that is bound to the attribute 
-     * provider and the predicate builder or null if the provider does not
-     * support update.
-     *
-     * @throws SecurityException if a SecurityManager is enabled and
-     * the caller has not been granted an
+     * @throws SecurityException if a SecurityManager is enabled and the 
caller
+     * has not been granted an
      * {@link  
javax.security.identity.permission.AttributeRepositoryPermission}
      * with action
      * {@link  
javax.security.identity.permission.ServiceAction#getUpdateService}
-     * for all the distinct RepositoryDescriptors occurring within
-     * the ProviderLookupContexts of the AttributeProvider.
+     * for all the distinct RepositoryDescriptors occurring within the
+     * ProviderLookupContexts of the AttributeProvider.
      */
+    @Override
     AttributeUpdateService getAttributeUpdateService();
 
     /**
-     * Create a predicate that represents the conjunction of the argument
-     * predicates.
-     *
-     * @param predicates a variable length array of 0 or more IDPredicate
-     * objects.
-     * @return an IDpredicate to evaluate the logical AND of the argument
-     * predicates. When 0 predicates are passed as argument, the returned
-     * predicate evaluates to true.
-     * 
-     * The returned predicate must be such that its
-     * getPredicates method returns the predicates passed as arguments to
-     * this method, and such that its getPredicateOperator method returns
-     * {@link javax.security.identity.client.IDBooleanOperator#and}.
-     *
-     * @throws SecurityException if a SecurityManager is enabled and 
-     * the caller has not been granted an
+     * @throws SecurityException if a SecurityManager is enabled and the 
caller
+     * has not been granted an
      * {@link  
javax.security.identity.permission.AttributeRepositoryPermission}
      * with action
      * {@link  
javax.security.identity.permission.AttributeAction#getPredicate}
-     * for all the distinct RepositoryDescriptors occurring within
-     * the ProviderLookupContexts of the AttributeProvider.
-     *
-     * Note this method could have been put on IDPredicate, except then there
-     * would no way to create an empty true predicate.
+     * for all the distinct RepositoryDescriptors occurring within the
+     * ProviderLookupContexts of the AttributeProvider.
      */
+    @Override
     IDPredicate and(IDPredicate... predicates);
 
     /**
-     * Create a predicate that represents the disjunction of the argument
-     * predicates
-     *
-     * @param predicates a variable length array of 0 or more IDPredicate
-     * objects
-     * @return an IDpredicate to evaluate the logical OR of the argument
-     * predicates. When 0 predicates are passed as argument, the returned
-     * predicate evaluates to false.
-     * 
-     * The returned predicate must be such that its
-     * getPredicates method returns the predicates passed as arguments to
-     * this method, and such that its getPredicateOperator method returns
-     * {@link javax.security.identity.client.IDBooleanOperator#or}.
-     *
-     * @throws SecurityException if a SecurityManager is enabled and
-     * the caller has not been granted an
+     * @throws SecurityException if a SecurityManager is enabled and the 
caller
+     * has not been granted an
      * {@link  
javax.security.identity.permission.AttributeRepositoryPermission}
      * with action
      * {@link  
javax.security.identity.permission.AttributeAction#getPredicate}
-     * for all the distinct RepositoryDescriptors occurring within
-     * the ProviderLookupContexts of the AttributeProvider.
-     *
-     * Note this method could have been put on IDPredicate, except then there
-     * would no way to create an empty false predicate.
+     * for all the distinct RepositoryDescriptors occurring within the
+     * ProviderLookupContexts of the AttributeProvider.
      */
-     IDPredicate or(IDPredicate... predicates);
-     
+    @Override
+    IDPredicate or(IDPredicate... predicates);
+
     /**
-     * Create a predicate for comparing the argument expression to the
-     * corresponding aspect of an attribute.
-     *
-     * <p><i>Note that a single value does not equal a collection with one
-     * equivalent value and collection comparison, including order
-     * dependency ,is dependent on the definition of the Collection
-     * returned by IDExpression.getValues()
-     * <i>
-     * @param x an expression of type ?
-     * @return an IDpredicate that evaluates whether an attribute is equal to
-     * the argument expression in terms of the aspects identified by the
-     * argument expression.
-     * The returned predicate must be such that its
-     * getExpression method returns the expression passed as argument to
-     * this method, and such that its getPredicateOperator method returns
-     * {@link javax.security.identity.client.IDOperator#equal}.
-     *
-     * @throws SecurityException if a SecurityManager is enabled and 
-     * the caller has not been granted an
+     * @throws SecurityException if a SecurityManager is enabled and the 
caller
+     * has not been granted an
      * {@link  
javax.security.identity.permission.AttributeRepositoryPermission}
      * with action
      * {@link  
javax.security.identity.permission.AttributeAction#getPredicate}
-     * for all the distinct RepositoryDescriptors occurring within
-     * the ProviderLookupContexts of the AttributeProvider.
+     * for all the distinct RepositoryDescriptors occurring within the
+     * ProviderLookupContexts of the AttributeProvider.
      */
+    @Override
     IDPredicate equal(IDExpression<? extends Serializable> x);
 
     /**
-     * Create a predicate for testing whether an attribute is greater than 
the
-     * argument expression.
-     *
-     * @param x an expression of type Comparable
-     * @return an IDpredicate that evaluates whether an attribute is greater 
than
-     * the argument expression.
-     * The returned predicate must be such that its
-     * getExpression method returns the expression passed as argument to
-     * this method, and such that its getPredicateOperator method returns
-     * {@link javax.security.identity.client.IDOperator#greaterThan}.
-     *
-     * @throws SecurityException if a SecurityManager is enabled and 
-     * the caller has not been granted an
+     * @throws SecurityException if a SecurityManager is enabled and the 
caller
+     * has not been granted an
      * {@link  
javax.security.identity.permission.AttributeRepositoryPermission}
      * with action
      * {@link  
javax.security.identity.permission.AttributeAction#getPredicate}
-     * for all the distinct RepositoryDescriptors occurring within
-     * the ProviderLookupContexts of the AttributeProvider.
+     * for all the distinct RepositoryDescriptors occurring within the
+     * ProviderLookupContexts of the AttributeProvider.
      */
-     <C extends Serializable & Comparable<C>> IDPredicate 
greaterThan(IDExpression<C> x);
-     
+    @Override
+    <C extends Serializable & Comparable<C>> IDPredicate 
greaterThan(IDExpression<C> x);
+
     /**
-     * Create a predicate for testing whether an attribute is less than the
-     * argument expression.
-     *
-     * @param x an expression of type Comparable
-     * @return an IDpredicate that evaluates whether an attribute is less 
than
-     * the argument expression. 
-     * The returned predicate must be such that its
-     * getExpression method returns the expression passed as argument to
-     * this method, and such that its getPredicateOperator method returns
-     * {@link javax.security.identity.client.IDOperator#lessThan}.
-     *
-     * @throws SecurityException if a SecurityManager is enabled and 
-     * the caller has not been granted an
+     * @throws SecurityException if a SecurityManager is enabled and the 
caller
+     * has not been granted an
      * {@link  
javax.security.identity.permission.AttributeRepositoryPermission}
      * with action
      * {@link  
javax.security.identity.permission.AttributeAction#getPredicate}
-     * for all the distinct RepositoryDescriptors occurring within 
-     * the ProviderLookupContexts of the AttributeProvider.
+     * for all the distinct RepositoryDescriptors occurring within the
+     * ProviderLookupContexts of the AttributeProvider.
      */
-     <C extends Serializable & Comparable<C>> IDPredicate 
lessThan(IDExpression<C> x);
-    
+    @Override
+    <C extends Serializable & Comparable<C>> IDPredicate 
lessThan(IDExpression<C> x);
+
     /**
-     * Create a predicate for testing whether an attribute contains the 
argument
-     * expression.
-     * 
-     * The type of the argument expression establishes whether the 
attribute's
-     * names or values are tested for containment. The corresponding aspect 
of
-     * the attribute must be multi-valued in order for it to contain those 
in the
-     * expression, and for a multi-valued expression to be contained, the
-     * attribute's corresponding aspect must contain all those in the 
expression.
-     *
-     * @param x an expression
-     * @return an IDpredicate that tests whether an attribute contains the
-     * argument expression. 
-     * The returned predicate must be such that its
-     * getExpression method returns the expression passed as argument to
-     * this method, and such that its getPredicateOperator method returns
-     * {@link javax.security.identity.client.IDOperator#contains}.
-     *
-     * @throws SecurityException if a SecurityManager is enabled and
-     * the caller has not been granted an
+     * @throws SecurityException if a SecurityManager is enabled and the 
caller
+     * has not been granted an
      * {@link  
javax.security.identity.permission.AttributeRepositoryPermission}
      * with action
      * {@link  
javax.security.identity.permission.AttributeAction#getPredicate}
-     * for all the distinct RepositoryDescriptors occurring within
-     * the ProviderLookupContexts of the AttributeProvider.
+     * for all the distinct RepositoryDescriptors occurring within the
+     * ProviderLookupContexts of the AttributeProvider.
      */
+    @Override
     IDPredicate contains(IDExpression<? extends Serializable> x);
 
     /**
-     * Create a predicate for testing whether an attribute starts with the
-     * argument String expression.
-     *
-     * @param x an expression of type String
-     * @return an IDpredicate that evaluates whether an attribute starts 
with the
-     * argument String expression. 
-     * The returned predicate must be such that its
-     * getExpression method returns the expression passed as argument to
-     * this method, and such that its getPredicateOperator method returns
-     * {@link javax.security.identity.client.IDOperator#startsWith}.
-     *
-     * @throws SecurityException if a SecurityManager is enabled and
-     * the caller has not been granted an
+     * @throws SecurityException if a SecurityManager is enabled and the 
caller
+     * has not been granted an
      * {@link  
javax.security.identity.permission.AttributeRepositoryPermission}
      * with action
      * {@link  
javax.security.identity.permission.AttributeAction#getPredicate}
-     * for all the distinct RepositoryDescriptors occurring within
-     * the ProviderLookupContexts of the AttributeProvider.
+     * for all the distinct RepositoryDescriptors occurring within the
+     * ProviderLookupContexts of the AttributeProvider.
      */
-     IDPredicate startsWith(IDExpression<String> x);
-     
+    @Override
+    IDPredicate startsWith(IDExpression<String> x);
+
     /**
-     * Create a predicate for testing whether an attribute ends with the
-     * argument String expression.
-     *
-     * @param x an expression of type String
-     * @return an IDpredicate that evaluates whether an attribute ends with 
the
-     * argument String expression. 
-     * The returned predicate must be such that its
-     * getExpression method returns the expression passed as argument to
-     * this method, and such that its getPredicateOperator method returns
-     * {@link javax.security.identity.client.IDOperator#endsWith}.
-     *
-     * @throws SecurityException if a SecurityManager is enabled and
-     * the caller has not been granted an
+     * @throws SecurityException if a SecurityManager is enabled and the 
caller
+     * has not been granted an
      * {@link  
javax.security.identity.permission.AttributeRepositoryPermission}
      * with action
      * {@link  
javax.security.identity.permission.AttributeAction#getPredicate}
-     * for all the distinct RepositoryDescriptors occurring within
-     * the ProviderLookupContexts of the AttributeProvider.
+     * for all the distinct RepositoryDescriptors occurring within the
+     * ProviderLookupContexts of the AttributeProvider.
      */
-     IDPredicate endsWith(IDExpression<String> x);
-     
+    @Override
+    IDPredicate endsWith(IDExpression<String> x);
+
     /**
-     * Create a predicate for testing whether the argument regular expression
-     * matches the attribute
-     *
-     * @param x a ReqularExpression
-     * @return an IDpredicate that evaluates whether an attribute is matched 
by
-     * the regular expression. 
-     * The returned predicate must be such that its
-     * getExpression method returns the expression passed as argument to
-     * this method, and such that its getPredicateOperator method returns
-     * {@link javax.security.identity.client.IDOperator#matches}.
-     * 
-     * @throws SecurityException if a SecurityManager is enabled and
-     * the caller has not been granted an
+     * @throws SecurityException if a SecurityManager is enabled and the 
caller
+     * has not been granted an
      * {@link  
javax.security.identity.permission.AttributeRepositoryPermission}
      * with action
      * {@link  
javax.security.identity.permission.AttributeAction#getPredicate}
-     * for all the distinct RepositoryDescriptors occurring within
-     * the ProviderLookupContexts of the AttributeProvider.
+     * for all the distinct RepositoryDescriptors occurring within the
+     * ProviderLookupContexts of the AttributeProvider.
      */
-     IDPredicate matches(RegularExpression x);
+    @Override
+    IDPredicate matches(RegularExpression x);
 
     /**
-     * Extensibility point for the predicate builder aspect of the attribute
-     * provider interface. This method creates a predicate for testing 
whether
-     * an attribute corresponds, according to the argument operator to the
-     * expression passed as argument.
-     *
-     * @param operator an enum that extends the ExpressionPredicateOperator 
interface, and 
-     * that identifies the function to be used in the evaluation of
-     * the correspondence between an attribute and the expression.
-     * @param x an IDExpression formed from value(s) that implement
-     * Serializable.
-     * @return an IDpredicate that evaluates whether an attribute 
corresponds to
-     * the expression according to the argument operator.      
-     * The returned predicate must be such that its getExpression method 
-     * returns the argument expression passed to this method, and such that 
-     * its getPredicateOperator method returns the operator passed to this
-     * method.
-     *  
-     * @throws UnsupportedOperationException if the argument operator is not
-     * supported by the attribute provider.
-     * 
-     * @throws IllegalArgumentException if one or more of the argument 
-     * predicates were not acquired from an attribute provider with an 
equivalent
-     * ProviderLookupContext to this attribute provider.
-     *
-     * @throws IllegalArgumentException if the argument expression is
-     * incompatible with the argument operation
-     * @throws SecurityException if a SecurityManager is enabled and
-     * the caller has not been granted an
+     * @throws SecurityException if a SecurityManager is enabled and the 
caller
+     * has not been granted an
      * {@link  
javax.security.identity.permission.AttributeRepositoryPermission}
      * with action
      * {@link  
javax.security.identity.permission.AttributeAction#getPredicate}
-     * for all the distinct RepositoryDescriptors occurring within
-     * the ProviderLookupContexts of the AttributeProvider.
+     * for all the distinct RepositoryDescriptors occurring within the
+     * ProviderLookupContexts of the AttributeProvider.
      */
+    @Override
     IDPredicate getPredicate(ExpressionPredicateOperator<? extends Enum<?>> 
operator, IDExpression<? extends Serializable> x);
 
     /**
-     * Extensibility point for the predicate builder aspect of the attribute
-     * provider interface. This method creates a predicate from 0 or more
-     * argument predicates.
-     *
-     * @param operator an enum that extends the BooleanPredicateOperator
-     * interface, and that identifies the boolean function to be used to
-     * create the predicate from the argument predicates.
-     *
-     * @param predicates an array of zero or more IDPredicates from which a
-     * predicate is to be created.
-     *
-     * @return an IDpredicate that performs the boolean operation over the
-     * argument predicates.
-     * The returned predicate must be such that its getPredicates method 
-     * returns the argument predicates passed to this method, and such that 
-     * its getPredicateOperator method returns argument operator
-     * passed to this method.
-     *
-     * @throws UnsupportedOperationException if the argument operator is not
-     * supported by the attribute provider.
-     *
-     * @throws IllegalArgumentException if one or more of the argument 
-     * predicates were not acquired from an AttributeProvider with an 
equivalent
-     * ProviderLookupContext to this attribute provider.
-     *
      * @throws IllegalArgumentException if one or more of the argument
      * predicates are incompatible with the attribute provider.
-     * @throws SecurityException if a SecurityManager is enabled 
-     * and the caller has not been granted an
+     * @throws SecurityException if a SecurityManager is enabled and the 
caller
+     * has not been granted an
      * {@link  
javax.security.identity.permission.AttributeRepositoryPermission}
      * with action
      * {@link  
javax.security.identity.permission.AttributeAction#getPredicate}
-     * for all the distinct RepositoryDescriptors occurring within
-     * the ProviderLookupContexts of the AttributeProvider.
+     * for all the distinct RepositoryDescriptors occurring within the
+     * ProviderLookupContexts of the AttributeProvider.
      */
+    @Override
     IDPredicate getPredicate(BooleanPredicateOperator<? extends Enum<?>> 
operator, IDPredicate... predicates);
-     
 }

--- /dev/null
+++ 
b/IdentityApiGit/src/main/java/javax/security/identity/provider/RepositoryLookupService.java
@@ -0,0 +1,138 @@
+/*
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
+ *
+ * Copyright (c) 2011-2012 Oracle and/or its affiliates. All rights reserved.
+ *
+ * The contents of this file are subject to the JSR 351 Specification
+ * License at:
+ *
+ * 
http://jcp.org/aboutJava/communityprocess/licenses/jsr351/351SpecLicenseIdentityJSR.pdf
+ *
+ * The JSR 351 Reference Implementation is Licensed under Apache License, 
+ * version 2.0, at:
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+package javax.security.identity.provider;
+
+import java.util.Collection;
+import javax.security.identity.IDAttribute;
+import javax.security.identity.IDAttributeReference;
+import javax.security.identity.IDEntityReference;
+import javax.security.identity.client.AttributeSelector;
+import javax.security.identity.client.PropertySelector;
+
+/**
+ * Entity and attribute lookup interfaces obtained from the corresponding
+ * attribute provider.
+ *
+ * @author ronmonzillo
+ */
+public interface RepositoryLookupService {
+
+    /**
+     * Return a reference to the one or more entities that satisfy the query.
+     *
+     * @param entitySelectors an array of predicates that represent the
+     * attribute name and value relationships that identify the entities to 
be
+     * returned. For an entity to be selected, it must contain at least one
+     * attribute that satisfies each of the existence predicates. if no 
+     * entitySelector arguments are passed, then no entities are to be 
selected
+     * by the search.
+     *
+     * @return a Collection of EntityReferences that can be used to interact
+     * with the entities that satisfy the query.
+     */
+    Collection<IDEntityReference> search(AttributeSelector ... 
entitySelectors);
+
+    /**
+     * Given an entity reference, an attributeSelector, and 0 or more
+     * propertySelectors, return references to the attributes of the entity 
that
+     * satisfy the attribute selector, and that contain properties sufficient
+     * to satisfy all of propertySelectors.
+     * 
+     * @param entity a reference that identifies the entity whose attribute
+     * references are to be returned
+     * 
+     * @param attributeSelector an attribute name and or attribute value 
based
+     * predicate that identifies the attributes whose references are to be
+     * returned.
+     * 
+     * @param propertySelectors an array of predicates that represent the
+     * property name and property value relationships that must be satisfied
+     * by the selected attributes. For an attribute to be selected, it must
+     * contain at least one property that satisfies each of the property 
+     * selectors. if no propertySelector arguments are passed, then 
attributes
+     * are to be selected based solely on the attributeSelector.
+     * 
+     * @return a Collection of AttributeReferences that can be used to 
interact
+     * with the attributes that satisfy the selectors.
+     */
+    Collection<IDAttributeReference> 
getAttributeReferences(IDEntityReference entity, AttributeSelector 
attributeSelector, PropertySelector ... propertySelectors);
+
+    /**
+     * Given an entity reference, an attributeSelector, and 0 or more
+     * propertySelectors, return the attributes of the entity that
+     * satisfy the attribute selector, and that contain properties sufficient
+     * to satisfy all of propertySelectors.
+     *
+     * @param entity a reference that identifies the entity whose attributes 
are
+     * to be returned
+     * 
+     * @param attributeSelector an attribute name and or attribute value 
based
+     * predicate that identifies the attributes that are to be returned.
+     * 
+     * @param propertySelectors an array of predicates that represent the
+     * property name and property value relationships that must be satisfied
+     * by the selected attributes. For an attribute to be selected, it must
+     * contain at least one property that satisfies each of property 
selectors.
+     * if no propertySelector arguments are passed, then attributes
+     * are to be selected based solely on the attributeSelector.
+     * 
+     * @return A collection containing the attributes selected from the 
entity.
+     */
+    Collection<IDAttribute> getAttributes(IDEntityReference entity, 
AttributeSelector attributeSelector, PropertySelector ... propertySelectors);
+
+    /**
+     * Given a collection of attribute references, returns the collection of
+     * attributes referenced by the references.
+     *
+     * @param references a Collection<IDAttributeReference> that identify the
+     * attributes to be returned.
+     *
+     * @return a collection<IDAttribute> containing, one IDAttribute for each
+     * reference in the argument collection.
+     */
+    Collection<IDAttribute> getAttributes(Collection<IDAttributeReference> 
references);
+
+    /**
+     * Given an attribute reference, returns the attribute referenced by the
+     * reference.
+     *
+     * @param reference an IDAttributeReference that identifies the 
attribute to
+     * be returned.
+     *
+     * @return the referenced IDAttribute.
+     */
+    IDAttribute getAttribute(IDAttributeReference reference);
+    
+    /**
+     * Convenience function to get references to all the attributes of a
+     * referenced entity
+     *
+     * @param entity the entity reference
+     * @return a Collection<IDAttributeReference> containing reference to the
+     * attributes of the referenced entity. 
+    */
+    Collection<IDAttributeReference> 
getAttributeReferences(IDEntityReference entity);
+    
+    /**
+     * Convenience function to get all the attributes of a referenced entity
+     *
+     * @param entity the entity reference
+     * @return a Collection<IDAttribute> containing the attributes of the
+     * referenced entity. 
+     */
+    Collection<IDAttribute> getAttributes(IDEntityReference entity);
+
+}

--- /dev/null
+++ 
b/IdentityApiGit/src/main/java/javax/security/identity/provider/RepositoryUpdateService.java
@@ -0,0 +1,367 @@
+/*
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
+ *
+ * Copyright (c) 2011-2012 Oracle and/or its affiliates. All rights reserved.
+ *
+ * The contents of this file are subject to the JSR 351 Specification
+ * License at:
+ *
+ * 
http://jcp.org/aboutJava/communityprocess/licenses/jsr351/351SpecLicenseIdentityJSR.pdf
+ *
+ * The JSR 351 Reference Implementation is Licensed under Apache License, 
+ * version 2.0, at:
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+package javax.security.identity.provider;
+
+import java.util.Collection;
+import javax.security.identity.*;
+import javax.security.identity.client.expression.IDName;
+
+/**
+ * Entity and attribute update interfaces obtained from the corresponding
+ * attribute provider.
+ *
+ * @author ronmonzillo
+ */
+public interface RepositoryUpdateService {
+    
+    /**
+     * Issues
+     * 1. how should input IDNamedValues be created.
+     * 2. define thrown exceptions
+     */
+    
+    /**
+     * Create a new entity and assign to it a collection of attributes
+     * 
+     * @param attributes the Collection of IDNamedAttributeValue objects 
used to define
+     * the attributes to be assigned to the entity. the Collection may be 
null
+     * or empty.
+     * 
+     * @return a reference to the new entity.
+     * 
+     * @throws SecurityException if a SecurityManager is enabled and 
+     * the caller has not been granted an 
+     * {@link  
javax.security.identity.permission.AttributeRepositoryPermission}
+     * with action 
+     * {@link  javax.security.identity.permission.AttributeAction#addEntity}
+     * for all the distinct RepositoryDescriptors occurring within 
+     * the ProviderLookupContext of the AttributeProvider. 
+     */
+
+    IDEntityReference addEntity(Collection<IDNamedAttributeValue> 
attributes);
+    
+    /**
+     * Add an attribute to the referenced entity
+     *  
+     * @param entity an IDEntityReference that identifies the entity to which
+     * the attribute is to be added.
+     * 
+     * @param attribute the IDNamedAttributeValue used to define the 
attribute to 
+     * added to the entity.
+     * 
+     * @return an IDAttributeReeference to the added attribute
+     * 
+     * @throws SecurityException if a SecurityManager is enabled and 
+     * the caller has not been granted an 
+     * {@link  
javax.security.identity.permission.AttributeRepositoryPermission}
+     * with action 
+     * {@link  
javax.security.identity.permission.AttributeAction#addAttribute}
+     * for all the distinct RepositoryDescriptors occurring within 
+     * the ProviderLookupContext of the AttributeProvider. 
+     */
+    IDAttributeReference addAttribute(IDEntityReference entity, 
IDNamedAttributeValue attribute);
+    
+    /**
+     * Add a collection of attributes to the referenced entity
+     * 
+     * @param entity an IDEntityReference that identifies the entity to which
+     * the attributes are to be added.
+     * 
+     * @param attributes the Collection of IDNamedAttributeValue objects 
used to define
+     * the attributes to be assigned to the entity. the Collection may be 
null
+     * or empty.
+     * 
+     * @return a Collection containing an IDAttributeReference to each added
+     * attribute.
+     * 
+     * @throws SecurityException if a SecurityManager is enabled and 
+     * the caller has not been granted an 
+     * {@link  
javax.security.identity.permission.AttributeRepositoryPermission}
+     * with action 
+     * {@link  
javax.security.identity.permission.AttributeAction#addAttribute}
+     * for all the distinct RepositoryDescriptors occurring within 
+     * the ProviderLookupContext of the AttributeProvider. 
+     */
+    Collection<IDAttributeReference> addAttributes(IDEntityReference entity, 
Collection<IDNamedAttributeValue> attributes);
+    
+    /**
+     * Add a property to an attribute. If a property by the same name 
already exists in
+     * the attribute, its value is replaced by this call.
+     * 
+     * @param attribute a reference to the attribute to which the property 
is to
+     * be added
+     * @param propertyName the name of the property to be added
+     * @param propertyValue the value of the property to be added
+     * 
+     * @return true or false to indicate whether or not the property was
+     * successfully added; with true indicating success.
+     * 
+     * @throws SecurityException if a SecurityManager is enabled and 
+     * the caller has not been granted an 
+     * {@link  
javax.security.identity.permission.AttributeRepositoryPermission}
+     * with action 
+     * {@link  
javax.security.identity.permission.AttributeAction#addProperty}
+     * for all the distinct RepositoryDescriptors occurring within 
+     * the ProviderLookupContext of the AttributeProvider. 
+     */
+    boolean addProperty(IDAttributeReference attribute, IDName propertyName, 
IDAttributeValue propertyValue);
+
+    /**
+     * Delete the referenced entity
+     * 
+     * @param entity an IDEntityReference that identifies the entity to be 
deleted.
+     * @return true or false to indicate whether or not the entity was
+     * successfully deleted; with true indicating success.
+     * 
+     * @throws SecurityException if a SecurityManager is enabled and 
+     * the caller has not been granted an 
+     * {@link  
javax.security.identity.permission.AttributeRepositoryPermission}
+     * with action 
+     * {@link  
javax.security.identity.permission.AttributeAction#deleteEntity}
+     * for all the distinct RepositoryDescriptors occurring within 
+     * the ProviderLookupContext of the AttributeProvider. 
+     */
+    boolean deleteEntity(IDEntityReference entity);
+    
+    /**
+     * Delete the referenced attribute
+     * 
+     * @param attribute a reference to the attribute to be deleted.
+     * 
+     * @return true or false to indicate whether or not the attribute was
+     * successfully deleted; with true indicating success.
+     * 
+     * @throws SecurityException if a SecurityManager is enabled and 
+     * the caller has not been granted an 
+     * {@link  
javax.security.identity.permission.AttributeRepositoryPermission}
+     * with action 
+     * {@link  
javax.security.identity.permission.AttributeAction#deleteAttribute}
+     * for all the distinct RepositoryDescriptors occurring within 
+     * the ProviderLookupContext of the AttributeProvider. 
+     */
+    boolean deleteAttribute(IDAttributeReference attribute);
+    
+    /**
+     * Delete the referenced attributes
+     * 
+     * @param attributes Collection of references identifying the
+     * attributes to be deleted. The references may be to attributes
+     * in different entities.
+     * 
+     * @return null or a non-empty Collection<IDAttributeRefence> containing 
the
+     * references to any attributes that could not be deleted.
+     * 
+     * @throws SecurityException if a SecurityManager is enabled and 
+     * the caller has not been granted an 
+     * {@link  
javax.security.identity.permission.AttributeRepositoryPermission}
+     * with action 
+     * {@link  
javax.security.identity.permission.AttributeAction#deleteAttribute}
+     * for all the distinct RepositoryDescriptors occurring within 
+     * the ProviderLookupContext of the AttributeProvider. 
+     */
+    Collection<IDAttributeReference> 
deleteAttributes(Collection<IDAttributeReference> attributes);
+
+    /**
+     * Delete the named property from the referenced attribute.
+     * 
+     * @param attribute the reference to the target attribute.
+     * @param propertyName the name of the property to be deleted.
+     *
+     * @return true or false to indicate whet
[truncated due to length]



[identity-api-spec commits] [identity-api-spec~git:128363be] aditorial change in comment

monzillo 09/12/2013
 
 
Close
loading
Please Confirm
Close