Add method to call installation asynchronously

Trigger from JMX/Touch UI leveraging server-sent events
Consume the messages in JQuery UI/Coral UI dialog

This closes #801

Author: kwin

accesscontroltool-bundle/pom.xml

@@ -142,6 +142,11 @@
             <artifactId>org.apache.sling.serviceusermapper</artifactId>
             <scope>provided</scope>
         </dependency>
+        <dependency>
+            <groupId>org.apache.sling</groupId>
+            <artifactId>org.apache.sling.event</artifactId>
+            <scope>provided</scope>
+        </dependency>
         <dependency>
             <groupId>org.apache.sling</groupId>
             <artifactId>org.apache.sling.commons.scheduler</artifactId>

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

@@ -1,5 +1,8 @@
 package biz.netcentric.cq.tools.actool.api;
 
+import java.util.function.BiConsumer;
+import java.util.function.Consumer;
+
 /*-
  * #%L
  * Access Control Tool Bundle
@@ -18,6 +21,29 @@
 @ProviderType
 public interface AcInstallationService {
 
+    /**
+     * Applies the configuration asynchronously.
+     * Almost immediately returns a string with the ID of the started job.
+     * Only one execution at a time is allowed.
+     * @param options
+     * @throws IllegalStateException if another asynchronous installation is currently running
+     * @return the job id
+     * @since 3.6.0
+     * @see #attachLogListener(String, InstallationLogListener)
+     */
+    public String applyAsynchronously(InstallationOptions options);
+
+    /** Attaches the log listener callback to an installation triggered previously via {@link #applyAsynchronously(InstallationOptions)}.
+     * 
+     * @param jobId the job id returned by {@link #applyAsynchronously(InstallationOptions)}
+     * @param listener the listener to attach, receives the level and the message per each log line
+     * @param finishListener the listener to attach, receives a boolean status indicating success or failure once the installation was finished
+     * @return {@code true} if the listeners were attached successfully (i.e. an installation with the given executionId was triggered before and is still ongoing), {@code false} otherwise
+     * @since 3.6.0 
+     * @see #applyAsynchronously(InstallationOptions)
+     */
+    public boolean attachLogListener(String jobId, BiConsumer<InstallationLogLevel, String> listener, Consumer<Boolean> finishListener);
+
     /** Applies the full configuration as stored at the path configured at PID biz.netcentric.cq.tools.actool.impl.AcInstallationServiceImpl
      * to the repository.
      * 
@@ -69,7 +95,7 @@ public interface AcInstallationService {
     @Deprecated
     public InstallationLog apply(String configurationRootPath, String[] restrictedToPaths, boolean skipIfConfigUnchanged);
 
-    /** Applies the configuration
+    /** Applies the configuration.
      * 
      * @param options the installation options which further specify the installation
      * @return the installation log

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

@@ -0,0 +1,21 @@
+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%
+ */
+
+public enum InstallationLogLevel {
+    ERROR,
+    WARNING,
+    INFO,
+    TRACE
+}

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

@@ -14,6 +14,7 @@
  */
 
 import java.util.List;
+import java.util.Map;
 import java.util.Optional;
 
 import org.osgi.annotation.versioning.ProviderType;
@@ -52,4 +53,14 @@ public interface InstallationOptions {
      */
     public boolean shouldUpdateExistingExternalGroups();
 
+    /** 
+     * For asynchronous installations the options need to be persisted in the repository.
+     * As regular Java serialization cannot be used with Sling Jobs (<a href="https://issues.apache.org/jira/browse/SLING-12745">SLING-12745</a>)
+     * one has to rely on types compliant with default JCR.
+     * 
+     * @return a new map with properties of types which are natively supported by the JCR resource provider
+     * @see InstallationOptionsBuilder
+     */
+    public Map<String, Object> getPersistableProperties();
+
 }

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

@@ -1,5 +1,7 @@
 package biz.netcentric.cq.tools.actool.api;
 
