#503 Improved documentation

Author: ghenzler

accesscontroltool-bundle/src/main/java/biz/netcentric/cq/tools/actool/authorizableinstaller/impl/PrefetchingUserManager.java

@@ -24,12 +24,27 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-import com.google.common.annotations.VisibleForTesting;
-
 import biz.netcentric.cq.tools.actool.helper.Constants;
 import biz.netcentric.cq.tools.actool.history.InstallationLogger;
 
-/** Prefetches a) all groups and system users (but not regular users) and b) all memberships between these authorizables in constructor.  */
+/**
+ * <p>
+ * Special user manager that prefetches
+ * <ul>
+ * <li>all groups, system users and anonymous (but not regular users)</li>
+ * <li>all memberships between the preloaded authorizables</li>
+ * <ul>
+ * upon creation. 
+ * </p>
+ * <p>
+ * The membership relationships are cached in lookup maps to quickly be able to query the repository state for both
+ * authorizable.declaredMemberOf() (this we call in this class also) and group.getDeclaredMembers(). Having called declaredMemberOf() for
+ * all groups of the repository has also retrieved all memberships (expect regular user memberships), hence the method getDeclaredMembers()
+ * does not have to be called anymore. This is particularly useful because that way the AC tool does not have to iterate over a potentially
+ * huge number of users in production to then only filter out a few relevant groups in the end (the AC Tool does not touch user memberships
+ * to groups).
+ * </p>
+ */
 class PrefetchingUserManager implements UserManager {
 
     private static final Logger LOG = LoggerFactory.getLogger(PrefetchingUserManager.class);
@@ -45,7 +60,7 @@ public PrefetchingUserManager(UserManager delegate, final ValueFactory valueFact
         this.delegate = delegate;
 
         long startPrefetch = System.currentTimeMillis();
-        Iterator<Authorizable> allAuthorizables = delegate.findAuthorizables(new Query() {
+        Iterator<Authorizable> allGroupsAndSystemUsersAndAnonymous = delegate.findAuthorizables(new Query() {
             public <T> void build(QueryBuilder<T> builder) {
                 builder.setCondition(
                         builder.or( //
@@ -54,8 +69,8 @@ public <T> void build(QueryBuilder<T> builder) {
                 );
             }
         });
-        while (allAuthorizables.hasNext()) {
-            Authorizable auth = allAuthorizables.next();
+        while (allGroupsAndSystemUsersAndAnonymous.hasNext()) {
+            Authorizable auth = allGroupsAndSystemUsersAndAnonymous.next();
             String authId = auth.getID();
             authorizableCache.put(authId, auth);
 
@@ -96,11 +111,11 @@ public Authorizable getAuthorizable(String id) throws RepositoryException {
     }
 
     public Set<String> getDeclaredIsMemberOf(String id) throws RepositoryException {
-        
-        if(isMemberOfByAuthorizableId.containsKey(id)) {
+
+        if (isMemberOfByAuthorizableId.containsKey(id)) {
             return isMemberOfByAuthorizableId.get(id);
         } else {
-            // for users fall back to retrieve on demand 
+            // for users fall back to retrieve on demand
             Set<String> memberOfSet = new HashSet<String>();
             Iterator<Group> memberOfIt = getAuthorizable(id).declaredMemberOf();
             while (memberOfIt.hasNext()) {
@@ -112,7 +127,8 @@ public Set<String> getDeclaredIsMemberOf(String id) throws RepositoryException {
     }
 
     public Set<String> getDeclaredMembersWithoutRegularUsers(String id) {
-        return nonRegularUserMembersByAuthorizableId.containsKey(id) ? nonRegularUserMembersByAuthorizableId.get(id): Collections.<String>emptySet();
+        return nonRegularUserMembersByAuthorizableId.containsKey(id) ? nonRegularUserMembersByAuthorizableId.get(id)
+                : Collections.<String> emptySet();
     }
 
     public int getCacheSize() {

accesscontroltool-bundle/src/test/java/biz/netcentric/cq/tools/actool/authorizableinstaller/impl/PrefetchingUserManagerTest.java

@@ -36,10 +36,10 @@ public class PrefetchingUserManagerTest {
 
     @Mock
     ValueFactory valueFactory;
-    
+
     @Mock
     InstallationLogger installationLogger;
-    
+
     @Mock
     Group group1;
 
@@ -48,22 +48,22 @@ public class PrefetchingUserManagerTest {
 
     @Mock
     Group group3;
-    
+
     @Mock
     User user1;
-    
+
     @Mock
     User user2;
 
     @Mock
     User userNonCached;
-    
+
     PrefetchingUserManager prefetchingUserManager;
-    
+
     @Before
     public void before() throws RepositoryException {
-        
-        setupAuthorizable(group1, "group1", Collections.<Group>emptyList());
+
+        setupAuthorizable(group1, "group1", Collections.<Group> emptyList());
         setupAuthorizable(group2, "group2", Arrays.asList(group1));
         setupAuthorizable(group3, "group3", Arrays.asList(group2));
         setupAuthorizable(user1, "user1", Arrays.asList(group3));
@@ -72,7 +72,7 @@ public void before() throws RepositoryException {
 
         when(userManager.findAuthorizables(any(Query.class))).thenReturn(Arrays.asList(group1, group2, group3, user1, user2).iterator());
     }
-    
+
     private void setupAuthorizable(Authorizable auth, String id, List<Group> memberOf) throws RepositoryException {
         when(auth.getID()).thenReturn(id);
         when(auth.declaredMemberOf()).thenReturn(memberOf.iterator());
@@ -81,7 +81,7 @@ private void setupAuthorizable(Authorizable auth, String id, List<Group> memberO
     @Test
     public void testPrefetchedAuthorizablesUserManager() throws RepositoryException {
         prefetchingUserManager = new PrefetchingUserManager(userManager, valueFactory, installationLogger);
-        
+
         assertEquals(5, prefetchingUserManager.getCacheSize());
         assertEquals(group1, prefetchingUserManager.getAuthorizable("group1"));
         assertEquals(null, prefetchingUserManager.getAuthorizable("userNonCached"));
@@ -99,60 +99,52 @@ public void testDelegation() throws RepositoryException {
         prefetchingUserManager.getAuthorizable(testPrincipal);
         verify(userManager, times(1)).getAuthorizable(testPrincipal);
 
-
-
         String userPath = "/home/users/path";
         prefetchingUserManager.getAuthorizableByPath(userPath);
         verify(userManager, times(1)).getAuthorizableByPath(userPath);
-        
+
         String relPath = "profile/test";
         String testVal = "testval";
         prefetchingUserManager.findAuthorizables(relPath, testVal);
         verify(userManager, times(1)).findAuthorizables(relPath, testVal);
         prefetchingUserManager.findAuthorizables(relPath, testVal, UserManager.SEARCH_TYPE_AUTHORIZABLE);
         verify(userManager, times(1)).findAuthorizables(relPath, testVal, UserManager.SEARCH_TYPE_AUTHORIZABLE);
-        
+
         Query testQuery = new Query() {
             public <T> void build(QueryBuilder<T> builder) {
                 // fetch all authorizables
             }
         };
         prefetchingUserManager.findAuthorizables(testQuery);
         verify(userManager, times(1)).findAuthorizables(testQuery);
-        
+
         String testpw = "pw";
         prefetchingUserManager.createUser(testuser, testpw);
         verify(userManager, times(1)).createUser(testuser, testpw);
 
         prefetchingUserManager.createUser(testuser, testpw, testPrincipal, userPath);
         verify(userManager, times(1)).createUser(testuser, testpw, testPrincipal, userPath);
-        
+
         prefetchingUserManager.createSystemUser(testuser, userPath);
         verify(userManager, times(1)).createSystemUser(testuser, userPath);
-        
+
         prefetchingUserManager.createGroup(testuser);
         verify(userManager, times(1)).createGroup(testuser);
 
         prefetchingUserManager.createGroup(testPrincipal);
         verify(userManager, times(1)).createGroup(testPrincipal);
-        
+
         prefetchingUserManager.createGroup(testPrincipal, userPath);
         verify(userManager, times(1)).createGroup(testPrincipal, userPath);
 
         prefetchingUserManager.createGroup(testuser, testPrincipal, userPath);
         verify(userManager, times(1)).createGroup(testuser, testPrincipal, userPath);
-        
+
         prefetchingUserManager.autoSave(true);
         verify(userManager, times(1)).autoSave(true);
-        
+
         prefetchingUserManager.isAutoSave();
         verify(userManager, times(1)).isAutoSave();
     }
 
-
-    
-    
-    
-    
-    
 }