fix(javadoc): phase 7 — Card/CardHolder rewrites, ChannelAdaptor, UI, BSH, misc

- Card.java: full rewrite — all inline javadocs expanded, Builder methods documented
- CardHolder.java: add descriptions to all bare-tag javadocs; fix @exception descriptions;
  add @param pan/exp to constructor; document hasTrack2/getTrack2/setSecurityData/getSecurityData
- Channel.java: add description to receive(long timeout)
- ChannelAdaptor.java: fix addFilters (add @param channel + @throws); move Receiver/Sender
  javadoc before @SuppressWarnings; add Receiver/Sender constructors; add disconnect() doc
- ChannelAdaptorMBean.java: document all JMX methods
- BinaryEMVTag.java: document all 3 constructors
- UIAware.java: add method description to setUI
- UIFactory.java: add create() method description
- BSHUI.java: add explicit documented constructor; move doScript() javadoc
- CALCLUHN.java: move class javadoc before @SuppressWarnings; add exec() comment
- BSH.java: add class javadoc; add explicit documented constructor
- BSHGroupSelector.java: add explicit constructor; add class javadoc
- BcdPrefixer.java, BinaryPrefixer.java: expand inline constructor javadocs to multi-line
- BinaryTagValue.java: expand constructor javadoc
- BlockingQueue.java: move class javadoc before @SuppressWarnings
- BufferedExceptionLogListener.java: add class javadoc and constructor
- DefaultICCBERTLVPackager.java: add @param tag description

Author: ar-agt

jpos/src/main/java/org/jpos/bsh/BSHUI.java