+import java.io.Serializable;
+
 /*-
  * #%L
  * Access Control Tool Bundle
@@ -17,6 +19,7 @@
 import java.util.Collection;
 import java.util.LinkedList;
 import java.util.List;
+import java.util.Map;
 import java.util.Objects;
 import java.util.Optional;
 
@@ -25,28 +28,43 @@
  * @since 3.6.0 */
 public final class InstallationOptionsBuilder {
 
-    private Optional<String> configurationRootPath;
+    private String configurationRootPath;
     private List<String> restrictedToPaths;
     private boolean skipIfConfigUnchanged;
     private boolean updateExistingExternalGroups;
 
+    /**
+     * Creates a new builder with the given properties previously returned by {@link InstallationOptions#getPersistableProperties()}.
+     */
+    public InstallationOptionsBuilder(Map<String, Object> properties) {
+        this.configurationRootPath = (String)properties.get("configurationRootPath");
+        String[] restrictedToPathsArray = (String[])properties.get("restrictedToPaths");
+        if (restrictedToPathsArray != null) {
+            this.restrictedToPaths = new LinkedList<>(Arrays.asList(restrictedToPathsArray));
+        } else {
+            this.restrictedToPaths = new LinkedList<>();
+        }
+        this.skipIfConfigUnchanged = (Boolean)properties.getOrDefault("skipIfConfigUnchanged", Boolean.FALSE);
+        this.updateExistingExternalGroups = (Boolean)properties.getOrDefault("updateExistingExternalGroups", Boolean.FALSE);
+    }
+    
     public InstallationOptionsBuilder() {
-        this.configurationRootPath = Optional.empty();
+        this.configurationRootPath = null;
         this.restrictedToPaths = new LinkedList<>();
         this.skipIfConfigUnchanged = false;
         this.updateExistingExternalGroups = false;
     }
 
     public InstallationOptionsBuilder(InstallationOptions options) {
-        this.configurationRootPath = options.getConfigurationRootPath();
+        this.configurationRootPath = options.getConfigurationRootPath().orElse(null);
         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);
+        this.configurationRootPath = configurationRootPath;
         return this;
     }
 
