fix(javadoc): phase 5 — BlockingQueue, BSH classes, TLV packagers, SMAdapter, QBean, etc.

- BlockingQueue: add class/constructor/all method docs
- BSHAction: add class/field/constructor comments
- BSHFilter, BinaryTagValue: add class-level descriptions
- BinaryEMVTag: add getValue/getTag/getFormattedValue comments
- BcdPrefixer, BinaryPrefixer: add INSTANCE field comments
- XmlConfigurable: add description to setConfiguration
- ISOFilter, RawIncomingFilter: add descriptions and fix bare @throws
- BCDChannel: add @exception descriptions
- GenericPackager: add missing @throws ISOException
- QBean: add getServer/getName descriptions
- QBeanSupport: add logger/realm field comments
- BSH: add class/field javadoc
- GroupSelector, BSHGroupSelector, BSHMethod: add descriptions
- UIAware, UIFactory, BorderLayoutFactory: add method/class javadocs
- LogListener: add log() method description
- BSHLogListener: add field/method/inner class comments
- TLV packagers (BinaryHexTaggedSequencePackager, TaggedSequencePackager,
  BERTLVPackager, BERTLVAsciiHexPackager, BERTLVBinaryPackager, BERTLVEbcdicHexPackager,
  BERTLVFormatMapper, DefaultICCBERTLVFormatMapper): add constructor/method/field comments
- BaseSMAdapter: add field/constructor comments; fix getName/setName descriptions; fix @throws
- SMAdapter: fix remaining @param descriptions
- ISOMsg: fix getSource description
- ISOFieldPackager: expand all remaining inline javadocs

Author: ar-agt

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

@@ -26,9 +26,12 @@
 import java.awt.event.ActionEvent;
 import java.awt.event.ActionListener;
 
