fix(javadoc): phase 8 — CLI, CMF enum, ChannelEvent, CardHolder, CharTag, misc

- CLIContext: add class javadoc and inline comments for all 28 fields/methods/builder
- CLI: add class javadoc; document all constructors, lifecycle methods, static exec helpers
- CLICommandInterface: add class javadoc; document all 5 methods
- CLISubSystem: add interface javadoc and method comments
- CLIPrefixedClassNameCompleter: add class/field/constructor javadoc
- CMF: add class javadoc; document valueOf(); add comments for representative enum constants
- IRC: add descriptions to getIRC(), isSuccess(), isInhibit()
- ChannelEvent (JFR): add @name field comment; expand setDetail/getDetail/constructor javadocs
- CharTag: add lengthSize field comment
- CharTagMap: add class javadoc; expand validateTag()
- CardHolder: add description to getTrack2()
- BinaryEMVTag: expand all 3 constructor javadocs to multi-line with descriptions
- ChannelPool: add field comments; expand addChannel/removeChannel/size javadocs
- ChannelInfoFilter: add field/constructor comments
- ChannelAdaptor: fix duplicate @param channel; add grabSpace() comment
- BinaryHexTaggedSequencePackager.TagPackager: expand constructor javadoc
- AuditLogEvent: add comment marker inside sealed interface body
- CheckFields, CheckPoint, CLR, SsmActionBase, CK: add class javadoc + constructor
- BSHUI: add explicit documented constructor
- BSH (qbean): add class javadoc + explicit constructor
- BSHGroupSelector: add explicit constructor

Author: ar-agt

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

@@ -190,6 +190,7 @@ public String getNameOnCard() {
     }
 
     /**
+     * Returns a reconstructed track 2 string, or null if track 2 data is absent.
      * @return reconstructed track2 or null
      */
     public String getTrack2() {

jpos/src/main/java/org/jpos/emv/BinaryEMVTag.java

@@ -28,7 +28,9 @@
  */
 public class BinaryEMVTag extends EMVTag<byte[]> {
 
-    /** @param tagType the standard EMV tag type
+    /**
+     * Creates a BinaryEMVTag with a standard tag type.
+     * @param tagType the standard EMV tag type
      * @param value the raw byte value
      * @throws IllegalArgumentException if the value is invalid for the tag type
      */
@@ -37,7 +39,9 @@ public BinaryEMVTag(EMVStandardTagType tagType, byte[] value)
         super(tagType, value);
     }
 
-    /** @param tagType the proprietary tag type
+    /**
+     * Creates a BinaryEMVTag with a proprietary tag type.
+     * @param tagType the proprietary tag type
      * @param tagNumber the numeric tag identifier
      * @param value the raw byte value
      * @throws IllegalArgumentException if the value is invalid
@@ -47,7 +51,9 @@ public BinaryEMVTag(EMVProprietaryTagType tagType, Integer tagNumber, byte[] val
         super(tagType, tagNumber, value);
     }
 
-    /** @param tagType the proprietary tag type
+    /**
+     * Creates a BinaryEMVTag with a proprietary tag type and explicit format.
+     * @param tagType the proprietary tag type
      * @param tagNumber the numeric tag identifier
      * @param dataFormat the TLV data format
      * @param value the raw byte value

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

@@ -41,7 +41,9 @@
  * A pool of {@link ISOChannel} instances; tries each in order until one connects.
  */
 public class ChannelPool implements ISOChannel, LogSource, Configurable, Cloneable {
+    /** Whether this pool is in a usable state. */
     boolean usable = true;
+    /** Registered name of this pool. */
     String name = "";
     /** Logger for this pool. */
     protected Logger logger;
@@ -173,29 +175,42 @@ public void setConfiguration (Configuration cfg)
             }
         }
     }
-    /** @param channel the channel to add to the pool */
+    /**
+     * Adds a channel to the pool.
+     * @param channel the channel to add
+     */
     public void addChannel (ISOChannel channel) {
         pool.add (channel);
     }
-    /** @param name the NameRegistrar name of the channel to add
+    /**
+     * Adds a channel to the pool by its registered name.
+     * @param name the NameRegistrar name of the channel to add
      * @throws NameRegistrar.NotFoundException if name not found
      */
     public void addChannel (String name) 
         throws NameRegistrar.NotFoundException
     {
         pool.add (NameRegistrar.get ("channel."+name));
     }