@@ -75,12 +93,12 @@ public InstallationOptions build() {
     }
 
     private static final class InstallationOptionsImpl implements InstallationOptions {
-        private final Optional<String> configurationRootPath;
+        private final String configurationRootPath;
         private final List<String> restrictedToPaths;
         private final boolean skipIfConfigUnchanged;
         private final boolean updateExistingExternalGroups;
 
-        public InstallationOptionsImpl(InstallationOptionsBuilder builder) {
+       InstallationOptionsImpl(InstallationOptionsBuilder builder) {
             this.configurationRootPath = builder.configurationRootPath;
             this.restrictedToPaths = builder.restrictedToPaths;
             this.skipIfConfigUnchanged = builder.skipIfConfigUnchanged;
@@ -89,7 +107,7 @@ public InstallationOptionsImpl(InstallationOptionsBuilder builder) {
 
         @Override
         public Optional<String> getConfigurationRootPath() {
-            return configurationRootPath;
+            return Optional.ofNullable(configurationRootPath);
         }
 
         @Override
@@ -132,5 +150,15 @@ public String toString() {
                     + ", skipIfConfigUnchanged=" + skipIfConfigUnchanged + ", updateExistingExternalGroups=" + updateExistingExternalGroups
                     + "]";
         }
+
+        @Override
+        public Map<String, Object> getPersistableProperties() {
+            Map<String, Object> properties = new java.util.HashMap<>();
+            properties.put("configurationRootPath", configurationRootPath);
+            properties.put("restrictedToPaths", restrictedToPaths.toArray(new String[0]));
+            properties.put("skipIfConfigUnchanged", skipIfConfigUnchanged);
+            properties.put("updateExistingExternalGroups", updateExistingExternalGroups);
+            return properties;
+        }
     }
 }

accesscontroltool-bundle/src/main/java/biz/netcentric/cq/tools/actool/history/InstallationListener.java

@@ -17,6 +17,11 @@
 import org.osgi.annotation.versioning.ConsumerType;
 
 @ConsumerType
+/** Listener interface for installation events.
+ * 
+ * @deprecated Unused. Will be removed in a future release.
+ */
+@Deprecated()
 public interface InstallationListener {
 
 	void onWarning(String message);

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

@@ -1,9 +1,5 @@
-
 package biz.netcentric.cq.tools.actool.history.impl;
 
-import java.io.PrintWriter;
-import java.io.StringWriter;
-
 /*-
  * #%L
  * Access Control Tool Bundle
@@ -17,36 +13,45 @@
  * #L%
  */
 
+import java.io.Closeable;
+import java.io.IOException;
+import java.io.PrintWriter;
+import java.io.StringWriter;
 import java.sql.Timestamp;
 import java.text.DateFormat;
 import java.text.NumberFormat;
 import java.text.SimpleDateFormat;
+import java.util.Collection;
 import java.util.Date;
 import java.util.HashSet;
 import java.util.Locale;
 import java.util.Map;
 import java.util.Set;
 import java.util.TreeSet;
+import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.function.BiConsumer;
+import java.util.function.Consumer;
 
 import org.slf4j.Logger;
 
 import biz.netcentric.cq.tools.actool.api.HistoryEntry;
 import biz.netcentric.cq.tools.actool.api.InstallationLog;
+import biz.netcentric.cq.tools.actool.api.InstallationLogLevel;
 import biz.netcentric.cq.tools.actool.api.InstallationResult;
 import biz.netcentric.cq.tools.actool.comparators.HistoryEntryComparator;
 import biz.netcentric.cq.tools.actool.history.InstallationLogger;
 
-public class PersistableInstallationLogger implements InstallationLogger, InstallationLog, InstallationResult {
+public class PersistableInstallationLogger implements InstallationLogger, InstallationLog, InstallationResult, Closeable {
 
     static final String EOL = "\n";
     protected static final String MSG_IDENTIFIER_ERROR = "ERROR: ";
     protected static final String MSG_IDENTIFIER_WARNING = "WARNING: ";
 
-    private Set<HistoryEntry> warnings = new HashSet<HistoryEntry>();
-    private Set<HistoryEntry> messages = new HashSet<HistoryEntry>();
-    private Set<HistoryEntry> errors = new HashSet<HistoryEntry>();
+    private Set<HistoryEntry> warnings = new HashSet<>();
+    private Set<HistoryEntry> messages = new HashSet<>();
+    private Set<HistoryEntry> errors = new HashSet<>();
 
-    private Set<HistoryEntry> verboseMessages = new HashSet<HistoryEntry>();
+    private Set<HistoryEntry> verboseMessages = new HashSet<>();
 
     private boolean success = true;
     private final Date installationDate;
@@ -73,8 +78,13 @@ public class PersistableInstallationLogger implements InstallationLogger, Instal
     private int missingParentPathsForInitialContent = 0;
 
     private DateFormat timestampFormat = new SimpleDateFormat("HH:mm:ss.SSS");
+    
+    private final Collection<BiConsumer<InstallationLogLevel, String>> listeners;
+    private final Collection<Consumer<Boolean>> finishListeners;
 
     public PersistableInstallationLogger() {
+        listeners = new CopyOnWriteArrayList<>();
+        finishListeners = new CopyOnWriteArrayList<>();
         installationDate = new Date();
     }
 
@@ -132,6 +142,7 @@ public void addWarning(Logger log, String warning) {
     protected void addWarning(String warning) {
         warnings.add(new HistoryEntry(msgIndex, new Timestamp(
                 new Date().getTime()), MSG_IDENTIFIER_WARNING + warning));
+        listeners.forEach(l -> l.accept(InstallationLogLevel.WARNING, warning));
         msgIndex++;
     }
 
@@ -144,6 +155,7 @@ public void addMessage(Logger log, String message) {
     protected void addMessage(String message) {
         messages.add(new HistoryEntry(msgIndex, new Timestamp(new Date()
                 .getTime()), " " + message));
+        listeners.forEach(l -> l.accept(InstallationLogLevel.INFO, message));
         msgIndex++;
     }
 
@@ -164,6 +176,7 @@ public void addError(final String error, Throwable e) {
         }
         errors.add(new HistoryEntry(msgIndex, new Timestamp(
                 new Date().getTime()), MSG_IDENTIFIER_ERROR + fullErrorValue));
+        listeners.forEach(l -> l.accept(InstallationLogLevel.ERROR, error));
         success = false;
         msgIndex++;
         if (e != null) {
@@ -183,6 +196,7 @@ public void addVerboseMessage(Logger log, String message) {
     protected void addVerboseMessage(String message) {
         verboseMessages.add(new HistoryEntry(msgIndex, new Timestamp(
                 new Date().getTime()), " " + message));
+        listeners.forEach(l -> l.accept(InstallationLogLevel.TRACE, message));
         msgIndex++;
     }
 
@@ -370,4 +384,17 @@ public int getCountAuthorizablesMoved() {
         return countAuthorizablesMoved;
     }
 
+    @Override
+    public void close() throws IOException {
+        finishListeners.forEach(l -> l.accept(success));
+    }
+
+    public void attachMessageListener(BiConsumer<InstallationLogLevel, String> messageListener) {
+        listeners.add(messageListener);
+    }
+
+    public void attachFinishListener(Consumer<Boolean> finishListener) {
+        finishListeners.add(finishListener);
+    }
+
 }