+/** Swing {@link ActionListener} implemented via a BeanShell script. */
 public class BSHAction implements ActionListener, UIAware {
+    /** The UI context. */
     public UI ui;
 
+    /** Default constructor. */
     public BSHAction () {
         super();
     }

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

@@ -73,7 +73,9 @@
 public class BSHLogListener implements org.jpos.util.LogListener, org.jpos.core.Configurable {
     /**Holds the configuration for this object*/
     protected Configuration cfg;
+    /** Pattern names used for script filename matching. */
     protected static final String[] patterns = {"tag", "realm"};
+    /** Cache of loaded BeanShell scripts keyed by filename. */
     protected Map<String, ScriptInfo> scripts = new HashMap<>();
     /** Creates a new instance of BSHLogListener */
     public BSHLogListener() {
@@ -83,6 +85,11 @@ public BSHLogListener() {
     public void setConfiguration(org.jpos.core.Configuration cfg) {
         this.cfg = cfg;
     }
+    /** @param src source strings
+     * @param patterns patterns to replace
+     * @param to replacement strings
+     * @return result array with patterns replaced
+     */
     protected static String[] replace(String[] src, String[] patterns, String[] to){
         String[] ret = new String[src.length];
         for(int i=0; i<src.length; i++){
@@ -166,6 +173,10 @@ public LogEvent log(LogEvent ev) {
             return ret;
         }
     }
+    /** @param f script file to load
+     * @return file contents as a string
+     * @throws IOException on read failure
+     */
     protected String loadCode(File f) throws IOException{
         StringBuilder buf = new StringBuilder((int)f.length());
         char[] content = new char[(int)f.length()];
@@ -179,27 +190,40 @@ protected String loadCode(File f) throws IOException{
         return buf.toString();
     }
 
+    /** @param filename the script filename key
+     * @return cached ScriptInfo or null
+     */
     protected ScriptInfo getScriptInfo(String filename){
         Objects.requireNonNull(filename, "The script file name cannot be null");
         return scripts.get(filename);
     }
 
+    /** @param filename the script filename key
+     * @param code the script source code
+     * @param lastModified last-modified timestamp
+     */
     protected void addScriptInfo(String filename, String code, long lastModified){
         Objects.requireNonNull(filename, "The script file name cannot be null");
         scripts.put(filename, new ScriptInfo(code, lastModified));
     }
+    /** Holds a cached BeanShell script and its namespace. */
     protected static class ScriptInfo{
         String code;
         long lastModified;
         long lastCheck;
         NameSpace nameSpace;
 
+        /** Default constructor creating an empty ScriptInfo. */
         public ScriptInfo(){
         }
+        /** @param ns the BeanShell namespace to use */
         public ScriptInfo(NameSpace ns){
             nameSpace = ns;
         }
 
+        /** @param code the script source code
+         * @param lastModified last-modified timestamp of the script file
+         */
         public ScriptInfo(String code, long lastModified){
             setCode(code);
             setLastModified(lastModified);

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

@@ -30,6 +30,7 @@ public class BcdPrefixer implements Prefixer
     /**
      * A length prefixer for up to 9 chars. The length is encoded with 1 BCD digit.
      */
+    /** Pre-built BcdPrefixer instances for common lengths. */
     public static final BcdPrefixer L = new BcdPrefixer(1);
     /**
 	 * A length prefixer for up to 99 chars. The length is encoded with 2 BCD digits.

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

@@ -29,6 +29,7 @@ public class BinaryPrefixer implements Prefixer
     /**
 	 * A length prefixer for up to 255 chars. The length is encoded with 1 unsigned byte.
 	 */
+    /** Pre-built BinaryPrefixer instances for common lengths. */
     public static final BinaryPrefixer B = new BinaryPrefixer(1);
 
     /**

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

@@ -88,11 +88,17 @@ public ISOFieldPackager(int len, String description) {
     public String getDescription() {
         return description;
     }
-    /** Sets the field description. @param description the description */
+    /**
+     * Sets the field description.
+     * @param description the description text
+     */
     public void setDescription(String description) {
         this.description = description;
     }
-    /** Returns the maximum field length. @return max field length */
+    /**
+     * Returns the maximum field length.
+     * @return max field length
+     */
     public int getLength() {
         return len;
     }

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

@@ -49,7 +49,7 @@ public VetoException (String detail, Exception nested) {
      * @param m ISOMsg to filter
      * @param evt LogEvent
      * @return an ISOMsg (possibly parameter m)
-     * @throws VetoException
+     * @throws VetoException if the message should be suppressed
      */
     ISOMsg filter(ISOChannel channel, ISOMsg m, LogEvent evt)
         throws VetoException;

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

@@ -1259,6 +1259,7 @@ public void setSource (ISOSource source) {
         this.sourceRef = new WeakReference (source);
     }
     /**
+     * Returns the associated ISOSource (e.g. the channel that received this message).
      * @return an ISOSource or null
      */
     public ISOSource getSource () {

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

@@ -34,7 +34,7 @@ public interface RawIncomingFilter extends ISOFilter {
      * @param image raw image
      * @param evt LogEvent
      * @return an ISOMsg (possibly parameter m)
-     * @throws VetoException
+     * @throws VetoException if the message should be suppressed
      */
     ISOMsg filter(ISOChannel channel, ISOMsg m,
                   byte[] header, byte[] image, LogEvent evt)

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

@@ -59,7 +59,7 @@ public BCDChannel (String host, int port, ISOPackager p, byte[] TPDU) {
      * Construct server ISOChannel
      * @param p     an ISOPackager
      * @param TPDU  an optional raw header (i.e. TPDU)
-     * @exception IOException
+     * @exception IOException on I/O failure
      * @see ISOPackager
      */
     public BCDChannel (ISOPackager p, byte[] TPDU) throws IOException {

jpos/src/main/java/org/jpos/iso/packager/Base1_BITMAP126.java

@@ -52,7 +52,7 @@ public Base1_BITMAP126(int len, String description)
     /**
     * @param c - a component
     * @return packed component
-    * @exception ISOException
+    * @throws ISOException on packing/unpacking error
     */
     public byte[] pack (ISOComponent c) throws ISOException 
     {