Add SPI for registering external AuditLogEvent types

Replace the static @JsonSubTypes list on AuditLogEvent with
AuditLogEventRegistry, which holds the built-in type ids and merges
mappings contributed by AuditLogEventProvider implementations through
ServiceLoader. JsonlLogWriter and the JSON/XML renderers register
subtypes via the registry so external modules can ship their own
events without modifying jPOS. Built-in ids and serialization are
unchanged.

Author: ar

jpos/src/main/java/org/jpos/log/AuditLogEvent.java

@@ -18,33 +18,19 @@
 
 package org.jpos.log;
 
-import com.fasterxml.jackson.annotation.JsonSubTypes;
 import com.fasterxml.jackson.annotation.JsonTypeInfo;
-import org.jpos.log.evt.*;
 
+/**
+ * Marker interface for log payload event records.
+ *
+ * <p>Concrete implementations are mapped to a stable type id through
+ * {@link AuditLogEventRegistry}. Built-in ids are listed there; external
+ * modules contribute their own via {@link AuditLogEventProvider} and
+ * {@link java.util.ServiceLoader}.</p>
+ */
 @JsonTypeInfo(
   use = JsonTypeInfo.Id.NAME,
   include = JsonTypeInfo.As.PROPERTY,
   property = "t"
 )
-@JsonSubTypes({
-  @JsonSubTypes.Type(value = Warning.class, name = "warn"),
-  @JsonSubTypes.Type(value = Start.class, name = "start"),
-  @JsonSubTypes.Type(value = Stop.class, name = "stop"),
-  @JsonSubTypes.Type(value = Deploy.class, name = "deploy"),
-  @JsonSubTypes.Type(value = UnDeploy.class, name = "undeploy"),
-  @JsonSubTypes.Type(value = LogMessage.class, name = "msg"),
-  @JsonSubTypes.Type(value = Shutdown.class, name = "shutdown"),
-  @JsonSubTypes.Type(value = DeployActivity.class, name = "deploy-activity"),
-  @JsonSubTypes.Type(value = ThrowableAuditLogEvent.class, name = "throwable"),
-  @JsonSubTypes.Type(value = License.class, name = "license"),
-  @JsonSubTypes.Type(value = SysInfo.class, name = "sysinfo"),
-  @JsonSubTypes.Type(value = Connect.class, name = "connect"),
-  @JsonSubTypes.Type(value = Disconnect.class, name = "disconnect"),
-  @JsonSubTypes.Type(value = Listen.class, name = "listen"),
-  @JsonSubTypes.Type(value = SessionStart.class, name = "session-start"),
-  @JsonSubTypes.Type(value = SessionEnd.class, name = "session-end"),
-  @JsonSubTypes.Type(value = Txn.class, name = "txn")
-})
-
 public interface AuditLogEvent { }

jpos/src/main/java/org/jpos/log/AuditLogEventProvider.java

@@ -0,0 +1,44 @@
+/*
+ * jPOS Project [http://jpos.org]
+ * Copyright (C) 2000-2026 jPOS Software SRL
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package org.jpos.log;
+
+import java.util.Collection;
+
+/**
+ * SPI for contributing additional {@link AuditLogEvent} implementations.
+ *
+ * <p>External modules register their event classes by declaring an implementation in
+ * {@code META-INF/services/org.jpos.log.AuditLogEventProvider}; the
+ * {@link AuditLogEventRegistry} discovers and merges them with the built-in mappings
+ * via {@link java.util.ServiceLoader}.</p>
+ *
+ * <p>Type ids must be unique. Providers must not reuse any of the built-in ids
+ * ({@code warn}, {@code start}, {@code stop}, {@code deploy}, {@code undeploy},
+ * {@code msg}, {@code shutdown}, {@code deploy-activity}, {@code throwable},
+ * {@code license}, {@code sysinfo}, {@code connect}, {@code disconnect},
+ * {@code listen}, {@code session-start}, {@code session-end}, {@code txn}).</p>
+ *
+ * @since 3.0.0
+ */
+public interface AuditLogEventProvider {
+    /**
+     * @return the type mappings contributed by this provider; must not be {@code null}.
+     */
+    Collection<AuditLogEventType> types();
+}

jpos/src/main/java/org/jpos/log/AuditLogEventRegistry.java