@@ -32,6 +32,10 @@
  *
  */
 public class BSHUI extends UI {
+    /** Default constructor. */
+    public BSHUI() { super(); }
+    /** {@inheritDoc} */
+    @Override
     protected JComponent doScript (JComponent component, Element e) {
         try {
             Interpreter bsh = new Interpreter ();

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

@@ -247,12 +247,18 @@ public void setTrailler (String trailer) {
         this.trailer = trailer;
     }
 
-    /** @return the card trailer string */
+    /**
+     * Returns the card trailer string.
+     * @return card trailer
+     */
     public String getTrailer() {
         return trailer;
     }
 
-    /** @param trailer the card trailer string */
+    /**
+     * Sets the card trailer string.
+     * @param trailer card trailer
+     */
     public void setTrailer(String trailer) {
         this.trailer = trailer;
     }
@@ -284,8 +290,10 @@ public String getPAN () {
      * Can be used for the newer 8-digit BINs, or some arbitrary length.
      * @return <code>len</code>-digit bank issuer number
      */
-    /** @param len number of BIN digits to return
-     * @return the BIN (first {@code len} digits of the PAN)
+    /**
+     * Returns the first {@code len} digits of the PAN (the BIN).
+     * @param len number of BIN digits to return
+     * @return the BIN prefix
      */
     public String getBIN (int len) {
         return pan.substring(0, len);
@@ -350,12 +358,17 @@ public boolean isExpired(Date currentDate) {
         }
         return true;
     }
-    /** @return true if the PAN passes the Luhn check */
+    /**
+     * Returns true if the PAN passes the Luhn (mod-10) check.
+     * @return true if the Luhn check passes
+     */
     public boolean isValidCRC () {
         return isValidCRC(this.pan);
     }
-    /** @param p the PAN to validate
-     * @return true if {@code p} passes the Luhn check
+    /**
+     * Returns true if the given PAN passes the Luhn (mod-10) check.
+     * @param p the PAN to validate
+     * @return true if the Luhn check passes
      */
     public static boolean isValidCRC (String p) {
         int i, crc;
@@ -412,7 +425,10 @@ public String getServiceCode () {
             trailer.substring (0, 3) :
             "   ";
     }
-    /** @return true if this card entry appears to be manual (not swiped/dipped) */
+    /**
+     * Returns true if this card appears to have been entered manually.
+     * @return true if manual entry is suspected
+     */
     public boolean seemsManualEntry() {
         return trailer == null || trailer.trim().length() == 0;
     }

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

@@ -28,16 +28,31 @@
  */
 public class BinaryEMVTag extends EMVTag<byte[]> {
 
+    /** @param tagType the standard EMV tag type
+     * @param value the raw byte value
+     * @throws IllegalArgumentException if the value is invalid for the tag type
+     */
     public BinaryEMVTag(EMVStandardTagType tagType, byte[] value)
             throws IllegalArgumentException {
         super(tagType, value);
     }
 
+    /** @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
+     */
     public BinaryEMVTag(EMVProprietaryTagType tagType, Integer tagNumber, byte[] value)
             throws IllegalArgumentException {
         super(tagType, tagNumber, value);
     }
 
+    /** @param tagType the proprietary tag type
+     * @param tagNumber the numeric tag identifier
+     * @param dataFormat the TLV data format
+     * @param value the raw byte value
+     * @throws IllegalArgumentException if the value is invalid
+     */
     public BinaryEMVTag(EMVProprietaryTagType tagType, Integer tagNumber, TLVDataFormat dataFormat, byte[] value)
             throws IllegalArgumentException {
         super(tagType, tagNumber, dataFormat, value);

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

@@ -58,7 +58,10 @@ public class BcdPrefixer implements Prefixer
     /** The number of digits allowed to express the length */
     private int nDigits;
 
-    /** @param nDigits the number of BCD digits used for the length prefix */
+    /**
+     * Creates a BcdPrefixer with the given number of digits.
+     * @param nDigits the number of BCD digits used for the length prefix
+     */
     public BcdPrefixer(int nDigits)
     {
         this.nDigits = nDigits;

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

@@ -42,7 +42,10 @@ public class BinaryPrefixer implements Prefixer
     /** The number of digits allowed to express the length */
     private int nBytes;
 
-    /** @param nBytes the number of bytes used for the length prefix */
+    /**
+     * Creates a BinaryPrefixer with the given number of bytes.
+     * @param nBytes the number of bytes used for the length prefix
+     */
     public BinaryPrefixer(int nBytes)
     {
         this.nBytes = nBytes;

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

@@ -38,8 +38,9 @@ public interface Channel {
      */
     ISOMsg receive();
     /**
+     * Receives an ISO message, waiting at most {@code timeout} milliseconds.
      * @param timeout time to wait for a message
-     * @return received message or null
+     * @return received message or null on timeout
      */
     ISOMsg receive(long timeout);
 }

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

@@ -37,16 +37,22 @@
 import java.util.concurrent.locks.ReentrantLock;
 
 @SuppressWarnings("unchecked")
+/**
+ * A pool of {@link ISOChannel} instances; tries each in order until one connects.
+ */
 public class ChannelPool implements ISOChannel, LogSource, Configurable, Cloneable {
     boolean usable = true;
     String name = "";
+    /** Logger for this pool. */
     protected Logger logger;
+    /** Log realm for this pool. */
     protected String realm;
     Configuration cfg = null;
     List pool;
     ISOChannel current;
     Lock lock = new ReentrantLock();
 
+    /** Default constructor. */
     public ChannelPool () {
         super ();
         pool = new Vector ();
@@ -167,23 +173,36 @@ public void setConfiguration (Configuration cfg)
             }
         }
     }
+    /** @param channel the channel to add to the pool */
     public void addChannel (ISOChannel channel) {
         pool.add (channel);
     }
+    /** @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 */
     public void removeChannel (ISOChannel channel) {
         pool.remove (channel);
     }
+    /** @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 */
     public int size() {
         return pool.size();
     }
+    /** Returns the currently active channel, trying to connect if necessary.
+     * @return the active ISOChannel
+     * @throws IOException if no channel can be connected
+     */
     public ISOChannel getCurrent () throws IOException {
         lock.lock();
         try {

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

@@ -20,63 +20,103 @@
 
 import jdk.jfr.*;
 
+/**
+ * JFR event base class for jPOS channel operations.
+ */
 @Category("jPOS")
 @Name("jpos.Channel")
 @StackTrace
 public class ChannelEvent extends Event {
     @Name("detail")
+    /** Channel event detail string. */
     protected String detail;
 
+    /** Creates a ChannelEvent with no detail. */
     public ChannelEvent() {}
+    /** Creates a ChannelEvent with the given detail.
+     * @param detail event detail string
+     */
     public ChannelEvent(String detail) {
         this.detail = detail;
     }
 
+    /** @param detail new detail string */
     public void setDetail(String detail) {
         this.detail = detail;
     }
 
+    /** @return the event detail string */
     public String getDetail() {
         return detail;
     }
 
+    /** Appends additional detail to this event.
+     * @param additionalDetail text to append
+     * @return this event
+     */
     public ChannelEvent append (String additionalDetail) {
         detail = detail != null ?
           "%s, %s".formatted (detail, additionalDetail) : additionalDetail;
         return this;
     }
 
+    /** JFR event for a channel send operation. */
     @Name("jpos.Channel.Send")
-    public static class Send extends ChannelEvent { }
+    public static class Send extends ChannelEvent {
+        /** Default constructor. */
+        public Send() { }
+    }
 
+    /** JFR event for a channel receive operation. */
     @Name("jpos.Channel.Receive")
-    public static class Receive extends ChannelEvent { }
+    public static class Receive extends ChannelEvent {
+        /** Default constructor. */
+        public Receive() { }
+    }
 
+    /** JFR event for a channel connect operation. */
     @Name("jpos.Channel.Connect")
-    public static class Connect extends ChannelEvent { }
+    public static class Connect extends ChannelEvent {
+        /** Default constructor. */
+        public Connect() { }
+    }
 
+    /** JFR event for a channel accept (inbound connection) operation. */
     @Name("jpos.Channel.Accept")
-    public static class Accept extends ChannelEvent { }
+    public static class Accept extends ChannelEvent {
+        /** Default constructor. */
+        public Accept() { }
+    }
 
+    /** JFR event for a channel disconnect operation. */
     @Name("jpos.Channel.Disconnect")
-    public static class Disconnect extends ChannelEvent { }
+    public static class Disconnect extends ChannelEvent {
+        /** Default constructor. */
+        public Disconnect() { }
+    }
 
+    /** JFR event for a channel connection exception. */
     @Name("jpos.Channel.ConnectionException")
     public static class ConnectionException extends ChannelEvent {
+        /** @param detail exception detail string */
         public ConnectionException(String detail) {
             super(detail);
         }
     }
 
+    /** JFR event for a channel accept exception. */
     @Name("jpos.Channel.AcceptException")
     public static class AcceptException extends ChannelEvent {
+        /** @param detail exception detail string */
         public AcceptException(String detail) {
             super(detail);
         }
     }
 
+    /** JFR event for a channel send exception. */
     @Name("jpos.Channel.SendException")
     public static class SendException extends ChannelEvent {
+        /** @param detail exception detail string */
         public SendException(String detail) {
             super(detail);
         }

jpos/src/main/java/org/jpos/q2/cli/CALCLUHN.java

@@ -22,13 +22,17 @@
 import org.jpos.q2.CLICommand;
 import org.jpos.q2.CLIContext;
 
-@SuppressWarnings("unused")
 /**
  * CLI command that calculates a Luhn check digit.
  */
+@SuppressWarnings("unused")
 public class CALCLUHN implements CLICommand {
     /** Default constructor. */
     public CALCLUHN() { }
+    /** @param ctx CLI context
+     * @param args command arguments (first arg = PAN to check)
+     * @throws Exception on error
+     */
     public void exec(CLIContext ctx, String[] args) throws Exception {
         if (args.length < 2) {
             ctx.println (String.format ("Usage: %span(s)", args[0]));