fix(javadoc): phase 10 — Configuration, Context, ContextConstants, Connect, CLI, misc

- Configuration: add descriptions to all 16 interface methods
- ConfigurationException: add descriptions to all 4 constructors
- ConfigValidator: add class javadoc + explicit constructor
- Config (annotation): expand value() javadoc to multi-line
- Connector: add field/constructor/inner class comments
- Pausable: add descriptions to setTimeout/getTimeout/pause/resume/cancel/reset
- Console (JCE): add class/constructor/exec javadocs
- Command: add interface javadoc + exec() method description
- ConfigDecorationProvider: add interface javadoc + method comments
- ConfigurationFactory: add interface javadoc + method description
- ConcurrentUtil: add class javadoc + private constructor + method description
- CMFConverter: add class/constructor javadocs
- IRCConverter: add method descriptions
- Connect (record): add class/constructor javadocs
- CharTagMap: add explicit default constructor
- ChannelPool: move class javadoc before @SuppressWarnings annotation
- CMF: document USER constant; auto-comment all undocumented enum constants
- Context: add constructor; expand put/remove/move/getString/getMap/getPMap/getMapClone/dumpMap/log
- ContextConstants: add class javadoc; document all 24 enum constants
- CLI: expand both constructors to multi-line with descriptions
- ISOException: add description to getNested()

Author: ar-agt

jpos/src/main/java/org/jpos/core/ConfigValidator.java

@@ -47,7 +47,10 @@
  * @author apr
  * @since 3.0.2
  */
+/** Validates {@link Configuration} properties against annotated field declarations. */
 public class ConfigValidator {
+    /** Default constructor. */
+    public ConfigValidator() { }
     private final List<ValidationRule> rules = new ArrayList<>();
 
     /**

jpos/src/main/java/org/jpos/core/Configuration.java

@@ -32,29 +32,48 @@
  *
  */
 public interface Configuration {
+    /** @param propertyName the property name
+     * @return the property value, or an empty string if not found
+     */
     String get(String propertyName);
     /**
-     * @param propertyName  ditto
-     * @return all properties with a given name (or a zero-length array)
+     * Returns all property values with the given name.
+     * @param propertyName the property name
+     * @return all matching values, or a zero-length array
      */
     String[] getAll(String propertyName);
+    /** @param propertyName the property name @return all values as int array */
     int[] getInts(String propertyName);
+    /** @param propertyName the property name @return all values as long array */
     long[] getLongs(String propertyName);
+    /** @param propertyName the property name @return all values as double array */
     double[] getDoubles(String propertyName);
+    /** @param propertyName the property name @return all values as boolean array */
     boolean[] getBooleans(String propertyName);
+    /** @param propertyName the property name @param defaultValue value to return if not found @return the value or defaultValue */
     String get(String propertyName, String defaultValue);
+    /** @param propertyName the property name @return the value as an int, or 0 if not found */
     int getInt(String propertyName);
+    /** @param propertyName the property name @param defaultValue default if not found @return the value as int */
     int getInt(String propertyName, int defaultValue);
+    /** @param propertyName the property name @return the value as a long, or 0 if not found */
     long getLong(String propertyName);
+    /** @param propertyName the property name @param defaultValue default if not found @return the value as long */
     long getLong(String propertyName, long defaultValue);
+    /** @param propertyName the property name @return the value as a double, or 0.0 if not found */
     double getDouble(String propertyName);
+    /** @param propertyName the property name @param defaultValue default if not found @return the value as double */
     double getDouble(String propertyName, double defaultValue);
+    /** @param propertyName the property name @return the value as a boolean, or false if not found */
     boolean getBoolean(String propertyName);
+    /** @param propertyName the property name @param defaultValue default if not found @return the value as boolean */
     boolean getBoolean(String propertyName, boolean defaultValue);
     /**
-     * @param name the Property name
-     * @param value typically a String, but could be a String[] too
+     * Stores a property value.
+     * @param name the property name
+     * @param value the value (typically a String or String[])
      */
     void put(String name, Object value);
+    /** @return the set of all property names in this configuration */
     Set<String> keySet();
 }

jpos/src/main/java/org/jpos/core/ConfigurationException.java

@@ -30,15 +30,19 @@
 public class ConfigurationException extends ISOException {
 
     private static final long serialVersionUID = -5605240786314946532L;
+    /** Default constructor. */
     public ConfigurationException () {
         super();
     }
+    /** @param detail error message */
     public ConfigurationException (String detail) {
         super (detail);
     }
+    /** @param nested the root cause */
     public ConfigurationException (Throwable nested) {
         super (nested);
     }
+    /** @param detail error message @param nested the root cause */
     public ConfigurationException (String detail, Throwable nested) {
         super (detail, nested);
     }

jpos/src/main/java/org/jpos/core/annotation/Config.java

@@ -24,5 +24,9 @@
 @Target(ElementType.FIELD)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Config {
+    /**
+     * Returns the property name to inject (defaults to field name).
+     * @return property name
+     */
     String value();
 }

jpos/src/main/java/org/jpos/iso/Connector.java

@@ -41,11 +41,16 @@ public class Connector
     private Logger logger;
     private String realm;
     private boolean preserveSourceHeader = true;
+    /** Name of the QMUX to look up. */
     protected String muxName;
+    /** Name of the channel to look up. */
     protected String channelName;
+    /** Response timeout in milliseconds (0 = no timeout). */
     protected int timeout = 0;
+    /** Shared thread pool for processing incoming messages. */
     protected static ThreadPool pool;
 
+    /** Default constructor. */
     public Connector () {
         super();
     }
@@ -85,6 +90,7 @@ public void setConfiguration (Configuration cfg)
         }
     }
 
