s1651 - More tests, documentation

projects/cadcAccessControl/src/ca/nrc/cadc/ac/client/GMSClient.java

@@ -107,7 +107,8 @@ import ca.nrc.cadc.net.HttpUpload;
 import ca.nrc.cadc.net.NetUtil;
 
 /**
- * Client class for communicating with the access control web service.
+ * Client class for performing group searching and group actions
+ * with the access control web service.
  */
 public class GMSClient
 {
@@ -119,8 +120,10 @@ public class GMSClient
     private String baseURL;
 
     /**
-     *
-     * @param baseURL
+     * Constructor.
+     * 
+     * @param baseURL The URL of the supporting access control web service
+     * obtained from the registry.
      */
     public GMSClient(String baseURL)
         throws IllegalArgumentException
@@ -165,7 +168,7 @@ public class GMSClient
     }
 
     /**
-     * Create a new group
+     * Create a new group.
      *
      * @param group The group to create
      * @return The newly created group will all the information.
@@ -652,6 +655,17 @@ public class GMSClient
         }
     }
 
+    /**
+     * Get all the memberships of the user of a certain role.
+     * 
+     * @param userID Identifies the user.
+     * @param role The role to look up.
+     * @return A list of groups for which the user has the role.
+     * @throws UserNotFoundException If the user does not exist.
+     * @throws AccessControlException If not allowed to peform the search.
+     * @throws IllegalArgumentException If a parameter is null.
+     * @throws IOException If an unknown error occured.
+     */
     public List<Group> getMemberships(Principal userID, Role role)
         throws UserNotFoundException, AccessControlException, IOException
     {
@@ -722,12 +736,41 @@ public class GMSClient
         }
     }
     
+    /**
+     * Return the group, specified by paramter groupName, if the user,
+     * identified by userID, is a member of that group.  Return null
+     * otherwise.
+     * 
+     * This call is identical to getMemberShip(userID, groupName, Role.MEMBER)
+     *  
+     * @param userID Identifies the user.
+     * @param groupName Identifies the group.
+     * @return The group or null of the user is not a member.
+     * @throws UserNotFoundException If the user does not exist.
+     * @throws AccessControlException If not allowed to peform the search.
+     * @throws IllegalArgumentException If a parameter is null.
+     * @throws IOException If an unknown error occured.
+     */
     public Group getMembership(Principal userID, String groupName)
         throws UserNotFoundException, AccessControlException, IOException
     {
         return getMembership(userID, groupName, Role.MEMBER);
     }
     
+    /**
+     * Return the group, specified by paramter groupName, if the user,
+     * identified by userID, is a member (of type role) of that group.
+     * Return null otherwise.
+     * 
+     * @param userID Identifies the user.
+     * @param groupName Identifies the group.
+     * @param role The membership role to search.
+     * @return The group or null of the user is not a member.
+     * @throws UserNotFoundException If the user does not exist.
+     * @throws AccessControlException If not allowed to peform the search.
+     * @throws IllegalArgumentException If a parameter is null.
+     * @throws IOException If an unknown error occured.
+     */
     public Group getMembership(Principal userID, String groupName, Role role)
         throws UserNotFoundException, AccessControlException, IOException
     {
@@ -817,12 +860,37 @@ public class GMSClient
         }
     }
     
+    /**
+     * Check if userID is a member of groupName.
+     * 
+     * This is equivalent to isMember(userID, groupName, Role.MEMBER)
+     * 
+     * @param userID Identifies the user.
+     * @param groupName Identifies the group.
+     * @return True if the user is a member of the group
+     * @throws UserNotFoundException If the user does not exist.
+     * @throws AccessControlException If not allowed to peform the search.
+     * @throws IllegalArgumentException If a parameter is null.
+     * @throws IOException If an unknown error occured.
+     */
     public boolean isMember(Principal userID, String groupName)
         throws UserNotFoundException, AccessControlException, IOException
     {
         return isMember(userID, groupName, Role.MEMBER);
     }
     
+    /**
+     * Check if userID is a member (of type role) of groupName.
+     * 
+     * @param userID Identifies the user.
+     * @param groupName Identifies the group.
+     * @param role The type of membership.
+     * @return True if the user is a member of the group
+     * @throws UserNotFoundException If the user does not exist.
+     * @throws AccessControlException If not allowed to peform the search.
+     * @throws IllegalArgumentException If a parameter is null.
+     * @throws IOException If an unknown error occured.
+     */
     public boolean isMember(Principal userID, String groupName, Role role)
         throws UserNotFoundException, AccessControlException, IOException
     {

projects/cadcAccessControl/test/src/ca/nrc/cadc/ac/client/GMSClientTest.java

@@ -99,6 +99,40 @@ public class GMSClientTest
         Log4jInit.setLevel("ca.nrc.cadc.ac", Level.INFO);
     }
     
+    @Test
+    public void testUserIsSubject()
+    {
+        try
+        {
+            Subject subject = new Subject();
+            HttpPrincipal userID = new HttpPrincipal("test");
+            HttpPrincipal userID2 = new HttpPrincipal("test2");
+            subject.getPrincipals().add(userID);
+            
+            RegistryClient regClient = new RegistryClient();
+            URL baseURL = regClient.getServiceURL(new URI(AC.GMS_SERVICE_URI));
+            GMSClient client = new GMSClient(baseURL.toString());
+
+            Assert.assertFalse(client.userIsSubject(null, null));
+            Assert.assertFalse(client.userIsSubject(userID, null));
+            Assert.assertFalse(client.userIsSubject(null, subject));
+            Assert.assertFalse(client.userIsSubject(userID2, subject));
+            Assert.assertTrue(client.userIsSubject(userID, subject));
+            
+            HttpPrincipal userID3 = new HttpPrincipal("test3");
+            subject.getPrincipals().add(userID3);
+            
+            Assert.assertTrue(client.userIsSubject(userID, subject));
+            Assert.assertFalse(client.userIsSubject(userID2, subject));
+            Assert.assertTrue(client.userIsSubject(userID3, subject));
+        }
+        catch (Throwable t)
+        {
+            log.error("Unexpected exception", t);
+            Assert.fail("Unexpected exception: " + t.getMessage());
+        }
+    }
+    
     @Test
     public void testGroupCaching()
     {
@@ -163,7 +197,6 @@ public class GMSClientTest
             List<Group> actual = client.getCachedGroups(userID, Role.MEMBER);
             Assert.assertNull("Cache should still be null", actual);
         }
-
         catch (Throwable t)
         {
             log.error("Unexpected exception", t);