fix(javadoc): phase 1 — fix all errors, add missing descriptions and type params

Errors fixed (100 → 0):
- Replace <font>/<tt> HTML4 tags with {@code} or plain text
  (BSHLogListener, JCEHandler, ISOBinaryField, ISOField, CharTag,
   CharTagMap, SimpleConfiguration)
- Remove bare <email> angle brackets from @author tags (11 files)
- Fix stray </p> after </ul> (TPS, ExceptionHandlerAware, LSpace,
  CryptographicServiceMessage, FSDMsg, RotateLogListener)
- Replace <p/> self-closing with <p> (TaggedFieldPackagerBase,
  GenericPackager, TaggedSequencePackager, SMAdapter, ISOMsg, ISOUtil)
- Escape raw XML tags in prose with {@code} or <pre>{@code}</pre>
  (RealmLogFilter, RemoveNewLinesMapper, QFactory, SelectDestination,
   VErrorParser, BSHLogListener table)
- Fix bare & entities → &amp; (IFE_CHAR, IF_ECHAR, IF_NOP, FilterLogListener,
  KeyScheme, ModeOfUse, SMAdapter, TLVList)
- Fix @see 'url' format → @see <a href=...> (ISOCurrency)
- Wrap orphan <li> items in <ul> (ISOUtil, SMAdapter, ARPCMethod,
  JCESecurityModule)
- Fix trailing ; on @throws/@exception class names (ISOSource,
  BaseChannel, ISOServer, QMUX and others)
- Split comma-separated @exception into individual tags
  (ASCIIChannel, CSChannel, GICCChannel, GZIPChannel)