@@ -0,0 +1,149 @@
+/*
+ * jPOS Project [http://jpos.org]
+ * Copyright (C) 2000-2026 jPOS Software SRL
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package org.jpos.log;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.jsontype.NamedType;
+import org.jpos.log.evt.Connect;
+import org.jpos.log.evt.Deploy;
+import org.jpos.log.evt.DeployActivity;
+import org.jpos.log.evt.Disconnect;
+import org.jpos.log.evt.License;
+import org.jpos.log.evt.Listen;
+import org.jpos.log.evt.LogMessage;
+import org.jpos.log.evt.SessionEnd;
+import org.jpos.log.evt.SessionStart;
+import org.jpos.log.evt.Shutdown;
+import org.jpos.log.evt.Start;
+import org.jpos.log.evt.Stop;
+import org.jpos.log.evt.SysInfo;
+import org.jpos.log.evt.ThrowableAuditLogEvent;
+import org.jpos.log.evt.Txn;
+import org.jpos.log.evt.UnDeploy;
+import org.jpos.log.evt.Warning;
+
+import java.util.Collection;
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.ServiceLoader;
+
+/**
+ * Registry of {@link AuditLogEvent} type mappings.
+ *
+ * <p>Holds the built-in type ids and discovers additional ones contributed by
+ * {@link AuditLogEventProvider} implementations through
+ * {@link ServiceLoader}. The result is a single source of truth used by every
+ * Jackson-based renderer in jPOS to register subtypes on its {@code ObjectMapper}.</p>
+ *
+ * <p>The registry is initialized lazily on first use. Built-in entries are
+ * always registered first so external providers cannot shadow them: any
+ * provider entry that re-uses a built-in id, or that collides with another
+ * provider entry, is rejected with {@link IllegalStateException}.</p>
+ *
+ * @since 3.0.0
+ */
+public final class AuditLogEventRegistry {
+    private static final List<AuditLogEventType> BUILTINS = List.of(
+      new AuditLogEventType("warn", Warning.class),
+      new AuditLogEventType("start", Start.class),
+      new AuditLogEventType("stop", Stop.class),
+      new AuditLogEventType("deploy", Deploy.class),
+      new AuditLogEventType("undeploy", UnDeploy.class),
+      new AuditLogEventType("msg", LogMessage.class),
+      new AuditLogEventType("shutdown", Shutdown.class),
+      new AuditLogEventType("deploy-activity", DeployActivity.class),
+      new AuditLogEventType("throwable", ThrowableAuditLogEvent.class),
+      new AuditLogEventType("license", License.class),
+      new AuditLogEventType("sysinfo", SysInfo.class),
+      new AuditLogEventType("connect", Connect.class),
+      new AuditLogEventType("disconnect", Disconnect.class),
+      new AuditLogEventType("listen", Listen.class),
+      new AuditLogEventType("session-start", SessionStart.class),
+      new AuditLogEventType("session-end", SessionEnd.class),
+      new AuditLogEventType("txn", Txn.class)
+    );
+
+    private static volatile Map<String, AuditLogEventType> types;
+
+    private AuditLogEventRegistry() { }
+
+    /**
+     * @return all known type mappings, built-ins first, then ServiceLoader-discovered.
+     */
+    public static Collection<AuditLogEventType> types() {
+        return load().values();
+    }
+
+    /**
+     * Registers every known {@link AuditLogEvent} subtype on the given
+     * {@code ObjectMapper}. Renderers should call this once after constructing
+     * their mapper.
+     *
+     * @param mapper the Jackson {@link ObjectMapper} (or subclass, e.g. {@code XmlMapper})
+     * @return the same mapper for chaining
+     */
+    public static <M extends ObjectMapper> M register(M mapper) {
+        for (AuditLogEventType t : load().values()) {
+            mapper.registerSubtypes(new NamedType(t.clazz(), t.name()));
+        }
+        return mapper;
+    }
+
+    /**
+     * Reloads the registry. Visible for testing — callers shouldn't need this in
+     * production, since mappings discovered through {@link ServiceLoader} are
+     * fixed for the lifetime of the JVM.
+     */
+    static synchronized void reload() {
+        types = null;
+        load();
+    }
+
+    private static Map<String, AuditLogEventType> load() {
+        Map<String, AuditLogEventType> snapshot = types;
+        if (snapshot != null)
+            return snapshot;
+        synchronized (AuditLogEventRegistry.class) {
+            if (types != null)
+                return types;
+            Map<String, AuditLogEventType> map = new LinkedHashMap<>();
+            for (AuditLogEventType t : BUILTINS)
+                map.put(t.name(), t);
+            for (AuditLogEventProvider provider : ServiceLoader.load(AuditLogEventProvider.class)) {
+                Collection<AuditLogEventType> contributed = provider.types();
+                if (contributed == null)
+                    continue;
+                for (AuditLogEventType t : contributed) {
+                    AuditLogEventType existing = map.get(t.name());
+                    if (existing != null && !existing.equals(t)) {
+                        throw new IllegalStateException(
+                          "AuditLogEventProvider " + provider.getClass().getName()
+                            + " attempted to register conflicting type id '" + t.name()
+                            + "' (already mapped to " + existing.clazz().getName() + ")");
+                    }
+                    map.put(t.name(), t);
+                }
+            }
+            types = Collections.unmodifiableMap(map);
+            return types;
+        }
+    }
+}