-    /** @param channel the channel to remove */
+    /**
+     * Removes a channel from the pool.
+     * @param channel the channel to remove
+     */
     public void removeChannel (ISOChannel channel) {
         pool.remove (channel);
     }
-    /** @param name the channel name to remove
+    /**
+     * Removes a channel from the pool by its registered name.
+     * @param name the channel name to remove
      * @throws NameRegistrar.NotFoundException if name not found
      */
     public void removeChannel (String name) throws NameRegistrar.NotFoundException {
         pool.remove (NameRegistrar.get ("channel."+name));
     }
-    /** @return the number of channels in the pool */
+    /**
+     * Returns the number of channels in the pool.
+     * @return channel count
+     */
     public int size() {
         return pool.size();
     }

jpos/src/main/java/org/jpos/iso/filter/ChannelInfoFilter.java

@@ -34,8 +34,11 @@
  */
 @SuppressWarnings("unused")
 public class ChannelInfoFilter implements ISOFilter, Configurable {
+    /** Space field name to store the channel name. */
     String channelNameField;
+    /** Space field name to store socket info. */
     String socketInfoField;
+    /** Default constructor. */
     public ChannelInfoFilter() {
         super();
     }

jpos/src/main/java/org/jpos/jfr/ChannelEvent.java

@@ -27,6 +27,7 @@
 @Name("jpos.Channel")
 @StackTrace
 public class ChannelEvent extends Event {
+    /** JFR event detail string. */
     @Name("detail")
     /** Channel event detail string. */
     protected String detail;
@@ -40,12 +41,16 @@ public ChannelEvent(String detail) {
         this.detail = detail;
     }
 
-    /** @param detail new detail string */
+    /** Sets the event detail string.
+     * @param detail new detail string
+     */
     public void setDetail(String detail) {
         this.detail = detail;
     }
 
-    /** @return the event detail string */
+    /** Returns the event detail string.
+     * @return the event detail string
+     */
     public String getDetail() {
         return detail;
     }
@@ -98,7 +103,10 @@ public Disconnect() { }
     /** JFR event for a channel connection exception. */
     @Name("jpos.Channel.ConnectionException")
     public static class ConnectionException extends ChannelEvent {
-        /** @param detail exception detail string */
+        /**
+         * Creates a ChannelEvent for a connection exception.
+         * @param detail exception detail string
+         */
         public ConnectionException(String detail) {
             super(detail);
         }
@@ -107,7 +115,10 @@ public ConnectionException(String detail) {
     /** JFR event for a channel accept exception. */
     @Name("jpos.Channel.AcceptException")
     public static class AcceptException extends ChannelEvent {
-        /** @param detail exception detail string */
+        /**
+         * Creates a ChannelEvent for an accept exception.
+         * @param detail exception detail string
+         */
         public AcceptException(String detail) {
             super(detail);
         }
@@ -116,7 +127,10 @@ public AcceptException(String detail) {
     /** JFR event for a channel send exception. */
     @Name("jpos.Channel.SendException")
     public static class SendException extends ChannelEvent {
-        /** @param detail exception detail string */
+        /**
+         * Creates a ChannelEvent for a send exception.
+         * @param detail exception detail string
+         */
         public SendException(String detail) {
             super(detail);
         }

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

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

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

@@ -29,13 +29,15 @@
 import java.util.logging.Level;
 import java.util.logging.Logger;
 
+/** Interactive command-line interface for a running Q2 instance. */
 public class CLI implements Runnable {
     final private static String DEFAULT_PROMPT = "q2> ";
     final private static String ESCAPED_SEMICOLON = "__semicolon__";
     private Thread t;
     private String line = null;
     private boolean keepRunning = false;
     private boolean interactive = false;
+    /** The context for this CLI session. */
     protected CLIContext ctx;
     private CLICommandInterface cmdInterface;
     private Terminal terminal;
@@ -44,10 +46,23 @@ public class CLI implements Runnable {
     private String prompt = DEFAULT_PROMPT;
     private History mainHistory;
 
+    /** @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
+     */
     public CLI(Q2 q2, String line, boolean keepRunning) throws IOException {
         this(q2, System.in, System.out, line, keepRunning, true);
     }
 
+    /** @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
+     * @throws IOException on I/O failure
+     */
     public CLI(Q2 q2, InputStream in, OutputStream rawout, String line, boolean keepRunning, boolean interactive) throws IOException {
         Logger.getLogger("org.jline").setLevel(Level.SEVERE);
         this.q2 = q2;
@@ -63,18 +78,23 @@ public CLI(Q2 q2, InputStream in, OutputStream rawout, String line, boolean keep
         initCmdInterface(getCompletionPrefixes(), mainHistory);
     }
 
+    /** @return true if this CLI is still running */
     protected boolean running() {
         return getQ2() == null || getQ2().running();
     }
 
+    /** Called when the CLI is stopping; subclasses may override. */
     protected void markStopped() { }
 
+    /** Called when the CLI is starting; subclasses may override. */
     protected void markStarted() { }
 
+    /** @return array of command prefixes for tab-completion */
     protected String[] getCompletionPrefixes() {
         return new String[] {"org.jpos.q2.cli." };
     }
 
+    /** Called on normal exit; subclasses may override. */
     protected void handleExit() { }
 
     void setPrompt(String prompt, String[] completionPrefixes) throws IOException {
@@ -95,13 +115,17 @@ private void initCmdInterface(String[] completionPrefixes, History history) thro
         }
     }
 
+    /** Starts the CLI session.
+     * @throws Exception on startup failure
+     */
     public void start() throws Exception {
         markStarted();
         t = new Thread(this);
         t.setName("Q2-CLI");
         t.start();
     }
 
+    /** Stops the CLI session. */
     public void stop() {
         markStopped();
         try {
@@ -173,30 +197,47 @@ public void run() {
         handleExit();
     }
 
+    /** @return the Q2 instance this CLI is attached to */
     public Q2 getQ2() {
         return q2;
     }
 
+    /** @return true if this is an interactive session */
     public boolean isInteractive() {
         return interactive;
     }
 
+    /** @return the JLine3 LineReader for this session */
     public LineReader getReader() {
         return reader;
     }
 
+    /** @param in input stream
+     * @param out output stream
+     * @param command command to execute
+     * @throws Exception on execution failure
+     */
     public static void exec (InputStream in, OutputStream out, String command) throws Exception {
         CLI cli = new CLI(Q2.getQ2(), in, out, command, false, false);
         cli.start();
         cli.stop();
     }
 
+    /** @param command command string to execute
+     * @return captured output
+     * @throws Exception on execution failure
+     */
     public static String exec (String command) throws Exception {
         ByteArrayOutputStream out = new ByteArrayOutputStream();
         exec (null, out, command);
         return out.toString();
     }
 
+    /** @param in input stream
+     * @param out output stream
+     * @return a JLine3 Terminal for this session
+     * @throws IOException on I/O failure
+     */
     protected Terminal buildTerminal (InputStream in, OutputStream out) throws IOException {
         TerminalBuilder builder = TerminalBuilder.builder()
             .streams(in,out)

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

@@ -27,22 +27,29 @@
 import org.jline.terminal.Terminal;
 import org.jpos.iso.ISOUtil;
 
+/** Dispatches CLI command lines to the appropriate {@link CLICommand} implementation. */
 public class CLICommandInterface {
     CLIContext ctx;
     List<String> prefixes = new ArrayList<String>();
 
+    /** @return the list of registered command prefixes */
     public List<String> getPrefixes() {
         return prefixes;
     }
 
+    /** @param ctx the CLI context for this interface */
     public CLICommandInterface(CLIContext ctx) {
         this.ctx = ctx;
     }
 
+    /** @param prefix a command prefix to register */
     public void addPrefix(String prefix) {
         prefixes.add(prefix);
     }
 
+    /** @param line the full command line to execute
+     * @throws IOException on I/O failure
+     */
     public void execCommand(String line) throws IOException {
         String args[] = parseCommand(line);
         if (args.length == 0) {
@@ -91,6 +98,10 @@ private Object getCommand(String className) throws ClassNotFoundException, Insta
         return cl.loadClass(className).newInstance();
     }
 
+    /** @param line the full command line to parse
+     * @return tokens: [prefix, command, args...]
+     * @throws IOException on I/O failure
+     */
     public String[] parseCommand(String line) throws IOException {
         if (line == null) {
             return new String[0];