+    /** Runnable that processes a single incoming message through the MUX. */
     protected class Process implements Runnable {
         ISOSource source;
         ISOMsg m;

jpos/src/main/java/org/jpos/iso/ISOException.java

@@ -76,6 +76,7 @@ public ISOException (String s, Throwable nested) {
     }
 
     /**
+     * Returns the nested (wrapped) exception, if any.
      * @return nested exception (may be null)
      */
     public Throwable getNested() {

jpos/src/main/java/org/jpos/iso/channel/ChannelPool.java

@@ -36,10 +36,10 @@
 import java.util.concurrent.locks.Lock;
 import java.util.concurrent.locks.ReentrantLock;
 
-@SuppressWarnings("unchecked")
 /**
  * A pool of {@link ISOChannel} instances; tries each in order until one connects.
  */
+@SuppressWarnings("unchecked")
 public class ChannelPool implements ISOChannel, LogSource, Configurable, Cloneable {
     /** Whether this pool is in a usable state. */
     boolean usable = true;

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

@@ -54,5 +54,4 @@ public sealed interface AuditLogEvent
         permits Connect, Deploy, DeployActivity, Disconnect, License, Listen, LogMessage,
                 SessionEnd, SessionStart, Shutdown, Start, Stop, SysInfo,
                 ThrowableAuditLogEvent, Txn, UnDeploy, Warning {
-    // marker interface — no methods
 }

jpos/src/main/java/org/jpos/log/evt/Connect.java

@@ -21,14 +21,17 @@
 import com.fasterxml.jackson.annotation.JsonInclude;
 import org.jpos.log.AuditLogEvent;
 
+/** Audit log event recording a channel connection attempt. */
 public record Connect(String host, int remotePort, int localPort, @JsonInclude(JsonInclude.Include.NON_NULL) String error) implements AuditLogEvent {
+    /** @param host remote host @param remotePort remote port @param localPort local port @param error error message, or null on success */
     public Connect(String host, int remotePort, int localPort, String error) {
         this.host = host;
         this.remotePort = remotePort;
         this.localPort = localPort;
         this.error = error;
     }
 
+    /** @param host remote host @param remotePort remote port @param localPort local port */
     public Connect(String host, int remotePort, int localPort) {
         this(host, remotePort, localPort, null);
     }

jpos/src/main/java/org/jpos/q2/CLI.java

@@ -46,7 +46,9 @@ public class CLI implements Runnable {
     private String prompt = DEFAULT_PROMPT;
     private History mainHistory;
 
-    /** @param q2 the Q2 instance
+    /**
+     * Creates a simple CLI with a single command and no streams.
+     * @param q2 the Q2 instance
      * @param line the initial command line
      * @param keepRunning true to keep running after the first command
      * @throws IOException on I/O failure
@@ -55,12 +57,14 @@ public CLI(Q2 q2, String line, boolean keepRunning) throws IOException {
         this(q2, System.in, System.out, line, keepRunning, true);
     }
 
-    /** @param q2 the Q2 instance
+    /**
+     * Creates a full CLI with explicit I/O streams.
+     * @param q2 the Q2 instance
      * @param in input stream
      * @param rawout output stream
-     * @param line initial command
-     * @param keepRunning true to keep running
-     * @param interactive true for interactive mode
+     * @param line initial command (may be null for interactive mode)
+     * @param keepRunning true to keep running after commands
+     * @param interactive true for interactive (line-edit) mode
      * @throws IOException on I/O failure
      */
     public CLI(Q2 q2, InputStream in, OutputStream rawout, String line, boolean keepRunning, boolean interactive) throws IOException {