fix(javadoc): phase 4 — SMAdapter/BaseSMAdapter, ISOMsg, BaseChannelMBean, misc interfaces

- SMAdapter: add descriptions to all bare @throws SMException/@throws JCEHandlerException
- BaseSMAdapter: expand all 79 bare @param tags; fix all bare @throws
- ISOMsg: add main descriptions to 20+ methods (getDirection, isIncoming, isOutgoing,
  getMaxField, setPackager, getPackager, pack, unpack, hasFields, isInner, setMTI,
  hasMTI, getMTI, isRequest/Response/Authorization/Financial/FileAction/Reversal/
  Chargeback/Reconciliation/Administrative/FeeCollection/NetworkManagement/Retransmission,
  getValue); fix @exception descriptions; add @OverRide unpack(InputStream)
- BaseChannelMBean: expand all inline single-line javadocs to multi-line with descriptions
- ISOFieldPackager: expand inline javadocs (setLength/setPad/setTrim/pack(ObjectOutput))
- BASE1Header: convert /* to /** for class-level Javadoc
- BaseHeader: add field and constructor comments
- LogSource: expand inline javadocs for getRealm/getLogger
- Loggeable: add dump() method description
- LogEventWriter: add method comments
- BaseLogEventWriter: add explicit documented constructor
- AuditLogEvent: reformat sealed interface to multi-line; fix class comment
- ISOMsgMetrics.Source: expand inline javadocs
- BaseChannel: expand isSoLingerOn/getSoLingerSeconds/isExpectKeepAlive
- SpaceFactory: revert MDB additions (belong in wip/mdb-space)
- Base1_BITMAP126: @exception → @throws conversion
- BASE24TCPChannel: add @exception descriptions

Author: ar-agt

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

@@ -471,11 +471,17 @@ public void setSoLinger(boolean on, int linger) {
         this.soLingerOn = on;
         this.soLingerSeconds = linger;
     }
-    /** @return true if SO_LINGER is enabled */
+    /**
+     * Returns true if SO_LINGER is enabled.
+     * @return true if SO_LINGER is on
+     */
     public boolean isSoLingerOn() {
         return soLingerOn;
     }
-    /** @return the SO_LINGER timeout in seconds */
+    /**
+     * Returns the SO_LINGER timeout.
+     * @return SO_LINGER timeout in seconds
+     */
     public int getSoLingerSeconds() {
         return soLingerSeconds;
     }
@@ -852,7 +858,10 @@ public void sendKeepAlive () throws IOException {
         }
     }
 
-    /** @return true if this channel expects keep-alive messages from the remote end */
+    /**
+     * Returns true if this channel expects keep-alive messages from the remote end.
+     * @return true if keep-alive is expected
+     */
     public boolean isExpectKeepAlive() {
         return expectKeepAlive;
     }

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

@@ -23,21 +23,45 @@
  * JMX management interface for {@link BaseChannel}.
  */
 public interface BaseChannelMBean {
-    /** @return the remote host name or address */
+    /**
+     * Returns the remote host name or address.
+     * @return remote host
+     */
     String getHost();
-    /** @param host the remote host name or address */
+    /**
+     * Sets the remote host name or address.
+     * @param host remote host
+     */
     void setHost(String host);
-    /** @return the remote port number */
+    /**
+     * Returns the remote port number.
+     * @return remote port
+     */
     int    getPort();
-    /** @param port the remote port number */
+    /**
+     * Sets the remote port number.
+     * @param port remote port
+     */
     void setPort(int port);
-    /** @return true if the channel is currently connected */
+    /**
+     * Returns true if the channel has an active connection.
+     * @return true if connected
+     */
     boolean isConnected();
-    /** Establishes a connection. @throws IOException on connection failure */
+    /**
+     * Establishes a connection.
+     * @throws IOException on connection failure
+     */
     void connect() throws IOException;
-    /** Closes the connection. @throws IOException on close failure */
+    /**
+     * Closes the connection.
+     * @throws IOException on close failure
+     */
     void disconnect() throws IOException;
-    /** Reconnects the channel. @throws IOException on connection failure */
+    /**
+     * Reconnects the channel.
+     * @throws IOException on connection failure
+     */
     void reconnect() throws IOException;
 }
 

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

@@ -42,15 +42,15 @@ public abstract class ISOComponent implements Cloneable {
     /**
      * Set a field within this message
      * @param c - a component
-     * @exception ISOException
+     * @exception ISOException on ISO error
      */
     public void set (ISOComponent c) throws ISOException {
         throw new ISOException ("Can't add to Leaf");
     }
     /**
      * Unset a field
      * @param fldno - the field number
-     * @exception ISOException
+     * @exception ISOException on ISO error
      */
     public void unset (int fldno) throws ISOException {
         throw new ISOException ("Can't remove from Leaf");
@@ -72,23 +72,23 @@ public ISOComponent getComposite() {
      * to this field.
      *
      * @return object representing the field number
-     * @exception ISOException
+     * @exception ISOException on ISO error
      */
     public Object getKey() throws ISOException {
         throw new ISOException ("N/A in Composite");
     }
     /**
      * valid on Leafs only.
      * @return object representing the field value
-     * @exception ISOException
+     * @exception ISOException on ISO error
      */
     public Object getValue() throws ISOException {
         throw new ISOException ("N/A in Composite");
     }
     /**
      * get Value as bytes (when possible)
      * @return byte[] representing this field
-     * @exception ISOException
+     * @exception ISOException on ISO error
      */
     public byte[] getBytes() throws ISOException {
         throw new ISOException ("N/A in Composite");

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

@@ -96,17 +96,26 @@ public void setDescription(String description) {
     public int getLength() {
         return len;
     }
-    /** Sets the maximum field length. @param len the maximum length */
+    /**
+     * Sets the maximum field length.
+     * @param len the maximum length
+     */
     public void setLength(int len) {
         this.len = len;
     }
 
-    /** Enables or disables padding for this field. @param pad true to enable padding */
+    /**
+     * Enables or disables padding for this field.
+     * @param pad true to enable padding
+     */
     public void setPad(boolean pad) {
         this.pad = pad;
     }
 
-    /** Enables or disables trimming for this field. @param trim true to enable trimming */
+    /**
+     * Enables or disables trimming for this field.
+     * @param trim true to enable trimming
+     */
     public void setTrim(boolean trim) {
         this.trim = trim;
     }
@@ -157,10 +166,11 @@ public void unpack (ISOComponent c, InputStream in)
         unpack (c, readBytes (in, getMaxPackedLength ()), 0);
     }
     /**
-     * @param c   - the Component to unpack
+     * Packs the component to an ObjectOutput stream.
+     * @param c   - the Component to pack
      * @param out - output stream
-     * @exception ISOException on packing/unpacking error
-     * @exception IOException
+     * @throws ISOException on packing error
+     * @throws IOException on I/O failure
      */
     public void pack (ISOComponent c, ObjectOutput out) 
         throws IOException, ISOException