Optionally allow to also remove IMS group admins which are no longer

configured

Add toString, equals and hashCode methods to deserialized JSON objects
Add InstallationOptions argument for installer methods
Expose all installation options in Touch UI

This closes #798

Author: kwin

accesscontroltool-apps-package/pom.xml

@@ -15,7 +15,7 @@
     <parent>
         <groupId>biz.netcentric.cq.tools.accesscontroltool</groupId>
         <artifactId>accesscontroltool</artifactId>
-        <version>3.5.2-SNAPSHOT</version>
+        <version>3.6.0-SNAPSHOT</version>
     </parent>
 
     <!-- ====================================================================== -->

accesscontroltool-bundle/pom.xml

@@ -11,7 +11,7 @@
     <parent>
         <groupId>biz.netcentric.cq.tools.accesscontroltool</groupId>
         <artifactId>accesscontroltool</artifactId>
-        <version>3.5.2-SNAPSHOT</version>
+        <version>3.6.0-SNAPSHOT</version>
     </parent>
 
     <!-- ====================================================================== -->

accesscontroltool-bundle/src/main/java/biz/netcentric/cq/tools/actool/api/AcInstallationService.java

@@ -21,27 +21,39 @@ public interface AcInstallationService {
     /** Applies the full configuration as stored at the path configured at PID biz.netcentric.cq.tools.actool.impl.AcInstallationServiceImpl
      * to the repository.
      * 
-     * @return the installation log */
+     * @return the installation log
+     * @deprecated use {@link #apply(InstallationOptions)} instead
+     */
+    @Deprecated
     public InstallationLog apply();
 
     /** Applies the configuration as stored at the given configurationRootPath to the repository.
      * 
      * @param configurationRootPath the root path for configuration files
-     * @return the installation log */
+     * @return the installation log 
+     * @deprecated use {@link #apply(InstallationOptions)} instead
+     */
+    @Deprecated
     public InstallationLog apply(String configurationRootPath);
 
     /** Applies parts of the configuration (based on given paths)
      * 
      * @param restrictedToPaths only apply ACLs to root paths as given
-     * @return the installation log */
+     * @return the installation log  
+     * @deprecated use {@link #apply(InstallationOptions)} instead
+     */
+    @Deprecated
     public InstallationLog apply(String[] restrictedToPaths);
 
     /** Applies the configuration as stored at the given configurationRootPath to the repository, but only apply ACEs to given
      * restrictedToPaths.
      * 
      * @param restrictedToPaths only apply ACLs to root paths as given
      * @param configurationRootPath the root path for configuration files
-     * @return the installation log */
+     * @return the installation log
+     * @deprecated use {@link #apply(InstallationOptions)} instead
+     */
+    @Deprecated
     public InstallationLog apply(String configurationRootPath, String[] restrictedToPaths);
 
 
@@ -51,10 +63,20 @@ public interface AcInstallationService {
      * @param restrictedToPaths only apply ACLs to root paths as given
      * @param configurationRootPath the root path for configuration files
      * @param skipIfConfigUnchanged will check if the config is unchanged compared to last execution with same parameters
-     * @return the installation log */
+     * @return the installation log
+     * @deprecated use {@link #apply(InstallationOptions)} instead
+     */
+    @Deprecated
     public InstallationLog apply(String configurationRootPath, String[] restrictedToPaths, boolean skipIfConfigUnchanged);
 
-    
+    /** Applies the configuration
+     * 
+     * @param options the installation options which further specify the installation
+     * @return the installation log
+     * @since 3.6.0
+     */
+    public InstallationLog apply(InstallationOptions options);
+
     /** purges all acls of the node specified by path (no deletion of acls of subnodes)
      *
      * @param path the path from which to purge the ACL

accesscontroltool-bundle/src/main/java/biz/netcentric/cq/tools/actool/api/InstallationOptions.java

@@ -0,0 +1,55 @@
+package biz.netcentric.cq.tools.actool.api;
+
+/*-
+ * #%L
+ * Access Control Tool Bundle
+ * %%
+ * Copyright (C) 2015 - 2025 Cognizant Netcentric
+ * %%
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ * #L%
+ */
+
+import java.util.List;
+import java.util.Optional;
+
+import org.osgi.annotation.versioning.ProviderType;
+
+import biz.netcentric.cq.tools.actool.impl.AcInstallationServiceImpl;
+
+/** 
+ * Options to be used when applying the configuration.
+ * Create an instance using {@link InstallationOptionsBuilder}.
+ * @since 3.6.0 
+ */
+@ProviderType
+public interface InstallationOptions {
+
+    /**
+     * 
+     * @return the root path of the configuration files. If not set the one configured in {@link AcInstallationServiceImpl} is used.
+     */
+    public Optional<String> getConfigurationRootPath();
+
+    /**
+     * 
+     * @return the list of root path entry below which ACLs should be modified. Note this does not restrict the installation of authorizables (users/groups) only the ACEs.
+     */
+    public List<String> getRestrictedToPaths();
+
+    /**
+     * 
+     * @return {@code true} if the installation should be skipped if the configuration is unchanged compared to last execution with same parameters
+     */
+    public boolean shouldSkipIfConfigUnchanged();
+
+    /**
+     * 
+     * @return {@code true} if the installation should also update existing external groups. By default only new ones are created but existing ones not touched.
+     */
+    public boolean shouldUpdateExistingExternalGroups();
+
+}

accesscontroltool-bundle/src/main/java/biz/netcentric/cq/tools/actool/api/InstallationOptionsBuilder.java

@@ -0,0 +1,136 @@
+package biz.netcentric.cq.tools.actool.api;
+
+/*-
+ * #%L
+ * Access Control Tool Bundle
+ * %%
+ * Copyright (C) 2015 - 2025 Cognizant Netcentric
+ * %%
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ * #L%
+ */
+
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.LinkedList;
+import java.util.List;
+import java.util.Objects;
+import java.util.Optional;
+
+/** Builder for {@link InstallationOptions}.
+ * 
+ * @since 3.6.0 */
+public final class InstallationOptionsBuilder {
+
+    private Optional<String> configurationRootPath;
+    private List<String> restrictedToPaths;
+    private boolean skipIfConfigUnchanged;
+    private boolean updateExistingExternalGroups;
+
+    public InstallationOptionsBuilder() {
+        this.configurationRootPath = Optional.empty();
+        this.restrictedToPaths = new LinkedList<>();
+        this.skipIfConfigUnchanged = false;
+        this.updateExistingExternalGroups = false;
+    }
+
+    public InstallationOptionsBuilder(InstallationOptions options) {
+        this.configurationRootPath = options.getConfigurationRootPath();
+        this.restrictedToPaths = new LinkedList<>();
+        this.restrictedToPaths.addAll(options.getRestrictedToPaths());
+        this.skipIfConfigUnchanged = options.shouldSkipIfConfigUnchanged();
+        this.updateExistingExternalGroups = options.shouldUpdateExistingExternalGroups();
+    }
+
+    public InstallationOptionsBuilder withConfigurationRootPath(String configurationRootPath) {
+        this.configurationRootPath = Optional.of(configurationRootPath);
+        return this;
+    }
+
+    public InstallationOptionsBuilder withRestrictedToPaths(String... restrictedToPaths) {
+        this.restrictedToPaths.addAll(Arrays.asList(restrictedToPaths));
+        return this;
+    }
+
+    public InstallationOptionsBuilder withRestrictedToPaths(Collection<String> restrictedToPaths) {
+        this.restrictedToPaths.addAll(restrictedToPaths);
+        return this;
+    }
+
+    public InstallationOptionsBuilder skipIfConfigUnchanged() {
+        this.skipIfConfigUnchanged = true;
+        return this;
+    }
+
+    public InstallationOptionsBuilder updateExistingExternalGroups() {
+        this.updateExistingExternalGroups = true;
+        return this;
+    }
+
+    public InstallationOptions build() {
+        return new InstallationOptionsImpl(this);
+    }
+
+    private static final class InstallationOptionsImpl implements InstallationOptions {
+        private final Optional<String> configurationRootPath;
+        private final List<String> restrictedToPaths;
+        private final boolean skipIfConfigUnchanged;
+        private final boolean updateExistingExternalGroups;
+
+        public InstallationOptionsImpl(InstallationOptionsBuilder builder) {
+            this.configurationRootPath = builder.configurationRootPath;
+            this.restrictedToPaths = builder.restrictedToPaths;
+            this.skipIfConfigUnchanged = builder.skipIfConfigUnchanged;
+            this.updateExistingExternalGroups = builder.updateExistingExternalGroups;
+        }
+
+        @Override
+        public Optional<String> getConfigurationRootPath() {
+            return configurationRootPath;
+        }
+
+        @Override
+        public List<String> getRestrictedToPaths() {
+            return restrictedToPaths;
+        }
+
+        @Override
+        public boolean shouldSkipIfConfigUnchanged() {
+            return skipIfConfigUnchanged;
+        }
+
+        @Override
+        public boolean shouldUpdateExistingExternalGroups() {
+            return updateExistingExternalGroups;
+        }
+
+        @Override
+        public int hashCode() {
+            return Objects.hash(configurationRootPath, restrictedToPaths, skipIfConfigUnchanged, updateExistingExternalGroups);
+        }
+
+        @Override
+        public boolean equals(Object obj) {
+            if (this == obj)
+                return true;
+            if (obj == null)
+                return false;
+            if (getClass() != obj.getClass())
+                return false;
+            InstallationOptionsImpl other = (InstallationOptionsImpl) obj;
+            return Objects.equals(configurationRootPath, other.configurationRootPath)
+                    && Objects.equals(restrictedToPaths, other.restrictedToPaths) && skipIfConfigUnchanged == other.skipIfConfigUnchanged
+                    && updateExistingExternalGroups == other.updateExistingExternalGroups;
+        }
+
+        @Override
+        public String toString() {
+            return "InstallationOptionsImpl [configurationRootPath=" + configurationRootPath + ", restrictedToPaths=" + restrictedToPaths
+                    + ", skipIfConfigUnchanged=" + skipIfConfigUnchanged + ", updateExistingExternalGroups=" + updateExistingExternalGroups
+                    + "]";
+        }
+    }
+}

accesscontroltool-bundle/src/main/java/biz/netcentric/cq/tools/actool/api/package-info.java

@@ -1,4 +1,4 @@
-@Version("3.0.0")
+@Version("3.1.0")
 package biz.netcentric.cq.tools.actool.api;
 
 /*-

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

@@ -21,6 +21,7 @@
 
 import org.apache.sling.api.resource.LoginException;
 
+import biz.netcentric.cq.tools.actool.api.InstallationOptions;
 import biz.netcentric.cq.tools.actool.configmodel.AcConfiguration;
 import biz.netcentric.cq.tools.actool.configmodel.AuthorizablesConfig;
 import biz.netcentric.cq.tools.actool.history.InstallationLogger;
@@ -30,6 +31,6 @@ public interface AuthorizableInstallerService {
     void installAuthorizables(
             AcConfiguration acConfiguration,
             AuthorizablesConfig authorizablesConfigBeans,
-            final Session session, InstallationLogger installLog)
+            final Session session, InstallationLogger installLog, InstallationOptions options)
     throws RepositoryException, AuthorizableCreatorException, LoginException, IOException, GeneralSecurityException;
 }

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

@@ -63,6 +63,7 @@
 import com.adobe.granite.keystore.KeyStoreNotInitialisedException;
 import com.adobe.granite.keystore.KeyStoreService;
 
+import biz.netcentric.cq.tools.actool.api.InstallationOptions;
 import biz.netcentric.cq.tools.actool.authorizableinstaller.AuthorizableCreatorException;
 import biz.netcentric.cq.tools.actool.authorizableinstaller.AuthorizableInstallerService;
 import biz.netcentric.cq.tools.actool.configmodel.AcConfiguration;
@@ -117,7 +118,7 @@ public class AuthorizableInstallerServiceImpl implements
     public void installAuthorizables(
             AcConfiguration acConfiguration,
             AuthorizablesConfig authorizablesConfigBeans,
-            final Session session, InstallationLogger installLog)
+            final Session session, InstallationLogger installLog, InstallationOptions options)
             throws RepositoryException, AuthorizableCreatorException, LoginException, IOException, GeneralSecurityException {
 
         AuthInstallerUserManager userManager = new AuthInstallerUserManagerPrefetchingImpl(AccessControlUtils.getUserManagerAutoSaveDisabled(session), session.getValueFactory(), installLog);
@@ -136,16 +137,16 @@ public void installAuthorizables(
         }
 
         installLog.addMessage(LOG, "Created "+installLog.getCountAuthorizablesCreated() + " authorizables (moved "+installLog.getCountAuthorizablesMoved() + " authorizables)");
-        syncWithExternalGroupManagement(groupsToSyncWithExternalUserMgmt, installLog);
+        syncWithExternalGroupManagement(groupsToSyncWithExternalUserMgmt, installLog, options);
 
     }
 
-    private void syncWithExternalGroupManagement(Collection<AuthorizableConfigBean> groupConfigBeans, InstallationLogger installLog) throws IOException {
+    private void syncWithExternalGroupManagement(Collection<AuthorizableConfigBean> groupConfigBeans, InstallationLogger installLog, InstallationOptions options) throws IOException {
         if (groupConfigBeans.isEmpty()) {
             return;
         }
         for (ExternalGroupManagement externalGroupManagement : externalGroupManagementServices) {
-            int numGroupsSynced = externalGroupManagement.updateGroups(groupConfigBeans);
+            int numGroupsSynced = externalGroupManagement.updateGroups(groupConfigBeans, options);
             installLog.addMessage(LOG, "Synchronized " + numGroupsSynced + " groups with external user management " + externalGroupManagement.getLabel());
         }
     }

accesscontroltool-bundle/src/main/java/biz/netcentric/cq/tools/actool/externalusermanagement/ExternalGroupManagement.java

@@ -16,6 +16,7 @@
 import java.io.IOException;
 import java.util.Collection;
 
+import biz.netcentric.cq.tools.actool.api.InstallationOptions;
 import biz.netcentric.cq.tools.actool.configmodel.AuthorizableConfigBean;
 
 /**
@@ -25,10 +26,11 @@ public interface ExternalGroupManagement {
     /**
      * Updates the groups in the external directory.
      * @param groupConfigs the groups to be updated
+     * @param options the installation options
      * @return the effective number of groups updated (may be less than the number of groups in {@code groupConfigs}) if some are considered up to date
      * @throws IOException
      */
-    int updateGroups(Collection<AuthorizableConfigBean> groupConfigs) throws IOException;
+    int updateGroups(Collection<AuthorizableConfigBean> groupConfigs, InstallationOptions options) throws IOException;
 
     /**
      * 

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

@@ -25,6 +25,7 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+import biz.netcentric.cq.tools.actool.api.InstallationOptions;
 import biz.netcentric.cq.tools.actool.helper.runtime.RuntimeHelper;
 import biz.netcentric.cq.tools.actool.history.impl.HistoryUtils;
 
@@ -35,10 +36,10 @@
 public class AcConfigChangeTracker {
     private static final Logger LOG = LoggerFactory.getLogger(AcConfigChangeTracker.class);
 
-    public boolean configIsUnchangedComparedToLastExecution(Map<String, String> configFiles, String[] restrictedToPaths, Session session) {
+    public boolean configIsUnchangedComparedToLastExecution(Map<String, String> configFiles, Session session, InstallationOptions options) {
 
 
-        String executionKey = createExecutionKey(configFiles, restrictedToPaths, session);
+        String executionKey = createExecutionKey(configFiles, session, options);
 
         try {
             String hashOfConfigFilesThisExecution = createHashOverConfigFiles(configFiles);
@@ -65,9 +66,9 @@ public boolean configIsUnchangedComparedToLastExecution(Map<String, String> conf
         return false;
     }
 
-    private String createExecutionKey(Map<String, String> configFiles, String[] restrictedToPaths, Session session) {
+    private String createExecutionKey(Map<String, String> configFiles, Session session, InstallationOptions options) {
         boolean isCompositeNodeStore= RuntimeHelper.isCompositeNodeStore(session);
-        String restrictedToPathsKey = restrictedToPaths==null || restrictedToPaths.length==0 ? "ALL_PATHS" : StringUtils.join(restrictedToPaths, "+").replace("$", "").replace("^", "");
+        String restrictedToPathsKey = options.getRestrictedToPaths().isEmpty() ? "ALL_PATHS" : String.join("+", options.getRestrictedToPaths()).replace("$", "").replace("^", "");
         String effectiveRootPathOfConfigs = getEffectiveConfigRootPath(configFiles);
         String executionKey = "hash("+StringUtils.removeEnd(effectiveRootPathOfConfigs, "/").replace('/', '\\') + "," + restrictedToPathsKey.replace('/', '\\').replace(':', '_')+","+(isCompositeNodeStore?"compNodeStore":"stdRepo")+")";
         return executionKey;