- Fix <H1>/<H3> heading sequence → <h2> (FSDMsg, CMFChannel)
- Fix broken @ tags with space (KeySerialNumber)
- Fix @exception for undeclared checked exceptions (IF_NOP, Metrics)
- Fix email in @author: Leonard Thomas in BaseChannel
- Fix missing semicolon on &gt entity (ISOMeterFactory)
- Add table caption (BSHLogListener, SMAdapter)
- Fix invalid </br> → <br> (ISOMsgMetrics)
- Fix {@link} reference not found (CMFChannel → BaseChannel#accept)
- Fix <br/> self-closing (GenericPackager, others)

Warnings fixed (partial):
- Add @param <K>/<V>/<T> to 15 generic classes
  (Space, LocalSpace, SpaceListener, SpaceInterceptor, TSpace, LSpace,
   JESpace, JDBMSpace, MDBSpace, TagSequence, TagValue, TagValueBase,
   EMVTag, BaseSMAdapter, SMAdapter)
- Add missing main description to ~70 classes/interfaces
  (util, space, q2, ui, iso, tlv, emv, transaction packages)

Remaining: 100 warnings (no main description x56, @exception/@throws
descriptions, missing @throws IOException, misc @param/@return gaps)

Author: ar-agt

.sdkmanrc

@@ -1,3 +1,3 @@
 java=25.0.1-amzn
-gradle=9.2.1
+gradle=9.4.0
 

gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-9.2.1-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-9.4.0-bin.zip
 networkTimeout=10000
 validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME

jpos/build.gradle

@@ -12,6 +12,7 @@ extraJavaModuleInfo {
     automaticModule ('org.apache-extras.beanshell:bsh', 'bsh')
     automaticModule ('com.sleepycat:je', 'com.sleepycat.je')
     automaticModule ('jdbm:jdbm', 'org.jdbm')
+    automaticModule ('org.mapdb:mapdb', 'org.mapdb')
 }
 
 dependencies { 
@@ -32,6 +33,7 @@ dependencies {
 
     implementation libs.yaml;
     implementation libs.jdbm
+    implementation libs.mapdb
     implementation libs.sleepycatje
     implementation libs.hdrhistogram
 

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

@@ -38,55 +38,37 @@
  * can define scripts whose name depends on the event being processed, and the
  * realm of the object that generated it.
  * This way you can set a configuration like this:
+ * <pre>{@code
  * <log-listener class="org.jpos.bsh.BSHLoglistener">
  *    <property name="source" value="general.bsh"/>
- *    <property name="source" value="tag_$tag.bsh"/> <!--this is to handle
- * specific tags-->
- *    <property name="source" value="realm_$realm.bsh"/> <!-- to handle specific
- * realms-->
- *    <property name="source" value="tag_$tag_realm_$realm.bsh"/> <!-- to handle
- * specific tags from specific realms-->
+ *    <property name="source" value="tag_$tag.bsh"/>
+ *    <property name="source" value="realm_$realm.bsh"/>
+ *    <property name="source" value="tag_$tag_realm_$realm.bsh"/>
  * </log-listener>
- * <!-- the following lines are for html doc-->
- * <br>
- * <pre>
- * <font color="#008080">&lt;</font><font color="#008080">log-listener</font><font color="#008080"> </font><font color="#2e8b57"><b>class</b></font>=<font color="#ff00ff">&quot;org.jpos.bsh.BSHLoglistener&quot;</font><font color="#008080">&gt;</font>
- *       <font color="#008080">&lt;</font><font color="#008080">property</font><font color="#008080"> </font><font color="#2e8b57"><b>name</b></font>=<font color="#ff00ff">&quot;source&quot;</font><font color="#008080"> </font><font color="#2e8b57"><b>value</b></font>=<font color="#ff00ff">&quot;general.bsh&quot;</font><font color="#008080">/&gt;</font>
- *       <font color="#008080">&lt;</font><font color="#008080">property</font><font color="#008080"> </font><font color="#2e8b57"><b>name</b></font>=<font color="#ff00ff">&quot;source&quot;</font><font color="#008080"> </font><font color="#2e8b57"><b>value</b></font>=<font color="#ff00ff">&quot;tag_$tag.bsh&quot;</font><font color="#008080">/&gt;</font> <font color="#0000ff">&lt;!</font><font color="#0000ff">--this is to handle specific tags--</font><font color="#0000ff">&gt;</font>
- *       <font color="#008080">&lt;</font><font color="#008080">property</font><font color="#008080"> </font><font color="#2e8b57"><b>name</b></font>=<font color="#ff00ff">&quot;source&quot;</font><font color="#008080"> </font><font color="#2e8b57"><b>value</b></font>=<font color="#ff00ff">&quot;realm_$realm.bsh&quot;</font><font color="#008080">/&gt;</font> <font color="#0000ff">&lt;!</font><font color="#0000ff">-- to handle specific realms--</font><font color="#0000ff">&gt;</font>
- *       <font color="#008080">&lt;</font><font color="#008080">property</font><font color="#008080"> </font><font color="#2e8b57"><b>name</b></font>=<font color="#ff00ff">&quot;source&quot;</font><font color="#008080"> </font><font color="#2e8b57"><b>value</b></font>=<font color="#ff00ff">&quot;tag_$tag_realm_$realm.bsh&quot;</font><font color="#008080">/&gt;</font> <font color="#0000ff">&lt;!</font><font color="#0000ff">-- to handle specific tags from specific realms--</font><font color="#0000ff">&gt;</font>
- * <font color="#008080">&lt;/log-listener&gt;</font>
- * </pre>
- * <!-- end of lines for html doc-->
+ * }</pre>
  * If a source with the given name is not found, or it canbe read, it is not processed, so this lets
  * you change what is processed in real time, if you put a file called
  * tag_SystemMonitor_realm_monitor.bsh it will be executed whenever the system
  * monitor is run.<BR>
  * If you want to filter an event so that the remaining log listeners don't see
  * it, you have to set event = null in your script.<br>
- * <table border=1 color="black">
- * <caption>Other Configuration Options: </caption>
- * <th><td> Name                </td><td>Type       </td><td>Description</td></th>
- * <tr><td> filter-by-default   </td><td>boolean    </td><td>
- *  If true, filter the events if no script is processed, this way you can put a
- * Log Listener that filters every thing unless you put some script file, even if
- * it is empty, you also can dynamically change what kind of message are filtered
- * by placing empty files with names like tag_SystemMonitor_realm_monitor.bsh in
- * the previous example, if you "touch" a file with this name these events will
- * begin to be processed.</TD></TR>
- * <TR><TD> preload-scripts     </TD><TD>boolean    </TD><TD>If true scripts a
- * loaded once, and kept in memory, being realoaded only if they are touched. This
- * is good when you have lots of RAM memory but ou have troubles with
- * speed</TD></TR>
- * <TR><TD> save-name-space     </TD><TD>boolean    </TD><TD>If true the namespace
- * of the script instance will be saved so that in the next event you can access
- * them from the script, by default it's off, this property is overriden if the
- * script exposes a boolean variable named saveNameSpace</TD></TR>
- * <TR><TD> reload              </TD><TD>long       </TD><TD>this property is used
- * if the preload-script property is true, is the time in milliseconds between
- * updates in the script, during this time BSHLogListener will not check if the
- * script source was modified or deleted on disk </TD></TR>
- * </TABLE>
+ * <table>
+ * <caption>Other Configuration Options</caption>
+ * <thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead>
+ * <tbody>
+ * <tr><td>{@code filter-by-default}</td><td>boolean</td><td>
+ *   If true, filter the events if no script is processed, so you can dynamically
+ *   control what is logged by placing or removing script files.</td></tr>
+ * <tr><td>{@code preload-scripts}</td><td>boolean</td><td>
+ *   If true, scripts are loaded once and kept in memory, reloaded only when touched.</td></tr>
+ * <tr><td>{@code save-name-space}</td><td>boolean</td><td>
+ *   If true, the BeanShell namespace is preserved between events (default: false).
+ *   Overridden by a {@code saveNameSpace} variable in the script.</td></tr>
+ * <tr><td>{@code reload}</td><td>long</td><td>
+ *   When {@code preload-scripts} is true, the interval in milliseconds between
+ *   script modification checks.</td></tr>
+ * </tbody>
+ * </table>
  */
 public class BSHLogListener implements org.jpos.util.LogListener, org.jpos.core.Configurable {
     /**Holds the configuration for this object*/

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

@@ -47,7 +47,7 @@ public SimpleConfiguration (String filename)
     }
 
     /**
-     * Returns the value of the configuration property named <tt>name</tt>, or the default value <tt>def</tt>.
+     * Returns the value of the configuration property named {@code name}, or the default value {@code def}.
      *
      * If the property value has the format <code>${xxx}</code> then its value is taken from a system property
      * if it exists, or an environment variable. System property takes priority over environment variable.
@@ -57,8 +57,8 @@ public SimpleConfiguration (String filename)
      *
      * @param name The configuration property key name.
      * @param def  The default value.
-     * @return  The value stored under <tt>name</tt>,
-     *          or <tt>def</tt> if there's no configuration property under the given <tt>name</tt>.
+     * @return  The value stored under {@code name},
+     *          or {@code def} if there's no configuration property under the given {@code name}.
      */
     public String get (String name, String def) {
         Object obj = props.get (name);

jpos/src/main/java/org/jpos/core/handlers/exception/ExceptionHandlerAware.java

@@ -25,14 +25,12 @@
 /**
  * Interface that modifies an implementing class to add an exception handling pipeline.
  *
- * <p>
- *     The main pipeline consists of multiple sub-pipelines:
- *     <ul>
- *         <li>A pipeline for which handlers are called regardless of the type of exception handled.  Stored under a null key.</li>
- *         <li>A pipeline per targeted exception type.</li>
- *     </ul>
- *     The targeted pipeline always executes before the default pipeline.
- * </p>
+ * The main pipeline consists of multiple sub-pipelines:
+ * <ul>
+ *     <li>A pipeline for which handlers are called regardless of the type of exception handled.  Stored under a null key.</li>
+ *     <li>A pipeline per targeted exception type.</li>
+ * </ul>
+ * The targeted pipeline always executes before the default pipeline.
  * <p>
  *     In the event that both of the pipelines are empty, the default behavior is to rethrow the initial exception.
  * </p>

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

@@ -23,6 +23,7 @@
 
 
 /**
+ * An EMV tag whose value is represented as raw binary data.
  * @author Vishnu Pillai
  */
 public class BinaryEMVTag extends EMVTag<byte[]> {

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

@@ -27,6 +27,7 @@
 
 
 /**
+ * Enumeration of standard EMV tag types as defined in EMV specifications.
  * @author Vishnu Pillai
  */
 public enum EMVStandardTagType implements EMVTagType {

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

@@ -26,7 +26,10 @@
 
 
 /**
+ * Abstract base for EMV (Europay/Mastercard/Visa) tag-value pairs.
  * @author Vishnu Pillai
+
+ * @param <T> the tag value type
  */
 public abstract class EMVTag<T> implements TagValue<T>, Serializable {
 

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

@@ -22,6 +22,7 @@
 import org.jpos.tlv.TagSequenceBase;
 
 /**
+ * An ordered sequence of EMV tag-value elements.
  * @author Vishnu Pillai
  */
 public class EMVTagSequence extends TagSequenceBase {