jpos/src/main/java/org/jpos/log/AuditLogEventType.java

@@ -0,0 +1,41 @@
+/*
+ * jPOS Project [http://jpos.org]
+ * Copyright (C) 2000-2026 jPOS Software SRL
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package org.jpos.log;
+
+import java.util.Objects;
+
+/**
+ * Pairs a stable type id with the {@link AuditLogEvent} implementation it identifies.
+ *
+ * <p>Used by {@link AuditLogEventProvider} implementations and by
+ * {@link AuditLogEventRegistry} to register Jackson subtype mappings.</p>
+ *
+ * @param name  stable type id used as the JSON/XML discriminator value (e.g. {@code "warn"})
+ * @param clazz the {@link AuditLogEvent} implementation
+ *
+ * @since 3.0.0
+ */
+public record AuditLogEventType(String name, Class<? extends AuditLogEvent> clazz) {
+    public AuditLogEventType {
+        Objects.requireNonNull(name, "name");
+        Objects.requireNonNull(clazz, "clazz");
+        if (name.isBlank())
+            throw new IllegalArgumentException("name must not be blank");
+    }
+}

jpos/src/main/java/org/jpos/log/render/json/AuditLogEventJsonLogRenderer.java

@@ -22,6 +22,7 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
 import org.jpos.log.AuditLogEvent;
+import org.jpos.log.AuditLogEventRegistry;
 import org.jpos.log.LogRenderer;
 
 import java.io.PrintStream;
@@ -32,6 +33,7 @@ public final class AuditLogEventJsonLogRenderer implements LogRenderer<AuditLogE
     public AuditLogEventJsonLogRenderer () {
         mapper.registerModule(new JavaTimeModule());
         mapper.disable(com.fasterxml.jackson.databind.SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
+        AuditLogEventRegistry.register(mapper);
     }
 
     @Override

jpos/src/main/java/org/jpos/log/render/json/LogEventJsonLogRenderer.java

@@ -24,6 +24,7 @@
 import com.fasterxml.jackson.databind.module.SimpleModule;
 import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
 import org.jpos.log.AuditLogEvent;
+import org.jpos.log.AuditLogEventRegistry;
 
 import org.jpos.log.LogRenderer;
 import org.jpos.log.evt.LogEvt;
@@ -51,6 +52,7 @@ public LogEventJsonLogRenderer() {
         SimpleModule module = new SimpleModule();
         module.addSerializer(Throwable.class, new ThrowableSerializer());
         mapper.registerModule(module);
+        AuditLogEventRegistry.register(mapper);
     }
 
     @Override

jpos/src/main/java/org/jpos/log/render/xml/LogEventXmlLogRenderer.java

@@ -24,6 +24,7 @@
 import com.fasterxml.jackson.dataformat.xml.XmlMapper;
 import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
 import org.jpos.log.AuditLogEvent;
+import org.jpos.log.AuditLogEventRegistry;
 
 import org.jpos.log.LogRenderer;
 import org.jpos.log.evt.LogEvt;
@@ -53,6 +54,7 @@ public LogEventXmlLogRenderer() {
         SimpleModule module = new SimpleModule();
         module.addSerializer(Throwable.class, new ThrowableSerializer());
         mapper.registerModule(module);
+        AuditLogEventRegistry.register(mapper);
     }
 
     @Override

jpos/src/main/java/org/jpos/util/JsonlLogWriter.java

@@ -29,6 +29,7 @@
 import org.jpos.iso.ISOMsg;
 import org.jpos.iso.ISOUtil;
 import org.jpos.log.AuditLogEvent;
+import org.jpos.log.AuditLogEventRegistry;
 import org.jpos.log.evt.LogEvt;
 import org.jpos.log.evt.LogMessage;
 import org.jpos.log.evt.ThrowableAuditLogEvent;
@@ -172,6 +173,7 @@ private void initMapper() {
         SimpleModule module = new SimpleModule();
         module.addSerializer(Throwable.class, new ThrowableSerializer());
         mapper.registerModule(module);
+        AuditLogEventRegistry.register(mapper);
     }
 
     private static Set<Integer> toIntSet(String spaceSeparated) {