diff --git a/.sdkmanrc b/.sdkmanrc index a493f64f02..b3011fbc1b 100644 --- a/.sdkmanrc +++ b/.sdkmanrc @@ -1,3 +1,3 @@ java=25.0.1-amzn -gradle=9.2.1 +gradle=9.4.0 diff --git a/gradle/wrapper/gradle-wrapper.properties b/gradle/wrapper/gradle-wrapper.properties index 23449a2b54..dbc3ce4a04 100644 --- a/gradle/wrapper/gradle-wrapper.properties +++ b/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 diff --git a/jpos/build.gradle b/jpos/build.gradle index 59617fc6bf..141f927f5d 100644 --- a/jpos/build.gradle +++ b/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 diff --git a/jpos/src/main/java/org/jpos/bsh/BSHAction.java b/jpos/src/main/java/org/jpos/bsh/BSHAction.java index fc770f4a34..159842bf56 100644 --- a/jpos/src/main/java/org/jpos/bsh/BSHAction.java +++ b/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(); } diff --git a/jpos/src/main/java/org/jpos/bsh/BSHFilter.java b/jpos/src/main/java/org/jpos/bsh/BSHFilter.java index 8f18c3ab0f..02830eca28 100644 --- a/jpos/src/main/java/org/jpos/bsh/BSHFilter.java +++ b/jpos/src/main/java/org/jpos/bsh/BSHFilter.java @@ -34,7 +34,9 @@ * @version $Revision$ $Date$ */ public class BSHFilter implements RawIncomingFilter, Configurable { + /** Configuration for this filter. */ Configuration cfg; + /** Default constructor. */ public BSHFilter () { super(); } diff --git a/jpos/src/main/java/org/jpos/bsh/BSHLogListener.java b/jpos/src/main/java/org/jpos/bsh/BSHLogListener.java index 844d0ef318..7d1f97d4dd 100644 --- a/jpos/src/main/java/org/jpos/bsh/BSHLogListener.java +++ b/jpos/src/main/java/org/jpos/bsh/BSHLogListener.java @@ -38,60 +38,44 @@ * 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: + * 
{@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-->
- * </log-listener>
- * 

- * 
+ * }
* 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.
* 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.
- * - * - * - * - * - * - * - *
Other Configuration Options:
Name Type Description
filter-by-default boolean - * 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.
preload-scripts boolean 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
save-name-space boolean 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
reload long 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
+ * + * + * + * + * + * + * + * + * + *
Other Configuration Options
NameTypeDescription
{@code filter-by-default}boolean + * If true, filter the events if no script is processed, so you can dynamically + * control what is logged by placing or removing script files.
{@code preload-scripts}boolean + * If true, scripts are loaded once and kept in memory, reloaded only when touched.
{@code save-name-space}boolean + * If true, the BeanShell namespace is preserved between events (default: false). + * Overridden by a {@code saveNameSpace} variable in the script.
{@code reload}long + * When {@code preload-scripts} is true, the interval in milliseconds between + * script modification checks.
*/ 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 scripts = new HashMap<>(); /** Creates a new instance of BSHLogListener */ public BSHLogListener() { @@ -101,6 +85,13 @@ public BSHLogListener() { public void setConfiguration(org.jpos.core.Configuration cfg) { this.cfg = cfg; } + /** + * Replaces pattern tokens in the source strings. + * @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 whitelist; + /** BeanShell source file paths. */ protected String[] bshSource; + /** Configuration for this listener. */ Configuration cfg; + /** Default constructor. */ public BSHRequestListener () { super(); } diff --git a/jpos/src/main/java/org/jpos/bsh/BSHUI.java b/jpos/src/main/java/org/jpos/bsh/BSHUI.java index bf1cbe6ddd..4b2c4c1ee8 100644 --- a/jpos/src/main/java/org/jpos/bsh/BSHUI.java +++ b/jpos/src/main/java/org/jpos/bsh/BSHUI.java @@ -25,11 +25,17 @@ import javax.swing.*; /** - * @author Alejandro Revilla * * UI with BSH script support + * + * @author Alejandro Revilla + * */ public class BSHUI extends UI { + /** Default constructor. */ + public BSHUI() { super(); } + /** {@inheritDoc} */ + @Override protected JComponent doScript (JComponent component, Element e) { try { Interpreter bsh = new Interpreter (); diff --git a/jpos/src/main/java/org/jpos/core/Card.java b/jpos/src/main/java/org/jpos/core/Card.java index aaa89b0333..edb1f2135c 100644 --- a/jpos/src/main/java/org/jpos/core/Card.java +++ b/jpos/src/main/java/org/jpos/core/Card.java @@ -27,23 +27,36 @@ import java.util.Objects; /** + * Immutable card data carrier. + * + * This class is based on the old {@code CardHolder} class and adds support for multiple + * PAN and expiration date sources (manual entry, track 1, track 2). It also fixes naming. + * * @author apr@jpos.org * @since jPOS 2.0.5 - * - * This class is based on the old 'CardHolder' class and adds support for multiple - * PAN and Expiration dates taken from manual entry, track1, track2. It also corrects the name. */ public class Card { + /** Primary account number. */ private String pan; + /** Expiration date (YYMM). */ private String exp; + /** CVV2 / CVC2 value. */ private String cvv2; + /** 3-digit ISO service code. */ private String serviceCode; + /** Track 1 data. */ private Track1 track1; + /** Track 2 data. */ private Track2 track2; + /** Length of the BIN (Bank Identification Number) in digits. */ public static final int BINLEN = 6; private Card() { } + /** + * Creates a Card from the given Builder. + * @param builder the builder + */ public Card(Builder builder) { pan = builder.pan; exp = builder.exp; @@ -53,60 +66,95 @@ public Card(Builder builder) { track2 = builder.track2; } + /** + * Returns the primary account number. + * @return the PAN + */ public String getPan() { return pan; } + /** + * Returns the primary account number as a {@link BigInteger}. + * @return the PAN as a BigInteger + */ public BigInteger getPanAsNumber() { return new BigInteger(pan); } + /** + * Returns the card expiry date. + * @return the expiry date in YYMM format + */ public String getExp() { return exp; } + /** + * Returns the CVV2 / CVC2 value. + * @return the CVV2 value + */ public String getCvv2() { return cvv2; } + /** + * Returns the ISO service code. + * @return the 3-digit service code + */ public String getServiceCode() { return serviceCode; } + /** + * Returns true if track 1 data is present. + * @return true if track 1 is available + */ public boolean hasTrack1() { return track1 != null; } + /** + * Returns true if track 2 data is present. + * @return true if track 2 is available + */ public boolean hasTrack2() { return track2 != null; } + /** + * Returns true if both track 1 and track 2 data are present. + * @return true if both tracks are available + */ public boolean hasBothTracks() { return hasTrack1() && hasTrack2(); } /** - * Returns the traditional 6-digit BIN from the PAN - * @return the first 6 digits of the PAN + * Returns the traditional 6-digit BIN from the PAN. + * @return the first {@value #BINLEN} digits of the PAN */ public String getBin () { return getBin(BINLEN); } /** - * Returns the first len digits from the PAN. + * Returns the first {@code len} digits from the PAN. * Can be used for the newer 8-digit BINs, or some arbitrary length. - * @return the first len digits of the PAN + * @param len number of leading digits to return + * @return the first {@code len} digits of the PAN */ public String getBin (int len) { return pan.substring(0, len); } + /** {@inheritDoc} */ @Override public String toString() { return pan != null ? ISOUtil.protect(pan) : "nil"; } + /** {@inheritDoc} */ @Override public boolean equals(Object o) { if (this == o) return true; @@ -120,19 +168,33 @@ public boolean equals(Object o) { Objects.equals(track2, card.track2); } + /** {@inheritDoc} */ @Override public int hashCode() { return Objects.hash(pan, exp, cvv2, serviceCode, track1, track2); } + /** + * Returns the Track 1 data. + * @return the {@link Track1} object, or null if not present + */ public Track1 getTrack1() { return track1; } + /** + * Returns the Track 2 data. + * @return the {@link Track2} object, or null if not present + */ public Track2 getTrack2() { return track2; } + /** + * Returns true if the card is expired relative to the given date. + * @param currentDate the date to compare against + * @return true if the card is expired as of {@code currentDate} + */ public boolean isExpired (Date currentDate) { if (exp == null || exp.length() != 4) return true; @@ -151,11 +213,17 @@ public boolean isExpired (Date currentDate) { return true; } + /** + * Returns a new {@link Builder} for constructing a {@link Card}. + * @return a new Builder + */ public static Builder builder() { return new Builder(); } + /** Builder for constructing {@link Card} instances. */ public static class Builder { + /** Default card validator instance. */ public static CardValidator DEFAULT_CARD_VALIDATOR = new DefaultCardValidator(); private String pan; private String exp; @@ -169,31 +237,99 @@ public static class Builder { private CardValidator validator = DEFAULT_CARD_VALIDATOR; private Builder () { } + + /** + * Sets the primary account number. + * @param pan the PAN + * @return this builder + */ public Builder pan (String pan) { this.pan = pan; return this; } + + /** + * Sets the expiry date. + * @param exp the expiry in YYMM format + * @return this builder + */ public Builder exp (String exp) { this.exp = exp; return this; } + + /** + * Sets the CVV1 value. + * @param cvv the CVV1 value + * @return this builder + */ public Builder cvv (String cvv) { this.cvv = cvv; return this; } + + /** + * Sets the CVV2 value. + * @param cvv2 the CVV2 value + * @return this builder + */ public Builder cvv2 (String cvv2) { this.cvv2 = cvv2; return this; } + + /** + * Sets the service code. + * @param serviceCode the 3-digit service code + * @return this builder + */ public Builder serviceCode (String serviceCode) { this.serviceCode = serviceCode; return this; } + + /** + * Sets the card validator. + * @param validator the card validator to use + * @return this builder + */ public Builder validator (CardValidator validator) { this.validator = validator; return this; } + + /** + * Provides a Track 1 builder. + * @param track1Builder a {@link Track1.Builder} instance + * @return this builder + */ public Builder withTrack1Builder (Track1.Builder track1Builder) { this.track1Builder = track1Builder; return this; } + + /** + * Provides a Track 2 builder. + * @param track2Builder a {@link Track2.Builder} instance + * @return this builder + */ public Builder withTrack2Builder (Track2.Builder track2Builder) { this.track2Builder = track2Builder; return this; } + + /** + * Sets the Track 1 data. + * @param track1 the {@link Track1} object + * @return this builder + */ public Builder track1 (Track1 track1) { this.track1 = track1; return this; } + + /** + * Sets the Track 2 data. + * @param track2 the {@link Track2} object + * @return this builder + */ public Builder track2 (Track2 track2) { this.track2 = track2; return this; } + + /** + * Populates card data from an {@link ISOMsg}. + * Extracts PAN, expiry, track 1, and track 2 from the appropriate fields. + * @param m an ISOMsg to extract card data from + * @return this builder + * @throws InvalidCardException if card data is invalid + */ public Builder isomsg (ISOMsg m) throws InvalidCardException { if (m.hasField(2)) pan(m.getString(2)); @@ -230,6 +366,11 @@ public Builder isomsg (ISOMsg m) throws InvalidCardException { return this; } + /** + * Builds and validates the {@link Card}. + * @return a new Card instance + * @throws InvalidCardException if the card data is invalid + */ public Card build() throws InvalidCardException { Card c = new Card(this); if (validator != null) diff --git a/jpos/src/main/java/org/jpos/core/CardHolder.java b/jpos/src/main/java/org/jpos/core/CardHolder.java index 78a566811b..ef73121437 100644 --- a/jpos/src/main/java/org/jpos/core/CardHolder.java +++ b/jpos/src/main/java/org/jpos/core/CardHolder.java @@ -29,11 +29,13 @@ import java.util.StringTokenizer; /** - * @author apr@cs.com.uy - * @since jPOS 1.1 * * This class is called 'CardHolder', but a better name could have been 'Card' * At some point we'll deprecate this one and create a new 'Card' class. + * + * @author apr@cs.com.uy + * @since jPOS 1.1 + * */ public class CardHolder implements Cloneable, Serializable, Loggeable { private static final long serialVersionUID = 7449770625551878435L; @@ -77,7 +79,7 @@ public CardHolder() { /** * creates a new CardHolder based on track2 * @param track2 cards track2 - * @exception InvalidCardException + * @exception InvalidCardException if card data fails validation */ public CardHolder (String track2) throws InvalidCardException @@ -87,8 +89,10 @@ public CardHolder (String track2) } /** - * creates a new CardHolder based on pan and exp - * @exception InvalidCardException + * Creates a new CardHolder with the given PAN and expiry date. + * @param pan the primary account number + * @param exp the expiry date (YYMM) + * @exception InvalidCardException if card data is invalid */ public CardHolder (String pan, String exp) throws InvalidCardException @@ -102,7 +106,7 @@ public CardHolder (String pan, String exp) * Construct a CardHolder based on content received on * field 35 (track2) or field 2 (PAN) + field 14 (EXP) * @param m an ISOMsg - * @throws InvalidCardException + * @throws InvalidCardException if card data is invalid */ public CardHolder (ISOMsg m) throws InvalidCardException @@ -128,7 +132,7 @@ else if (m.hasField(2)) { /** * extract pan/exp/trailler from track2 * @param s a valid track2 - * @exception InvalidCardException + * @exception InvalidCardException if card data is invalid */ public void parseTrack2 (String s) throws InvalidCardException @@ -145,6 +149,7 @@ public void parseTrack2 (String s) } /** + * Sets the track1 data. * @param track1 card's track1 */ public void setTrack1(String track1) { @@ -152,13 +157,15 @@ public void setTrack1(String track1) { } /** - * @return the track1 + * Returns the track 1 raw data. + * @return the track1 string, or null */ public String getTrack1() { return track1; } /** + * Returns true if track1 data is present. * @return true if we have a track1 */ public boolean hasTrack1() { @@ -166,6 +173,7 @@ public boolean hasTrack1() { } /** + * Returns the cardholder name from track1. * @return the Name written on the card (from track1) */ public String getNameOnCard() { @@ -182,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() { @@ -191,6 +200,7 @@ public String getTrack2() { return null; } /** + * Returns true if track2 data is (potentially) present. * @return true if we have a (may be valid) track2 */ public boolean hasTrack2() { @@ -205,12 +215,14 @@ public void setSecurityCode(String securityCode) { this.securityCode = securityCode; } /** + * Returns the card security code (CVV/CVC), or null. * @return securityCode (or null) */ public String getSecurityCode() { return securityCode; } /** + * Returns true if a security code is present. * @return true if we have a security code */ public boolean hasSecurityCode() { @@ -236,10 +248,18 @@ public void setTrailler (String trailer) { this.trailer = trailer; } + /** + * Returns the card trailer string. + * @return card trailer + */ public String getTrailer() { return trailer; } + /** + * Sets the card trailer string. + * @param trailer card trailer + */ public void setTrailer(String trailer) { this.trailer = trailer; } @@ -247,7 +267,7 @@ public void setTrailer(String trailer) { /** * Sets Primary Account Number * @param pan Primary Account NUmber - * @exception InvalidCardException + * @exception InvalidCardException if the PAN is too short or fails validation */ public void setPAN (String pan) throws InvalidCardException @@ -258,6 +278,7 @@ public void setPAN (String pan) } /** + * Returns the Primary Account Number. * @return Primary Account Number */ public String getPAN () { @@ -270,6 +291,11 @@ public String getPAN () { * Can be used for the newer 8-digit BINs, or some arbitrary length. * @return len-digit bank issuer number */ + /** + * 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); } @@ -285,7 +311,7 @@ public String getBIN () { /** * Set Expiration Date * @param exp card expiration date - * @exception InvalidCardException + * @exception InvalidCardException if card data is invalid */ public void setEXP (String exp) throws InvalidCardException @@ -333,9 +359,18 @@ public boolean isExpired(Date currentDate) { } return true; } + /** + * 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); } + /** + * 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; @@ -383,6 +418,7 @@ public void dump (PrintStream p, String indent) { } /** + * Returns the service code from track2, or three blanks if not available. * @return ServiceCode (if available) or a String with three blanks */ public String getServiceCode () { @@ -390,6 +426,10 @@ public String getServiceCode () { trailer.substring (0, 3) : " "; } + /** + * 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; } diff --git a/jpos/src/main/java/org/jpos/core/CardValidator.java b/jpos/src/main/java/org/jpos/core/CardValidator.java index 795577b3aa..1654538809 100644 --- a/jpos/src/main/java/org/jpos/core/CardValidator.java +++ b/jpos/src/main/java/org/jpos/core/CardValidator.java @@ -18,6 +18,14 @@ package org.jpos.core; +/** + * Validates {@link Card} instances (e.g. checks expiry, Luhn check, BIN ranges). + */ public interface CardValidator { + /** + * Validates the given card. + * @param card the card to validate + * @throws InvalidCardException if the card is invalid + */ void validate (Card card) throws InvalidCardException; } diff --git a/jpos/src/main/java/org/jpos/core/ConfigValidator.java b/jpos/src/main/java/org/jpos/core/ConfigValidator.java index cf1e79c50e..98868ccba5 100644 --- a/jpos/src/main/java/org/jpos/core/ConfigValidator.java +++ b/jpos/src/main/java/org/jpos/core/ConfigValidator.java @@ -47,7 +47,10 @@ * @author apr * @since 3.0.2 */ +/** Validates {@link Configuration} properties against annotated field declarations. */ public class ConfigValidator { + /** Default constructor. */ + public ConfigValidator() { } private final List rules = new ArrayList<>(); /** diff --git a/jpos/src/main/java/org/jpos/core/Configurable.java b/jpos/src/main/java/org/jpos/core/Configurable.java index 15c88caef8..4cc473b65d 100644 --- a/jpos/src/main/java/org/jpos/core/Configurable.java +++ b/jpos/src/main/java/org/jpos/core/Configurable.java @@ -27,8 +27,9 @@ */ public interface Configurable { /** + * Configures this object with the supplied {@link Configuration}. * @param cfg Configuration object - * @throws ConfigurationException + * @throws ConfigurationException if the configuration is invalid */ void setConfiguration(Configuration cfg) throws ConfigurationException; diff --git a/jpos/src/main/java/org/jpos/core/Configuration.java b/jpos/src/main/java/org/jpos/core/Configuration.java index c31d087dd2..31a812fb6b 100644 --- a/jpos/src/main/java/org/jpos/core/Configuration.java +++ b/jpos/src/main/java/org/jpos/core/Configuration.java @@ -22,37 +22,120 @@ import java.util.Set; /** + * + * CardAgents relies on a Configuration object to provide + * runtime configuration parameters such as merchant number, etc. + * * @author apr@cs.com.uy * @version $Id$ * @since jPOS 1.1 * - * CardAgents relies on a Configuration object to provide - * runtime configuration parameters such as merchant number, etc. */ public interface Configuration { + /** + * Returns the value of a configuration property. + * @param propertyName the property name + * @return the property value, or an empty string if not found + */ String get(String propertyName); /** - * @param propertyName ditto - * @return all properties with a given name (or a zero-length array) + * Returns all property values with the given name. + * @param propertyName the property name + * @return all matching values, or a zero-length array */ String[] getAll(String propertyName); + /** + * Returns all values of a configuration property as an int array. + * @param propertyName the property name + * @return all values as int array + */ int[] getInts(String propertyName); + /** + * Returns all values of a configuration property as a long array. + * @param propertyName the property name + * @return all values as long array + */ long[] getLongs(String propertyName); + /** + * Returns all values of a configuration property as a double array. + * @param propertyName the property name + * @return all values as double array + */ double[] getDoubles(String propertyName); + /** + * Returns all values of a configuration property as a boolean array. + * @param propertyName the property name + * @return all values as boolean array + */ boolean[] getBooleans(String propertyName); + /** + * Returns the value of a configuration property, or a default. + * @param propertyName the property name + * @param defaultValue value to return if not found + * @return the property value or {@code defaultValue} + */ String get(String propertyName, String defaultValue); + /** + * Returns the value of a configuration property as an int. + * @param propertyName the property name + * @return the value as an int, or 0 if not found + */ int getInt(String propertyName); + /** + * Returns the value of a configuration property as an int, or a default. + * @param propertyName the property name + * @param defaultValue default if not found + * @return the value as an int + */ int getInt(String propertyName, int defaultValue); + /** + * Returns the value of a configuration property as a long. + * @param propertyName the property name + * @return the value as a long, or 0 if not found + */ long getLong(String propertyName); + /** + * Returns the value of a configuration property as a long, or a default. + * @param propertyName the property name + * @param defaultValue default if not found + * @return the value as a long + */ long getLong(String propertyName, long defaultValue); + /** + * Returns the value of a configuration property as a double. + * @param propertyName the property name + * @return the value as a double, or 0.0 if not found + */ double getDouble(String propertyName); + /** + * Returns the value of a configuration property as a double, or a default. + * @param propertyName the property name + * @param defaultValue default if not found + * @return the value as a double + */ double getDouble(String propertyName, double defaultValue); + /** + * Returns the value of a configuration property as a boolean. + * @param propertyName the property name + * @return the value as a boolean, or false if not found + */ boolean getBoolean(String propertyName); + /** + * Returns the value of a configuration property as a boolean, or a default. + * @param propertyName the property name + * @param defaultValue default if not found + * @return the value as a boolean + */ boolean getBoolean(String propertyName, boolean defaultValue); /** - * @param name the Property name - * @param value typically a String, but could be a String[] too + * Stores a property value. + * @param name the property name + * @param value the value (typically a String or String[]) */ void put(String name, Object value); + /** + * Returns the set of all property names in this configuration. + * @return the property name set + */ Set keySet(); } diff --git a/jpos/src/main/java/org/jpos/core/ConfigurationException.java b/jpos/src/main/java/org/jpos/core/ConfigurationException.java index 7e45776cd6..5dd5438126 100644 --- a/jpos/src/main/java/org/jpos/core/ConfigurationException.java +++ b/jpos/src/main/java/org/jpos/core/ConfigurationException.java @@ -21,6 +21,7 @@ import org.jpos.iso.ISOException; /** + * Thrown when a configurable component cannot be initialised due to invalid or missing configuration. * @author Alejandro P. Revilla * @version $Revision$ $Date$ * @see Configurable @@ -29,15 +30,29 @@ public class ConfigurationException extends ISOException { private static final long serialVersionUID = -5605240786314946532L; + /** Default constructor. */ public ConfigurationException () { super(); } + /** + * Creates a ConfigurationException with a detail message. + * @param detail error message + */ public ConfigurationException (String detail) { super (detail); } + /** + * Creates a ConfigurationException wrapping a root cause. + * @param nested the root cause + */ public ConfigurationException (Throwable nested) { super (nested); } + /** + * Creates a ConfigurationException with a detail message and root cause. + * @param detail error message + * @param nested the root cause + */ public ConfigurationException (String detail, Throwable nested) { super (detail, nested); } diff --git a/jpos/src/main/java/org/jpos/core/InvalidCardException.java b/jpos/src/main/java/org/jpos/core/InvalidCardException.java index 11862e9c68..791479c8ab 100644 --- a/jpos/src/main/java/org/jpos/core/InvalidCardException.java +++ b/jpos/src/main/java/org/jpos/core/InvalidCardException.java @@ -19,6 +19,7 @@ package org.jpos.core; /** + * Thrown when card data (PAN, expiry, etc.) is invalid or cannot be parsed. * @author apr@cs.com.uy * @version $Id$ * @since jPOS 1.1 diff --git a/jpos/src/main/java/org/jpos/core/Sequencer.java b/jpos/src/main/java/org/jpos/core/Sequencer.java index 747967d376..614636a14b 100644 --- a/jpos/src/main/java/org/jpos/core/Sequencer.java +++ b/jpos/src/main/java/org/jpos/core/Sequencer.java @@ -20,13 +20,15 @@ /** - * @author apr@cs.com.uy - * @version $Id$ - * @since jPOS 1.1 * * Multipurpose sequencer.
* CardAgents requires persistent sequence number
* Sequencer interface isolate from particular DB implementations + * + * @author apr@cs.com.uy + * @version $Id$ + * @since jPOS 1.1 + * */ public interface Sequencer { int get(String counterName); diff --git a/jpos/src/main/java/org/jpos/core/SimpleConfiguration.java b/jpos/src/main/java/org/jpos/core/SimpleConfiguration.java index 01bf499731..eaf7bc785e 100644 --- a/jpos/src/main/java/org/jpos/core/SimpleConfiguration.java +++ b/jpos/src/main/java/org/jpos/core/SimpleConfiguration.java @@ -26,6 +26,7 @@ import java.util.stream.IntStream; /** + * A {@link Configuration} implementation backed by a {@link java.util.Properties} object. * @author apr@cs.com.uy * @version $Id$ * @since jPOS 1.1 @@ -47,7 +48,7 @@ public SimpleConfiguration (String filename) } /** - * Returns the value of the configuration property named name, or the default value def. + * Returns the value of the configuration property named {@code name}, or the default value {@code def}. * * If the property value has the format ${xxx} 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 +58,8 @@ public SimpleConfiguration (String filename) * * @param name The configuration property key name. * @param def The default value. - * @return The value stored under name, - * or def if there's no configuration property under the given name. + * @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); diff --git a/jpos/src/main/java/org/jpos/core/Track1.java b/jpos/src/main/java/org/jpos/core/Track1.java index 96b1c3862a..5cbb3d0a9e 100644 --- a/jpos/src/main/java/org/jpos/core/Track1.java +++ b/jpos/src/main/java/org/jpos/core/Track1.java @@ -25,11 +25,13 @@ import java.util.regex.Pattern; /** - * @author apr@jpos.org - * @since jPOS 2.0.5 * * This class is based on the old 'CardHolder' class and adds support for multiple * PAN and Expiration dates taken from manual entry, track1, track1. It also corrects the name. + * + * @author apr@jpos.org + * @since jPOS 2.0.5 + * */ @SuppressWarnings("unused") diff --git a/jpos/src/main/java/org/jpos/core/Track2.java b/jpos/src/main/java/org/jpos/core/Track2.java index 64b197ded7..01727072dc 100644 --- a/jpos/src/main/java/org/jpos/core/Track2.java +++ b/jpos/src/main/java/org/jpos/core/Track2.java @@ -25,11 +25,13 @@ import java.util.regex.Pattern; /** - * @author apr@jpos.org - * @since jPOS 2.0.5 * * This class is based on the old 'CardHolder' class and adds support for multiple * PAN and Expiration dates taken from manual entry, track1, track2. It also corrects the name. + * + * @author apr@jpos.org + * @since jPOS 2.0.5 + * */ @SuppressWarnings("unused") public class Track2 { diff --git a/jpos/src/main/java/org/jpos/core/VolatileSequencer.java b/jpos/src/main/java/org/jpos/core/VolatileSequencer.java index e91b03e5d8..0044b82b80 100644 --- a/jpos/src/main/java/org/jpos/core/VolatileSequencer.java +++ b/jpos/src/main/java/org/jpos/core/VolatileSequencer.java @@ -22,12 +22,14 @@ import java.util.Map; /** + * + * A simple sequencer intended for Debugging applications.
+ * Production grade Sequencers are required to be persistent capables + * * @author apr@cs.com.uy * @version $Id$ * @since jPOS 1.1 * - * A simple sequencer intended for Debugging applications.
- * Production grade Sequencers are required to be persistent capables */ @SuppressWarnings("unchecked") public class VolatileSequencer implements Sequencer, VolatileSequencerMBean { diff --git a/jpos/src/main/java/org/jpos/core/VolatileSequencerMBean.java b/jpos/src/main/java/org/jpos/core/VolatileSequencerMBean.java index 23be004fab..df1d4b2223 100644 --- a/jpos/src/main/java/org/jpos/core/VolatileSequencerMBean.java +++ b/jpos/src/main/java/org/jpos/core/VolatileSequencerMBean.java @@ -20,6 +20,7 @@ /** + * JMX management interface for {@link VolatileSequencer}. * @author apr@cs.com.uy * @version $Id$ * @since jPOS 1.3.9 diff --git a/jpos/src/main/java/org/jpos/core/XmlConfigurable.java b/jpos/src/main/java/org/jpos/core/XmlConfigurable.java index 825744b956..ca49fbe8c1 100644 --- a/jpos/src/main/java/org/jpos/core/XmlConfigurable.java +++ b/jpos/src/main/java/org/jpos/core/XmlConfigurable.java @@ -28,6 +28,7 @@ */ public interface XmlConfigurable { /** + * Configures this object from an XML element. * @param e Configuration element * @throws ConfigurationException on error */ diff --git a/jpos/src/main/java/org/jpos/core/annotation/Config.java b/jpos/src/main/java/org/jpos/core/annotation/Config.java index 60b11c3359..d77f7a81b8 100644 --- a/jpos/src/main/java/org/jpos/core/annotation/Config.java +++ b/jpos/src/main/java/org/jpos/core/annotation/Config.java @@ -24,5 +24,9 @@ @Target(ElementType.FIELD) @Retention(RetentionPolicy.RUNTIME) public @interface Config { + /** + * Returns the property name to inject (defaults to field name). + * @return property name + */ String value(); } diff --git a/jpos/src/main/java/org/jpos/core/handlers/exception/ExceptionHandler.java b/jpos/src/main/java/org/jpos/core/handlers/exception/ExceptionHandler.java index 31965381ee..d198a3738b 100644 --- a/jpos/src/main/java/org/jpos/core/handlers/exception/ExceptionHandler.java +++ b/jpos/src/main/java/org/jpos/core/handlers/exception/ExceptionHandler.java @@ -19,6 +19,7 @@ package org.jpos.core.handlers.exception; /** + * A single handler in the exception-handling pipeline; processes a given exception and decides whether to rethrow it. * @author Alwyn Schoeman * @since 2.1.2 */ diff --git a/jpos/src/main/java/org/jpos/core/handlers/exception/ExceptionHandlerAware.java b/jpos/src/main/java/org/jpos/core/handlers/exception/ExceptionHandlerAware.java index 66234aa528..4e04bce1ec 100644 --- a/jpos/src/main/java/org/jpos/core/handlers/exception/ExceptionHandlerAware.java +++ b/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. * - *

- * The main pipeline consists of multiple sub-pipelines: - *

    - *
  • A pipeline for which handlers are called regardless of the type of exception handled. Stored under a null key.
    • - *
  • A pipeline per targeted exception type.
    • - *
- * The targeted pipeline always executes before the default pipeline. - *

+ * The main pipeline consists of multiple sub-pipelines: + *
    + *
  • A pipeline for which handlers are called regardless of the type of exception handled. Stored under a null key.
    • + *
  • A pipeline per targeted exception type.
    • + *
+ * The targeted pipeline always executes before the default pipeline. *

* In the event that both of the pipelines are empty, the default behavior is to rethrow the initial exception. *

@@ -46,7 +44,7 @@ public interface ExceptionHandlerAware { /** - * + * Returns the map of targeted exception handlers, keyed by exception class. * @return A map of exception classes to exception handlers. These handlers only execute if the exception matches. */ Map, List> getExceptionHandlers(); diff --git a/jpos/src/main/java/org/jpos/emv/BinaryEMVTag.java b/jpos/src/main/java/org/jpos/emv/BinaryEMVTag.java index c879ad1089..072b953498 100644 --- a/jpos/src/main/java/org/jpos/emv/BinaryEMVTag.java +++ b/jpos/src/main/java/org/jpos/emv/BinaryEMVTag.java @@ -23,20 +23,42 @@ /** + * An EMV tag whose value is represented as raw binary data. * @author Vishnu Pillai */ public class BinaryEMVTag extends EMVTag { + /** + * 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 + */ public BinaryEMVTag(EMVStandardTagType tagType, byte[] value) throws IllegalArgumentException { super(tagType, value); } + /** + * 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 + */ public BinaryEMVTag(EMVProprietaryTagType tagType, Integer tagNumber, byte[] value) throws IllegalArgumentException { super(tagType, tagNumber, value); } + /** + * 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 + * @throws IllegalArgumentException if the value is invalid + */ public BinaryEMVTag(EMVProprietaryTagType tagType, Integer tagNumber, TLVDataFormat dataFormat, byte[] value) throws IllegalArgumentException { super(tagType, tagNumber, dataFormat, value); diff --git a/jpos/src/main/java/org/jpos/emv/CVRMastercard.java b/jpos/src/main/java/org/jpos/emv/CVRMastercard.java index d1e3e308af..7ef2b8e83e 100644 --- a/jpos/src/main/java/org/jpos/emv/CVRMastercard.java +++ b/jpos/src/main/java/org/jpos/emv/CVRMastercard.java @@ -32,8 +32,8 @@ public class CVRMastercard implements Loggeable { private final byte[] cvr; /** - * - * @param cvr Byte array containing the CVR value. + * Creates a CVRMastercard from raw bytes. + * @param cvr byte array containing the CVR value (must be 6 bytes) */ public CVRMastercard(byte[] cvr) { Objects.requireNonNull("cvr", "CVR cannot be null."); @@ -44,8 +44,8 @@ public CVRMastercard(byte[] cvr) { } /** - * - * @param cvr Hexadecimal string representation of the CVR value. + * Creates a CVRMastercard from a hex string. + * @param cvr hexadecimal string representation (must be 12 chars) */ public CVRMastercard(String cvr) { Objects.requireNonNull("cvr", "CVR cannot be null."); @@ -56,70 +56,138 @@ public CVRMastercard(String cvr) { this.cvr = ISOUtil.hex2byte(cvr); } + /** + * Returns true if aac returned in second generate a c. + * @return true if condition applies + */ public boolean aacReturnedInSecondGenerateAC() { return !isBitOn(cvr[0], 8) && !isBitOn(cvr[0], 7); } + /** + * Returns true if aac returned in first generate a c. + * @return true if condition applies + */ public boolean aacReturnedInFirstGenerateAC() { return !isBitOn(cvr[0], 6) && !isBitOn(cvr[0], 5); } + /** + * Returns true if tc returned in second generate a c. + * @return true if condition applies + */ public boolean tcReturnedInSecondGenerateAC() { return !isBitOn(cvr[0], 8) && isBitOn(cvr[0], 7); } + /** + * Returns true if arqc returned in first generate a c. + * @return true if condition applies + */ public boolean arqcReturnedInFirstGenerateAC() { return isBitOn(cvr[0], 6) && !isBitOn(cvr[0], 5); } + /** + * Returns true if tc returned in first generate a c. + * @return true if condition applies + */ public boolean tcReturnedInFirstGenerateAC() { return !isBitOn(cvr[0], 6) && isBitOn(cvr[0], 5); } + /** + * Returns true if offline p i n verification performed. + * @return true if condition applies + */ public boolean offlinePINVerificationPerformed() { return isBitOn(cvr[0], 3); } + /** + * Returns true if offline p i n verification not performed. + * @return true if condition applies + */ public boolean offlinePINVerificationNotPerformed() { return isBitOn(cvr[3], 6); } + /** + * Returns true if dda returned. + * @return true if condition applies + */ public boolean ddaReturned() { return isBitOn(cvr[1], 8); } + /** + * Returns true if combined d d a a c generation returned in first generate a c. + * @return true if condition applies + */ public boolean combinedDDAACGenerationReturnedInFirstGenerateAC() { return isBitOn(cvr[1], 7); } + /** + * Returns true if combined d d a a c generation returned in second generate a c. + * @return true if condition applies + */ public boolean combinedDDAACGenerationReturnedInSecondGenerateAC() { return isBitOn(cvr[1], 6); } + /** + * Returns true if issuer authentication failed. + * @return true if condition applies + */ public boolean issuerAuthenticationFailed() { return isBitOn(cvr[4], 3); } + /** + * Returns true if script received. + * @return true if condition applies + */ public boolean scriptReceived() { return isBitOn(cvr[4], 2); } + /** + * Returns true if script failed. + * @return true if condition applies + */ public boolean scriptFailed() { return isBitOn(cvr[4], 1); } + /** + * Returns true if ciac default skipped on c a t3. + * @return true if condition applies + */ public boolean ciacDefaultSkippedOnCAT3() { return isBitOn(cvr[1], 4); } + /** + * Returns true if match found in additional check table. + * @return true if condition applies + */ public boolean matchFoundInAdditionalCheckTable() { return isBitOn(cvr[5], 2); } + /** + * Returns true if no match found in additional check table. + * @return true if condition applies + */ public boolean noMatchFoundInAdditionalCheckTable() { return isBitOn(cvr[5], 1); } + /** + * Returns the right nibble of script counter. + * @return the value + */ public int rightNibbleOfScriptCounter() { StringBuilder sb = new StringBuilder(); sb.append(isBitOn(cvr[2], 8) ? "1" : "0"); @@ -129,6 +197,10 @@ public int rightNibbleOfScriptCounter() { return Integer.parseInt(sb.toString(), 2); } + /** + * Returns the right nibble of p i n try counter. + * @return the value + */ public int rightNibbleOfPINTryCounter() { StringBuilder sb = new StringBuilder(); sb.append(isBitOn(cvr[2], 4) ? "1" : "0"); @@ -138,58 +210,114 @@ public int rightNibbleOfPINTryCounter() { return Integer.parseInt(sb.toString(), 2); } + /** + * Returns true if offline p i n verification failed. + * @return true if condition applies + */ public boolean offlinePINVerificationFailed() { return isBitOn(cvr[0], 2); } + /** + * Returns true if ptl exceeded. + * @return true if condition applies + */ public boolean ptlExceeded() { return isBitOn(cvr[0], 2); } + /** + * Returns true if international transaction. + * @return true if condition applies + */ public boolean internationalTransaction() { return isBitOn(cvr[3], 3); } + /** + * Returns true if domestic transaction. + * @return true if condition applies + */ public boolean domesticTransaction() { return isBitOn(cvr[3], 2); } + /** + * Returns true if terminal erroneously considers offline p i n o k. + * @return true if condition applies + */ public boolean terminalErroneouslyConsidersOfflinePINOK() { return isBitOn(cvr[3], 1); } + /** + * Returns true if lower consecutive offline limit exceeded. + * @return true if condition applies + */ public boolean lowerConsecutiveOfflineLimitExceeded() { return isBitOn(cvr[4], 8); } + /** + * Returns true if upper consecutive offline limit exceeded. + * @return true if condition applies + */ public boolean upperConsecutiveOfflineLimitExceeded() { return isBitOn(cvr[4], 7); } + /** + * Returns true if lower cumulative offline limit exceeded. + * @return true if condition applies + */ public boolean lowerCumulativeOfflineLimitExceeded() { return isBitOn(cvr[4], 6); } + /** + * Returns true if upper cumulative offline limit exceeded. + * @return true if condition applies + */ public boolean upperCumulativeOfflineLimitExceeded() { return isBitOn(cvr[4], 5); } + /** + * Returns true if go online on next transaction set. + * @return true if condition applies + */ public boolean goOnlineOnNextTransactionSet() { return isBitOn(cvr[4], 4); } + /** + * Returns true if unable to go online. + * @return true if condition applies + */ public boolean unableToGoOnline() { return isBitOn(cvr[3], 7); } + /** + * Returns true if second generate a c not requested. + * @return true if condition applies + */ public boolean secondGenerateACNotRequested() { return isBitOn(cvr[0], 8) && !isBitOn(cvr[0], 7); } + /** + * Returns true if issuer authentication performed. + * @return true if condition applies + */ public boolean issuerAuthenticationPerformed() { return isBitOn(cvr[1], 5); } + /** + * Returns true if offline encrypted p i n verification performed. + * @return true if condition applies + */ public boolean offlineEncryptedPINVerificationPerformed() { return isBitOn(cvr[0], 2); } diff --git a/jpos/src/main/java/org/jpos/emv/EMVConstructedTag.java b/jpos/src/main/java/org/jpos/emv/EMVConstructedTag.java index 2bc6bc1d99..df4d45047d 100644 --- a/jpos/src/main/java/org/jpos/emv/EMVConstructedTag.java +++ b/jpos/src/main/java/org/jpos/emv/EMVConstructedTag.java @@ -25,6 +25,8 @@ /** + * An EMV tag whose value is a constructed (composite) TLV structure. + * @param the type of the contained value * @author Vishnu Pillai */ public class EMVConstructedTag implements Serializable { diff --git a/jpos/src/main/java/org/jpos/emv/EMVProprietaryTagType.java b/jpos/src/main/java/org/jpos/emv/EMVProprietaryTagType.java index aae7841ab9..be0d7607c1 100644 --- a/jpos/src/main/java/org/jpos/emv/EMVProprietaryTagType.java +++ b/jpos/src/main/java/org/jpos/emv/EMVProprietaryTagType.java @@ -19,6 +19,7 @@ package org.jpos.emv; /** + * Represents a proprietary (non-standard) EMV tag type definition. * @author Vishnu Pillai */ public interface EMVProprietaryTagType extends EMVTagType { diff --git a/jpos/src/main/java/org/jpos/emv/EMVStandardTagType.java b/jpos/src/main/java/org/jpos/emv/EMVStandardTagType.java index 33c2104cb9..295cdcc81a 100644 --- a/jpos/src/main/java/org/jpos/emv/EMVStandardTagType.java +++ b/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 { diff --git a/jpos/src/main/java/org/jpos/emv/EMVTag.java b/jpos/src/main/java/org/jpos/emv/EMVTag.java index 9e82ec6144..241aed68e8 100644 --- a/jpos/src/main/java/org/jpos/emv/EMVTag.java +++ b/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 the tag value type */ public abstract class EMVTag implements TagValue, Serializable { diff --git a/jpos/src/main/java/org/jpos/emv/EMVTagSequence.java b/jpos/src/main/java/org/jpos/emv/EMVTagSequence.java index 91603f49b2..af53334166 100644 --- a/jpos/src/main/java/org/jpos/emv/EMVTagSequence.java +++ b/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 { diff --git a/jpos/src/main/java/org/jpos/emv/EMVTagType.java b/jpos/src/main/java/org/jpos/emv/EMVTagType.java index 7922989863..e3b675a926 100644 --- a/jpos/src/main/java/org/jpos/emv/EMVTagType.java +++ b/jpos/src/main/java/org/jpos/emv/EMVTagType.java @@ -22,6 +22,7 @@ import org.jpos.tlv.TLVDataFormat; /** + * Describes the type metadata (tag number, name, format) of an EMV data element. * @author Vishnu Pillai */ public interface EMVTagType { diff --git a/jpos/src/main/java/org/jpos/emv/LiteralEMVTag.java b/jpos/src/main/java/org/jpos/emv/LiteralEMVTag.java index 2ac0498406..afd982ee9d 100644 --- a/jpos/src/main/java/org/jpos/emv/LiteralEMVTag.java +++ b/jpos/src/main/java/org/jpos/emv/LiteralEMVTag.java @@ -23,6 +23,7 @@ /** + * An EMV tag whose value is represented as a literal string. * @author Vishnu Pillai */ public class LiteralEMVTag extends EMVTag { diff --git a/jpos/src/main/java/org/jpos/emv/ProprietaryFormatException.java b/jpos/src/main/java/org/jpos/emv/ProprietaryFormatException.java index 266c62c05c..fb2dc2fc33 100644 --- a/jpos/src/main/java/org/jpos/emv/ProprietaryFormatException.java +++ b/jpos/src/main/java/org/jpos/emv/ProprietaryFormatException.java @@ -19,6 +19,7 @@ package org.jpos.emv; /** + * Thrown when an EMV field uses a proprietary format that cannot be processed. * @author Vishnu Pillai */ public class ProprietaryFormatException extends Exception { diff --git a/jpos/src/main/java/org/jpos/emv/UnknownTagNumberException.java b/jpos/src/main/java/org/jpos/emv/UnknownTagNumberException.java index 5c667c5037..1848064c91 100644 --- a/jpos/src/main/java/org/jpos/emv/UnknownTagNumberException.java +++ b/jpos/src/main/java/org/jpos/emv/UnknownTagNumberException.java @@ -19,6 +19,7 @@ package org.jpos.emv; /** + * Thrown when an EMV tag number is not recognised in the current tag dictionary. * @author Vishnu Pillai */ public class UnknownTagNumberException extends Exception { diff --git a/jpos/src/main/java/org/jpos/emv/cryptogram/CryptogramDataBuilder.java b/jpos/src/main/java/org/jpos/emv/cryptogram/CryptogramDataBuilder.java index 39b674d7ec..190e28925c 100644 --- a/jpos/src/main/java/org/jpos/emv/cryptogram/CryptogramDataBuilder.java +++ b/jpos/src/main/java/org/jpos/emv/cryptogram/CryptogramDataBuilder.java @@ -33,7 +33,9 @@ */ public interface CryptogramDataBuilder { + /** Specifies the padding method applied when building cryptogram data. */ enum PaddingMethod { + /** No padding is applied. */ NO_PADDING, /** @@ -76,6 +78,11 @@ public String apply(String data) { } }; + /** + * Applies this padding method to the given hex string. + * @param data the hex string to pad + * @return the padded hex string + */ public String apply(String data) { return data; } diff --git a/jpos/src/main/java/org/jpos/iso/AsciiHexInterpreter.java b/jpos/src/main/java/org/jpos/iso/AsciiHexInterpreter.java index e4da1195a6..c9218972d5 100644 --- a/jpos/src/main/java/org/jpos/iso/AsciiHexInterpreter.java +++ b/jpos/src/main/java/org/jpos/iso/AsciiHexInterpreter.java @@ -27,6 +27,9 @@ public class AsciiHexInterpreter implements BinaryInterpreter { /** An instance of this Interpreter. Only one needed for the whole system */ + /** Private constructor — use the {@code INSTANCE} singleton. */ + private AsciiHexInterpreter() { } + /** Singleton instance of this interpreter. */ public static final AsciiHexInterpreter INSTANCE = new AsciiHexInterpreter(); /** 0-15 to ASCII hex digit lookup table. */ diff --git a/jpos/src/main/java/org/jpos/iso/AsciiInterpreter.java b/jpos/src/main/java/org/jpos/iso/AsciiInterpreter.java index 2e4210e85e..716b248847 100644 --- a/jpos/src/main/java/org/jpos/iso/AsciiInterpreter.java +++ b/jpos/src/main/java/org/jpos/iso/AsciiInterpreter.java @@ -29,6 +29,9 @@ public class AsciiInterpreter implements Interpreter { /** An instance of this Interpreter. Only one needed for the whole system */ + /** Private constructor — use the {@code INSTANCE} singleton. */ + private AsciiInterpreter() { } + /** Singleton instance of this interpreter. */ public static final AsciiInterpreter INSTANCE = new AsciiInterpreter(); /** diff --git a/jpos/src/main/java/org/jpos/iso/AsciiPrefixer.java b/jpos/src/main/java/org/jpos/iso/AsciiPrefixer.java index b037a20771..9576b742e4 100644 --- a/jpos/src/main/java/org/jpos/iso/AsciiPrefixer.java +++ b/jpos/src/main/java/org/jpos/iso/AsciiPrefixer.java @@ -64,6 +64,9 @@ public class AsciiPrefixer implements Prefixer /** The number of digits allowed to express the length */ private int nDigits; + /** Creates an AsciiPrefixer that uses the specified number of ASCII decimal digits for the length prefix. + * @param nDigits number of ASCII decimal digits in the length prefix + */ public AsciiPrefixer(int nDigits) { this.nDigits = nDigits; diff --git a/jpos/src/main/java/org/jpos/iso/BaseChannel.java b/jpos/src/main/java/org/jpos/iso/BaseChannel.java index a21d730476..7edfcaa6fa 100644 --- a/jpos/src/main/java/org/jpos/iso/BaseChannel.java +++ b/jpos/src/main/java/org/jpos/iso/BaseChannel.java @@ -82,29 +82,49 @@ public abstract class BaseChannel extends Observable private int maxPacketLength = 100000; private boolean keepAlive; private boolean expectKeepAlive; + /** Whether SO_LINGER is enabled when closing the socket. */ private boolean soLingerOn = true; + /** SO_LINGER timeout in seconds. */ private int soLingerSeconds = 5; + /** Configuration for this channel. */ private Configuration cfg; + /** Whether this channel is in a usable state. */ protected boolean usable; + /** When true, this channel's own header overrides the message's header. */ protected boolean overrideHeader; + /** Registered name of this channel in the NameRegistrar. */ private String name; + /** Send timeout in milliseconds. */ private long sendTimeout = 15000L; // private int serverPort = -1; + /** Input stream for reading from the connected socket. */ protected DataInputStream serverIn; + /** Output stream for writing to the connected socket. */ protected DataOutputStream serverOut; // The lock objects should be final, and never changed, but due to the clone() method, they must be set there. + /** Lock guarding {@link #serverIn} and read operations. */ protected Lock serverInLock = new ReentrantLock(); + /** Lock guarding {@link #serverOut} and write operations. */ protected Lock serverOutLock = new ReentrantLock(); + /** The packager used to pack/unpack ISO messages. */ protected ISOPackager packager; + /** The server socket used when this channel acts as a server. */ protected ServerSocket serverSocket = null; + /** Filter chains applied to incoming and outgoing messages respectively. */ protected List incomingFilters, outgoingFilters; + /** Optional factory for creating client sockets. */ protected ISOClientSocketFactory socketFactory = null; + /** Event counters (connect, sent, received, etc.). */ protected int[] cnt; + /** The logger for this channel. */ protected Logger logger = null; + /** The current log realm. */ protected String realm = null; + /** The original log realm before any modification. */ protected String originalRealm = null; + /** Optional channel-level header prepended to outgoing messages. */ protected byte[] header = null; private static final int DEFAULT_TIMEOUT = 300000; private int nextHostPort = 0; @@ -255,6 +275,7 @@ public void resetCounters() { cnt[i] = 0; } /** + * Returns the internal message counters (indexed by counter type). * @return counters */ public int[] getCounters() { @@ -311,16 +332,22 @@ protected void connect (Socket socket) throws IOException { setChanged(); notifyObservers(); } + /** + * Hook called after a successful connect; subclasses may override. + * @throws IOException on I/O error + */ protected void postConnectHook() throws IOException { // do nothing } /** * factory method pattern (as suggested by Vincent.Greene@amo.com) + * + * Use Socket factory if exists. If it is missing create a normal socket + * * @param host remote host * @param port remote port * @throws IOException on error * - * Use Socket factory if exists. If it is missing create a normal socket * @see ISOClientSocketFactory * @return newly created socket */ @@ -346,6 +373,13 @@ protected Socket newSocket(String host, int port) throws IOException { throw new IOException (e.getMessage()); } } + /** Creates a connected socket to one of the given hosts/ports. + * @param hosts candidate host addresses + * @param ports corresponding port numbers + * @param evt log event for diagnostic output + * @return a connected Socket + * @throws IOException on connection failure + */ protected Socket newSocket (String[] hosts, int[] ports, LogEvent evt) throws IOException { @@ -383,12 +417,14 @@ protected Socket newSocket (String[] hosts, int[] ports, LogEvent evt) return s; } /** + * Returns the underlying socket for this channel, or {@code null} if not connected. * @return current socket */ public Socket getSocket() { return socket; } /** + * Returns the server socket used to accept inbound connections, or {@code null} if not in server mode. * @return current serverSocket */ public ServerSocket getServerSocket() { @@ -397,7 +433,7 @@ public ServerSocket getServerSocket() { /** * sets socket timeout (as suggested by - * Leonard Thomas ) + * Leonard Thomas (leonard@rhinosystemsinc.com)) * @param timeout in milliseconds * @throws SocketException on error */ @@ -405,13 +441,17 @@ public void setTimeout (int timeout) throws SocketException { this.timeout = timeout; applyTimeout(); } + /** + * Returns the current socket read timeout. + * @return socket timeout in milliseconds + */ public int getTimeout () { return timeout; } /** - * sets timeout, and also keep alive - * @throws SocketException + * Applies the configured socket timeout and keep-alive settings to the current socket. + * @throws SocketException if socket options cannot be set */ protected void applyTimeout () throws SocketException { if (socket != null && socket.isConnected()) { @@ -423,21 +463,31 @@ protected void applyTimeout () throws SocketException { } /** * Socket SO_LINGER option to use when closing the socket. + * @param on whether to enable SO_LINGER + * @param linger linger timeout in seconds * @see java.net.Socket#setSoLinger(boolean, int) */ public void setSoLinger(boolean on, int linger) { this.soLingerOn = on; this.soLingerSeconds = linger; } + /** + * Returns true if SO_LINGER is enabled. + * @return true if SO_LINGER is on + */ public boolean isSoLingerOn() { return soLingerOn; } + /** + * Returns the SO_LINGER timeout. + * @return SO_LINGER timeout in seconds + */ public int getSoLingerSeconds() { return soLingerSeconds; } /** * Connects client ISOChannel to server - * @exception IOException + * @exception IOException if the connection cannot be established */ public void connect () throws IOException { ChannelEvent jfr = new ChannelEvent.Connect(); @@ -464,7 +514,7 @@ public void connect () throws IOException { /** * Accepts connection - * @exception IOException + * @exception IOException if the accept fails */ public void accept(ServerSocket s) throws IOException { ChannelEvent jfr = new ChannelEvent.Accept(); @@ -492,8 +542,10 @@ public void accept(ServerSocket s) throws IOException { } /** - * @param b - new Usable state (used by ISOMUX internals to + * * flag as unusable in order to force a reconnection) + * + * @param b - new Usable state (used by ISOMUX internals to */ public void setUsable(boolean b) { Logger.log (new LogEvent (this, "usable", b)); @@ -540,7 +592,16 @@ protected ISOHeader getDynamicHeader (byte[] image) { return image != null ? new BaseHeader (image) : null; } + /** Sends the message length preamble. + * @param len message length to send + * @throws IOException on I/O failure + */ protected void sendMessageLength(int len) throws IOException { } + /** Sends the message header, if any. + * @param m the ISO message + * @param len packed message length + * @throws IOException on I/O failure + */ protected void sendMessageHeader(ISOMsg m, int len) throws IOException { if (!isOverrideHeader() && m.getHeader() != null) serverOut.write(m.getHeader()); @@ -559,10 +620,13 @@ protected void sendMessageTrailler(ISOMsg m, int len) throws IOException } /** - * @deprecated use sendMessageTrailer(ISOMsg m, byte[] b instead. + * @deprecated use {@link #sendMessageTrailer(ISOMsg, byte[])} instead. + * @param m the ISOMsg + * @param b the packed bytes + * @throws IOException on I/O failure */ - @SuppressWarnings ("deprecation") @Deprecated + @SuppressWarnings ("deprecation") protected void sendMessageTrailler(ISOMsg m, byte[] b) throws IOException { sendMessageTrailler (m, b.length); } @@ -572,6 +636,7 @@ protected void sendMessageTrailler(ISOMsg m, byte[] b) throws IOException { * * @param m The unpacked ISOMsg. * @param b The packed ISOMsg image. + * @throws IOException on I/O failure */ @SuppressWarnings("deprecation") protected void sendMessageTrailer(ISOMsg m, byte[] b) throws IOException { @@ -581,6 +646,7 @@ protected void sendMessageTrailer(ISOMsg m, byte[] b) throws IOException { /** * @deprecated use getMessageTrailer(ISOMsg m) instead. + * @throws IOException on I/O failure */ @Deprecated protected void getMessageTrailler() throws IOException { @@ -590,32 +656,70 @@ protected void getMessageTrailler() throws IOException { * Read some trailer data from this channel and optionally store it in the incoming ISOMsg. * * @param m The ISOMessage to store the trailer data. - * @see ISOMsg#setTrailer(byte[]). + * @see ISOMsg#setTrailer(byte[]) + * @throws IOException on I/O failure */ @SuppressWarnings("deprecation") protected void getMessageTrailer(ISOMsg m) throws IOException { getMessageTrailler(); } + /** + * Reads exactly {@code len} bytes from the input stream into the buffer. + * @param b buffer to read into + * @param offset buffer offset + * @param len number of bytes to read + * @throws IOException on I/O failure + * @throws ISOException on protocol error + */ protected void getMessage (byte[] b, int offset, int len) throws IOException, ISOException { serverIn.readFully(b, offset, len); } + /** Returns the message length; {@code -1} indicates variable or unavailable. + * @return message length in bytes, or -1 + * @throws IOException on I/O failure + * @throws ISOException on protocol error + */ protected int getMessageLength() throws IOException, ISOException { return -1; } + /** + * Returns the length of the channel-level header, or 0 if none. + * @return header length in bytes + */ protected int getHeaderLength() { return header != null ? header.length : 0; } + /** + * Returns the header length for the given raw buffer; default is 0. + * @param b raw buffer + * @return header length + */ protected int getHeaderLength(byte[] b) { return 0; } + /** + * Returns the effective header length for the given message. + * @param m the ISO message + * @return header length in bytes + */ protected int getHeaderLength(ISOMsg m) { return !overrideHeader && m.getHeader() != null ? m.getHeader().length : getHeaderLength(); } + /** Receives raw bytes from the stream for stream-mode channels. + * @return received bytes + * @throws IOException on I/O failure + */ protected byte[] streamReceive() throws IOException { return new byte[0]; } + /** Writes {@code len} bytes from {@code b} starting at {@code offset} to the output stream. + * @param b source byte array + * @param offset start offset + * @param len number of bytes to write + * @throws IOException on I/O failure + */ protected void sendMessage (byte[] b, int offset, int len) throws IOException { @@ -638,12 +742,13 @@ protected void sendMessage (byte[] b, int offset, int len) * * * If a {@link VetoException} is thrown by a filter, the message is not sent, and the exception is logged. - * - * @param m the ISO message to be sent. The message will be modified in-place: its direction and packager + * * will be updated, and filters may alter its content. + * or if an unexpected I/O error occurs. + * + * @param m the ISO message to be sent. The message will be modified in-place: its direction and packager * * @throws IOException if the channel is not connected, if the output stream fails, if locking times out, - * or if an unexpected I/O error occurs. * @throws ISOException if packing the message fails or other ISO-specific issues occur. * @throws VetoException if an outgoing filter vetoes the message. * @@ -711,9 +816,9 @@ public void send (ISOMsg m) /** * sends a byte[] over the TCP/IP session * @param b the byte array to be sent - * @exception IOException - * @exception ISOException - * @exception ISOFilter.VetoException; + * @exception IOException on I/O failure + * @exception ISOException on ISO packing failure + * @exception org.jpos.iso.ISOFilter.VetoException if a filter vetoes the message */ public void send (byte[] b) throws IOException, ISOException { var jfr = new ChannelEvent.Send(); @@ -753,14 +858,30 @@ public void sendKeepAlive () throws IOException { } } + /** + * 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; } + /** + * Returns true if the given message frame should be treated as a rejection. + * Subclasses (e.g. VAPChannel) may override. + * @param b raw message bytes + * @return true if rejected + */ protected boolean isRejected(byte[] b) { // VAP Header support - see VAPChannel return false; } + /** + * Returns true if the given message frame should be silently ignored. + * Subclasses (e.g. VAPChannel) may override. + * @param b raw message bytes + * @return true if the frame should be ignored + */ protected boolean shouldIgnore (byte[] b) { // VAP Header support - see VAPChannel return false; @@ -772,6 +893,10 @@ protected boolean shouldIgnore (byte[] b) { protected ISOMsg createMsg () { return createISOMsg(); } + /** + * Creates a new ISOMsg using the configured packager. + * @return new ISOMsg instance + */ protected ISOMsg createISOMsg () { return packager.createISOMsg (); } @@ -791,8 +916,8 @@ protected byte[] readHeader(int hLen) throws IOException { /** * Waits and receive an ISOMsg over the TCP/IP session * @return the Message received - * @throws IOException - * @throws ISOException + * @throws IOException on I/O failure + * @throws ISOException on ISO unpacking failure */ public ISOMsg receive() throws IOException, ISOException { var jfr = new ChannelEvent.Receive(); @@ -886,10 +1011,12 @@ else if (len > 0 && len <= getMaxPacketLength()) { } /** * Low level receive + * + * or -1 if there is no more data because the end of the stream has been reached. + * * @param b byte array * @throws IOException on error * @return the total number of bytes read into the buffer, - * or -1 if there is no more data because the end of the stream has been reached. */ public int getBytes (byte[] b) throws IOException { return serverIn.read (b); @@ -897,7 +1024,7 @@ public int getBytes (byte[] b) throws IOException { /** * disconnects the TCP/IP session. The instance is ready for * a reconnection. There is no need to create a new ISOChannel
- * @exception IOException + * @exception IOException if an I/O error occurs during disconnect */ public void disconnect () throws IOException { var jfr = new ChannelEvent.Disconnect(); @@ -938,7 +1065,7 @@ public void disconnect () throws IOException { } /** * Issues a disconnect followed by a connect - * @exception IOException + * @exception IOException if the reconnect fails */ public void reconnect() throws IOException { disconnect(); @@ -953,9 +1080,17 @@ public void setLogger (Logger logger, String realm) { public String getRealm () { return realm; } + /** + * Returns the Logger associated with this channel. + * @return the channel Logger + */ public Logger getLogger() { return logger; } + /** + * Returns the original realm name, or the class name if none was set. + * @return original realm + */ public String getOriginalRealm() { return originalRealm == null ? this.getClass().getName() : originalRealm; @@ -976,6 +1111,7 @@ public String getName() { return this.name; } /** + * Adds a filter to this channel's filter chain. * @param filter filter to add * @param direction ISOMsg.INCOMING, ISOMsg.OUTGOING, 0 for both */ @@ -1014,6 +1150,7 @@ public void addFilter (ISOFilter filter) { addFilter (filter, 0); } /** + * Removes a filter from this channel's filter chain. * @param filter filter to remove * @param direction ISOMsg.INCOMING, ISOMsg.OUTGOING, 0 for both */ @@ -1049,6 +1186,13 @@ public void removeIncomingFilter (ISOFilter filter) { public void removeOutgoingFilter (ISOFilter filter) { removeFilter (filter, ISOMsg.OUTGOING); } + /** + * Applies the outgoing filter chain to the given message. + * @param m message to filter + * @param evt log event + * @return filtered message + * @throws VetoException if a filter vetoes the message + */ protected ISOMsg applyOutgoingFilters (ISOMsg m, LogEvent evt) throws VetoException { @@ -1056,11 +1200,27 @@ protected ISOMsg applyOutgoingFilters (ISOMsg m, LogEvent evt) m = f.filter (this, m, evt); return m; } + /** + * Applies the incoming filter chain to the given message. + * @param m message to filter + * @param evt log event + * @return filtered message + * @throws VetoException if a filter vetoes the message + */ protected ISOMsg applyIncomingFilters (ISOMsg m, LogEvent evt) throws VetoException { return applyIncomingFilters (m, null, null, evt); } + /** + * Applies the incoming filter chain, optionally providing raw header and image bytes. + * @param m message to filter + * @param header raw header bytes (may be null) + * @param image raw message image (may be null) + * @param evt log event + * @return filtered message + * @throws VetoException if a filter vetoes the message + */ protected ISOMsg applyIncomingFilters (ISOMsg m, byte[] header, byte[] image, LogEvent evt) throws VetoException { @@ -1072,9 +1232,21 @@ protected ISOMsg applyIncomingFilters (ISOMsg m, byte[] header, byte[] image, Lo } return m; } + /** + * Unpacks the byte array into the given message using the configured packager. + * @param m message to unpack into + * @param b packed bytes + * @throws ISOException on unpacking error + */ protected void unpack (ISOMsg m, byte[] b) throws ISOException { m.unpack (b); } + /** + * Packs the given message into a byte array using the configured packager. + * @param m message to pack + * @return packed bytes + * @throws ISOException on packing error + */ protected byte[] pack (ISOMsg m) throws ISOException { return m.pack(); } @@ -1090,7 +1262,7 @@ protected byte[] pack (ISOMsg m) throws ISOException { * (host not present indicates a ServerChannel) * * @param cfg Configuration - * @throws ConfigurationException + * @throws ConfigurationException if the configuration is invalid or incomplete */ public void setConfiguration (Configuration cfg) throws ConfigurationException @@ -1134,40 +1306,81 @@ public void setConfiguration (Configuration cfg) throw new ConfigurationException (e); } } + /** + * Returns this channel's current configuration. + * @return the channel configuration + */ public Configuration getConfiguration() { return cfg; } + /** + * Returns the incoming filter chain. + * @return incoming filters + */ public Collection getIncomingFilters() { return incomingFilters; } + /** + * Returns the outgoing filter chain. + * @return outgoing filters + */ public Collection getOutgoingFilters() { return outgoingFilters; } + /** + * Replaces the incoming filter chain. + * @param filters the new incoming filter set + */ public void setIncomingFilters (Collection filters) { incomingFilters = new ArrayList (filters); } + /** + * Replaces the outgoing filter chain. + * @param filters the new outgoing filter set + */ public void setOutgoingFilters (Collection filters) { outgoingFilters = new ArrayList (filters); } + /** + * Sets the channel-level header prepended to outgoing messages. + * @param header header bytes + */ public void setHeader (byte[] header) { this.header = header; } + /** + * Sets the channel-level header from a string (encoded as platform bytes). + * @param header header string + */ public void setHeader (String header) { setHeader (header.getBytes()); } + /** + * Returns the channel-level header bytes. + * @return header bytes, or null if none is configured + */ public byte[] getHeader () { return header; } + /** + * Controls whether the channel-level header overrides the message header. + * @param overrideHeader true to override + */ public void setOverrideHeader (boolean overrideHeader) { this.overrideHeader = overrideHeader; } + /** + * Returns true if the channel-level header overrides the message's own header. + * @return true if overriding + */ public boolean isOverrideHeader () { return overrideHeader; } /** + * Looks up a registered {@link ISOChannel} by name from the {@link org.jpos.util.NameRegistrar}. * @param name the Channel's name (without the "channel." prefix) * @return ISOChannel instance with given name. - * @throws NameRegistrar.NotFoundException; + * @throws org.jpos.util.NameRegistrar.NotFoundException if not registered * @see NameRegistrar */ public static ISOChannel getChannel (String name) @@ -1190,15 +1403,31 @@ public ISOClientSocketFactory getSocketFactory() { * @see ISOClientSocketFactory * @since 1.3.3 */ + /** + * Sets the socket factory used for outbound connections. + * @param socketFactory the socket factory + */ public void setSocketFactory(ISOClientSocketFactory socketFactory) { this.socketFactory = socketFactory; } + /** + * Returns the maximum packet length this channel will accept. + * @return max packet length + */ public int getMaxPacketLength() { return maxPacketLength; } + /** + * Sets the maximum packet length this channel will accept. + * @param maxPacketLength max packet length + */ public void setMaxPacketLength(int maxPacketLength) { this.maxPacketLength = maxPacketLength; } + /** + * Closes the underlying socket; idempotent. + * @throws IOException on close failure + */ protected void closeSocket() throws IOException { Socket s = null; synchronized (this) { @@ -1252,11 +1481,21 @@ private UUID getSocketUUID() { uuid; } + /** + * Records an incoming message in metrics if configured. + * @param m the received message + * @throws ISOException on metrics error + */ protected void incrementMsgInCounter(ISOMsg m) throws ISOException { if (isoMsgMetrics != null) { isoMsgMetrics.recordMessage(m, MeterInfo.ISOMSG_IN); } } + /** + * Records an outgoing message in metrics if configured. + * @param m the sent message + * @throws ISOException on metrics error + */ protected void incrementMsgOutCounter(ISOMsg m) throws ISOException { if (isoMsgMetrics != null) { isoMsgMetrics.recordMessage(m, MeterInfo.ISOMSG_OUT); diff --git a/jpos/src/main/java/org/jpos/iso/BaseChannelMBean.java b/jpos/src/main/java/org/jpos/iso/BaseChannelMBean.java index 19c62c24cb..512e2e3aeb 100644 --- a/jpos/src/main/java/org/jpos/iso/BaseChannelMBean.java +++ b/jpos/src/main/java/org/jpos/iso/BaseChannelMBean.java @@ -19,14 +19,49 @@ package org.jpos.iso; import java.io.IOException; +/** + * JMX management interface for {@link BaseChannel}. + */ public interface BaseChannelMBean { + /** + * Returns the remote host name or address. + * @return remote host + */ String getHost(); + /** + * Sets the remote host name or address. + * @param host remote host + */ void setHost(String host); + /** + * Returns the remote port number. + * @return remote port + */ int getPort(); + /** + * Sets the remote port number. + * @param port remote port + */ void setPort(int port); + /** + * Returns true if the channel has an active connection. + * @return true if connected + */ boolean isConnected(); + /** + * Establishes a connection. + * @throws IOException on connection failure + */ void connect() throws IOException; + /** + * Closes the connection. + * @throws IOException on close failure + */ void disconnect() throws IOException; + /** + * Reconnects the channel. + * @throws IOException on connection failure + */ void reconnect() throws IOException; } diff --git a/jpos/src/main/java/org/jpos/iso/BcdPrefixer.java b/jpos/src/main/java/org/jpos/iso/BcdPrefixer.java index 4d2bddff89..4f7d0c6fe0 100644 --- a/jpos/src/main/java/org/jpos/iso/BcdPrefixer.java +++ b/jpos/src/main/java/org/jpos/iso/BcdPrefixer.java @@ -30,6 +30,9 @@ public class BcdPrefixer implements Prefixer /** * A length prefixer for up to 9 chars. The length is encoded with 1 BCD digit. */ + /** + * Pre-built {@link BcdPrefixer} for common BCD length prefix sizes. + */ public static final BcdPrefixer L = new BcdPrefixer(1); /** * A length prefixer for up to 99 chars. The length is encoded with 2 BCD digits. @@ -55,6 +58,10 @@ public class BcdPrefixer implements Prefixer /** The number of digits allowed to express the length */ private int nDigits; + /** + * 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; diff --git a/jpos/src/main/java/org/jpos/iso/BinaryInterpreter.java b/jpos/src/main/java/org/jpos/iso/BinaryInterpreter.java index 6ccb79d773..2f6883ca6a 100644 --- a/jpos/src/main/java/org/jpos/iso/BinaryInterpreter.java +++ b/jpos/src/main/java/org/jpos/iso/BinaryInterpreter.java @@ -54,8 +54,9 @@ public interface BinaryInterpreter byte[] uninterpret(byte[] rawData, int offset, int length); /** - * Returns the number of bytes required to interpret a byte array of length - * nBytes. + * Returns the number of bytes required to interpret a byte array of length nBytes. + * @param nBytes the number of raw bytes + * @return the packed length required to represent nBytes */ int getPackedLength(int nBytes); } \ No newline at end of file diff --git a/jpos/src/main/java/org/jpos/iso/BinaryPrefixer.java b/jpos/src/main/java/org/jpos/iso/BinaryPrefixer.java index 103dbf92b6..18ba945583 100644 --- a/jpos/src/main/java/org/jpos/iso/BinaryPrefixer.java +++ b/jpos/src/main/java/org/jpos/iso/BinaryPrefixer.java @@ -29,6 +29,9 @@ public class BinaryPrefixer implements Prefixer /** * A length prefixer for up to 255 chars. The length is encoded with 1 unsigned byte. */ + /** + * Pre-built {@link BinaryPrefixer} for common binary length prefix sizes. + */ public static final BinaryPrefixer B = new BinaryPrefixer(1); /** @@ -39,6 +42,10 @@ public class BinaryPrefixer implements Prefixer /** The number of digits allowed to express the length */ private int nBytes; + /** + * 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; diff --git a/jpos/src/main/java/org/jpos/iso/Channel.java b/jpos/src/main/java/org/jpos/iso/Channel.java index 9f3acbb400..7518f1597a 100644 --- a/jpos/src/main/java/org/jpos/iso/Channel.java +++ b/jpos/src/main/java/org/jpos/iso/Channel.java @@ -28,16 +28,19 @@ */ public interface Channel { /** + * Sends an ISO message over this channel. * @param m message to send */ void send(ISOMsg m); /** + * Receives an ISO message from this channel. * @return received message */ 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); } diff --git a/jpos/src/main/java/org/jpos/iso/ClientChannel.java b/jpos/src/main/java/org/jpos/iso/ClientChannel.java index 74b8499180..bae6469428 100644 --- a/jpos/src/main/java/org/jpos/iso/ClientChannel.java +++ b/jpos/src/main/java/org/jpos/iso/ClientChannel.java @@ -39,11 +39,13 @@ public interface ClientChannel extends ISOChannel { void setHost(String host, int port); /** + * Returns the remote host this client channel connects to. * @return hostname (may be null) */ String getHost(); /** + * Returns the remote port this client channel connects to. * @return port number (may be 0) */ int getPort(); diff --git a/jpos/src/main/java/org/jpos/iso/Connector.java b/jpos/src/main/java/org/jpos/iso/Connector.java index 52da35bce7..747becd57a 100644 --- a/jpos/src/main/java/org/jpos/iso/Connector.java +++ b/jpos/src/main/java/org/jpos/iso/Connector.java @@ -41,11 +41,16 @@ public class Connector private Logger logger; private String realm; private boolean preserveSourceHeader = true; + /** Name of the QMUX to look up. */ protected String muxName; + /** Name of the channel to look up. */ protected String channelName; + /** Response timeout in milliseconds (0 = no timeout). */ protected int timeout = 0; + /** Shared thread pool for processing incoming messages. */ protected static ThreadPool pool; + /** Default constructor. */ public Connector () { super(); } @@ -85,6 +90,7 @@ public void setConfiguration (Configuration cfg) } } + /** Runnable that processes a single incoming message through the MUX. */ protected class Process implements Runnable { ISOSource source; ISOMsg m; diff --git a/jpos/src/main/java/org/jpos/iso/Currency.java b/jpos/src/main/java/org/jpos/iso/Currency.java index 2b42df4b26..a96df415e8 100644 --- a/jpos/src/main/java/org/jpos/iso/Currency.java +++ b/jpos/src/main/java/org/jpos/iso/Currency.java @@ -29,10 +29,19 @@ */ public class Currency implements Serializable { + /** ISO alpha currency code (e.g. "USD"). */ String alphacode; + /** ISO numeric currency code. */ int isocode; + /** Number of decimal places for this currency. */ int numdecimals; + /** + * Creates a Currency with the given code and decimal count. + * @param alphacode ISO alpha code (e.g. "USD") + * @param isocode ISO numeric code + * @param numdecimals number of decimal places + */ public Currency(String alphacode, int isocode, int numdecimals) { this.alphacode = alphacode; @@ -40,21 +49,38 @@ public Currency(String alphacode, int isocode, int numdecimals) this.numdecimals = numdecimals; } + /** + * Returns the number of decimal places for this currency. + * @return decimal count + */ public int getDecimals() { return numdecimals; } + /** + * Returns the ISO numeric currency code. + * @return ISO numeric code + */ public int getIsoCode() { return isocode; } + /** + * Returns the ISO alpha currency code. + * @return alpha code (e.g. "USD") + */ public String getAlphaCode() { return alphacode; } + /** + * Formats an amount for inclusion in an ISO message (zero-padded, 12 digits). + * @param amount the amount to format + * @return 12-character zero-padded string + */ public String formatAmountForISOMsg(double amount) { try diff --git a/jpos/src/main/java/org/jpos/iso/FactoryChannel.java b/jpos/src/main/java/org/jpos/iso/FactoryChannel.java index f79e1381a2..68e4dbb18f 100644 --- a/jpos/src/main/java/org/jpos/iso/FactoryChannel.java +++ b/jpos/src/main/java/org/jpos/iso/FactoryChannel.java @@ -27,6 +27,7 @@ public interface FactoryChannel { /** + * Sets the {@link ISOClientSocketFactory} used to create sockets for this channel. * @param sfac a socket factory */ void setSocketFactory(ISOClientSocketFactory sfac); diff --git a/jpos/src/main/java/org/jpos/iso/FilteredChannel.java b/jpos/src/main/java/org/jpos/iso/FilteredChannel.java index cf3adf8903..d8312e3f8a 100644 --- a/jpos/src/main/java/org/jpos/iso/FilteredChannel.java +++ b/jpos/src/main/java/org/jpos/iso/FilteredChannel.java @@ -31,48 +31,60 @@ public interface FilteredChannel extends ISOChannel { /** + * Adds a filter to the incoming filter chain. * @param filter incoming filter to add */ void addIncomingFilter(ISOFilter filter); /** + * Adds a filter to the outgoing filter chain. * @param filter outgoing filter to add */ void addOutgoingFilter(ISOFilter filter); + /** Adds a filter to both incoming and outgoing chains. + * @param filter filter to add + */ void addFilter(ISOFilter filter); /** + * Removes a filter from both incoming and outgoing chains. * @param filter filter to remove (both directions) */ void removeFilter(ISOFilter filter); /** + * Removes a filter from the incoming filter chain. * @param filter incoming filter to remove */ void removeIncomingFilter(ISOFilter filter); /** + * Removes a filter from the outgoing filter chain. * @param filter outgoing filter to remove */ void removeOutgoingFilter(ISOFilter filter); /** + * Returns all filters in the incoming filter chain. * @return Collection containing all incoming filters */ Collection getIncomingFilters(); /** + * Returns all filters in the outgoing filter chain. * @return Collection containing all outgoing filters */ Collection getOutgoingFilters(); /** + * Replaces the entire incoming filter chain with the given collection. * @param filters incoming filter set */ void setIncomingFilters(Collection filters); /** + * Replaces the entire outgoing filter chain with the given collection. * @param filters outgoing filter set */ void setOutgoingFilters(Collection filters); diff --git a/jpos/src/main/java/org/jpos/iso/IFA_LLBNUM.java b/jpos/src/main/java/org/jpos/iso/IFA_LLBNUM.java index 64585808ed..81edf0c620 100644 --- a/jpos/src/main/java/org/jpos/iso/IFA_LLBNUM.java +++ b/jpos/src/main/java/org/jpos/iso/IFA_LLBNUM.java @@ -25,7 +25,7 @@ * Value is represented in BCD * ISOFieldPackager Binary LLNUM * - * @author Mladen Mrkic + * @author Mladen Mrkic (mmrkic@arius.co.yu) * * @see ISOComponent */ diff --git a/jpos/src/main/java/org/jpos/iso/IFA_LLLLCHAR.java b/jpos/src/main/java/org/jpos/iso/IFA_LLLLCHAR.java index 762d5a4e7a..8cc2eda019 100644 --- a/jpos/src/main/java/org/jpos/iso/IFA_LLLLCHAR.java +++ b/jpos/src/main/java/org/jpos/iso/IFA_LLLLCHAR.java @@ -21,7 +21,7 @@ /** * ISOFieldPackager ASCII variable len CHAR * - * @author Victor A. Salaman + * @author Victor A. Salaman (salaman@teknos.com) * @version $Id$ * @see ISOComponent */ diff --git a/jpos/src/main/java/org/jpos/iso/IFA_LLLLLCHAR.java b/jpos/src/main/java/org/jpos/iso/IFA_LLLLLCHAR.java index 7789945d91..78d8887a7f 100644 --- a/jpos/src/main/java/org/jpos/iso/IFA_LLLLLCHAR.java +++ b/jpos/src/main/java/org/jpos/iso/IFA_LLLLLCHAR.java @@ -21,7 +21,7 @@ /** * ISOFieldPackager ASCII variable len CHAR * - * @author Victor A. Salaman + * @author Victor A. Salaman (salaman@teknos.com) * @version $Id$ * @see ISOComponent */ diff --git a/jpos/src/main/java/org/jpos/iso/IFB_LLLHECHAR.java b/jpos/src/main/java/org/jpos/iso/IFB_LLLHECHAR.java index bad79fd999..9693545d7b 100644 --- a/jpos/src/main/java/org/jpos/iso/IFB_LLLHECHAR.java +++ b/jpos/src/main/java/org/jpos/iso/IFB_LLLHECHAR.java @@ -20,6 +20,7 @@ /** + * ISOFieldPackager for a binary-length-prefixed LLHECHAR field. * @author apr@cs.com.uy * @version $Id$ * @see ISOComponent diff --git a/jpos/src/main/java/org/jpos/iso/IFE_CHAR.java b/jpos/src/main/java/org/jpos/iso/IFE_CHAR.java index 5b4aa8cfc2..eb8c726c67 100644 --- a/jpos/src/main/java/org/jpos/iso/IFE_CHAR.java +++ b/jpos/src/main/java/org/jpos/iso/IFE_CHAR.java @@ -19,7 +19,7 @@ package org.jpos.iso; /** - * ISOFieldPackager CHARACTERS (ASCII & BINARY) + * ISOFieldPackager CHARACTERS (ASCII & BINARY) * EBCDIC version of IF_CHAR * @author apr@cs.com.uy * @version $Id$ diff --git a/jpos/src/main/java/org/jpos/iso/IFE_LLLLBINARY.java b/jpos/src/main/java/org/jpos/iso/IFE_LLLLBINARY.java index 0122cf44cb..d87c10dab8 100644 --- a/jpos/src/main/java/org/jpos/iso/IFE_LLLLBINARY.java +++ b/jpos/src/main/java/org/jpos/iso/IFE_LLLLBINARY.java @@ -19,8 +19,9 @@ package org.jpos.iso; /** + * ISOFieldPackager EBCDIC variable-length binary field with a 4-digit length prefix. * - * @author edwin < edwinkun at gmail dot com > + * @author edwin (edwinkun at gmail dot com) */ public class IFE_LLLLBINARY extends ISOBinaryFieldPackager { diff --git a/jpos/src/main/java/org/jpos/iso/IFE_LLLLCHAR.java b/jpos/src/main/java/org/jpos/iso/IFE_LLLLCHAR.java index b40667ae8f..5c85ef0fc2 100644 --- a/jpos/src/main/java/org/jpos/iso/IFE_LLLLCHAR.java +++ b/jpos/src/main/java/org/jpos/iso/IFE_LLLLCHAR.java @@ -19,8 +19,9 @@ package org.jpos.iso; /** + * ISOFieldPackager EBCDIC variable-length character field with a 4-digit length prefix. * - * @author edwin < edwinkun at gmail dot com > + * @author edwin (edwinkun at gmail dot com) */ public class IFE_LLLLCHAR extends ISOStringFieldPackager diff --git a/jpos/src/main/java/org/jpos/iso/IF_ECHAR.java b/jpos/src/main/java/org/jpos/iso/IF_ECHAR.java index 8ad01eb2c7..f6e934a580 100644 --- a/jpos/src/main/java/org/jpos/iso/IF_ECHAR.java +++ b/jpos/src/main/java/org/jpos/iso/IF_ECHAR.java @@ -19,7 +19,7 @@ package org.jpos.iso; /** - * ISOFieldPackager CHARACTERS (ASCII & BINARY) + * ISOFieldPackager CHARACTERS (ASCII & BINARY) * EBCDIC version of IF_CHAR * @author apr@cs.com.uy * @version $Id$ diff --git a/jpos/src/main/java/org/jpos/iso/IF_NOP.java b/jpos/src/main/java/org/jpos/iso/IF_NOP.java index aaf8c7846c..fbbe4f2ecd 100644 --- a/jpos/src/main/java/org/jpos/iso/IF_NOP.java +++ b/jpos/src/main/java/org/jpos/iso/IF_NOP.java @@ -20,7 +20,8 @@ /** - * @author apr@cs.com.uy & dflc@cs.com.uy + * A no-operation ISOFieldPackager; used as a placeholder for fields that require no packing/unpacking. + * @author apr@cs.com.uy, dflc@cs.com.uy * @version $Id$ * @see ISOComponent * @see IFA_LLNUM @@ -40,7 +41,6 @@ public IF_NOP (int len, String description) { /** * @param c - a component * @return packed component - * @exception ISOException */ public byte[] pack (ISOComponent c) { return new byte[0]; diff --git a/jpos/src/main/java/org/jpos/iso/ISOAmountFieldPackager.java b/jpos/src/main/java/org/jpos/iso/ISOAmountFieldPackager.java index e4dc80314f..f191c8eb39 100644 --- a/jpos/src/main/java/org/jpos/iso/ISOAmountFieldPackager.java +++ b/jpos/src/main/java/org/jpos/iso/ISOAmountFieldPackager.java @@ -22,6 +22,7 @@ import java.io.InputStream; /** + * Marker interface for field packagers that handle ISO-8583 amount fields. * @author joconnor * @version $Revision$ $Date$ */ diff --git a/jpos/src/main/java/org/jpos/iso/ISOBasePackager.java b/jpos/src/main/java/org/jpos/iso/ISOBasePackager.java index e883475859..72e9b3f69b 100644 --- a/jpos/src/main/java/org/jpos/iso/ISOBasePackager.java +++ b/jpos/src/main/java/org/jpos/iso/ISOBasePackager.java @@ -54,9 +54,14 @@ public void setThirdBitmapField(int f) throws ISOException throw new ISOException("thirdBitmapField should be >= 0 and <= 128"); thirdBitmapField= f; } + /** + * Returns the field number used as the third bitmap, or -1 if not configured. + * @return third bitmap field number + */ public int getThirdBitmapField() { return thirdBitmapField; } /** + * Indicates whether a bitmap field should be emitted when packing. * @return true if BitMap have to be emited */ protected boolean emitBitMap () { @@ -80,7 +85,7 @@ protected int getFirstField() { * * @param m the Component to pack * @return Message image - * @exception ISOException + * @exception ISOException on packing error */ @Override public byte[] pack (ISOComponent m) throws ISOException @@ -218,7 +223,7 @@ public byte[] pack (ISOComponent m) throws ISOException * @param m the Container of this message * @param b ISO message image * @return consumed bytes - * @exception ISOException + * @exception ISOException on unpacking error */ @Override public int unpack (ISOComponent m, byte[] b) throws ISOException { @@ -429,7 +434,12 @@ public void unpack (ISOComponent m, InputStream in) /** * Internal helper logging function. - * Assumes evt is not null. + * @param evt the log event to append to (must not be null) + * @param fldno the field number being unpacked + * @param c the unpacked component + * @param fld the field packager used + * @param logFieldName whether to include the field name in the log output + * @throws ISOException on logging error */ protected static void fieldUnpackLogger(LogEvent evt, int fldno, ISOComponent c, ISOFieldPackager fld, boolean logFieldName) throws ISOException { @@ -462,6 +472,7 @@ public String getFieldDescription(ISOComponent m, int fldNumber) { return fld[fldNumber].getDescription(); } /** + * Returns the {@link ISOFieldPackager} assigned to the given field number. * @param fldNumber the Field Number * @return Field Packager for this field */ @@ -469,6 +480,7 @@ public ISOFieldPackager getFieldPackager (int fldNumber) { return fld != null && fldNumber < fld.length ? fld[fldNumber] : null; } /** + * Assigns an {@link ISOFieldPackager} to the given field number. * @param fldNumber the Field Number * @param fieldPackager the Field Packager */ @@ -477,16 +489,19 @@ public ISOFieldPackager getFieldPackager (int fldNumber) { { fld[fldNumber] = fieldPackager; } + /** Creates and returns a new {@link ISOMsg} instance. @return new ISOMsg */ public ISOMsg createISOMsg () { return new ISOMsg(); } /** + * Returns the maximum valid field number for this packager. * @return 128 for ISO-8583, should return 64 for ANSI X9.2 */ protected int getMaxValidField() { return 128; } /** + * Returns the {@link ISOFieldPackager} to use for the bitmap field. * @return suitable ISOFieldPackager for Bitmap */ protected ISOFieldPackager getBitMapfieldPackager() { diff --git a/jpos/src/main/java/org/jpos/iso/ISOBinaryField.java b/jpos/src/main/java/org/jpos/iso/ISOBinaryField.java index b00592e97c..3aa9473b3e 100644 --- a/jpos/src/main/java/org/jpos/iso/ISOBinaryField.java +++ b/jpos/src/main/java/org/jpos/iso/ISOBinaryField.java @@ -44,7 +44,7 @@ public class ISOBinaryField /** * No args constructor - * (required by Externalizable support on ISOMsg) + * (required by Externalizable support on ISOMsg) */ public ISOBinaryField () { fieldNumber = -1; diff --git a/jpos/src/main/java/org/jpos/iso/ISOBinaryFieldPackager.java b/jpos/src/main/java/org/jpos/iso/ISOBinaryFieldPackager.java index 4eeeddcd08..b2ed4f3f07 100644 --- a/jpos/src/main/java/org/jpos/iso/ISOBinaryFieldPackager.java +++ b/jpos/src/main/java/org/jpos/iso/ISOBinaryFieldPackager.java @@ -22,6 +22,7 @@ import java.io.InputStream; /** + * Marker interface for {@link org.jpos.iso.ISOFieldPackager} implementations that handle binary fields. * @author joconnor * @version $Revision$ $Date$ */ diff --git a/jpos/src/main/java/org/jpos/iso/ISOChannel.java b/jpos/src/main/java/org/jpos/iso/ISOChannel.java index 7e7e7ec6d8..540319f548 100644 --- a/jpos/src/main/java/org/jpos/iso/ISOChannel.java +++ b/jpos/src/main/java/org/jpos/iso/ISOChannel.java @@ -41,19 +41,19 @@ public interface ISOChannel extends ISOSource { /** * Connects ISOChannel - * @exception IOException + * @exception IOException on I/O failure */ void connect() throws IOException; /** * disconnects ISOChannel - * @exception IOException + * @exception IOException on I/O failure */ void disconnect() throws IOException; /** * Reconnect channel - * @exception IOException + * @exception IOException on I/O failure */ void reconnect() throws IOException; @@ -65,28 +65,29 @@ public interface ISOChannel extends ISOSource { /** * Receives an ISOMsg * @return the Message received - * @exception IOException - * @exception ISOException + * @exception IOException on I/O failure + * @exception ISOException on ISO packing/unpacking failure */ ISOMsg receive() throws IOException, ISOException; /** * sends an ISOMsg over the TCP/IP session * @param m the Message to be sent - * @exception IOException - * @exception ISOException + * @exception IOException on I/O failure + * @exception ISOException on ISO packing/unpacking failure */ void send(ISOMsg m) throws IOException, ISOException; /** * sends a byte[] over the TCP/IP session * @param b the byte array to be sent - * @exception IOException - * @exception ISOException + * @exception IOException on I/O failure + * @exception ISOException on ISO packing/unpacking failure */ void send(byte[] b) throws IOException, ISOException; /** + * Marks this channel as usable or not; a non-usable channel will not accept messages. * @param b - usable state */ void setUsable(boolean b); @@ -99,17 +100,20 @@ public interface ISOChannel extends ISOSource { void setName(String name); /** + * Returns this channel's registered name. * @return this ISOChannel's name ("" if no name was set) */ String getName(); /** + * Returns the packager used to pack/unpack ISO messages on this channel. * @return current packager */ ISOPackager getPackager(); /** - * Expose channel clonning interface + * Returns a clone of this channel. + * @return a deep copy of this ISOChannel */ Object clone(); diff --git a/jpos/src/main/java/org/jpos/iso/ISOComponent.java b/jpos/src/main/java/org/jpos/iso/ISOComponent.java index d010f473d0..aacec1af53 100644 --- a/jpos/src/main/java/org/jpos/iso/ISOComponent.java +++ b/jpos/src/main/java/org/jpos/iso/ISOComponent.java @@ -42,7 +42,7 @@ 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"); @@ -50,7 +50,7 @@ public void set (ISOComponent c) throws ISOException { /** * 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,7 +72,7 @@ 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"); @@ -80,7 +80,7 @@ public Object getKey() throws ISOException { /** * 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"); @@ -88,7 +88,7 @@ public Object getValue() throws ISOException { /** * 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"); diff --git a/jpos/src/main/java/org/jpos/iso/ISOCurrency.java b/jpos/src/main/java/org/jpos/iso/ISOCurrency.java index 61d0692cd4..261eebc77f 100644 --- a/jpos/src/main/java/org/jpos/iso/ISOCurrency.java +++ b/jpos/src/main/java/org/jpos/iso/ISOCurrency.java @@ -30,8 +30,8 @@ * @author vsalaman@gmail.com * @author Jonathan.O'Connor@xcom.de * @version $Id$ - * @see "http://www.evertype.com/standards/iso4217/iso4217-en.html" - * "http://www.iso.org/iso/en/prods-services/popstds/currencycodeslist.html" + * @see ISO 4217 currency codes + * @see ISO currency codes list */ public class ISOCurrency { diff --git a/jpos/src/main/java/org/jpos/iso/ISOException.java b/jpos/src/main/java/org/jpos/iso/ISOException.java index 9452ad38ba..d904e44e87 100644 --- a/jpos/src/main/java/org/jpos/iso/ISOException.java +++ b/jpos/src/main/java/org/jpos/iso/ISOException.java @@ -76,6 +76,7 @@ public ISOException (String s, Throwable nested) { } /** + * Returns the nested (wrapped) exception, if any. * @return nested exception (may be null) */ public Throwable getNested() { diff --git a/jpos/src/main/java/org/jpos/iso/ISOField.java b/jpos/src/main/java/org/jpos/iso/ISOField.java index b24d80b273..58c41596b6 100644 --- a/jpos/src/main/java/org/jpos/iso/ISOField.java +++ b/jpos/src/main/java/org/jpos/iso/ISOField.java @@ -40,7 +40,7 @@ public class ISOField /** * No args constructor - * (required by Externalizable support on ISOMsg) + * (required by Externalizable support on ISOMsg) */ public ISOField () { fieldNumber = -1; diff --git a/jpos/src/main/java/org/jpos/iso/ISOFieldPackager.java b/jpos/src/main/java/org/jpos/iso/ISOFieldPackager.java index 613b801a22..c478c3f8e3 100644 --- a/jpos/src/main/java/org/jpos/iso/ISOFieldPackager.java +++ b/jpos/src/main/java/org/jpos/iso/ISOFieldPackager.java @@ -73,6 +73,7 @@ public ISOFieldPackager() } /** + * Creates an ISOFieldPackager with the given length and description. * @param len - field Len * @param description - details */ @@ -80,53 +81,90 @@ public ISOFieldPackager(int len, String description) { this.len = len; this.description = description; } + /** + * Returns the field description. + * @return field description + */ public String getDescription() { return 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 + */ public int getLength() { return len; } + /** + * 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 + */ public void setPad(boolean pad) { this.pad = pad; } + /** + * Enables or disables trimming for this field. + * @param trim true to enable trimming + */ public void setTrim(boolean trim) { this.trim = trim; } + /** + * Returns the maximum number of bytes this packager can produce. + * @return maximum packed length in bytes + */ public abstract int getMaxPackedLength(); + /** + * Creates an {@link ISOComponent} instance appropriate for this packager. + * @param fieldNumber the field number to assign to the new component + * @return a new ISOComponent + */ public ISOComponent createComponent(int fieldNumber) { return new ISOField (fieldNumber); } /** + * Packs the given component into a byte array. * @param c - a component * @return packed component - * @exception ISOException + * @exception ISOException on packing error */ public abstract byte[] pack (ISOComponent c) throws ISOException; /** + * Unpacks a field from the binary image into the given component. * @param c - the Component to unpack * @param b - binary image * @param offset - starting offset within the binary image * @return consumed bytes - * @exception ISOException + * @exception ISOException on unpacking error */ public abstract int unpack (ISOComponent c, byte[] b, int offset) throws ISOException; /** + * Unpacks a field from an input stream into the given component. * @param c - the Component to unpack * @param in - input stream - * @exception ISOException + * @throws IOException on I/O failure + * @throws ISOException on unpacking error */ public void unpack (ISOComponent c, InputStream in) throws IOException, ISOException @@ -134,10 +172,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 - * @exception IOException + * @throws ISOException on packing error + * @throws IOException on I/O failure */ public void pack (ISOComponent c, ObjectOutput out) throws IOException, ISOException diff --git a/jpos/src/main/java/org/jpos/iso/ISOFilledStringFieldPackager.java b/jpos/src/main/java/org/jpos/iso/ISOFilledStringFieldPackager.java index fff999facf..4d0f593e42 100644 --- a/jpos/src/main/java/org/jpos/iso/ISOFilledStringFieldPackager.java +++ b/jpos/src/main/java/org/jpos/iso/ISOFilledStringFieldPackager.java @@ -22,6 +22,7 @@ import java.io.InputStream; /** + * Marker interface for field packagers that produce padded/filled string values. * @author joconnor * @version $Revision$ $Date$ */ diff --git a/jpos/src/main/java/org/jpos/iso/ISOFilter.java b/jpos/src/main/java/org/jpos/iso/ISOFilter.java index 64c9763d92..e04da9c03f 100644 --- a/jpos/src/main/java/org/jpos/iso/ISOFilter.java +++ b/jpos/src/main/java/org/jpos/iso/ISOFilter.java @@ -45,11 +45,12 @@ public VetoException (String detail, Exception nested) { } } /** + * Filters an ISO message before sending or after receiving. * @param channel current ISOChannel instance * @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; diff --git a/jpos/src/main/java/org/jpos/iso/ISOHeader.java b/jpos/src/main/java/org/jpos/iso/ISOHeader.java index e2b3feaae0..8056861ab5 100644 --- a/jpos/src/main/java/org/jpos/iso/ISOHeader.java +++ b/jpos/src/main/java/org/jpos/iso/ISOHeader.java @@ -21,59 +21,63 @@ import java.io.Serializable; /** + * Represents the optional header portion of an ISO-8583 message frame. * @author Eoin.Flood@orbiscom.com */ public interface ISOHeader extends Cloneable,Serializable { /** - * Return this header as byte array. + * Packs this header into a byte array. + * @return this header serialised as a byte array */ byte[] pack(); /** - * Create a new ISOHeader from a byte array. - * - * @return The Number of bytes consumed. + * Unpacks the header from a raw byte array. + * @param b raw bytes to parse + * @return the number of bytes consumed */ int unpack(byte[] b); /** - * Set the Destination address in this ISOHeader. + * Sets the destination address in this ISOHeader. + * @param dst the destination address */ void setDestination(String dst); /** - * Return the destination address in this ISOHeader. - * returns null if there is no destination address + * Returns the destination address in this ISOHeader. + * @return the destination address, or null if not set */ String getDestination(); /** - * Set the Source address in this ISOHeader. + * Sets the source address in this ISOHeader. + * @param src the source address */ void setSource(String src); /** - * Return the source address in this ISOHeader. - * returns null if there is no source address + * Returns the source address in this ISOHeader. + * @return the source address, or null if not set */ String getSource(); /** - * return the number of bytes in this ISOHeader + * Returns the number of bytes in this ISOHeader when packed. + * @return header length in bytes */ int getLength(); - + /** - * Swap the source and destination addresses in this ISOHeader - * (if they exist). + * Swaps the source and destination addresses in this ISOHeader (if they exist). */ void swapDirection(); /** - * Allow object to be cloned. + * Returns a clone of this ISOHeader. + * @return cloned ISOHeader instance */ Object clone(); } - diff --git a/jpos/src/main/java/org/jpos/iso/ISOMsg.java b/jpos/src/main/java/org/jpos/iso/ISOMsg.java index 53e4224a50..a6d9697e80 100644 --- a/jpos/src/main/java/org/jpos/iso/ISOMsg.java +++ b/jpos/src/main/java/org/jpos/iso/ISOMsg.java @@ -123,12 +123,12 @@ public byte[] getHeader() { /** * Sets optional trailer data. - *

+ *

* Note: The trailer data requires a customised channel that explicitly handles the trailer data from the ISOMsg. * * @param trailer The trailer data. - * @see BaseChannel#getMessageTrailer(ISOMsg). - * @see BaseChannel#sendMessageTrailer(ISOMsg, byte[]). + * @see BaseChannel#getMessageTrailer(ISOMsg) + * @see BaseChannel#sendMessageTrailer(ISOMsg, byte[]) */ public void setTrailer(byte[] trailer) { this.trailer = trailer; @@ -151,28 +151,32 @@ public ISOHeader getISOHeader() { return header; } /** - * @return the direction (ISOMsg.INCOMING or ISOMsg.OUTGOING) + * Returns the message direction. + * @return the direction ({@code ISOMsg.INCOMING} or {@code ISOMsg.OUTGOING}) * @see ISOChannel */ public int getDirection() { return direction; } /** - * @return true if this message is an incoming message + * Returns true if this message was received from a channel. + * @return true if this is an incoming message * @see ISOChannel */ public boolean isIncoming() { return direction == INCOMING; } /** - * @return true if this message is an outgoing message + * Returns true if this message is to be sent via a channel. + * @return true if this is an outgoing message * @see ISOChannel */ public boolean isOutgoing() { return direction == OUTGOING; } /** - * @return the max field number associated with this message + * Returns the highest field number present in this message. + * @return the max field number */ @Override public int getMaxField() { @@ -189,6 +193,7 @@ private void recalcMaxField() { maxFieldDirty = false; } /** + * Sets the packager used to pack/unpack this message. * @param p - a peer packager */ public void setPackager (ISOPackager p) { @@ -201,6 +206,7 @@ public void setPackager (ISOPackager p) { } } /** + * Returns the packager associated with this message. * @return the peer packager */ public ISOPackager getPackager () { @@ -463,9 +469,9 @@ public Map getChildren() { return (Map) ((TreeMap)fields).clone(); } /** - * pack the message with the current packager + * Packs this message using the configured packager. * @return the packed message - * @exception ISOException + * @exception ISOException on packing error */ @Override public byte[] pack() throws ISOException { @@ -475,10 +481,10 @@ public byte[] pack() throws ISOException { } } /** - * unpack a message + * Unpacks the raw byte array into this message. * @param b - raw message * @return consumed bytes - * @exception ISOException + * @exception ISOException on unpacking error */ @Override public int unpack(byte[] b) throws ISOException { @@ -486,6 +492,10 @@ public int unpack(byte[] b) throws ISOException { return packager.unpack(this, b); } } + /** {@inheritDoc} + * @throws IOException on I/O failure + * @throws ISOException on unpacking error + */ @Override public void unpack (InputStream in) throws IOException, ISOException { synchronized (this) { @@ -746,7 +756,8 @@ public boolean hasField (String fpath) { } } /** - * @return true if ISOMsg has at least one field + * Returns true if this message has at least one field set. + * @return true if at least one field is present */ public boolean hasFields () { return !fields.isEmpty(); @@ -754,8 +765,8 @@ public boolean hasFields () { /** * Don't call setValue on an ISOMsg. You'll sure get * an ISOException. It's intended to be used on Leafs - * @param obj - * @throws org.jpos.iso.ISOException + * @param obj value to set (not supported on ISOMsg) + * @throws org.jpos.iso.ISOException always * @see ISOField * @see ISOException */ @@ -910,17 +921,22 @@ public Object getKey() throws ISOException { return fieldNumber; throw new ISOException ("This is not a subField"); } + /** Returns this message itself as its value. + * @return this ISOMsg + */ @Override public Object getValue() { return this; } /** + * Returns true if this is an inner (sub-) message. * @return true on inner messages */ public boolean isInner() { return fieldNumber > -1; } /** + * Sets the message type indicator. * @param mti new MTI * @exception ISOException if message is inner message */ @@ -953,7 +969,8 @@ public int getFieldNumber () { } /** - * @return true is message has MTI field + * Returns true if this message has an MTI field (field 0) set. + * @return true if MTI is present * @exception ISOException if this is an inner message */ public boolean hasMTI() throws ISOException { @@ -963,6 +980,7 @@ public boolean hasMTI() throws ISOException { return hasField(0); } /** + * Returns the message type indicator. * @return current MTI * @exception ISOException on inner message or MTI not set */ @@ -975,6 +993,7 @@ else if (!hasField(0)) } /** + * Returns true if the MTI suggests this is a request message. * @return true if message "seems to be" a request * @exception ISOException on MTI not set */ @@ -982,6 +1001,7 @@ public boolean isRequest() throws ISOException { return Character.getNumericValue(getMTI().charAt (2))%2 == 0; } /** + * Returns true if the MTI suggests this is a response message. * @return true if message "seems not to be" a request * @exception ISOException on MTI not set */ @@ -989,6 +1009,7 @@ public boolean isResponse() throws ISOException { return !isRequest(); } /** + * Returns true if this is an authorization message (MTI second digit = 1). * @return true if message class is "authorization" * @exception ISOException on MTI not set */ @@ -996,6 +1017,7 @@ public boolean isAuthorization() throws ISOException { return hasMTI() && getMTI().charAt(1) == '1'; } /** + * Returns true if this is a financial message (MTI second digit = 2). * @return true if message class is "financial" * @exception ISOException on MTI not set */ @@ -1003,6 +1025,7 @@ public boolean isFinancial() throws ISOException { return hasMTI() && getMTI().charAt(1) == '2'; } /** + * Returns true if this is a file action message (MTI second digit = 3). * @return true if message class is "file action" * @exception ISOException on MTI not set */ @@ -1010,6 +1033,7 @@ public boolean isFileAction() throws ISOException { return hasMTI() && getMTI().charAt(1) == '3'; } /** + * Returns true if this is a reversal message (MTI second digit = 4, last digit 0 or 1). * @return true if message class is "reversal" * @exception ISOException on MTI not set */ @@ -1017,6 +1041,7 @@ public boolean isReversal() throws ISOException { return hasMTI() && getMTI().charAt(1) == '4' && (getMTI().charAt(3) == '0' || getMTI().charAt(3) == '1'); } /** + * Returns true if this is a chargeback message (MTI second digit = 4, last digit 2 or 3). * @return true if message class is "chargeback" * @exception ISOException on MTI not set */ @@ -1024,6 +1049,7 @@ public boolean isChargeback() throws ISOException { return hasMTI() && getMTI().charAt(1) == '4' && (getMTI().charAt(3) == '2' || getMTI().charAt(3) == '3'); } /** + * Returns true if this is a reconciliation message (MTI second digit = 5). * @return true if message class is "reconciliation" * @exception ISOException on MTI not set */ @@ -1031,6 +1057,7 @@ public boolean isReconciliation() throws ISOException { return hasMTI() && getMTI().charAt(1) == '5'; } /** + * Returns true if this is an administrative message (MTI second digit = 6). * @return true if message class is "administrative" * @exception ISOException on MTI not set */ @@ -1038,6 +1065,7 @@ public boolean isAdministrative() throws ISOException { return hasMTI() && getMTI().charAt(1) == '6'; } /** + * Returns true if this is a fee collection message (MTI second digit = 7). * @return true if message class is "fee collection" * @exception ISOException on MTI not set */ @@ -1045,14 +1073,16 @@ public boolean isFeeCollection() throws ISOException { return hasMTI() && getMTI().charAt(1) == '7'; } /** - * @return true if message class is "fee collection" + * Returns true if this is a network management message (MTI second digit = 8). + * @return true if message class is "network management" * @exception ISOException on MTI not set */ public boolean isNetworkManagement() throws ISOException { return hasMTI() && getMTI().charAt(1) == '8'; } /** - * @return true if message is Retransmission + * Returns true if this is a retransmission (MTI last digit = 1). + * @return true if message is a retransmission * @exception ISOException on MTI not set */ public boolean isRetransmission() throws ISOException { @@ -1229,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 () { diff --git a/jpos/src/main/java/org/jpos/iso/ISOPackager.java b/jpos/src/main/java/org/jpos/iso/ISOPackager.java index 3fe6fca647..1ce82db3bd 100644 --- a/jpos/src/main/java/org/jpos/iso/ISOPackager.java +++ b/jpos/src/main/java/org/jpos/iso/ISOPackager.java @@ -22,34 +22,46 @@ import java.io.InputStream; /** + * Core interface for ISO-8583 packagers; responsible for packing and unpacking {@link org.jpos.iso.ISOMsg} instances. * @author apr * @version $Id$ * @see ISOComponent */ public interface ISOPackager { /** + * Packs an ISO-8583 message into a byte array. * @param m the Component to pack * @return Message image - * @exception ISOException on error + * @exception ISOException on packing error */ byte[] pack(ISOComponent m) throws ISOException; /** + * Unpacks an ISO-8583 byte array into the given message container. * @param m the Container of this message * @param b ISO message image * @return consumed bytes - * @exception ISOException on error + * @exception ISOException on unpacking error */ int unpack(ISOComponent m, byte[] b) throws ISOException; + /** + * Unpacks an ISO-8583 message from an input stream into the given container. + * @param m the container + * @param in the input stream + * @throws IOException on I/O failure + * @throws ISOException on unpacking error + */ void unpack(ISOComponent m, InputStream in) throws IOException, ISOException; /** + * Returns a human-readable description of this packager. * @return Packager's Description */ String getDescription(); /** + * Emits a description of the field identified by {@code fldno} in the given message to the log event. * @param m the Container (i.e. an ISOMsg) * @param fldNumber the Field Number * @return Field Description @@ -57,7 +69,8 @@ public interface ISOPackager { String getFieldDescription(ISOComponent m, int fldNumber); /** - * @return an ISOMsg + * Creates and returns a new ISOMsg instance appropriate for this packager. + * @return a new ISOMsg */ ISOMsg createISOMsg(); } diff --git a/jpos/src/main/java/org/jpos/iso/ISORequestListener.java b/jpos/src/main/java/org/jpos/iso/ISORequestListener.java index bc3fce92c1..d8ba661735 100644 --- a/jpos/src/main/java/org/jpos/iso/ISORequestListener.java +++ b/jpos/src/main/java/org/jpos/iso/ISORequestListener.java @@ -28,6 +28,8 @@ */ public interface ISORequestListener { /** + * Called when an unmatched request is received. + * Processes an unmatched ISO request. * @param source source where you optionally can reply * @param m the unmatched request * @return true if request was handled by this listener diff --git a/jpos/src/main/java/org/jpos/iso/ISOServer.java b/jpos/src/main/java/org/jpos/iso/ISOServer.java index e5acd3f4d2..7c3a06c415 100644 --- a/jpos/src/main/java/org/jpos/iso/ISOServer.java +++ b/jpos/src/main/java/org/jpos/iso/ISOServer.java @@ -560,7 +560,7 @@ public void setName (String name) { } /** * @return ISOServer instance with given name. - * @throws NameRegistrar.NotFoundException; + * @throws org.jpos.util.NameRegistrar.NotFoundException if not registered * @see NameRegistrar */ public static ISOServer getServer (String name) diff --git a/jpos/src/main/java/org/jpos/iso/ISOSource.java b/jpos/src/main/java/org/jpos/iso/ISOSource.java index b3f1fc03ef..382a172940 100644 --- a/jpos/src/main/java/org/jpos/iso/ISOSource.java +++ b/jpos/src/main/java/org/jpos/iso/ISOSource.java @@ -30,14 +30,15 @@ public interface ISOSource { /** * sends (or hands back) an ISOMsg * @param m the Message to be sent - * @exception IOException - * @exception ISOException - * @exception ISOFilter.VetoException; + * @exception IOException on I/O failure + * @exception ISOException on ISO packing failure + * @exception org.jpos.iso.ISOFilter.VetoException if a filter vetoes the message */ void send(ISOMsg m) throws IOException, ISOException; /** + * Indicates whether this source is currently connected and able to send messages. * @return true if source is connected and usable */ boolean isConnected(); diff --git a/jpos/src/main/java/org/jpos/iso/ISOStringFieldPackager.java b/jpos/src/main/java/org/jpos/iso/ISOStringFieldPackager.java index 06228dfbe3..c8b718abb4 100644 --- a/jpos/src/main/java/org/jpos/iso/ISOStringFieldPackager.java +++ b/jpos/src/main/java/org/jpos/iso/ISOStringFieldPackager.java @@ -22,6 +22,7 @@ import java.io.InputStream; /** + * Marker interface for {@link org.jpos.iso.ISOFieldPackager} implementations that handle string fields. * @author joconnor * @version $Revision$ $Date$ */ diff --git a/jpos/src/main/java/org/jpos/iso/ISOSubFieldPackager.java b/jpos/src/main/java/org/jpos/iso/ISOSubFieldPackager.java index 618561e76c..22b09e6485 100644 --- a/jpos/src/main/java/org/jpos/iso/ISOSubFieldPackager.java +++ b/jpos/src/main/java/org/jpos/iso/ISOSubFieldPackager.java @@ -26,7 +26,7 @@ * {@link org.jpos.iso.packager.GenericSubFieldPackager} or even * {@link org.jpos.iso.packager.GenericTaggedFieldsPackager}) * - * @author Robert Demski + * @author Robert Demski (drdemsey@gmail.com) */ public interface ISOSubFieldPackager { diff --git a/jpos/src/main/java/org/jpos/iso/ISOUtil.java b/jpos/src/main/java/org/jpos/iso/ISOUtil.java index 9694c2511c..84d54c5391 100644 --- a/jpos/src/main/java/org/jpos/iso/ISOUtil.java +++ b/jpos/src/main/java/org/jpos/iso/ISOUtil.java @@ -1165,8 +1165,10 @@ public static byte[] bitSet2extendedByte ( BitSet b ){ * Converts a String to an integer of base radix. *

* String constraints are: + *

    *
  • Number must be less than 10 digits
    • *
  • Number must be positive
    • + *
* @param s String representation of number * @param radix Number base to use * @return integer value of number @@ -1196,8 +1198,10 @@ public static int parseInt (String s, int radix) throws NumberFormatException { * Converts a String to an integer of radix 10. *

* String constraints are: + *
    *
  • Number must be less than 10 digits
    • *
  • Number must be positive
    • + *
* @param s String representation of number * @return integer value of number * @throws NumberFormatException @@ -1210,8 +1214,10 @@ public static int parseInt (String s) throws NumberFormatException { * Converts a character array to an integer of base radix. *

* Array constraints are: + *
    *
  • Number must be less than 10 digits
    • *
  • Number must be positive
    • + *
* @param cArray Character Array representation of number * @param radix Number base to use * @return integer value of number @@ -1241,8 +1247,10 @@ public static int parseInt (char[] cArray, int radix) throws NumberFormatExcepti * Converts a character array to an integer of radix 10. *

* Array constraints are: + *
    *
  • Number must be less than 10 digits
    • *
  • Number must be positive
    • + *
* @param cArray Character Array representation of number * @return integer value of number * @throws NumberFormatException @@ -1255,8 +1263,10 @@ public static int parseInt (char[] cArray) throws NumberFormatException { * Converts a byte array to an integer of base radix. *

* Array constraints are: + *
    *
  • Number must be less than 10 digits
    • *
  • Number must be positive
    • + *
* @param bArray Byte Array representation of number * @param radix Number base to use * @return integer value of number @@ -1286,8 +1296,10 @@ public static int parseInt (byte[] bArray, int radix) throws NumberFormatExcepti * Converts a byte array to an integer of radix 10. *

* Array constraints are: + *
    *
  • Number must be less than 10 digits
    • *
  • Number must be positive
    • + *
* @param bArray Byte Array representation of number * @return integer value of number * @throws NumberFormatException @@ -1479,7 +1491,7 @@ public static String millisToString (long millis) { /** * Format a string containing a amount conversion rate in the proper format - *

+ *

* Format: * The leftmost digit (i.e., position 1) of this data element denotes the number of * positions the decimal separator must be moved from the right. Positions 2–8 of @@ -1505,7 +1517,7 @@ public static String formatAmountConversionRate(double convRate) throws ISOExcep /** * Parse currency amount conversion rate string - *

+ *

* Suitble for parse fields 10 and 11 * * @param convRate amount conversation rate diff --git a/jpos/src/main/java/org/jpos/iso/Interpreter.java b/jpos/src/main/java/org/jpos/iso/Interpreter.java index a06e2752a4..c9b5241a3d 100644 --- a/jpos/src/main/java/org/jpos/iso/Interpreter.java +++ b/jpos/src/main/java/org/jpos/iso/Interpreter.java @@ -27,11 +27,13 @@ public interface Interpreter { /** - * Converts the string data into a different interpretation. Standard - * interpretations are ASCII, EBCDIC, BCD and LITERAL. - * + * Converts the string data into a different interpretation. Standard + * interpretations are ASCII, EBCDIC, BCD and LITERAL. + * @param data the string data to interpret + * @param b the target byte array + * @param offset the offset in {@code b} to start writing at * @throws ISOException on error - */ + */ void interpret(String data, byte[] b, int offset) throws ISOException; /** @@ -44,14 +46,19 @@ public interface Interpreter * The index in rawData to start interpreting at. * @param length * The number of data units to interpret. + * @return The uninterpreted data. * @throws ISOException on error - * @return The uninterpreted data. - */ + */ String uninterpret(byte[] rawData, int offset, int length) throws ISOException; /** * Returns the number of bytes required to interpret a String of length * nDataUnits. */ + /** + * Returns the number of bytes needed to store {@code nDataUnits} data units in this interpretation. + * @param nDataUnits the number of logical data units + * @return the packed byte length + */ int getPackedLength(int nDataUnits); } diff --git a/jpos/src/main/java/org/jpos/iso/Prefixer.java b/jpos/src/main/java/org/jpos/iso/Prefixer.java index 801c521d5c..f49f8380f6 100644 --- a/jpos/src/main/java/org/jpos/iso/Prefixer.java +++ b/jpos/src/main/java/org/jpos/iso/Prefixer.java @@ -28,29 +28,25 @@ public interface Prefixer { /** - * Fills a byte array with the field length data in raw form. - * - * @param length - * The length to be encoded. - * @param b - * The byte array to fill with the encoded length. - */ + * Encodes the field length into the byte array. + * @param length the field length to encode + * @param b the byte array to write the length prefix into + * @throws ISOException if the length exceeds the prefix capacity + */ void encodeLength(int length, byte[] b) throws ISOException; /** - * Decodes an encoded length. - * - * @param b - * The byte array to scan for the length. - * @param offset - * The offset to start scanning from. - * @return The length in chars of the field data to follow this - * LengthPrefix. - */ + * Decodes an encoded length from the byte array. + * @param b the byte array containing the length prefix + * @param offset the offset in {@code b} where the prefix starts + * @return the length in chars of the field data to follow this prefix + * @throws ISOException if the prefix cannot be decoded + */ int decodeLength(byte[] b, int offset) throws ISOException; /** - * Returns the number of bytes taken up by the length encoding. - */ + * Returns the number of bytes taken up by the length encoding. + * @return the number of bytes used by the length encoding + */ int getPackedLength(); } \ No newline at end of file diff --git a/jpos/src/main/java/org/jpos/iso/RawIncomingFilter.java b/jpos/src/main/java/org/jpos/iso/RawIncomingFilter.java index f5f7230a91..3500c9e53b 100644 --- a/jpos/src/main/java/org/jpos/iso/RawIncomingFilter.java +++ b/jpos/src/main/java/org/jpos/iso/RawIncomingFilter.java @@ -28,13 +28,14 @@ */ public interface RawIncomingFilter extends ISOFilter { /** + * Filters a raw incoming message before decoding. * @param channel current ISOChannel instance * @param m ISOMsg to filter * @param header optional header * @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) diff --git a/jpos/src/main/java/org/jpos/iso/ServerChannel.java b/jpos/src/main/java/org/jpos/iso/ServerChannel.java index 3de461a706..e8073ec41b 100644 --- a/jpos/src/main/java/org/jpos/iso/ServerChannel.java +++ b/jpos/src/main/java/org/jpos/iso/ServerChannel.java @@ -36,8 +36,9 @@ public interface ServerChannel extends ISOChannel { /** - * Accepts connection - * @exception IOException + * Accepts an inbound connection from the given server socket. + * @param s the server socket to accept on + * @exception IOException on I/O failure */ void accept(ServerSocket s) throws IOException; } diff --git a/jpos/src/main/java/org/jpos/iso/TaggedFieldPackager.java b/jpos/src/main/java/org/jpos/iso/TaggedFieldPackager.java index 0973573735..de0d0ec9e6 100644 --- a/jpos/src/main/java/org/jpos/iso/TaggedFieldPackager.java +++ b/jpos/src/main/java/org/jpos/iso/TaggedFieldPackager.java @@ -19,6 +19,7 @@ package org.jpos.iso; /** + * Marker interface for packagers that support tagged (TLV-style) ISO fields. * @author Vishnu Pillai * Date: 1/22/14 */ diff --git a/jpos/src/main/java/org/jpos/iso/TaggedFieldPackagerBase.java b/jpos/src/main/java/org/jpos/iso/TaggedFieldPackagerBase.java index dad8afb4c1..e8769c1b49 100644 --- a/jpos/src/main/java/org/jpos/iso/TaggedFieldPackagerBase.java +++ b/jpos/src/main/java/org/jpos/iso/TaggedFieldPackagerBase.java @@ -26,7 +26,7 @@ /** * Base class and template for handling tagged fields. - *

+ *

* This should support both fixed length and variable length tags. */ public abstract class TaggedFieldPackagerBase extends ISOFieldPackager { diff --git a/jpos/src/main/java/org/jpos/iso/channel/ASCIIChannel.java b/jpos/src/main/java/org/jpos/iso/channel/ASCIIChannel.java index 346c72be26..a63c6dc7fa 100644 --- a/jpos/src/main/java/org/jpos/iso/channel/ASCIIChannel.java +++ b/jpos/src/main/java/org/jpos/iso/channel/ASCIIChannel.java @@ -63,7 +63,7 @@ public ASCIIChannel (String host, int port, ISOPackager p) { /** * Construct server ISOChannel * @param p an ISOPackager - * @exception IOException + * @exception IOException on I/O failure * @see ISOPackager */ public ASCIIChannel (ISOPackager p) throws IOException { @@ -73,7 +73,7 @@ public ASCIIChannel (ISOPackager p) throws IOException { * constructs a server ISOChannel associated with a Server Socket * @param p an ISOPackager * @param serverSocket where to accept a connection - * @exception IOException + * @exception IOException on I/O failure * @see ISOPackager */ public ASCIIChannel (ISOPackager p, ServerSocket serverSocket) @@ -83,13 +83,19 @@ public ASCIIChannel (ISOPackager p, ServerSocket serverSocket) } + /** Sets the number of ASCII digits used for the message length prefix. + * @param len number of length digits + */ public void setLengthDigits(int len) { lengthDigits= len; } + /** Returns the number of ASCII digits used for the message length prefix. + * @return number of length digits + */ public int getLengthDigits() { return lengthDigits; } /** * @param len the packed Message len - * @exception IOException + * @exception IOException on I/O failure */ protected void sendMessageLength(int len) throws IOException { int maxLen= ten.pow(lengthDigits).intValue() - 1; // 10^lengthDigits - 1 @@ -102,7 +108,8 @@ else if (len < 0) } /** * @return the Message len - * @exception IOException, ISOException + * @exception IOException on I/O failure + * @exception ISOException on ISO packing/unpacking failure */ protected int getMessageLength() throws IOException, ISOException { int l = 0; @@ -135,7 +142,7 @@ protected int getMessageLength() throws IOException, ISOException { * defaulting to 4 * * @param cfg Configuration - * @throws ConfigurationException + * @throws ConfigurationException if the configuration is invalid */ @Override public void setConfiguration (Configuration cfg) throws ConfigurationException diff --git a/jpos/src/main/java/org/jpos/iso/channel/AmexChannel.java b/jpos/src/main/java/org/jpos/iso/channel/AmexChannel.java index c977a0becf..353335b1a2 100644 --- a/jpos/src/main/java/org/jpos/iso/channel/AmexChannel.java +++ b/jpos/src/main/java/org/jpos/iso/channel/AmexChannel.java @@ -16,102 +16,102 @@ * along with this program. If not, see . */ -package org.jpos.iso.channel; - -import org.jpos.iso.*; -import org.jpos.util.LogEvent; -import org.jpos.util.Logger; - -import java.io.IOException; -import java.net.ServerSocket; - -/** - * ISOChannel implementation - American Express - * - * @author marksalter@dsl.pipex.com - * @version $Id: AmexChannel.java,v 1.5 2006/01/27 10:36:18 mark Exp $ - * @see ISOMsg - * @see ISOException - * @see ISOChannel - */ -public class AmexChannel extends BaseChannel { - - /** - * Public constructor (used by Class.forName("...").newInstance()) - */ - public AmexChannel() { - super(); - } - - /** - * Construct client ISOChannel - * - * @param host - * server TCP Address - * @param port - * server port number - * @param p - * an ISOPackager (should be ISO87BPackager) - * @see org.jpos.iso.packager.ISO87BPackager - */ - public AmexChannel(String host, int port, ISOPackager p) { - super(host, port, p); - } - - /** - * Construct server ISOChannel - * - * @param p - * an ISOPackager (should be ISO87BPackager) - * @exception IOException - * @see org.jpos.iso.packager.ISO87BPackager - */ - public AmexChannel(ISOPackager p) throws IOException { - super(p); - } - - /** - * constructs a server ISOChannel associated with a Server Socket - * - * @param p - * an ISOPackager - * @param serverSocket - * where to accept a connection - * @exception IOException - * @see ISOPackager - */ - public AmexChannel(ISOPackager p, ServerSocket serverSocket) - throws IOException { - super(p, serverSocket); - } - - protected void sendMessageLength(int len) throws IOException { - serverOut.write(len+2 >> 8); - serverOut.write(len+2); - } - - protected int getMessageLength() throws IOException, ISOException { - int l = 0; - byte[] b = new byte[2]; - // ignore polls (0 message length) - while (l == 0) { - serverIn.readFully(b, 0, 2); - l = ((int) b[0] & 0xFF) << 8 | (int) b[1] & 0xFF; - if (l == 0 && isExpectKeepAlive()) { - serverOutLock.lock(); - try { - serverOut.write(b); - serverOut.flush(); - } finally { - serverOutLock.unlock(); - } - Logger.log(new LogEvent(this, "poll")); - } - } - // Message length includes length itself, so adjust the message total down by 2 - l = l - 2; - - return l; - } - -} +package org.jpos.iso.channel; + +import org.jpos.iso.*; +import org.jpos.util.LogEvent; +import org.jpos.util.Logger; + +import java.io.IOException; +import java.net.ServerSocket; + +/** + * ISOChannel implementation - American Express + * + * @author marksalter@dsl.pipex.com + * @version $Id: AmexChannel.java,v 1.5 2006/01/27 10:36:18 mark Exp $ + * @see ISOMsg + * @see ISOException + * @see ISOChannel + */ +public class AmexChannel extends BaseChannel { + + /** + * Public constructor (used by Class.forName("...").newInstance()) + */ + public AmexChannel() { + super(); + } + + /** + * Construct client ISOChannel + * + * @param host + * server TCP Address + * @param port + * server port number + * @param p + * an ISOPackager (should be ISO87BPackager) + * @see org.jpos.iso.packager.ISO87BPackager + */ + public AmexChannel(String host, int port, ISOPackager p) { + super(host, port, p); + } + + /** + * Construct server ISOChannel + * + * @param p + * an ISOPackager (should be ISO87BPackager) + * @exception IOException on I/O failure + * @see org.jpos.iso.packager.ISO87BPackager + */ + public AmexChannel(ISOPackager p) throws IOException { + super(p); + } + + /** + * constructs a server ISOChannel associated with a Server Socket + * + * @param p + * an ISOPackager + * @param serverSocket + * where to accept a connection + * @exception IOException on I/O failure + * @see ISOPackager + */ + public AmexChannel(ISOPackager p, ServerSocket serverSocket) + throws IOException { + super(p, serverSocket); + } + + protected void sendMessageLength(int len) throws IOException { + serverOut.write(len+2 >> 8); + serverOut.write(len+2); + } + + protected int getMessageLength() throws IOException, ISOException { + int l = 0; + byte[] b = new byte[2]; + // ignore polls (0 message length) + while (l == 0) { + serverIn.readFully(b, 0, 2); + l = ((int) b[0] & 0xFF) << 8 | (int) b[1] & 0xFF; + if (l == 0 && isExpectKeepAlive()) { + serverOutLock.lock(); + try { + serverOut.write(b); + serverOut.flush(); + } finally { + serverOutLock.unlock(); + } + Logger.log(new LogEvent(this, "poll")); + } + } + // Message length includes length itself, so adjust the message total down by 2 + l = l - 2; + + return l; + } + +} diff --git a/jpos/src/main/java/org/jpos/iso/channel/BASE24Channel.java b/jpos/src/main/java/org/jpos/iso/channel/BASE24Channel.java index 639562da2d..24c90a2a1b 100644 --- a/jpos/src/main/java/org/jpos/iso/channel/BASE24Channel.java +++ b/jpos/src/main/java/org/jpos/iso/channel/BASE24Channel.java @@ -60,7 +60,7 @@ public BASE24Channel (String host, int port, ISOPackager p) { * Construct server ISOChannel * @param p an ISOPackager * @see ISOPackager - * @exception IOException + * @exception IOException on I/O failure */ public BASE24Channel (ISOPackager p) throws IOException { super(p); @@ -69,7 +69,7 @@ public BASE24Channel (ISOPackager p) throws IOException { * constructs a server ISOChannel associated with a Server Socket * @param p an ISOPackager * @param serverSocket where to accept a connection - * @exception IOException + * @exception IOException on I/O failure * @see ISOPackager */ public BASE24Channel (ISOPackager p, ServerSocket serverSocket) @@ -80,14 +80,14 @@ public BASE24Channel (ISOPackager p, ServerSocket serverSocket) /** * @param m the Message to send (in this case it is unused) * @param len message len (ignored) - * @exception IOException + * @exception IOException on I/O failure */ protected void sendMessageTrailler(ISOMsg m, int len) throws IOException { serverOut.write (3); } /** * @return a byte array with the received message - * @exception IOException + * @exception IOException on I/O failure */ protected byte[] streamReceive() throws IOException { int i; diff --git a/jpos/src/main/java/org/jpos/iso/channel/BASE24TCPChannel.java b/jpos/src/main/java/org/jpos/iso/channel/BASE24TCPChannel.java index 5b2bdaad9b..7cfe33f0b1 100644 --- a/jpos/src/main/java/org/jpos/iso/channel/BASE24TCPChannel.java +++ b/jpos/src/main/java/org/jpos/iso/channel/BASE24TCPChannel.java @@ -64,7 +64,7 @@ public BASE24TCPChannel (String host, int port, ISOPackager p) { * Construct server ISOChannel * @param p an ISOPackager * @see ISOPackager - * @exception IOException + * @exception IOException on I/O failure */ public BASE24TCPChannel (ISOPackager p) throws IOException { super(p); @@ -73,7 +73,7 @@ public BASE24TCPChannel (ISOPackager p) throws IOException { * constructs a server ISOChannel associated with a Server Socket * @param p an ISOPackager * @param serverSocket where to accept a connection - * @exception IOException + * @exception IOException on I/O failure * @see ISOPackager */ public BASE24TCPChannel (ISOPackager p, ServerSocket serverSocket) @@ -84,7 +84,7 @@ public BASE24TCPChannel (ISOPackager p, ServerSocket serverSocket) /** * @param m the Message to send (in this case it is unused) * @param len message len (ignored) - * @exception IOException + * @exception IOException on I/O failure */ protected void sendMessageTrailler(ISOMsg m, int len) throws IOException { serverOut.write (3); diff --git a/jpos/src/main/java/org/jpos/iso/channel/BCDChannel.java b/jpos/src/main/java/org/jpos/iso/channel/BCDChannel.java index 0d599a19e0..9254255287 100644 --- a/jpos/src/main/java/org/jpos/iso/channel/BCDChannel.java +++ b/jpos/src/main/java/org/jpos/iso/channel/BCDChannel.java @@ -30,7 +30,7 @@ * Sends [LEN][TPDU][ISOMSG] * (len=2 bytes HEX) * - * @author Mladen Mrkic + * @author Mladen Mrkic (mmrkic@arius.co.yu) * @version $Revision: 2706 $ $Date: 2009-03-05 11:24:43 +0000 (Thu, 05 Mar 2009) $ * @see ISOMsg * @see ISOException @@ -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 { @@ -71,7 +71,7 @@ public BCDChannel (ISOPackager p, byte[] TPDU) throws IOException { * @param p an ISOPackager * @param TPDU an optional raw header (i.e. TPDU) * @param serverSocket where to accept a connection - * @exception IOException + * @exception IOException on I/O failure * @see ISOPackager */ public BCDChannel (ISOPackager p, byte[] TPDU, ServerSocket serverSocket) diff --git a/jpos/src/main/java/org/jpos/iso/channel/CMFChannel.java b/jpos/src/main/java/org/jpos/iso/channel/CMFChannel.java index a85e04b61c..b63b300442 100644 --- a/jpos/src/main/java/org/jpos/iso/channel/CMFChannel.java +++ b/jpos/src/main/java/org/jpos/iso/channel/CMFChannel.java @@ -30,12 +30,12 @@ * This channel uses a 3-byte big-endian length prefix (24-bit unsigned) and no * additional message header. * - *

Keep-alive handling

+ *

Keep-alive handling

* A zero-length frame is treated as a keep-alive. When a keep-alive is received and either * {@code replyKeepAlive} is enabled or {@link #isExpectKeepAlive()} returns {@code true}, the channel * echoes the keep-alive back to the peer. * - *

Configuration

+ *

Configuration

*
    *
  • {@code reply-keepalive} (boolean, default {@code true}): Whether to echo a received * keep-alive (zero-length frame) back to the peer.
    • @@ -97,8 +97,8 @@ public CMFChannel (String host, int port, ISOPackager p) { /** * Constructs a server {@code CMFChannel}. * - * This constructor creates a {@link ServerSocket} internally (as per {@link BaseChannel}) - * and waits for inbound connections when {@link #accept()} is invoked. + * This constructor creates a {@link java.net.ServerSocket} internally (as per {@link BaseChannel}) + * and waits for inbound connections when {@link BaseChannel#accept(java.net.ServerSocket)} is invoked. * * @param p the {@link ISOPackager} used to pack/unpack {@link ISOMsg}s. * @throws IOException if the underlying server socket cannot be created. @@ -110,7 +110,7 @@ public CMFChannel (ISOPackager p) throws IOException { } /** - * Constructs a server {@code CMFChannel} associated with an existing {@link ServerSocket}. + * Constructs a server {@code CMFChannel} associated with an existing {@link java.net.ServerSocket}. * * @param p the {@link ISOPackager} used to pack/unpack {@link ISOMsg}s. * @param serverSocket the server socket used to accept a connection. diff --git a/jpos/src/main/java/org/jpos/iso/channel/CSChannel.java b/jpos/src/main/java/org/jpos/iso/channel/CSChannel.java index 85dde10dea..f6dd69696d 100644 --- a/jpos/src/main/java/org/jpos/iso/channel/CSChannel.java +++ b/jpos/src/main/java/org/jpos/iso/channel/CSChannel.java @@ -88,7 +88,8 @@ protected void sendMessageLength(int len) throws IOException { } /** * @return the Message len - * @exception IOException, ISOException + * @exception IOException + * @exception ISOException */ protected int getMessageLength() throws IOException, ISOException { int l = 0; diff --git a/jpos/src/main/java/org/jpos/iso/channel/ChannelPool.java b/jpos/src/main/java/org/jpos/iso/channel/ChannelPool.java index facd733dd0..f223221648 100644 --- a/jpos/src/main/java/org/jpos/iso/channel/ChannelPool.java +++ b/jpos/src/main/java/org/jpos/iso/channel/ChannelPool.java @@ -36,17 +36,25 @@ import java.util.concurrent.locks.Lock; import java.util.concurrent.locks.ReentrantLock; +/** + * A pool of {@link ISOChannel} instances; tries each in order until one connects. + */ @SuppressWarnings("unchecked") 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; + /** 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 +175,49 @@ public void setConfiguration (Configuration cfg) } } } + /** + * Adds a channel to the pool. + * @param channel the channel to add + */ public void addChannel (ISOChannel channel) { pool.add (channel); } + /** + * 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)); } + /** + * Removes a channel from the pool. + * @param channel the channel to remove + */ public void removeChannel (ISOChannel channel) { pool.remove (channel); } + /** + * 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)); } + /** + * Returns the number of channels in the pool. + * @return channel count + */ 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 { diff --git a/jpos/src/main/java/org/jpos/iso/channel/GICCChannel.java b/jpos/src/main/java/org/jpos/iso/channel/GICCChannel.java index 7bf32b31a7..4b1d03a2ad 100644 --- a/jpos/src/main/java/org/jpos/iso/channel/GICCChannel.java +++ b/jpos/src/main/java/org/jpos/iso/channel/GICCChannel.java @@ -79,7 +79,8 @@ protected void sendMessageLength(int len) throws IOException { } /** * @return the Message len - * @exception IOException, ISOException + * @exception IOException + * @exception ISOException */ protected int getMessageLength() throws IOException, ISOException { int l = 0; diff --git a/jpos/src/main/java/org/jpos/iso/channel/GZIPChannel.java b/jpos/src/main/java/org/jpos/iso/channel/GZIPChannel.java index be25763768..08b66719ee 100644 --- a/jpos/src/main/java/org/jpos/iso/channel/GZIPChannel.java +++ b/jpos/src/main/java/org/jpos/iso/channel/GZIPChannel.java @@ -79,7 +79,8 @@ protected void sendMessageLength(int len) throws IOException { } /** * @return the Message len - * @exception IOException, ISOException + * @exception IOException + * @exception ISOException */ protected int getMessageLength() throws IOException, ISOException { int l = 0; diff --git a/jpos/src/main/java/org/jpos/iso/channel/HEXChannel.java b/jpos/src/main/java/org/jpos/iso/channel/HEXChannel.java index 2c6645f9f5..d952909147 100644 --- a/jpos/src/main/java/org/jpos/iso/channel/HEXChannel.java +++ b/jpos/src/main/java/org/jpos/iso/channel/HEXChannel.java @@ -28,7 +28,7 @@ /** * Sends a four ASCII hex characters indicating message length (up to 0xffff) * - * @author Mladen Mrkic + * @author Mladen Mrkic (mmrkic@arius.co.yu) * @author apr * @version $Revision$ $Date$ * @see ISOMsg diff --git a/jpos/src/main/java/org/jpos/iso/filter/ChannelInfoFilter.java b/jpos/src/main/java/org/jpos/iso/filter/ChannelInfoFilter.java index 82b6790a8c..32f1991623 100644 --- a/jpos/src/main/java/org/jpos/iso/filter/ChannelInfoFilter.java +++ b/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(); } diff --git a/jpos/src/main/java/org/jpos/iso/gui/ISOMeter.java b/jpos/src/main/java/org/jpos/iso/gui/ISOMeter.java index 5a670c8b62..9fe754e10d 100644 --- a/jpos/src/main/java/org/jpos/iso/gui/ISOMeter.java +++ b/jpos/src/main/java/org/jpos/iso/gui/ISOMeter.java @@ -30,7 +30,7 @@ * ISOMsgPanel * Swing based GUI to ISOMsg * @author apr@cs.com.uy - * @author Kris Leite + * @author Kris Leite (kleite at imcsoftware.com) * @see org.jpos.iso.ISOMsg */ @SuppressWarnings("deprecation") diff --git a/jpos/src/main/java/org/jpos/iso/header/BASE1Header.java b/jpos/src/main/java/org/jpos/iso/header/BASE1Header.java index 0de95eed20..f7fdb9b758 100644 --- a/jpos/src/main/java/org/jpos/iso/header/BASE1Header.java +++ b/jpos/src/main/java/org/jpos/iso/header/BASE1Header.java @@ -20,8 +20,8 @@ import org.jpos.iso.ISOUtil; -/* - * BASE1 Header +/** + * BASE1 header implementation. * 
      *   0 hlen;         Fld  1: Header Length        1B      (Byte     0)
  *   1 hformat;      Fld  2: Header Format        8N,bit  (Byte     1)
@@ -44,11 +44,17 @@
 public class BASE1Header extends BaseHeader {
 
     private static final long serialVersionUID = 6466427524726021374L;
+    /** Fixed length of a BASE-1 header in bytes. */
     public static final int LENGTH = 22;
 
+    /** Creates a BASE1Header with source and destination both set to {@code "000000"}. */
     public BASE1Header() {
         this("000000", "000000");
     }
+    /** Creates a BASE1Header with the given source and destination and default format (2).
+     * @param source 6-digit source ID
+     * @param destination 6-digit destination ID
+     */
     public BASE1Header(String source, String destination) {
         super();
         header = new byte[LENGTH];
@@ -58,6 +64,11 @@ public BASE1Header(String source, String destination) {
         setSource(source);
         setDestination(destination);
     }
+    /** Creates a BASE1Header with explicit format.
+     * @param source 6-digit source ID
+     * @param destination 6-digit destination ID
+     * @param format header format code
+     */
     public BASE1Header(String source, String destination, int format) {
         super();
         header = new byte[LENGTH];
@@ -67,37 +78,76 @@ public BASE1Header(String source, String destination, int format) {
         setSource(source);
         setDestination(destination);
     }
+    /** Creates a BASE1Header from a raw byte array.
+     * @param header raw header bytes
+     */
     public BASE1Header(byte[] header) {
         super(header);
     }
 
+    /**
+     * Returns the header length field value.
+     * @return header length
+     */
     public int getHLen() {
         return header[0] & 0xFF;
     }
+    /**
+     * Sets the header format byte.
+     * @param hformat header format value
+     */
     public void setHFormat(int hformat) {
         header[1] = (byte) hformat;
     }
+    /**
+     * Returns the message format code.
+     * @return message format code
+     */
     public int getFormat() {
         return header[2] & 0xFF;
     }
+    /**
+     * Sets the routing control byte.
+     * @param i routing control value
+     */
     public void setRtCtl(int i) {
         header[11] = (byte) i;
     }
+    /**
+     * Sets the flags field.
+     * @param i flags value
+     */
     public void setFlags(int i) {
         header[12] = (byte) (i >> 8 & 0xFF);
         header[13] = (byte) (i & 0xFF);
     }
+    /**
+     * Sets the status field.
+     * @param i status value
+     */
     public void setStatus(int i) {
         header[14] = (byte) (i >> 16 & 0xFF);
         header[15] = (byte) (i >> 8 & 0xFF);
         header[16] = (byte) (i & 0xFF);
     }
+    /**
+     * Sets the batch number.
+     * @param i batch number
+     */
     public void setBatchNumber(int i) {
         header[17] = (byte) (i & 0xFF);
     }
+    /**
+     * Sets the message format code.
+     * @param format the message format code
+     */
     public void setFormat(int format) {
         header[2] = (byte) format;
     }
+    /**
+     * Sets the message length field in the header.
+     * @param len the payload length (header length will be added automatically)
+     */
     public void setLen(int len) {
         len += header.length;
         header[3]  = (byte) (len >> 8 & 0xff);
@@ -125,6 +175,10 @@ public void swapDirection() {
             System.arraycopy(source, 0, header, 5, 3);
         }
     }
+    /**
+     * Returns true if this message is a BASE-1 reject.
+     * @return true if the message is rejected
+     */
     public boolean isRejected() {
         // Header length must be 26 or gerater
         // And header field 13 bit 1 must be 1 (field 13 starts at byte 22)
@@ -143,6 +197,10 @@ public String getRejectCode() {
     /*
      * parse header contributed by santhoshvee@yahoo.co.uk in jpos-dev mailing list
      */
+    /**
+     * Formats the header fields as a human-readable diagnostic string.
+     * @return formatted header dump
+     */
     public String formatHeader() {
         String h = ISOUtil.hexString(this.header);
         String lf = System.getProperty("line.separator");
diff --git a/jpos/src/main/java/org/jpos/iso/header/BaseHeader.java b/jpos/src/main/java/org/jpos/iso/header/BaseHeader.java
index 5f51de0c8d..530ed86e03 100644
--- a/jpos/src/main/java/org/jpos/iso/header/BaseHeader.java
+++ b/jpos/src/main/java/org/jpos/iso/header/BaseHeader.java
@@ -25,6 +25,7 @@
 import java.io.PrintStream;
 
 /**
+ * Base implementation of {@link org.jpos.iso.ISOHeader} providing common header handling for ISO-8583 channels.
  * @author Eoin Flood
  * @author Alejandro P. Revilla
  */
@@ -33,6 +34,7 @@ public class BaseHeader implements ISOHeader, Loggeable {
      * 
      */
     private static final long serialVersionUID = 8674535007934468935L;
+    /** Raw header bytes. */
     protected byte[] header;
     transient boolean asciiEncoding = false;
 
@@ -45,6 +47,9 @@ public BaseHeader()
         header = null;
     }
 
+    /** Creates a BaseHeader wrapping the given raw bytes.
+     * @param header raw header bytes
+     */
     public BaseHeader (byte[] header) {
         unpack(header);
     }
@@ -93,9 +98,17 @@ public void dump (PrintStream p, String indent) {
             );
         }
     }
+    /**
+     * Sets the encoding for source/destination fields.
+     * @param asciiEncoding true for ASCII, false for BCD
+     */
     public void setAsciiEncoding(boolean asciiEncoding) {
         this.asciiEncoding = asciiEncoding;
     }
+    /**
+     * Returns true if ASCII encoding is used for source/destination fields.
+     * @return true if ASCII encoding is active
+     */
     public boolean isAsciiEncoding() {
         return asciiEncoding;
     }
diff --git a/jpos/src/main/java/org/jpos/iso/packager/BASE24Packager.java b/jpos/src/main/java/org/jpos/iso/packager/BASE24Packager.java
index bff5b97a28..5f0847df02 100644
--- a/jpos/src/main/java/org/jpos/iso/packager/BASE24Packager.java
+++ b/jpos/src/main/java/org/jpos/iso/packager/BASE24Packager.java
@@ -23,7 +23,7 @@
 /**
  * BASE24 Packager made from ISO 8583 v1987 ASCII Packager
  *
- * @author Mike Trank 
+ * @author Mike Trank (mike@netcomsa.com)
  * @version $Id$
  * @see ISOPackager
  * @see ISOBasePackager
@@ -36,6 +36,7 @@
  *  There are notes where the comments are........ Mike.
  */
 public class BASE24Packager extends ISOBasePackager {
+    /** BASE-24 field packager definitions for fields 0-128. */
     protected ISOFieldPackager fld[] = {
             new IFA_NUMERIC (  4, "MESSAGE TYPE INDICATOR"),
             new IFA_BITMAP  ( 16, "BIT MAP"),
@@ -174,6 +175,7 @@ public class BASE24Packager extends ISOBasePackager {
             new IFA_LLCHAR (99, "BASE24-POS User Data"),
             new IFA_NUMERIC (16, "MAC 2")
         };
+    /** Creates BASE24Packager with the default BASE-24 field configuration. */
     public BASE24Packager() {
         super();
         setFieldPackager(fld);
diff --git a/jpos/src/main/java/org/jpos/iso/packager/Base1Packager.java b/jpos/src/main/java/org/jpos/iso/packager/Base1Packager.java
index 80eaf0a03f..fb104404ab 100644
--- a/jpos/src/main/java/org/jpos/iso/packager/Base1Packager.java
+++ b/jpos/src/main/java/org/jpos/iso/packager/Base1Packager.java
@@ -32,6 +32,7 @@
 public class Base1Packager extends ISOBasePackager 
 {
     private static final boolean pad = true;
+    /** BASE-1 field packager definitions for fields 0-128. */
     protected ISOFieldPackager base1Fld[] = 
     {
 /*000*/ new IFB_NUMERIC (  4, "MESSAGE TYPE INDICATOR", true),
@@ -169,8 +170,10 @@ public class Base1Packager extends ISOBasePackager
 /*128*/ new IFB_BINARY  (  8, "MAC 2")
     };
 
+    /** ISO-8583 sub-field packager for field 126. */
     protected static class F126Packager extends Base1SubFieldPackager
     {
+        /** Field packager definitions for sub-fields of field 126. */
         protected ISOFieldPackager fld126[] =
         {
             new Base1_BITMAP126(16, "Bit Map"),
@@ -186,6 +189,7 @@ protected static class F126Packager extends Base1SubFieldPackager
             new IFE_CHAR     (6,  "CVV2 Request Data"),
         };
 
+        /** Creates F126Packager with the default field configuration. */
         protected F126Packager ()
         {
             super();
@@ -193,8 +197,10 @@ protected F126Packager ()
         }
     }
 
+    /** ISO-8583 sub-field packager for field 127. */
     protected static class F127Packager extends ISOBasePackager 
     {
+        /** Field packager definitions for sub-fields of field 127. */
         protected ISOFieldPackager fld127[] = 
         {
             new IFE_CHAR    (1,   "FILE UPDATE COD"),
@@ -204,6 +210,7 @@ protected static class F127Packager extends ISOBasePackager
             new IFE_CHAR    (9,   "REGION CODING"),
             new IFB_NUMERIC (4,   "FILLER", true),
         };
+        /** Creates F127Packager with the default field configuration. */
         protected F127Packager () 
         {
             super();
@@ -211,6 +218,7 @@ protected F127Packager ()
         }
     }
 
+    /** Creates Base1Packager with the default BASE-1 field configuration. */
     public Base1Packager() 
     {
         super();
diff --git a/jpos/src/main/java/org/jpos/iso/packager/Base1SubFieldPackager.java b/jpos/src/main/java/org/jpos/iso/packager/Base1SubFieldPackager.java
index 9a2342332a..28d03beace 100644
--- a/jpos/src/main/java/org/jpos/iso/packager/Base1SubFieldPackager.java
+++ b/jpos/src/main/java/org/jpos/iso/packager/Base1SubFieldPackager.java
@@ -42,6 +42,8 @@
 @SuppressWarnings("unchecked")
 public class Base1SubFieldPackager extends ISOBasePackager
 {
+    /** Default constructor. */
+    public Base1SubFieldPackager() { super(); }
     // These methods are identical to ISOBasePackager
     // except that fld[1] has been replaced with fld[0]
     // and a secondard bitmap is not allowed
diff --git a/jpos/src/main/java/org/jpos/iso/packager/Base1_BITMAP126.java b/jpos/src/main/java/org/jpos/iso/packager/Base1_BITMAP126.java
index 618661c0b3..39a7258022 100644
--- a/jpos/src/main/java/org/jpos/iso/packager/Base1_BITMAP126.java
+++ b/jpos/src/main/java/org/jpos/iso/packager/Base1_BITMAP126.java
@@ -35,13 +35,15 @@
  */
 public class Base1_BITMAP126 extends ISOBitMapPackager 
 {
+    /** Default constructor. */
     public Base1_BITMAP126()
     {
         super();
     }
     /**
+    * Creates a Base1_BITMAP126 with the given length and description.
     * @param len - field len
-    * @param description symbolic descrption
+    * @param description symbolic description
     */
     public Base1_BITMAP126(int len, String description) 
     {
@@ -50,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 
     {
@@ -61,7 +63,7 @@ public byte[] pack (ISOComponent c) throws ISOException
     * @param b - binary image
     * @param offset - starting offset within the binary image
     * @return consumed bytes
-    * @exception ISOException
+    * @throws ISOException on error
     */
     public int unpack (ISOComponent c, byte[] b, int offset) throws ISOException
     {
diff --git a/jpos/src/main/java/org/jpos/iso/packager/GenericPackager.java b/jpos/src/main/java/org/jpos/iso/packager/GenericPackager.java
index 8352db6687..f98c30e23e 100644
--- a/jpos/src/main/java/org/jpos/iso/packager/GenericPackager.java
+++ b/jpos/src/main/java/org/jpos/iso/packager/GenericPackager.java
@@ -109,6 +109,7 @@ public GenericPackager() throws ISOException
      * Create a GenericPackager with the field descriptions
      * from an XML File
      * @param filename The XML field description file
+     * @throws ISOException on packing/unpacking error
      */
     public GenericPackager(String filename) throws ISOException
     {
@@ -120,6 +121,7 @@ public GenericPackager(String filename) throws ISOException
      * Create a GenericPackager with the field descriptions
      * from an XML InputStream
      * @param input The XML field description InputStream
+     * @throws ISOException on packing/unpacking error
      */
     public GenericPackager(InputStream input) throws ISOException
     {
@@ -188,6 +190,7 @@ protected ISOFieldPackager getBitMapfieldPackager()
      * The default parser is org.apache.crimson.parser.XMLReaderImpl
      *
    * @param filename The XML field description file + * @throws ISOException on packing/unpacking error */ public void readFile(String filename) throws ISOException { @@ -214,6 +217,7 @@ public void readFile(String filename) throws ISOException * The default parser is org.apache.crimson.parser.XMLReaderImpl * * @param input The XML field description InputStream + * @throws ISOException on packing/unpacking error */ public void readFile(InputStream input) throws ISOException { @@ -308,7 +312,7 @@ public static class GenericEntityResolver implements EntityResolver { /** * Allow the application to resolve external entities. - *

    + *

    * The strategy we follow is:

    * We first check whether the DTD points to a well defined URI, * and resolve to our internal DTDs.

    diff --git a/jpos/src/main/java/org/jpos/iso/packager/PostPackager.java b/jpos/src/main/java/org/jpos/iso/packager/PostPackager.java index 448dbf0404..47d028a700 100644 --- a/jpos/src/main/java/org/jpos/iso/packager/PostPackager.java +++ b/jpos/src/main/java/org/jpos/iso/packager/PostPackager.java @@ -60,8 +60,8 @@ /** * ISO 8583 v1987 Packager for Postilion * - * @author Victor A. Salaman - * @version Id: PostPackager.java,v 1.9 1999/09/17 12:08:02 salaman Exp + * @author Victor A. Salaman (salaman@teknos.com) + * @version $Id$ * @see ISOPackager * @see ISOBasePackager * @see ISOComponent diff --git a/jpos/src/main/java/org/jpos/iso/packager/TagMapper.java b/jpos/src/main/java/org/jpos/iso/packager/TagMapper.java index 1475d04376..f8832e22e1 100644 --- a/jpos/src/main/java/org/jpos/iso/packager/TagMapper.java +++ b/jpos/src/main/java/org/jpos/iso/packager/TagMapper.java @@ -19,7 +19,7 @@ package org.jpos.iso.packager; /** - * + * Maps between field IDs and tag names for tagged (TLV-style) ISO fields. */ public interface TagMapper { diff --git a/jpos/src/main/java/org/jpos/iso/packager/VISA1Packager.java b/jpos/src/main/java/org/jpos/iso/packager/VISA1Packager.java index 54f7248a1c..9fa9ace051 100644 --- a/jpos/src/main/java/org/jpos/iso/packager/VISA1Packager.java +++ b/jpos/src/main/java/org/jpos/iso/packager/VISA1Packager.java @@ -28,6 +28,7 @@ import java.io.InputStream; /** + * ISO-8583 packager for the VISA-1 message format. * @author apr@cs.com.uy * @version $Id$ * @see ISOPackager diff --git a/jpos/src/main/java/org/jpos/iso/packager/X92GenericPackager.java b/jpos/src/main/java/org/jpos/iso/packager/X92GenericPackager.java index 499a2bfdff..420229ce01 100644 --- a/jpos/src/main/java/org/jpos/iso/packager/X92GenericPackager.java +++ b/jpos/src/main/java/org/jpos/iso/packager/X92GenericPackager.java @@ -25,6 +25,7 @@ import java.io.InputStream; /** + * ISO-8583 packager for the X9.2 generic message format. * @see GenericPackager * @author Alejandro Revilla * @version $$evision: $ $Date$ diff --git a/jpos/src/main/java/org/jpos/iso/validator/VErrorParser.java b/jpos/src/main/java/org/jpos/iso/validator/VErrorParser.java index 73447c52ce..0012e0c6bc 100644 --- a/jpos/src/main/java/org/jpos/iso/validator/VErrorParser.java +++ b/jpos/src/main/java/org/jpos/iso/validator/VErrorParser.java @@ -71,8 +71,7 @@ public Logger getLogger() { /** * Parse error list, and get an dump * the xml string representing the list. - * 

    -     * Ex:
+     * 
    {@code
      * 
      *   
      *     
@@ -84,9 +83,9 @@ public Logger getLogger() {
      *       
      *     
      *   
-     *   
+     *   
      * 
-     * 
    
+     * }
    * @param p output stream * @param indent indent character */ diff --git a/jpos/src/main/java/org/jpos/jfr/ChannelEvent.java b/jpos/src/main/java/org/jpos/jfr/ChannelEvent.java index 9c1a850c30..a721cffe6a 100644 --- a/jpos/src/main/java/org/jpos/jfr/ChannelEvent.java +++ b/jpos/src/main/java/org/jpos/jfr/ChannelEvent.java @@ -20,63 +20,117 @@ import jdk.jfr.*; +/** + * JFR event base class for jPOS channel operations. + */ @Category("jPOS") @Name("jpos.Channel") @StackTrace public class ChannelEvent extends Event { + /** JFR event detail string. */ @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; } + /** Sets the event detail string. + * @param detail new detail string + */ public void setDetail(String detail) { this.detail = detail; } + /** Returns the event detail string. + * @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 { + /** + * Creates a ChannelEvent for a connection exception. + * @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 { + /** + * Creates a ChannelEvent for an accept exception. + * @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 { + /** + * Creates a ChannelEvent for a send exception. + * @param detail exception detail string + */ public SendException(String detail) { super(detail); } diff --git a/jpos/src/main/java/org/jpos/log/AuditLogEvent.java b/jpos/src/main/java/org/jpos/log/AuditLogEvent.java index 278886dae6..b6e19bf4ef 100644 --- a/jpos/src/main/java/org/jpos/log/AuditLogEvent.java +++ b/jpos/src/main/java/org/jpos/log/AuditLogEvent.java @@ -47,4 +47,11 @@ @JsonSubTypes.Type(value = Txn.class, name = "txn") }) -public sealed interface AuditLogEvent permits Connect, Deploy, DeployActivity, Disconnect, License, Listen, LogMessage, SessionEnd, SessionStart, Shutdown, Start, Stop, SysInfo, ThrowableAuditLogEvent, Txn, UnDeploy, Warning { } +/** + * Sealed marker interface for all jPOS structured audit log events. + */ +public sealed interface AuditLogEvent + permits Connect, Deploy, DeployActivity, Disconnect, License, Listen, LogMessage, + SessionEnd, SessionStart, Shutdown, Start, Stop, SysInfo, + ThrowableAuditLogEvent, Txn, UnDeploy, Warning { +} diff --git a/jpos/src/main/java/org/jpos/log/LogRenderer.java b/jpos/src/main/java/org/jpos/log/LogRenderer.java index 1f210243b5..043f8c6cc7 100644 --- a/jpos/src/main/java/org/jpos/log/LogRenderer.java +++ b/jpos/src/main/java/org/jpos/log/LogRenderer.java @@ -22,10 +22,29 @@ import java.io.PrintStream; public interface LogRenderer { + /** + * Renders the given object to the print stream with the specified indentation. + * @param obj the object to render + * @param ps the output stream + * @param indent indentation prefix + */ void render (T obj, PrintStream ps, String indent); + /** + * Returns the class this renderer handles. + * @return the handled class + */ Class clazz(); + /** + * Returns the log event type this renderer handles. + * @return the handled event type + */ Type type(); + /** + * Renders the given object to the print stream with no indentation. + * @param obj the object to render + * @param ps the output stream + */ default void render (T obj, PrintStream ps) { render (obj, ps, ""); } diff --git a/jpos/src/main/java/org/jpos/log/evt/Connect.java b/jpos/src/main/java/org/jpos/log/evt/Connect.java index c061c2e890..7d1f7fa273 100644 --- a/jpos/src/main/java/org/jpos/log/evt/Connect.java +++ b/jpos/src/main/java/org/jpos/log/evt/Connect.java @@ -21,7 +21,15 @@ import com.fasterxml.jackson.annotation.JsonInclude; import org.jpos.log.AuditLogEvent; +/** Audit log event recording a channel connection attempt. */ public record Connect(String host, int remotePort, int localPort, @JsonInclude(JsonInclude.Include.NON_NULL) String error) implements AuditLogEvent { + /** + * Creates a Connect event. + * @param host remote host + * @param remotePort remote port + * @param localPort local port + * @param error error message, or null on success + */ public Connect(String host, int remotePort, int localPort, String error) { this.host = host; this.remotePort = remotePort; @@ -29,6 +37,12 @@ public Connect(String host, int remotePort, int localPort, String error) { this.error = error; } + /** + * Creates a Connect event for a successful connection. + * @param host remote host + * @param remotePort remote port + * @param localPort local port + */ public Connect(String host, int remotePort, int localPort) { this(host, remotePort, localPort, null); } diff --git a/jpos/src/main/java/org/jpos/log/render/json/AuditLogEventJsonLogRenderer.java b/jpos/src/main/java/org/jpos/log/render/json/AuditLogEventJsonLogRenderer.java index 9b1a294550..aa50481986 100644 --- a/jpos/src/main/java/org/jpos/log/render/json/AuditLogEventJsonLogRenderer.java +++ b/jpos/src/main/java/org/jpos/log/render/json/AuditLogEventJsonLogRenderer.java @@ -26,9 +26,11 @@ import java.io.PrintStream; +/** JSON {@link LogRenderer} for {@link AuditLogEvent} instances; serialises audit events using Jackson. */ public final class AuditLogEventJsonLogRenderer implements LogRenderer { private final ObjectMapper mapper = new ObjectMapper(); + /** Creates the renderer and configures the Jackson mapper for ISO-8601 date output. */ public AuditLogEventJsonLogRenderer () { mapper.registerModule(new JavaTimeModule()); mapper.disable(com.fasterxml.jackson.databind.SerializationFeature.WRITE_DATES_AS_TIMESTAMPS); diff --git a/jpos/src/main/java/org/jpos/log/render/markdown/ByteArrayMarkdownLogRenderer.java b/jpos/src/main/java/org/jpos/log/render/markdown/ByteArrayMarkdownLogRenderer.java index 51cfccde11..0bae6554a2 100644 --- a/jpos/src/main/java/org/jpos/log/render/markdown/ByteArrayMarkdownLogRenderer.java +++ b/jpos/src/main/java/org/jpos/log/render/markdown/ByteArrayMarkdownLogRenderer.java @@ -23,7 +23,12 @@ import java.io.PrintStream; +/** + * Markdown {@link LogRenderer} for {@code byte[]} values; renders as a hex-dump code block. + */ public final class ByteArrayMarkdownLogRenderer implements LogRenderer { + /** Default constructor. */ + public ByteArrayMarkdownLogRenderer() { } @Override public void render(byte[] b, PrintStream ps, String indent) { if (b.length > 16) { diff --git a/jpos/src/main/java/org/jpos/log/render/markdown/ContextMarkdownRenderer.java b/jpos/src/main/java/org/jpos/log/render/markdown/ContextMarkdownRenderer.java index 7393e07fb0..e2f800940d 100644 --- a/jpos/src/main/java/org/jpos/log/render/markdown/ContextMarkdownRenderer.java +++ b/jpos/src/main/java/org/jpos/log/render/markdown/ContextMarkdownRenderer.java @@ -25,7 +25,10 @@ import java.io.PrintStream; import java.util.Map; +/** Markdown {@link LogRenderer} for {@link Context} instances. */ public final class ContextMarkdownRenderer implements LogRenderer { + /** Default constructor. */ + public ContextMarkdownRenderer() { } @Override public void render(Context ctx, PrintStream ps, String indent) { Map map = ctx.getMapClone(); diff --git a/jpos/src/main/java/org/jpos/metrics/Metrics.java b/jpos/src/main/java/org/jpos/metrics/Metrics.java index 90398a23f0..66c4e249b3 100644 --- a/jpos/src/main/java/org/jpos/metrics/Metrics.java +++ b/jpos/src/main/java/org/jpos/metrics/Metrics.java @@ -78,9 +78,8 @@ public static MeterRegistry getMeterRegistry() { *

    This variant blocks until Q2 is available or the timeout expires. * Useful during initialization when Q2 might not be fully started yet.

    * - * @param timeout maximum time to wait in milliseconds + * @param timeout maximum time to wait in milliseconds; throws {@code NameRegistrar.NotFoundException} if not found * @return MeterRegistry from Q2 - * @throws org.jpos.util.NameRegistrar.NotFoundException if Q2 not found within timeout */ public static MeterRegistry getMeterRegistry(long timeout) { return Q2.getQ2(timeout).getMeterRegistry(); @@ -104,9 +103,8 @@ public static MeterRegistry getMeterRegistry(String q2Name) { * Get the MeterRegistry from a named Q2 instance, waiting up to timeout milliseconds. * * @param q2Name Q2 instance name - * @param timeout maximum time to wait in milliseconds + * @param timeout maximum time to wait in milliseconds; throws {@code NameRegistrar.NotFoundException} if not found * @return MeterRegistry from named Q2 instance - * @throws org.jpos.util.NameRegistrar.NotFoundException if Q2 not found within timeout */ public static MeterRegistry getMeterRegistry(String q2Name, long timeout) { return org.jpos.util.NameRegistrar.get(q2Name, timeout).getMeterRegistry(); diff --git a/jpos/src/main/java/org/jpos/metrics/iso/ISOMsgMetrics.java b/jpos/src/main/java/org/jpos/metrics/iso/ISOMsgMetrics.java index bf663697a3..6da906caa8 100644 --- a/jpos/src/main/java/org/jpos/metrics/iso/ISOMsgMetrics.java +++ b/jpos/src/main/java/org/jpos/metrics/iso/ISOMsgMetrics.java @@ -18,8 +18,17 @@ public interface ISOMsgMetrics { String ENV_CHANNEL_FIELDS = "metrics.channel.fields"; String DEFAULT_CHANNEL_FIELDS = "mti"; + /** Implemented by components that expose an {@link ISOMsgMetrics} instance. */ interface Source{ + /** + * Sets the ISOMsgMetrics instance. + * @param metrics the ISOMsgMetrics to attach + */ void setISOMsgMetrics(ISOMsgMetrics metrics); + /** + * Returns the attached ISOMsgMetrics. + * @return the ISOMsgMetrics, or null + */ ISOMsgMetrics getISOMsgMetrics(); } @@ -34,9 +43,9 @@ interface Source{ default Tags getTags() { return addTags(Tags.empty()); } /** - * Records an {@link ISOMsg} in the meter registry.
    + * Records an {@link ISOMsg} in the meter registry.
    * The metric name and tags will be taken strictly from this object's - * configuration.
    + * configuration.
    * If this object hasn't been successfully registered, it throws an * {@link IllegalStateException}. * @@ -46,7 +55,7 @@ interface Source{ void recordMessage(ISOMsg m) throws IllegalStateException; /** - * Records an {@link ISOMsg} in the meter registry.
    + * Records an {@link ISOMsg} in the meter registry.
    * Similar to {@link #recordMessage(ISOMsg)} but using the metric name, description and maybe some * tags taken from the {@link MeterInfo} argument. *

    @@ -64,7 +73,7 @@ interface Source{ /** - * Register this object to work with a given {@link MeterRegistry}.
    + * Register this object to work with a given {@link MeterRegistry}.
    * * This method may serve more than one purpose in the object's lifecycle: *

      @@ -88,7 +97,7 @@ interface Source{ boolean register(MeterRegistry registry); /** - * It calls {@link #removeMeters()} and clears its internal reference to its {@link MeterRegistry}.
      + * It calls {@link #removeMeters()} and clears its internal reference to its {@link MeterRegistry}.
      * * It will also "unfreeze" the object, making it available for reconfiguration. */ @@ -101,7 +110,7 @@ interface Source{ /** * A unique meter signature, concatenating the meter name, vertical pipe, comma-separated sorted list of all tag keys - * that this object produces.
      + * that this object produces.
      * Default implementation uses the values from {@link #getMetricName()} and {@link #getTags()}. * A concrete implementation must make sure of gathering all the appropriate tag keys from internal config state * which may include more than what's returned by {@link #getTags()}. diff --git a/jpos/src/main/java/org/jpos/q2/CLI.java b/jpos/src/main/java/org/jpos/q2/CLI.java index 73786d6e2a..3e1fcf2e1f 100644 --- a/jpos/src/main/java/org/jpos/q2/CLI.java +++ b/jpos/src/main/java/org/jpos/q2/CLI.java @@ -29,6 +29,7 @@ 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__"; @@ -36,6 +37,7 @@ public class CLI implements Runnable { 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,27 @@ public class CLI implements Runnable { private String prompt = DEFAULT_PROMPT; private History mainHistory; + /** + * Creates a simple CLI with a single command and no streams. + * @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); } + /** + * Creates a full CLI with explicit I/O streams. + * @param q2 the Q2 instance + * @param in input stream + * @param rawout output stream + * @param line initial command (may be null for interactive mode) + * @param keepRunning true to keep running after commands + * @param interactive true for interactive (line-edit) 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 +82,29 @@ public CLI(Q2 q2, InputStream in, OutputStream rawout, String line, boolean keep initCmdInterface(getCompletionPrefixes(), mainHistory); } + /** + * Returns true if this CLI is still running. + * @return true if 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() { } + /** + * Returns command prefixes registered for tab-completion. + * @return array of command prefixes + */ 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,6 +125,9 @@ 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); @@ -102,6 +135,7 @@ public void start() throws Exception { t.start(); } + /** Stops the CLI session. */ public void stop() { markStopped(); try { @@ -173,30 +207,62 @@ public void run() { handleExit(); } + /** + * Returns the Q2 instance this CLI is attached to. + * @return the Q2 instance + */ public Q2 getQ2() { return q2; } + /** + * Returns true if this CLI session is interactive. + * @return true if interactive + */ public boolean isInteractive() { return interactive; } + /** + * Returns the JLine3 LineReader for this session. + * @return the LineReader + */ public LineReader getReader() { return reader; } + /** + * Executes a CLI command with the given I/O streams. + * @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(); } + /** + * Executes a CLI command and captures its output as a string. + * @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(); } + /** + * Builds a JLine3 Terminal for this session. + * @param in input stream + * @param out output stream + * @return the Terminal + * @throws IOException on I/O failure + */ protected Terminal buildTerminal (InputStream in, OutputStream out) throws IOException { TerminalBuilder builder = TerminalBuilder.builder() .streams(in,out) diff --git a/jpos/src/main/java/org/jpos/q2/CLICommand.java b/jpos/src/main/java/org/jpos/q2/CLICommand.java index b5345ef0cc..42908084fd 100644 --- a/jpos/src/main/java/org/jpos/q2/CLICommand.java +++ b/jpos/src/main/java/org/jpos/q2/CLICommand.java @@ -18,6 +18,13 @@ package org.jpos.q2; +/** Command interface for Q2 CLI commands. */ public interface CLICommand { + /** + * Executes the CLI command. + * @param cli the CLI context + * @param strings command arguments + * @throws Exception on error + */ void exec(CLIContext cli, String[] strings) throws Exception; } diff --git a/jpos/src/main/java/org/jpos/q2/CLICommandInterface.java b/jpos/src/main/java/org/jpos/q2/CLICommandInterface.java index 2664964aa3..77721b9b77 100644 --- a/jpos/src/main/java/org/jpos/q2/CLICommandInterface.java +++ b/jpos/src/main/java/org/jpos/q2/CLICommandInterface.java @@ -27,22 +27,40 @@ 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 prefixes = new ArrayList(); + /** + * Returns the list of registered command prefixes. + * @return command prefix list + */ public List getPrefixes() { return prefixes; } + /** + * Creates a CLICommandInterface for the given context. + * @param ctx the CLI context + */ public CLICommandInterface(CLIContext ctx) { this.ctx = ctx; } + /** + * Registers a command prefix. + * @param prefix the prefix to add + */ public void addPrefix(String prefix) { prefixes.add(prefix); } + /** + * Executes the given command line. + * @param line the full command line + * @throws IOException on I/O failure + */ public void execCommand(String line) throws IOException { String args[] = parseCommand(line); if (args.length == 0) { @@ -91,6 +109,12 @@ private Object getCommand(String className) throws ClassNotFoundException, Insta return cl.loadClass(className).newInstance(); } + /** + * Parses a command line into tokens. + * @param line the full command line + * @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]; diff --git a/jpos/src/main/java/org/jpos/q2/CLIContext.java b/jpos/src/main/java/org/jpos/q2/CLIContext.java index 5aa6b21e00..04437dcf8a 100644 --- a/jpos/src/main/java/org/jpos/q2/CLIContext.java +++ b/jpos/src/main/java/org/jpos/q2/CLIContext.java @@ -25,6 +25,7 @@ import java.util.LinkedHashMap; import java.util.Map; +/** Holds the I/O streams, LineReader, and metadata for a CLI session. */ public class CLIContext { private boolean stopped = false; private OutputStream out; @@ -47,10 +48,18 @@ private CLIContext(CLI cli, OutputStream out, OutputStream err, InputStream in, this.userData = userData; } + /** + * Returns the name of the active CLI sub-system. + * @return the active sub-system name, or null + */ public String getActiveSubSystem() { return activeSubSystem; } + /** + * Sets the active CLI sub-system by name. + * @param subSystem the name of the new active sub-system + */ public void setActiveSubSystem(String subSystem) { String activeSubSystem = getActiveSubSystem(); if (subSystem == null && activeSubSystem != null) { @@ -59,46 +68,87 @@ public void setActiveSubSystem(String subSystem) { this.activeSubSystem = subSystem; } + /** + * Returns true if this CLI session has been stopped. + * @return true if stopped + */ public boolean isStopped() { return stopped; } + /** + * Marks this CLI session as stopped. + * @param stopped true to stop + */ public void setStopped(boolean stopped) { this.stopped = stopped; } + /** + * Returns the JLine3 LineReader for interactive input. + * @return the LineReader + */ public LineReader getReader() { return reader; } + /** + * Sets the JLine3 LineReader. + * @param reader the LineReader + */ public void setReader(LineReader reader) { this.reader = reader; } + /** + * Returns the standard output stream for this session. + * @return the output stream + */ public OutputStream getOutputStream() { return out; } + /** + * Returns the error stream for this session. + * @return the error stream + */ public OutputStream getErrorStream() { return err; } + /** + * Returns the input stream for this session. + * @return the input stream + */ public InputStream getInputStream() { return in; } + /** + * Returns the mutable user-data map for sharing state across CLI commands. + * @return user data map + */ public Map getUserData() { return userData; } + /** + * Returns true if this session is interactive (has a LineReader). + * @return true if interactive + */ public boolean isInteractive() { return cli.isInteractive(); } + /** + * Returns the CLI instance managing this context. + * @return the CLI + */ public CLI getCLI() { return cli; } + /** Prints all user-data entries to the output stream. */ public void printUserData() { getUserData().forEach((k,v) -> { println("Key: " + k.toString()); @@ -106,18 +156,31 @@ public void printUserData() { }); } + /** + * Prints a throwable stack trace to the error stream. + * @param t the throwable to print + */ public void printThrowable(Throwable t) { ByteArrayOutputStream baos = new ByteArrayOutputStream(); t.printStackTrace(new PrintStream(baos)); println (baos.toString()); } + /** + * Dumps a Loggeable to the output stream. + * @param l the Loggeable to dump + * @param indent indentation prefix + */ public void printLoggeable(Loggeable l, String indent) { ByteArrayOutputStream baos = new ByteArrayOutputStream(); l.dump (new PrintStream(baos), indent); println (baos.toString()); } + /** + * Prints a string to the output stream (no trailing newline). + * @param s the string to print + */ public void print(String s) { if (isInteractive()) { PrintWriter writer = getReader().getTerminal().writer(); @@ -134,22 +197,41 @@ public void print(String s) { } } + /** + * Prints a string to the output stream followed by a newline. + * @param s the string to print + */ public void println(String s) { print (s + System.getProperty("line.separator")); } + /** + * Prompts the user for confirmation. + * @param prompt the confirmation prompt + * @return true if user confirmed + */ public boolean confirm(String prompt) { return "yes".equalsIgnoreCase(getReader().readLine(prompt)); } + /** + * Reads a string from the user without echoing (e.g. for passwords). + * @param prompt the prompt to display + * @return the input string + */ public String readSecurely(String prompt) { return getReader().readLine(prompt, '*'); } + /** + * Returns a new Builder for constructing a CLIContext. + * @return a new Builder + */ public static Builder builder() { return new Builder(); } + /** Builder for constructing {@link CLIContext} instances. */ public static class Builder { OutputStream out; OutputStream err; @@ -158,31 +240,60 @@ public static class Builder { CLI cli; private Builder () { } + /** + * Sets the standard output stream. + * @param out the standard output stream + * @return this + */ public Builder out (OutputStream out) { this.out = out; return this; } + /** + * Sets the error stream. + * @param err the error stream + * @return this + */ public Builder err (OutputStream err) { this.err = err; return this; } + /** + * Sets the input stream. + * @param in the input stream + * @return this + */ public Builder in (InputStream in) { this.in = in; return this; } + /** + * Sets the JLine3 LineReader. + * @param reader the LineReader + * @return this + */ public Builder reader (LineReader reader) { this.reader = reader; return this; } + /** + * Sets the CLI instance. + * @param cli the CLI + * @return this + */ public Builder cli (CLI cli) { this.cli = cli; return this; } + /** + * Builds and returns the CLIContext. + * @return the constructed CLIContext + */ public CLIContext build() { if (reader != null) { if (out == null) diff --git a/jpos/src/main/java/org/jpos/q2/CLIPrefixedClassNameCompleter.java b/jpos/src/main/java/org/jpos/q2/CLIPrefixedClassNameCompleter.java index 71c3d4ab99..1c657adb5d 100644 --- a/jpos/src/main/java/org/jpos/q2/CLIPrefixedClassNameCompleter.java +++ b/jpos/src/main/java/org/jpos/q2/CLIPrefixedClassNameCompleter.java @@ -33,9 +33,16 @@ import java.util.*; import java.util.jar.JarEntry; +/** JLine3 {@link Completer} that provides tab-completion for class names with given prefixes. */ public class CLIPrefixedClassNameCompleter implements Completer { + /** Pre-computed candidate list for tab completion. */ protected final Collection candidates = new ArrayList<>(); + /** + * Creates a completer that includes class names with the given prefixes. + * @param prefixes the class name prefixes to include as candidates + * @throws IOException if class scanning fails + */ public CLIPrefixedClassNameCompleter(Collection prefixes) throws IOException { for (String s : getClassNames(prefixes)) { candidates.add(new Candidate(AttributedString.stripAnsi(s), s, null, null, null, null, true)); diff --git a/jpos/src/main/java/org/jpos/q2/CLISubSystem.java b/jpos/src/main/java/org/jpos/q2/CLISubSystem.java index 0d6ca5e990..1758d1b851 100644 --- a/jpos/src/main/java/org/jpos/q2/CLISubSystem.java +++ b/jpos/src/main/java/org/jpos/q2/CLISubSystem.java @@ -19,7 +19,20 @@ package org.jpos.q2; +/** Extension point for adding sub-systems to the Q2 CLI. */ public interface CLISubSystem { + /** + * Returns the prompt string for this sub-system. + * @param ctx the CLI context + * @param args current command arguments + * @return the prompt string + */ String getPrompt(CLIContext ctx, String[] args); + /** + * Returns the command prefixes registered by this sub-system. + * @param ctx the CLI context + * @param args current command arguments + * @return command prefixes + */ String[] getCompletionPrefixes(CLIContext ctx, String args[]); } diff --git a/jpos/src/main/java/org/jpos/q2/Command.java b/jpos/src/main/java/org/jpos/q2/Command.java index fb190f6bfb..7c89897f4c 100644 --- a/jpos/src/main/java/org/jpos/q2/Command.java +++ b/jpos/src/main/java/org/jpos/q2/Command.java @@ -21,6 +21,15 @@ import java.io.InputStream; import java.io.OutputStream; +/** Q2 CLI command interface for external command execution. */ public interface Command { + /** + * Executes this command. + * @param is input stream + * @param os output stream + * @param err error stream + * @param strings command arguments + * @throws Exception on execution failure + */ void exec(InputStream is, OutputStream os, OutputStream err, String[] strings) throws Exception; } diff --git a/jpos/src/main/java/org/jpos/q2/ConfigDecorationProvider.java b/jpos/src/main/java/org/jpos/q2/ConfigDecorationProvider.java index 5a4c5bbfbf..3cf3f78eec 100644 --- a/jpos/src/main/java/org/jpos/q2/ConfigDecorationProvider.java +++ b/jpos/src/main/java/org/jpos/q2/ConfigDecorationProvider.java @@ -22,7 +22,19 @@ public interface ConfigDecorationProvider { + /** + * Initializes this provider with the given Q2 deploy directory. + * @param deployDir the Q2 deploy directory + * @throws Exception on initialization failure + */ void initialize(File deployDir) throws Exception; + /** Releases resources used by this provider. */ void uninitialize(); + /** + * Processes and decorates a deploy descriptor file. + * @param f deploy descriptor file + * @return the decorated content + * @throws Exception on processing failure + */ String decorateFile(File f) throws Exception; } diff --git a/jpos/src/main/java/org/jpos/q2/ConfigurationFactory.java b/jpos/src/main/java/org/jpos/q2/ConfigurationFactory.java index a9d08bbb25..6947aab2c6 100644 --- a/jpos/src/main/java/org/jpos/q2/ConfigurationFactory.java +++ b/jpos/src/main/java/org/jpos/q2/ConfigurationFactory.java @@ -22,7 +22,14 @@ import org.jpos.core.Configuration; import org.jpos.core.ConfigurationException; +/** Factory for creating {@link org.jpos.core.Configuration} from XML elements. */ public interface ConfigurationFactory { + /** + * Builds a Configuration from the given XML element. + * @param e XML configuration element + * @return the resulting Configuration + * @throws ConfigurationException on invalid configuration + */ Configuration getConfiguration(Element e) throws ConfigurationException; } diff --git a/jpos/src/main/java/org/jpos/q2/Q2.java b/jpos/src/main/java/org/jpos/q2/Q2.java index 27de82f94d..2302da3e2c 100644 --- a/jpos/src/main/java/org/jpos/q2/Q2.java +++ b/jpos/src/main/java/org/jpos/q2/Q2.java @@ -98,6 +98,7 @@ /** + * The jPOS Q2 container — bootstraps the deploy directory, manages QBean lifecycle, and provides the runtime environment. * @author Alireza Taherkordi * @author Alejandro P. Revilla * @author Alwyn Schoeman diff --git a/jpos/src/main/java/org/jpos/q2/QBean.java b/jpos/src/main/java/org/jpos/q2/QBean.java index a86a153f59..d4807433de 100644 --- a/jpos/src/main/java/org/jpos/q2/QBean.java +++ b/jpos/src/main/java/org/jpos/q2/QBean.java @@ -66,11 +66,13 @@ public interface QBean { void destroy () throws Exception; /** + * Returns the current state of this QBean. * @return state (STARTING, STARTED, FAILED, DESTROYED ...) */ int getState (); /** + * Returns the current state as a human-readable string. * @return state (STARTING, STARTED, FAILED, DESTROYED ...) */ default String getStateAsString () { diff --git a/jpos/src/main/java/org/jpos/q2/QBeanSupport.java b/jpos/src/main/java/org/jpos/q2/QBeanSupport.java index 5ddde74185..c59b5af74c 100644 --- a/jpos/src/main/java/org/jpos/q2/QBeanSupport.java +++ b/jpos/src/main/java/org/jpos/q2/QBeanSupport.java @@ -36,6 +36,7 @@ import java.util.concurrent.ScheduledThreadPoolExecutor; /** + * Convenience base class for QBean implementations; provides configuration, logging, and lifecycle support. * @author Alireza Taherkordi * @author Alejandro P. Revilla */ @@ -249,9 +250,21 @@ public String getDump () { } return toString(); } + /** Called during QBean initialization. Override to add startup logic. + * @throws Exception on error + */ protected void initService() throws Exception {} + /** Called when the QBean is started. Override to begin processing. + * @throws Exception on error + */ protected void startService() throws Exception {} + /** Called when the QBean is stopped. Override to cease processing. + * @throws Exception on error + */ protected void stopService() throws Exception {} + /** Called during QBean destruction. Override to release resources. + * @throws Exception on error + */ protected void destroyService() throws Exception {} protected synchronized ScheduledThreadPoolExecutor getScheduledThreadPoolExecutor() { diff --git a/jpos/src/main/java/org/jpos/q2/QBeanSupportMBean.java b/jpos/src/main/java/org/jpos/q2/QBeanSupportMBean.java index 54ee6ff7bd..5e57795c87 100644 --- a/jpos/src/main/java/org/jpos/q2/QBeanSupportMBean.java +++ b/jpos/src/main/java/org/jpos/q2/QBeanSupportMBean.java @@ -23,6 +23,7 @@ import java.net.URL; /** + * JMX management interface for {@link QBeanSupport}-based QBeans. * @author Alireza Taherkordi * @author Alejandro P. Revilla * @version $Revision$ $Date$ diff --git a/jpos/src/main/java/org/jpos/q2/QFactory.java b/jpos/src/main/java/org/jpos/q2/QFactory.java index ace8a4a421..eda2746ca9 100644 --- a/jpos/src/main/java/org/jpos/q2/QFactory.java +++ b/jpos/src/main/java/org/jpos/q2/QFactory.java @@ -43,6 +43,7 @@ import java.util.concurrent.Executors; /** + * Factory responsible for creating, configuring, and deploying QBean instances from XML deploy descriptors. * @author Alireza Taherkordi * @author Alejandro P. Revilla * @version $Revision$ $Date$ @@ -259,13 +260,13 @@ else if ("boolean".equals (type)) } - /** Creats a collection from a definition element with the format. - * 
      -     *    <{attr|item} type="...">
-     *        ...
+    /** Creates a collection from a definition element with the format.
+     * 
      {@code
+     *    
+     *        ...
      *        ...
      *    
-     * 
      
+     * }
      * @param type class type * @param e the Element * @throws ConfigurationException diff --git a/jpos/src/main/java/org/jpos/q2/cli/CALCLUHN.java b/jpos/src/main/java/org/jpos/q2/cli/CALCLUHN.java index e895f5dfc3..5c17cf48c3 100644 --- a/jpos/src/main/java/org/jpos/q2/cli/CALCLUHN.java +++ b/jpos/src/main/java/org/jpos/q2/cli/CALCLUHN.java @@ -22,8 +22,17 @@ import org.jpos.q2.CLICommand; import org.jpos.q2.CLIContext; +/** + * 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])); diff --git a/jpos/src/main/java/org/jpos/q2/cli/CLR.java b/jpos/src/main/java/org/jpos/q2/cli/CLR.java index 8d67488e58..845d2fab4c 100644 --- a/jpos/src/main/java/org/jpos/q2/cli/CLR.java +++ b/jpos/src/main/java/org/jpos/q2/cli/CLR.java @@ -22,8 +22,12 @@ import org.jpos.q2.CLICommand; import org.jpos.q2.CLIContext; +/** CLI command that clears the terminal screen. */ +@SuppressWarnings("unused") public class CLR implements CLICommand { + /** Default constructor. */ + public CLR() { super(); } public void exec(CLIContext ctx, String[] args) throws Exception { ctx.getReader().getTerminal().puts(InfoCmp.Capability.clear_screen); } diff --git a/jpos/src/main/java/org/jpos/q2/cli/ssm/SsmActionBase.java b/jpos/src/main/java/org/jpos/q2/cli/ssm/SsmActionBase.java index 68b662fa94..b1ab2ebdc7 100644 --- a/jpos/src/main/java/org/jpos/q2/cli/ssm/SsmActionBase.java +++ b/jpos/src/main/java/org/jpos/q2/cli/ssm/SsmActionBase.java @@ -30,9 +30,24 @@ * @author Alwyn Schoeman - alwyn.schoeman@gmail.com */ public abstract class SsmActionBase implements CLICommand { - + /** Default constructor. */ + public SsmActionBase() { } + /** + * Returns true if the command arguments are valid. + * @param cli CLI context + * @param strings command arguments + * @return true if usage is correct + */ protected abstract boolean checkUsage(CLIContext cli, String[] strings); + /** + * Executes the SSM command. + * @param cli CLI context + * @param sm the JCE security module + * @param keyLength the key length in bits + * @param strings command arguments + * @throws org.jpos.security.SMException on security module error + */ protected abstract void doCommand( CLIContext cli, JCESecurityModule sm, diff --git a/jpos/src/main/java/org/jpos/q2/cli/ssm/actions/CK.java b/jpos/src/main/java/org/jpos/q2/cli/ssm/actions/CK.java index 68e3a4b17b..8ad803fc83 100644 --- a/jpos/src/main/java/org/jpos/q2/cli/ssm/actions/CK.java +++ b/jpos/src/main/java/org/jpos/q2/cli/ssm/actions/CK.java @@ -29,7 +29,11 @@ * * @author Alwyn Schoeman - alwyn.schoeman@gmail.com */ +/** SSM CLI action for key check operations. */ +@SuppressWarnings("unused") public class CK extends SsmActionBase { + /** Default constructor. */ + public CK() { super(); } @Override protected boolean checkUsage(CLIContext cli, String[] strings) { diff --git a/jpos/src/main/java/org/jpos/q2/install/Install.java b/jpos/src/main/java/org/jpos/q2/install/Install.java index 16476b04c9..67a6b1f77f 100644 --- a/jpos/src/main/java/org/jpos/q2/install/Install.java +++ b/jpos/src/main/java/org/jpos/q2/install/Install.java @@ -27,6 +27,7 @@ import java.util.List; /** + * Utility that installs jPOS modules by resolving and deploying their artifacts into the Q2 deploy directory. * @author vsalaman */ public class Install diff --git a/jpos/src/main/java/org/jpos/q2/install/ModuleUtils.java b/jpos/src/main/java/org/jpos/q2/install/ModuleUtils.java index acb2cbc438..779bb5260b 100644 --- a/jpos/src/main/java/org/jpos/q2/install/ModuleUtils.java +++ b/jpos/src/main/java/org/jpos/q2/install/ModuleUtils.java @@ -32,6 +32,7 @@ import java.util.stream.Collectors; /** + * Helper utilities for jPOS module installation and descriptor processing. * @author vsalaman */ public class ModuleUtils diff --git a/jpos/src/main/java/org/jpos/q2/iso/ChannelAdaptor.java b/jpos/src/main/java/org/jpos/q2/iso/ChannelAdaptor.java index 0df24389bc..0457e8ed8d 100644 --- a/jpos/src/main/java/org/jpos/q2/iso/ChannelAdaptor.java +++ b/jpos/src/main/java/org/jpos/q2/iso/ChannelAdaptor.java @@ -55,6 +55,7 @@ import java.util.concurrent.TimeUnit; /** + * Q2 QBean that wraps an {@link org.jpos.iso.ISOChannel} and exposes it as a managed, reconnecting service. * @author Alejandro Revilla */ @SuppressWarnings("unchecked") @@ -62,6 +63,7 @@ public class ChannelAdaptor extends QBeanSupport implements ChannelAdaptorMBean, Channel, Loggeable, ExceptionHandlerConfigAware { + /** The Space used for message passing between sender and receiver. */ protected Space sp; private ISOChannel channel; String in, out, ready, reconnect; @@ -84,6 +86,7 @@ public class ChannelAdaptor @Config("soft-stop") private long softStop; + /** Default constructor. */ public ChannelAdaptor () { super (); resetCounters(); @@ -202,6 +205,13 @@ public String getOutQueue () { } /** Parses a {@code } element, returning an {@link ISOChannel} */ + /** + * Creates and configures a new {@link ISOChannel} from the given XML element. + * @param e the channel XML configuration element + * @param f the QFactory for creating objects + * @return configured ISOChannel + * @throws ConfigurationException on configuration error + */ public ISOChannel newChannel (Element e, QFactory f) throws ConfigurationException { String channelName = QFactory.getAttributeValue (e, "class"); String packagerName = QFactory.getAttributeValue (e, "packager"); @@ -279,6 +289,14 @@ public ISOChannel newChannel (Element e, QFactory f) throws ConfigurationExcepti return channel; } + /** + * Adds ISO filters from the XML configuration to the channel. + * @param channel the channel to configure + * Adds ISOFilters from the XML configuration to the given channel. + * @param e the XML configuration element + * @param fact the QFactory for creating filter instances + * @throws ConfigurationException if a filter cannot be configured + */ protected void addFilters (FilteredChannel channel, Element e, QFactory fact) throws ConfigurationException { @@ -300,6 +318,11 @@ else if ("both".equalsIgnoreCase(direction)) { } + /** + * Initialises the ISOChannel from the persisted configuration. + * @return configured ISOChannel + * @throws ConfigurationException on configuration error + */ protected ISOChannel initChannel () throws ConfigurationException { Element persist = getPersist (); Element e = persist.getChild ("channel"); @@ -321,6 +344,10 @@ protected ISOChannel initChannel () throws ConfigurationException { return c; } + /** + * Initialises the Space and queue names from the persisted configuration. + * @throws ConfigurationException on configuration error + */ protected void initSpaceAndQueues () throws ConfigurationException { Element persist = getPersist (); sp = grabSpace (persist.getChild ("space")); @@ -341,8 +368,10 @@ protected void initSpaceAndQueues () throws ConfigurationException { waitForWorkersOnStop = "yes".equalsIgnoreCase(Environment.get(persist.getChildTextTrim ("wait-for-workers-on-stop"))); } + /** Runnable that continuously reads from the outgoing space and sends messages via the channel. */ @SuppressWarnings("unchecked") public class Sender implements Runnable { + /** Default constructor. */ public Sender () { super (); } @@ -391,8 +420,10 @@ else if (keepAlive && channel.isConnected() && channel instanceof BaseChannel) { } } } + /** Runnable that continuously receives messages from the channel and posts them to the incoming space. */ @SuppressWarnings("unchecked") public class Receiver implements Runnable { + /** Default constructor. */ public Receiver () { super (); } @@ -462,6 +493,9 @@ public void run () { disconnect(); } } + /** + * Checks the channel connection and reconnects if it is down. + */ protected void checkConnection () { while (running() && sp.rdp (reconnect) != null) { ISOUtil.sleep(1000); @@ -481,6 +515,9 @@ protected void checkConnection () { if (running() && sp.rdp (ready) == null) sp.out (ready, new Date()); } + /** Closes the channel connection, flushing pending output. + * Synchronized on a dedicated lock to avoid deadlock between Sender/Receiver. + */ protected void disconnect () { // do not synchronize on this as both Sender and Receiver can deadlock against a thread calling stop() synchronized (disconnectLock) { @@ -555,18 +592,37 @@ public int getConnectsCounter () { public long getLastTxnTimestampInMillis() { return lastTxn; } + /** + * Returns the time elapsed since the last transaction, or -1 if no transaction has occurred. + * @return idle time in milliseconds + */ public long getIdleTimeInMillis() { return lastTxn > 0L ? System.currentTimeMillis() - lastTxn : -1L; } + /** + * Returns the socket factory class name from configuration. + * @return socket factory class name + */ public String getSocketFactory() { return getProperty(getProperties ("channel"), "socketFactory"); } public void dump (PrintStream p, String indent) { p.println (indent + getCountersAsString()); } + /** + * Returns a Space for the URI in the given XML element's text content. + * @param e XML element whose text content is the space URI + * @return the Space instance + */ protected Space grabSpace (Element e) { return SpaceFactory.getSpace (e != null ? e.getText() : ""); } + /** + * Appends a name=value stat entry to a StringBuilder. + * @param sb the builder to append to + * @param name the stat name + * @param value the stat value + */ protected void append (StringBuilder sb, String name, int value) { sb.append (name); sb.append (value); diff --git a/jpos/src/main/java/org/jpos/q2/iso/ChannelAdaptorMBean.java b/jpos/src/main/java/org/jpos/q2/iso/ChannelAdaptorMBean.java index cbc9dcbf0b..2a11963a24 100644 --- a/jpos/src/main/java/org/jpos/q2/iso/ChannelAdaptorMBean.java +++ b/jpos/src/main/java/org/jpos/q2/iso/ChannelAdaptorMBean.java @@ -27,24 +27,101 @@ */ @SuppressWarnings("unused") public interface ChannelAdaptorMBean extends QBeanSupportMBean { + /** + * Sets the reconnect delay. + * @param delay reconnect delay in milliseconds + */ void setReconnectDelay(long delay); + /** + * Returns the reconnect delay. + * @return reconnect delay in milliseconds + */ long getReconnectDelay(); + /** + * Sets the incoming space queue name. + * @param in name of the incoming space queue + */ void setInQueue(java.lang.String in); + /** + * Returns the incoming space queue name. + * @return name of the incoming space queue + */ String getInQueue(); + /** + * Sets the outgoing space queue name. + * @param out name of the outgoing space queue + */ void setOutQueue(java.lang.String out); + /** + * Returns the outgoing space queue name. + * @return name of the outgoing space queue + */ String getOutQueue(); + /** + * Sets the remote host name or address. + * @param host remote host + */ void setHost(java.lang.String host); + /** + * Returns the remote host name or address. + * @return remote host + */ String getHost(); + /** + * Sets the remote port number. + * @param port remote port + */ void setPort(int port); + /** + * Returns the remote port number. + * @return remote port + */ int getPort(); + /** + * Sets the socket factory class name. + * @param sFac socket factory class name + */ void setSocketFactory(java.lang.String sFac); + /** + * Returns the socket factory class name. + * @return socket factory class name + */ String getSocketFactory(); + /** + * Returns true if the channel is currently connected. + * @return true if connected + */ boolean isConnected(); + /** Resets all message counters to zero. */ void resetCounters(); + /** + * Returns all counters as a human-readable string. + * @return counters string + */ String getCountersAsString(); + /** + * Returns the transmitted message count. + * @return TX count + */ int getTXCounter(); + /** + * Returns the received message count. + * @return RX count + */ int getRXCounter(); + /** + * Returns the number of successful connections since last reset. + * @return connect count + */ int getConnectsCounter(); + /** + * Returns the timestamp of the last transaction. + * @return timestamp in milliseconds + */ long getLastTxnTimestampInMillis(); + /** + * Returns the idle time since the last transaction. + * @return idle time in milliseconds + */ long getIdleTimeInMillis(); } diff --git a/jpos/src/main/java/org/jpos/q2/iso/MUXPool.java b/jpos/src/main/java/org/jpos/q2/iso/MUXPool.java index 00831ad5f3..424c00de53 100644 --- a/jpos/src/main/java/org/jpos/q2/iso/MUXPool.java +++ b/jpos/src/main/java/org/jpos/q2/iso/MUXPool.java @@ -33,6 +33,7 @@ import java.util.concurrent.atomic.AtomicInteger; /** + * Q2 QBean that aggregates multiple MUX instances into a pool, distributing requests across available multiplexers. * @author apr */ public class MUXPool extends QBeanSupport implements MUX, MUXPoolMBean { diff --git a/jpos/src/main/java/org/jpos/q2/iso/MultiSessionChannelAdaptor.java b/jpos/src/main/java/org/jpos/q2/iso/MultiSessionChannelAdaptor.java index a356ca2b14..57222d029a 100644 --- a/jpos/src/main/java/org/jpos/q2/iso/MultiSessionChannelAdaptor.java +++ b/jpos/src/main/java/org/jpos/q2/iso/MultiSessionChannelAdaptor.java @@ -31,6 +31,7 @@ import java.util.Date; /** + * Q2 QBean that manages multiple concurrent sessions over a single ISOChannel. * @author apr * @since 1.8.5 */ diff --git a/jpos/src/main/java/org/jpos/q2/iso/QMUX.java b/jpos/src/main/java/org/jpos/q2/iso/QMUX.java index c1511b1902..78a4bd68a8 100644 --- a/jpos/src/main/java/org/jpos/q2/iso/QMUX.java +++ b/jpos/src/main/java/org/jpos/q2/iso/QMUX.java @@ -40,6 +40,7 @@ import java.util.concurrent.TimeUnit; /** + * Q2 QBean that implements a full-duplex ISO-8583 multiplexer over an {@link org.jpos.iso.ISOChannel}. * @author Alejandro Revilla */ @SuppressWarnings("unchecked") @@ -488,7 +489,7 @@ private LocalSpace grabSpace (Element e) * @param m the Message to be sent * @throws java.io.IOException * @throws org.jpos.iso.ISOException - * @throws org.jpos.iso.ISOFilter.VetoException; + * @throws org.jpos.iso.ISOFilter.VetoException if a filter vetoes the message */ public void send(ISOMsg m) throws IOException, ISOException { if (!isConnected()) diff --git a/jpos/src/main/java/org/jpos/q2/qbean/BSH.java b/jpos/src/main/java/org/jpos/q2/qbean/BSH.java index 0fa77a84c3..58a1456c99 100644 --- a/jpos/src/main/java/org/jpos/q2/qbean/BSH.java +++ b/jpos/src/main/java/org/jpos/q2/qbean/BSH.java @@ -25,9 +25,21 @@ import org.jpos.q2.Q2; import org.jpos.q2.QBeanSupport; +/** + * QBean that executes a BeanShell script on start/stop. + */ public class BSH extends QBeanSupport implements Runnable { + /** + * The BeanShell Interpreter instance. + */ protected Interpreter bsh; + /** + * Default constructor. + */ + public BSH() { super(); } + + /** {@inheritDoc} */ public void initService() { bsh = new Interpreter (); BshClassManager bcm = bsh.getClassManager(); diff --git a/jpos/src/main/java/org/jpos/q2/qbean/QThreadPoolExecutorMBean.java b/jpos/src/main/java/org/jpos/q2/qbean/QThreadPoolExecutorMBean.java index 52b67a940d..c336cd088c 100644 --- a/jpos/src/main/java/org/jpos/q2/qbean/QThreadPoolExecutorMBean.java +++ b/jpos/src/main/java/org/jpos/q2/qbean/QThreadPoolExecutorMBean.java @@ -16,85 +16,86 @@ * along with this program. If not, see . */ -package org.jpos.q2.qbean; - -import org.jpos.util.NameRegistrar.NotFoundException; - -/** - * @author dgrandemange - * - */ -public interface QThreadPoolExecutorMBean extends org.jpos.q2.QBeanSupportMBean { - /** - * @return executor service type - */ - String getExecSrvType(); - - /** - * @return await termination delay - */ - int getTerminationTimer(); - - /** - * @return approximate number of threads that are actively executing tasks - */ - int getActiveCount() throws NotFoundException; - - /** - * @return the approximate total number of tasks that have completed - * execution. - */ - long getCompletedTaskCount() throws NotFoundException; - - /** - * @return returns the core number of threads. - */ - int getCorePoolSize() throws NotFoundException; - - /** - * @return the thread keep-alive time, which is the amount of time (in - * milliseconds) which threads in excess of the core pool size may - * remain idle before being terminated - */ - long getKeepAliveTimeMS() throws NotFoundException; - - /** - * @return the largest number of threads that have ever simultaneously been - * in the pool. - */ - int getLargestPoolSize() throws NotFoundException; - - /** - * @return the maximum allowed number of threads. - */ - int getMaximumPoolSize() throws NotFoundException; - - /** - * @return the current number of threads in the pool. - */ - int getPoolSize() throws NotFoundException; - - /** - * @return the approximate total number of tasks that have been scheduled - * for execution - */ - long getTaskCount() throws NotFoundException; - - /** - * @return true if this executor has been shut down. - * @throws NotFoundException - */ - boolean isShutdown() throws NotFoundException; - - /** - * @return true if all tasks have completed following shut down - * @throws NotFoundException - */ - boolean isTerminated() throws NotFoundException; - - /** - * @return true if this executor is in the process of terminating after - * shutdown or shutdownNow but has not completely terminated. - */ - boolean isTerminating() throws NotFoundException; -} +package org.jpos.q2.qbean; + +import org.jpos.util.NameRegistrar.NotFoundException; + +/** + * JMX management interface for the Q2 thread-pool executor QBean. + * @author dgrandemange + * + */ +public interface QThreadPoolExecutorMBean extends org.jpos.q2.QBeanSupportMBean { + /** + * @return executor service type + */ + String getExecSrvType(); + + /** + * @return await termination delay + */ + int getTerminationTimer(); + + /** + * @return approximate number of threads that are actively executing tasks + */ + int getActiveCount() throws NotFoundException; + + /** + * @return the approximate total number of tasks that have completed + * execution. + */ + long getCompletedTaskCount() throws NotFoundException; + + /** + * @return returns the core number of threads. + */ + int getCorePoolSize() throws NotFoundException; + + /** + * @return the thread keep-alive time, which is the amount of time (in + * milliseconds) which threads in excess of the core pool size may + * remain idle before being terminated + */ + long getKeepAliveTimeMS() throws NotFoundException; + + /** + * @return the largest number of threads that have ever simultaneously been + * in the pool. + */ + int getLargestPoolSize() throws NotFoundException; + + /** + * @return the maximum allowed number of threads. + */ + int getMaximumPoolSize() throws NotFoundException; + + /** + * @return the current number of threads in the pool. + */ + int getPoolSize() throws NotFoundException; + + /** + * @return the approximate total number of tasks that have been scheduled + * for execution + */ + long getTaskCount() throws NotFoundException; + + /** + * @return true if this executor has been shut down. + * @throws NotFoundException + */ + boolean isShutdown() throws NotFoundException; + + /** + * @return true if all tasks have completed following shut down + * @throws NotFoundException + */ + boolean isTerminated() throws NotFoundException; + + /** + * @return true if this executor is in the process of terminating after + * shutdown or shutdownNow but has not completely terminated. + */ + boolean isTerminating() throws NotFoundException; +} diff --git a/jpos/src/main/java/org/jpos/q2/ui/UI.java b/jpos/src/main/java/org/jpos/q2/ui/UI.java index f8fc14efcf..b62e967429 100644 --- a/jpos/src/main/java/org/jpos/q2/ui/UI.java +++ b/jpos/src/main/java/org/jpos/q2/ui/UI.java @@ -24,6 +24,7 @@ import org.jpos.util.NameRegistrar; /** + * Q2 QBean that bootstraps the jPOS Swing-based GUI. * @author Alejandro Revilla * * org.jpos.ui.UI adapter diff --git a/jpos/src/main/java/org/jpos/rc/CMF.java b/jpos/src/main/java/org/jpos/rc/CMF.java index 0da773758b..8439a9e54c 100644 --- a/jpos/src/main/java/org/jpos/rc/CMF.java +++ b/jpos/src/main/java/org/jpos/rc/CMF.java @@ -21,202 +21,372 @@ import java.util.HashMap; import java.util.Map; +/** Common Message Format result codes used by jPOS Transaction Manager participants. */ public enum CMF implements IRC { // Approved + /** Approved. */ APPROVED (0, true), + /** Honor With Id. */ HONOR_WITH_ID (1, true), + /** Approved Partial. */ APPROVED_PARTIAL (2, true), + /** Approved Vip. */ APPROVED_VIP (3, true), + /** Approved Update Track3. */ APPROVED_UPDATE_TRACK3 (4, true), + /** Approved Issuer Specified Account. */ APPROVED_ISSUER_SPECIFIED_ACCOUNT (5, true), + /** Approved Partial Issuer Specified Account. */ APPROVED_PARTIAL_ISSUER_SPECIFIED_ACCOUNT (6, true), + /** Approved Fees Disputed. */ APPROVED_FEES_DISPUTED(8, true), + /** Approved With Overdraft. */ APPROVED_WITH_OVERDRAFT(9, true), + /** Approved Customer Reactivated. */ APPROVED_CUSTOMER_REACTIVATED(10, true), + /** Approved Terminal Unable To Process Online. */ APPROVED_TERMINAL_UNABLE_TO_PROCESS_ONLINE(11), + /** Approved Offline. */ APPROVED_OFFLINE (12), + /** Approved Offline Referral. */ APPROVED_OFFLINE_REFERRAL (13), // Denied Authorization + /** Do Not Honour. */ DO_NOT_HONOUR(1000), + /** Expired. */ EXPIRED (1001), + /** Suspected Fraud. */ SUSPECTED_FRAUD(1002), + /** Contact Acquirer. */ CONTACT_ACQUIRER(1003), + /** Restricted Card. */ RESTRICTED_CARD(1004), + /** Contact Acquirer Security. */ CONTACT_ACQUIRER_SECURITY(1005), + /** Max Pin Tries Exceeded. */ MAX_PIN_TRIES_EXCEEDED(1006), + /** Refer To Issuer. */ REFER_TO_ISSUER(1007), + /** Refer To Issuer Special. */ REFER_TO_ISSUER_SPECIAL(1008), + /** Invalid Card Acceptor. */ INVALID_CARD_ACCEPTOR(1009), + /** Invalid Amount. */ INVALID_AMOUNT(1010), + /** Invalid Card Number. */ INVALID_CARD_NUMBER(1011), + /** Pin Data Required. */ PIN_DATA_REQUIRED(1012), + /** Unacceptable Fee. */ UNACCEPTABLE_FEE(1013), + /** No Account Type. */ NO_ACCOUNT_TYPE(1014), + /** Unsupported Function. */ UNSUPPORTED_FUNCTION(1015), + /** Not Sufficient Funds. */ NOT_SUFFICIENT_FUNDS(1016), + /** Incorrect Pin. */ INCORRECT_PIN(1017), + /** No Card Record. */ NO_CARD_RECORD(1018), + /** Not Permitted To Cardholder. */ NOT_PERMITTED_TO_CARDHOLDER(1019), + /** Not Permitted To Terminal. */ NOT_PERMITTED_TO_TERMINAL(1020), + /** Exceeds Withdrawal Amount Limit. */ EXCEEDS_WITHDRAWAL_AMOUNT_LIMIT(1021), + /** Security Violation. */ SECURITY_VIOLATION(1022), + /** Exceeds Withdrawal Frequency Limit. */ EXCEEDS_WITHDRAWAL_FREQUENCY_LIMIT(1023), + /** Law Violation. */ LAW_VIOLATION(1024), + /** Card Not Effective. */ CARD_NOT_EFFECTIVE(1025), + /** Invalid Pinblock. */ INVALID_PINBLOCK(1026), + /** Pin Length Error. */ PIN_LENGTH_ERROR(1027), + /** Pin Key Sync Error. */ PIN_KEY_SYNC_ERROR(1028), + /** Suspected Counterfeit Card Dont Pickup. */ SUSPECTED_COUNTERFEIT_CARD_DONT_PICKUP(1029), + /** Unaccepted Currency. */ UNACCEPTED_CURRENCY(1030), + /** Declined Fees Disputed. */ DECLINED_FEES_DISPUTED(1031), + /** Lost Or Stolen Card. */ LOST_OR_STOLEN_CARD(1032), + /** Authorization Lifecycle Unacceptable. */ AUTHORIZATION_LIFECYCLE_UNACCEPTABLE(1033), + /** Authorization Lifecycle Expired. */ AUTHORIZATION_LIFECYCLE_EXPIRED(1034), + /** Closed Account. */ CLOSED_ACCOUNT(1035), + /** Closed Savings Account. */ CLOSED_SAVINGS_ACCOUNT(1036), + /** Closed Credit Account. */ CLOSED_CREDIT_ACCOUNT(1037), + /** Closed Account Type. */ CLOSED_ACCOUNT_TYPE(1038), + /** Closed Cheque Account. */ CLOSED_CHEQUE_ACCOUNT(1039), + /** Bad Debt. */ BAD_DEBT(1040), + /** From Account Bad Status. */ FROM_ACCOUNT_BAD_STATUS(1041), + /** To Account Bad Status. */ TO_ACCOUNT_BAD_STATUS(1042), + /** Cheque Already Posted. */ CHEQUE_ALREADY_POSTED(1043), + /** Information Not On File. */ INFORMATION_NOT_ON_FILE(1044), + /** Card Verification Data Failed. */ CARD_VERIFICATION_DATA_FAILED(1045), + /** Amount Not Found. */ AMOUNT_NOT_FOUND(1046), + /** Pin Change Required. */ PIN_CHANGE_REQUIRED(1047), + /** New Pin Invalid. */ NEW_PIN_INVALID(1048), + /** Bank Not Found. */ BANK_NOT_FOUND(1049), + /** Bank Not Effective. */ BANK_NOT_EFFECTIVE(1050), + /** Customer Vendor Not Found. */ CUSTOMER_VENDOR_NOT_FOUND(1051), + /** Customer Vendor Not Effective. */ CUSTOMER_VENDOR_NOT_EFFECTIVE(1052), + /** Customer Vendor Account Invalid. */ CUSTOMER_VENDOR_ACCOUNT_INVALID(1053), + /** Vendor Not Found. */ VENDOR_NOT_FOUND(1054), + /** Vendor Not Effective. */ VENDOR_NOT_EFFECTIVE(1055), + /** Vendor Data Invalid. */ VENDOR_DATA_INVALID(1056), + /** Payment Date Invalid. */ PAYMENT_DATE_INVALID(1057), + /** Personal Id Not Found. */ PERSONAL_ID_NOT_FOUND(1058), + /** Scheduled Transaction Exists. */ SCHEDULED_TRANSACTION_EXISTS(1059), + /** Indicates the transaction was aborted at the terminal. */ ABORTED_AT_TERMINAL(1060), + /** Unsupported Transaction. */ UNSUPPORTED_TRANSACTION(1061), + /** Cashback Not Allowed. */ CASHBACK_NOT_ALLOWED(1062), + /** Cashback Amount Exceeded. */ CASHBACK_AMOUNT_EXCEEDED(1063), + /** Declined Processed Offline. */ DECLINED_PROCESSED_OFFLINE(1064), + /** Declined Unable To Process. */ DECLINED_UNABLE_TO_PROCESS(1065), + /** Declined Processed Offline Referral. */ DECLINED_PROCESSED_OFFLINE_REFERRAL(1066), + /** Id Number Invalid. */ ID_NUMBER_INVALID(1068), + /** Driver Number Invalid. */ DRIVER_NUMBER_INVALID(1069), + /** Vid Invalid. */ VID_INVALID(1070), + /** Certificate Expired. */ CERTIFICATE_EXPIRED(1071), + /** Missing Field. */ MISSING_FIELD(1802), + /** Extra Field. */ EXTRA_FIELD(1803), + /** Invalid Card. */ INVALID_CARD(1804), + /** Card Not Active. */ CARD_NOT_ACTIVE(1806), + /** Card Not Configured. */ CARD_NOT_CONFIGURED(1808), + /** System Error Db. */ SYSTEM_ERROR_DB(1811, false, true), + /** System Error Txn. */ SYSTEM_ERROR_TXN(1812,false, true), + /** Configuration Error. */ CONFIGURATION_ERROR(1818), + /** Invalid Terminal. */ INVALID_TERMINAL(1819), + /** Inactive Terminal. */ INACTIVE_TERMINAL(1820), + /** Invalid Merchant. */ INVALID_MERCHANT(1821), + /** Duplicate Entity. */ DUPLICATE_ENTITY(1822), + /** Invalid Acquirer. */ INVALID_ACQUIRER(1823), + /** Invalid Field. */ INVALID_FIELD(1830), + /** Misconfigured Endpoint. */ MISCONFIGURED_ENDPOINT(1831), + /** Invalid Request. */ INVALID_REQUEST(1832), + /** Host Unreachable. */ HOST_UNREACHABLE(1833), // Denied Financial + /** Financial Do Not Honour. */ FINANCIAL_DO_NOT_HONOUR (2000), + /** Financial Expired. */ FINANCIAL_EXPIRED (2001), + /** Financial Suspected Fraud. */ FINANCIAL_SUSPECTED_FRAUD(2002), + /** Financial Contact Acquirer. */ FINANCIAL_CONTACT_ACQUIRER(2003), + /** Financial Restricted Card. */ FINANCIAL_RESTRICTED_CARD(2004), + /** Financial Contact Acquirer Security. */ FINANCIAL_CONTACT_ACQUIRER_SECURITY(2005), + /** Financial Max Pin Tries Exceeded. */ FINANCIAL_MAX_PIN_TRIES_EXCEEDED(2006), + /** Special Conditions. */ SPECIAL_CONDITIONS(2007), + /** Lost Card. */ LOST_CARD(2008), + /** Stolen Card. */ STOLEN_CARD(2009), + /** Suspected Counterfeit Card Pickup. */ SUSPECTED_COUNTERFEIT_CARD_PICKUP(2010), + /** Max Daily Withdrawal. */ MAX_DAILY_WITHDRAWAL(2011), + /** Max Daily Amount. */ MAX_DAILY_AMOUNT(2012), // File action + /** Successful. */ SUCCESSFUL(3000, true), + /** Not Supported By Receiver. */ NOT_SUPPORTED_BY_RECEIVER(3001), + /** Unable To Locate Record. */ UNABLE_TO_LOCATE_RECORD(3002), + /** Updated Record. */ UPDATED_RECORD(3003), + /** Field Edit Error. */ FIELD_EDIT_ERROR(3004), + /** File Locked Out. */ FILE_LOCKED_OUT(3005), + /** Not Successful. */ NOT_SUCCESSFUL(3006), + /** Format Error. */ FORMAT_ERROR(3007), + /** Duplicate. */ DUPLICATE(3008), + /** Unknown File. */ UNKNOWN_FILE(3009), + /** Invalid Card Or Cardholder Number. */ INVALID_CARD_OR_CARDHOLDER_NUMBER(3010), // Reversals + /** Reversal Accepted. */ REVERSAL_ACCEPTED(4000, true), // Reconciliation + /** Reconciled In Balance. */ RECONCILED_IN_BALANCE(5000, true), + /** Reconciled Out Of Balance. */ RECONCILED_OUT_OF_BALANCE(5001), + /** Amount Not Reconciled Totals Provided. */ AMOUNT_NOT_RECONCILED_TOTALS_PROVIDED(5002), + /** Totals Not Available. */ TOTALS_NOT_AVAILABLE(5003), + /** Not Reconciled Totals Provided. */ NOT_RECONCILED_TOTALS_PROVIDED(5004), // Administrative messages + /** Administrative message accepted. */ ADMIN_MESSAGE_ACCEPTED(6000, true), // Fee collection + /** Fee Collection Accepted. */ FEE_COLLECTION_ACCEPTED (7000, true), // Network Management + /** Net Accepted. */ NET_ACCEPTED (8000, true), + /** Net Retry. */ NET_RETRY(8001), // Misc + /** Advice acknowledged with no financial impact. */ ADVICE_ACK_NO_FINANCIAL(9000, true), + /** Advice accepted. */ ADVICE_ACCEPTED(9001, true), + /** Message Error. */ MESSAGE_ERROR(9100), + /** Invalid Transaction. */ INVALID_TRANSACTION(9102), + /** Retry Transaction. */ RETRY_TRANSACTION(9103), + /** Acquirer is not supported. */ ACQUIRER_NOT_SUPPORTED(9105), + /** Cutover In Process. */ CUTOVER_IN_PROCESS(9106), + /** Issuer Not Available. */ ISSUER_NOT_AVAILABLE(9107), + /** Routing Error. */ ROUTING_ERROR(9108), + /** System Error. */ SYSTEM_ERROR(9109), + /** Issuer Signed Off. */ ISSUER_SIGNED_OFF(9110), + /** Issuer Timeout. */ ISSUER_TIMEOUT(9111), + /** Issuer Unavailable. */ ISSUER_UNAVAILABLE(9112), + /** Duplicate Transmission. */ DUPLICATE_TRANSMISSION(9113), + /** Original Not Found. */ ORIGINAL_NOT_FOUND(9114), + /** Reconciliation Error. */ RECONCILIATION_ERROR(9115), + /** Mac Incorrect. */ MAC_INCORRECT(9116), + /** Mac Key Sync Error. */ MAC_KEY_SYNC_ERROR(9117), + /** Zmk Not Available. */ ZMK_NOT_AVAILABLE(9118), + /** Crypto Error. */ CRYPTO_ERROR(9119), + /** Hsm Error Retry. */ HSM_ERROR_RETRY(9120), + /** Hsm Error. */ HSM_ERROR (9121), + /** Out Of Sequence. */ OUT_OF_SEQUENCE(9122), + /** Request In Progress. */ REQUEST_IN_PROGRESS(9123), + /** Invalid Security Code. */ INVALID_SECURITY_CODE(9124), + /** Database Error. */ DATABASE_ERROR(9125), + /** Customer Vendor Format Error. */ CUSTOMER_VENDOR_FORMAT_ERROR(9128), + /** Recurring Data Error. */ RECURRING_DATA_ERROR(9132), + /** Update Not Allowed. */ UPDATE_NOT_ALLOWED(9133), + /** Agreement Violation. */ AGREEMENT_VIOLATION(9350), + /** General Decline. */ GENERAL_DECLINE(9999), // jPOS specific result codes + /** Jpos. */ JPOS(10000), + /** Internal Error. */ INTERNAL_ERROR(19999,false,true), // User specific result codes + /** User-defined result code. */ USER(90000); private final int irc; @@ -268,6 +438,11 @@ public boolean inhibit() { return inhibit; } + /** + * Looks up a CMF value by its integer code. + * @param i the integer code + * @return the matching IRC, or null if not found + */ public static IRC valueOf(int i) { return lookupInt.get(i); } diff --git a/jpos/src/main/java/org/jpos/rc/CMFConverter.java b/jpos/src/main/java/org/jpos/rc/CMFConverter.java index efc7de8933..a25c9dea65 100644 --- a/jpos/src/main/java/org/jpos/rc/CMFConverter.java +++ b/jpos/src/main/java/org/jpos/rc/CMFConverter.java @@ -27,6 +27,7 @@ import java.io.InputStream; import java.util.*; +/** Converts between {@link CMF} result codes and ISO response codes. */ public class CMFConverter implements IRCConverter, Configurable { private static final Map rcs = new HashMap<>(); private static final Map ircs = new HashMap<>(); @@ -39,10 +40,12 @@ public class CMFConverter implements IRCConverter, Configurable { } catch (IOException ignored) { } } + /** Default constructor. */ public CMFConverter() { super(); } + /** @param cfg the configuration */ public CMFConverter(Configuration cfg) { this.cfg = cfg; } diff --git a/jpos/src/main/java/org/jpos/rc/IRC.java b/jpos/src/main/java/org/jpos/rc/IRC.java index fc428272b8..00f9d6ae6e 100644 --- a/jpos/src/main/java/org/jpos/rc/IRC.java +++ b/jpos/src/main/java/org/jpos/rc/IRC.java @@ -36,6 +36,7 @@ */ public interface IRC { /** + * Returns the numeric internal result code. * @return internal result code */ int irc(); @@ -50,11 +51,13 @@ default String ircString() { } /** + * Returns true if this IRC represents a successful outcome. * @return true if this IRC can be considered a 'success' (not necessarily an approval, could be a partial approval, advice accepted, etc.) */ boolean success(); /** + * Returns true if this error type should inhibit the response to the client. * @return true if error type should inhibit response back to client */ boolean inhibit(); diff --git a/jpos/src/main/java/org/jpos/rc/IRCConverter.java b/jpos/src/main/java/org/jpos/rc/IRCConverter.java index dec9b29dc8..bba2947536 100644 --- a/jpos/src/main/java/org/jpos/rc/IRCConverter.java +++ b/jpos/src/main/java/org/jpos/rc/IRCConverter.java @@ -22,6 +22,16 @@ * Convert internal result code (IRC) to result code */ public interface IRCConverter { + /** + * Converts an IRC to an RC (response code). + * @param irc the IRC to convert + * @return the corresponding RC + */ RC convert (IRC irc); + /** + * Converts an RC to an IRC. + * @param rc the RC to convert + * @return the corresponding IRC + */ IRC convert (RC rc); } diff --git a/jpos/src/main/java/org/jpos/security/ARPCMethod.java b/jpos/src/main/java/org/jpos/security/ARPCMethod.java index 7b8d8d5822..af6afc1156 100644 --- a/jpos/src/main/java/org/jpos/security/ARPCMethod.java +++ b/jpos/src/main/java/org/jpos/security/ARPCMethod.java @@ -30,18 +30,22 @@ public enum ARPCMethod { /** * Method for the generation of an 8-byte ARPC consists of applying * the Triple-DES algorithm: + *
        *
      • the 8-byte ARQC *
      • the 2-byte Authorisation Response Code (ARC) + *
      */ - METHOD_1 + METHOD_1, /** * Method For the generation of a 4-byte ARPC consists of applying * the MAC algorithm: + *
        *
      • the 4-byte ARQC *
      • the 4-byte binary Card Status Update (CSU) *
      • the 0-8 byte binary Proprietary Authentication Data + *
      */ - ,METHOD_2 + METHOD_2 } diff --git a/jpos/src/main/java/org/jpos/security/BaseSMAdapter.java b/jpos/src/main/java/org/jpos/security/BaseSMAdapter.java index c7db603ea4..3685b41d57 100644 --- a/jpos/src/main/java/org/jpos/security/BaseSMAdapter.java +++ b/jpos/src/main/java/org/jpos/security/BaseSMAdapter.java @@ -48,19 +48,32 @@ *

      * @author Hani S. Kirollos * @version $Revision$ $Date$ + + * @param the SecureKey implementation type */ public class BaseSMAdapter implements SMAdapter, Configurable, LogSource { + /** Logger for this security module adapter. */ protected Logger logger = null; + /** Log realm for this security module adapter. */ protected String realm = null; + /** Configuration for this adapter. */ protected Configuration cfg; private String name; private boolean debug; + /** Default constructor. */ public BaseSMAdapter () { super(); } + /** + * Creates a BaseSMAdapter with the given configuration, logger and realm. + * @param cfg configuration + * @param logger the logger + * @param realm log realm + * @throws ConfigurationException on invalid configuration + */ public BaseSMAdapter (Configuration cfg, Logger logger, String realm) throws ConfigurationException { super(); @@ -101,6 +114,7 @@ public void setName (String name) { } /** + * Returns the registered name of this SMAdapter. * @return this SMAdapter's name ("" if no name was set) */ public String getName () { @@ -108,9 +122,10 @@ public String getName () { } /** - * @param name + * Looks up a registered SMAdapter by name from the NameRegistrar. + * @param name the registered adapter name * @return SMAdapter instance with given name. - * @throws NotFoundException + * @throws NotFoundException if name is not found in the registry * @see NameRegistrar */ public static SMAdapter getSMAdapter (String name) throws NameRegistrar.NotFoundException { @@ -975,7 +990,7 @@ public boolean verifydCVV(String accountNo, T imkac, String dcvv, * is assumed. * @param cvc3 dynamic Card Verification Code 3 * @return true if cvc3 is valid false if not - * @throws SMException + * @throws SMException on security module error */ @Override public boolean verifyCVC3(T imkcvc3, String accountNo, String acctSeqNo, @@ -1191,7 +1206,7 @@ public Pair translatePINGenerateSM_MAC(MKDMethod mkdm * @param data data to be encrypted * @param iv initial vector * @return encrypted data - * @throws SMException + * @throws SMException on security module error */ @Override public byte[] encryptData(CipherMode cipherMode, SecureDESKey kd @@ -1233,7 +1248,7 @@ public byte[] encryptData(CipherMode cipherMode, SecureDESKey kd * @param data data to be decrypted * @param iv initial vector * @return decrypted data - * @throws SMException + * @throws SMException on security module error */ @Override public byte[] decryptData(CipherMode cipherMode, SecureDESKey kd @@ -1498,10 +1513,10 @@ public void eraseOldLMK () throws SMException { /** * Your SMAdapter should override this method if it has this functionality - * @param keyLength - * @param keyType + * @param keyLength see method description + * @param keyType see method description * @return generated key - * @throws SMException + * @throws SMException on security module error */ protected SecureDESKey generateKeyImpl (short keyLength, String keyType) throws SMException { throw new SMException("Operation not supported in: " + this.getClass().getName()); @@ -1510,9 +1525,9 @@ protected SecureDESKey generateKeyImpl (short keyLength, String keyType) throws /** * Your SMAdapter should override this method if it has this functionality. * - * @param keySpec + * @param keySpec see method description * @return generated key - * @throws SMException + * @throws SMException on security module error */ protected SecureKey generateKeyImpl(SecureKeySpec keySpec) throws SMException { throw new UnsupportedOperationException("Operation not supported in: " + this.getClass().getName()); @@ -1520,9 +1535,9 @@ protected SecureKey generateKeyImpl(SecureKeySpec keySpec) throws SMException { /** * Your SMAdapter should override this method if it has this functionality - * @param kd + * @param kd see method description * @return generated Key Check Value - * @throws SMException + * @throws SMException on security module error */ protected byte[] generateKeyCheckValueImpl(T kd) throws SMException { throw new SMException("Operation not supported in: " + this.getClass().getName()); @@ -1530,10 +1545,10 @@ protected byte[] generateKeyCheckValueImpl(T kd) throws SMException { /** * Your SMAdapter should override this method if it has this functionality - * @param key - * @param destKeyScheme + * @param key see method description + * @param destKeyScheme see method description * @return translated key with {@code destKeyScheme} scheme - * @throws SMException + * @throws SMException on security module error */ protected SecureDESKey translateKeySchemeImpl(SecureDESKey key, KeyScheme destKeyScheme) throws SMException { @@ -1542,13 +1557,13 @@ protected SecureDESKey translateKeySchemeImpl(SecureDESKey key, KeyScheme destKe /** * Your SMAdapter should override this method if it has this functionality - * @param keyLength - * @param keyType - * @param encryptedKey - * @param kek - * @param checkParity + * @param keyLength see method description + * @param keyType — see method description + * @param encryptedKey see method description + * @param kek — see method description + * @param checkParity see method description * @return imported key - * @throws SMException + * @throws SMException on security module error */ protected SecureDESKey importKeyImpl(short keyLength, String keyType, byte[] encryptedKey, SecureDESKey kek, boolean checkParity) throws SMException { @@ -1558,12 +1573,12 @@ protected SecureDESKey importKeyImpl(short keyLength, String keyType, byte[] enc /** * Your SMAdapter should override this method if it has this functionality. * - * @param kek - * @param key - * @param keySpec - * @param checkParity + * @param kek see method description + * @param key — see method description + * @param keySpec see method description + * @param checkParity see method description * @return imported key - * @throws SMException + * @throws SMException on security module error */ protected SecureKey importKeyImpl(SecureKey kek, SecureKey key, SecureKeySpec keySpec, boolean checkParity) throws SMException { @@ -1572,10 +1587,10 @@ protected SecureKey importKeyImpl(SecureKey kek, SecureKey key, /** * Your SMAdapter should override this method if it has this functionality - * @param key - * @param kek + * @param key see method description + * @param kek see method description * @return exported key - * @throws SMException + * @throws SMException on security module error */ protected byte[] exportKeyImpl(SecureDESKey key, SecureDESKey kek) throws SMException { throw new SMException("Operation not supported in: " + this.getClass().getName()); @@ -1584,11 +1599,11 @@ protected byte[] exportKeyImpl(SecureDESKey key, SecureDESKey kek) throws SMExce /** * Your SMAdapter should override this method if it has this functionality. * - * @param kek - * @param key - * @param keySpec + * @param kek see method description + * @param key — see method description + * @param keySpec see method description * @return exported key - * @throws SMException + * @throws SMException on security module error */ protected SecureKey exportKeyImpl(SecureKey kek, SecureKey key , SecureKeySpec keySpec) throws SMException { @@ -1597,10 +1612,10 @@ protected SecureKey exportKeyImpl(SecureKey kek, SecureKey key /** * Your SMAdapter should override this method if it has this functionality - * @param pin - * @param accountNumber + * @param pin see method description + * @param accountNumber see method description * @return encrypted PIN under LMK - * @throws SMException + * @throws SMException on security module error */ protected EncryptedPIN encryptPINImpl (String pin, String accountNumber) throws SMException { throw new SMException("Operation not supported in: " + this.getClass().getName()); @@ -1609,11 +1624,11 @@ protected EncryptedPIN encryptPINImpl (String pin, String accountNumber) throws /** * Your SMAdapter should override this method if it has this functionality. * - * @param pin - * @param accountNumber - * @param pek + * @param pin see method description + * @param accountNumber — see method description + * @param pek see method description * @return encrypted PIN under PEK. - * @throws SMException + * @throws SMException on security module error */ protected EncryptedPIN encryptPINImpl(String pin, String accountNumber, T pek) throws SMException { throw new SMException("Operation not supported in: " + this.getClass().getName()); @@ -1621,9 +1636,9 @@ protected EncryptedPIN encryptPINImpl(String pin, String accountNumber, T pek) t /** * Your SMAdapter should override this method if it has this functionality - * @param pinUnderLmk + * @param pinUnderLmk see method description * @return clear pin as entered by card holder - * @throws SMException + * @throws SMException on security module error */ protected String decryptPINImpl (EncryptedPIN pinUnderLmk) throws SMException { throw new SMException("Operation not supported in: " + this.getClass().getName()); @@ -1631,10 +1646,10 @@ protected String decryptPINImpl (EncryptedPIN pinUnderLmk) throws SMException { /** * Your SMAdapter should override this method if it has this functionality - * @param pinUnderKd1 - * @param kd1 + * @param pinUnderKd1 see method description + * @param kd1 see method description * @return imported pin - * @throws SMException + * @throws SMException on security module error */ protected EncryptedPIN importPINImpl(EncryptedPIN pinUnderKd1, T kd1) throws SMException { throw new SMException("Operation not supported in: " + this.getClass().getName()); @@ -1642,12 +1657,12 @@ protected EncryptedPIN importPINImpl(EncryptedPIN pinUnderKd1, T kd1) throws SME /** * Your SMAdapter should override this method if it has this functionality - * @param pinUnderKd1 - * @param kd1 - * @param kd2 - * @param destinationPINBlockFormat + * @param pinUnderKd1 see method description + * @param kd1 — see method description + * @param kd2 see method description + * @param destinationPINBlockFormat see method description * @return translated pin - * @throws SMException + * @throws SMException on security module error */ protected EncryptedPIN translatePINImpl(EncryptedPIN pinUnderKd1, T kd1, T kd2, byte destinationPINBlockFormat) throws SMException { @@ -1657,11 +1672,11 @@ protected EncryptedPIN translatePINImpl(EncryptedPIN pinUnderKd1, T kd1, /** * Your SMAdapter should override this method if it has this functionality * @deprecated - * @param pinUnderDuk - * @param ksn - * @param bdk + * @param pinUnderDuk see method description + * @param ksn — see method description + * @param bdk see method description * @return imported pin - * @throws SMException + * @throws SMException on security module error */ @Deprecated protected EncryptedPIN importPINImpl(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, @@ -1671,12 +1686,12 @@ protected EncryptedPIN importPINImpl(EncryptedPIN pinUnderDuk, KeySerialNumber k /** * Your SMAdapter should override this method if it has this functionality - * @param pinUnderDuk - * @param ksn - * @param bdk - * @param tdes + * @param pinUnderDuk see method description + * @param ksn — see method description + * @param bdk see method description + * @param tdes see method description * @return imported pin - * @throws SMException + * @throws SMException on security module error */ protected EncryptedPIN importPINImpl(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, T bdk, boolean tdes) throws SMException { @@ -1686,13 +1701,13 @@ protected EncryptedPIN importPINImpl(EncryptedPIN pinUnderDuk, KeySerialNumber k /** * Your SMAdapter should override this method if it has this functionality * @deprecated - * @param pinUnderDuk - * @param ksn - * @param bdk - * @param kd2 - * @param destinationPINBlockFormat + * @param pinUnderDuk see method description + * @param ksn — see method description + * @param bdk see method description + * @param kd2 — see method description + * @param destinationPINBlockFormat see method description * @return translated pin - * @throws SMException + * @throws SMException on security module error */ @Deprecated protected EncryptedPIN translatePINImpl(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, @@ -1702,14 +1717,14 @@ protected EncryptedPIN translatePINImpl(EncryptedPIN pinUnderDuk, KeySerialNumbe /** * Your SMAdapter should override this method if it has this functionality - * @param pinUnderDuk - * @param ksn - * @param bdk - * @param kd2 - * @param tdes - * @param destinationPINBlockFormat + * @param pinUnderDuk see method description + * @param ksn — see method description + * @param bdk see method description + * @param kd2 — see method description + * @param tdes see method description + * @param destinationPINBlockFormat see method description * @return translated pin - * @throws SMException + * @throws SMException on security module error */ protected EncryptedPIN translatePINImpl(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, T bdk, T kd2, byte destinationPINBlockFormat, @@ -1719,11 +1734,11 @@ protected EncryptedPIN translatePINImpl(EncryptedPIN pinUnderDuk, KeySerialNumbe /** * Your SMAdapter should override this method if it has this functionality - * @param pinUnderLmk - * @param kd2 - * @param destinationPINBlockFormat + * @param pinUnderLmk see method description + * @param kd2 — see method description + * @param destinationPINBlockFormat see method description * @return exported pin - * @throws SMException + * @throws SMException on security module error */ protected EncryptedPIN exportPINImpl(EncryptedPIN pinUnderLmk, T kd2, byte destinationPINBlockFormat) throws SMException { @@ -1732,11 +1747,11 @@ protected EncryptedPIN exportPINImpl(EncryptedPIN pinUnderLmk, T kd2, /** * Your SMAdapter should override this method if it has this functionality - * @param accountNumber - * @param pinLen - * @param excludes + * @param accountNumber see method description + * @param pinLen — see method description + * @param excludes see method description * @return generated PIN under LMK - * @throws SMException + * @throws SMException on security module error */ protected EncryptedPIN generatePINImpl(String accountNumber, int pinLen, List excludes) throws SMException { @@ -1745,12 +1760,12 @@ protected EncryptedPIN generatePINImpl(String accountNumber, int pinLen, List fields) throws SMException { @@ -1759,13 +1774,13 @@ protected void printPINImpl(String accountNo, EncryptedPIN pinUnderKd1, T kd1 /** * Your SMAdapter should override this method if it has this functionality - * @param pinUnderLMK - * @param pvkA - * @param pvkB - * @param pvkIdx - * @param excludes + * @param pinUnderLMK see method description + * @param pvkA — see method description + * @param pvkB see method description + * @param pvkIdx — see method description + * @param excludes see method description * @return PVV (VISA PIN Verification Value) - * @throws SMException + * @throws SMException on security module error */ protected String calculatePVVImpl(EncryptedPIN pinUnderLMK, T pvkA, T pvkB, int pvkIdx, List excludes) @@ -1775,14 +1790,14 @@ protected String calculatePVVImpl(EncryptedPIN pinUnderLMK, /** * Your SMAdapter should override this method if it has this functionality - * @param pinUnderKd1 - * @param kd1 - * @param pvkA - * @param pvkB - * @param pvkIdx - * @param excludes + * @param pinUnderKd1 see method description + * @param kd1 — see method description + * @param pvkA see method description + * @param pvkB — see method description + * @param pvkIdx see method description + * @param excludes see method description * @return PVV (VISA PIN Verification Value) - * @throws SMException + * @throws SMException on security module error */ protected String calculatePVVImpl(EncryptedPIN pinUnderKd1, T kd1, T pvkA, T pvkB, int pvkIdx, @@ -1792,14 +1807,14 @@ protected String calculatePVVImpl(EncryptedPIN pinUnderKd1, T kd1, /** * Your SMAdapter should override this method if it has this functionality - * @param pinUnderKd - * @param kd - * @param pvkA - * @param pvkB - * @param pvki - * @param pvv + * @param pinUnderKd see method description + * @param kd — see method description + * @param pvkA see method description + * @param pvkB — see method description + * @param pvki see method description + * @param pvv see method description * @return true if pin is valid false if not - * @throws SMException + * @throws SMException on security module error */ protected boolean verifyPVVImpl(EncryptedPIN pinUnderKd, T kd, T pvkA, T pvkB, int pvki, String pvv) throws SMException { @@ -1808,14 +1823,14 @@ protected boolean verifyPVVImpl(EncryptedPIN pinUnderKd, T kd, T pvkA, /** * Your SMAdapter should override this method if it has this functionality - * @param pinUnderLmk - * @param pvk - * @param decTab - * @param pinValData - * @param minPinLen - * @param excludes + * @param pinUnderLmk see method description + * @param pvk — see method description + * @param decTab see method description + * @param pinValData — see method description + * @param minPinLen see method description + * @param excludes see method description * @return IBM PIN Offset - * @throws SMException + * @throws SMException on security module error */ protected String calculateIBMPINOffsetImpl(EncryptedPIN pinUnderLmk, T pvk, String decTab, String pinValData, int minPinLen, @@ -1825,15 +1840,15 @@ protected String calculateIBMPINOffsetImpl(EncryptedPIN pinUnderLmk, T pvk, /** * Your SMAdapter should override this method if it has this functionality - * @param pinUnderKd1 - * @param kd1 - * @param pvk - * @param decTab - * @param pinValData - * @param minPinLen - * @param excludes + * @param pinUnderKd1 see method description + * @param kd1 — see method description + * @param pvk see method description + * @param decTab — see method description + * @param pinValData see method description + * @param minPinLen — see method description + * @param excludes see method description * @return IBM PIN Offset - * @throws SMException + * @throws SMException on security module error */ protected String calculateIBMPINOffsetImpl(EncryptedPIN pinUnderKd1, T kd1, T pvk, String decTab, String pinValData, @@ -1844,15 +1859,15 @@ protected String calculateIBMPINOffsetImpl(EncryptedPIN pinUnderKd1, T kd1, /** * Your SMAdapter should override this method if it has this functionality - * @param pinUnderKd - * @param kd - * @param pvk - * @param offset - * @param decTab - * @param pinValData - * @param minPinLen + * @param pinUnderKd see method description + * @param kd — see method description + * @param pvk see method description + * @param offset — see method description + * @param decTab see method description + * @param pinValData — see method description + * @param minPinLen see method description * @return true if pin is valid false if not - * @throws SMException + * @throws SMException on security module error */ protected boolean verifyIBMPINOffsetImpl(EncryptedPIN pinUnderKd, T kd ,T pvk, String offset, String decTab @@ -1862,14 +1877,14 @@ protected boolean verifyIBMPINOffsetImpl(EncryptedPIN pinUnderKd, T kd /** * Your SMAdapter should override this method if it has this functionality - * @param accountNo - * @param pvk - * @param decTab - * @param pinValData - * @param minPinLen - * @param offset + * @param accountNo see method description + * @param pvk — see method description + * @param decTab see method description + * @param pinValData — see method description + * @param minPinLen see method description + * @param offset see method description * @return derived PIN under LMK - * @throws SMException + * @throws SMException on security module error */ protected EncryptedPIN deriveIBMPINImpl(String accountNo, T pvk, String decTab , String pinValData, int minPinLen, String offset) @@ -1879,13 +1894,13 @@ protected EncryptedPIN deriveIBMPINImpl(String accountNo, T pvk, String decTab /** * Your SMAdapter should override this method if it has this functionality - * @param accountNo - * @param cvkA - * @param cvkB - * @param expDate - * @param serviceCode + * @param accountNo see method description + * @param cvkA — see method description + * @param cvkB see method description + * @param expDate — see method description + * @param serviceCode see method description * @return Card Verification Code/Value - * @throws SMException + * @throws SMException on security module error */ protected String calculateCVVImpl(String accountNo, T cvkA, T cvkB, Date expDate, String serviceCode) throws SMException { @@ -1895,13 +1910,13 @@ protected String calculateCVVImpl(String accountNo, T cvkA, T cvkB, /** * Your SMAdapter should override this method if it has this functionality - * @param accountNo - * @param cvkA - * @param cvkB - * @param expDate - * @param serviceCode + * @param accountNo see method description + * @param cvkA — see method description + * @param cvkB see method description + * @param expDate — see method description + * @param serviceCode see method description * @return Card Verification Digit (Code/Value) - * @throws SMException + * @throws SMException on security module error */ protected String calculateCVDImpl(String accountNo, T cvkA, T cvkB, String expDate, String serviceCode) throws SMException { @@ -1911,13 +1926,13 @@ protected String calculateCVDImpl(String accountNo, T cvkA, T cvkB, /** * Your SMAdapter should override this method if it has this functionality - * @param accountNo - * @param cvk - * @param upn - * @param authrc - * @param sfarc + * @param accountNo see method description + * @param cvk — see method description + * @param upn see method description + * @param authrc — see method description + * @param sfarc see method description * @return Cardholder Authentication Verification Value - * @throws SMException + * @throws SMException on security module error */ protected String calculateCAVVImpl(String accountNo, T cvk, String upn, String authrc, String sfarc) throws SMException { @@ -1926,14 +1941,14 @@ protected String calculateCAVVImpl(String accountNo, T cvk, String upn, /** * Your SMAdapter should override this method if it has this functionality - * @param accountNo - * @param cvkA - * @param cvkB - * @param cvv - * @param expDate - * @param serviceCode + * @param accountNo see method description + * @param cvkA — see method description + * @param cvkB see method description + * @param cvv — see method description + * @param expDate see method description + * @param serviceCode see method description * @return true if CVV/CVC is falid or false if not - * @throws SMException + * @throws SMException on security module error */ protected boolean verifyCVVImpl(String accountNo, T cvkA, T cvkB, String cvv, Date expDate, String serviceCode) throws SMException { @@ -1942,14 +1957,14 @@ protected boolean verifyCVVImpl(String accountNo, T cvkA, T cvkB, /** * Your SMAdapter should override this method if it has this functionality - * @param accountNo - * @param cvkA - * @param cvkB - * @param cvv - * @param expDate - * @param serviceCode + * @param accountNo see method description + * @param cvkA — see method description + * @param cvkB see method description + * @param cvv — see method description + * @param expDate see method description + * @param serviceCode see method description * @return {@code true} if CVV/CVC is valid or {@code false} otherwise - * @throws SMException + * @throws SMException on security module error */ protected boolean verifyCVVImpl(String accountNo, T cvkA, T cvkB, String cvv, String expDate, String serviceCode) throws SMException { @@ -1958,14 +1973,14 @@ protected boolean verifyCVVImpl(String accountNo, T cvkA, T cvkB, /** * Your SMAdapter should override this method if it has this functionality - * @param accountNo - * @param cvk - * @param cavv - * @param upn - * @param authrc - * @param sfarc + * @param accountNo see method description + * @param cvk — see method description + * @param cavv see method description + * @param upn — see method description + * @param authrc see method description + * @param sfarc see method description * @return Cardholder Authentication Verification Value - * @throws SMException + * @throws SMException on security module error */ protected boolean verifyCAVVImpl(String accountNo, T cvk, String cavv, String upn, String authrc, String sfarc) throws SMException { @@ -1974,15 +1989,15 @@ protected boolean verifyCAVVImpl(String accountNo, T cvk, String cavv, /** * Your SMAdapter should override this method if it has this functionality - * @param accountNo - * @param imkac - * @param dcvv - * @param expDate - * @param serviceCode - * @param atc - * @param mkdm + * @param accountNo see method description + * @param imkac — see method description + * @param dcvv see method description + * @param expDate — see method description + * @param serviceCode see method description + * @param atc — see method description + * @param mkdm see method description * @return true if dcvv is valid false if not - * @throws SMException + * @throws SMException on security module error */ protected boolean verifydCVVImpl(String accountNo, T imkac, String dcvv, Date expDate, String serviceCode, byte[] atc, MKDMethod mkdm) @@ -1992,15 +2007,15 @@ protected boolean verifydCVVImpl(String accountNo, T imkac, String dcvv, /** * Your SMAdapter should override this method if it has this functionality - * @param accountNo - * @param imkac - * @param dcvv - * @param expDate - * @param serviceCode - * @param atc - * @param mkdm + * @param accountNo see method description + * @param imkac — see method description + * @param dcvv see method description + * @param expDate — see method description + * @param serviceCode see method description + * @param atc — see method description + * @param mkdm see method description * @return true if dcvv is valid false if not - * @throws SMException + * @throws SMException on security module error */ protected boolean verifydCVVImpl(String accountNo, T imkac, String dcvv, String expDate, String serviceCode, byte[] atc, MKDMethod mkdm) @@ -2010,16 +2025,16 @@ protected boolean verifydCVVImpl(String accountNo, T imkac, String dcvv, /** * Your SMAdapter should override this method if it has this functionality - * @param imkcvc3 - * @param accountNo - * @param acctSeqNo - * @param atc - * @param upn - * @param data - * @param mkdm - * @param cvc3 + * @param imkcvc3 see method description + * @param accountNo — see method description + * @param acctSeqNo see method description + * @param atc — see method description + * @param upn see method description + * @param data — see method description + * @param mkdm see method description + * @param cvc3 see method description * @return true if cvc3 is valid false if not - * @throws SMException + * @throws SMException on security module error */ protected boolean verifyCVC3Impl(T imkcvc3, String accountNo, String acctSeqNo, byte[] atc, byte[] upn, byte[] data, MKDMethod mkdm, String cvc3) @@ -2029,17 +2044,17 @@ protected boolean verifyCVC3Impl(T imkcvc3, String accountNo, String acctSeqNo, /** * Your SMAdapter should override this method if it has this functionality - * @param mkdm - * @param skdm - * @param imkac - * @param accountNo - * @param acctSeqNo - * @param arqc - * @param atc - * @param upn - * @param txnData + * @param mkdm see method description + * @param skdm — see method description + * @param imkac see method description + * @param accountNo — see method description + * @param acctSeqNo see method description + * @param arqc — see method description + * @param atc see method description + * @param upn — see method description + * @param txnData see method description * @return true if ARQC/TC/AAC is valid or false if not - * @throws SMException + * @throws SMException on security module error */ protected boolean verifyARQCImpl(MKDMethod mkdm, SKDMethod skdm, T imkac ,String accountNo, String acctSeqNo, byte[] arqc, byte[] atc @@ -2049,19 +2064,19 @@ protected boolean verifyARQCImpl(MKDMethod mkdm, SKDMethod skdm, T imkac /** * Your SMAdapter should override this method if it has this functionality - * @param mkdm - * @param skdm - * @param imkac - * @param accountNo - * @param acctSeqNo - * @param arqc - * @param atc - * @param upn - * @param arpcMethod - * @param arc - * @param propAuthData + * @param mkdm see method description + * @param skdm — see method description + * @param imkac see method description + * @param accountNo — see method description + * @param acctSeqNo see method description + * @param arqc — see method description + * @param atc see method description + * @param upn — see method description + * @param arpcMethod see method description + * @param arc — see method description + * @param propAuthData see method description * @return calculated ARPC - * @throws SMException + * @throws SMException on security module error */ protected byte[] generateARPCImpl(MKDMethod mkdm, SKDMethod skdm, T imkac ,String accountNo, String acctSeqNo, byte[] arqc, byte[] atc @@ -2072,20 +2087,20 @@ protected byte[] generateARPCImpl(MKDMethod mkdm, SKDMethod skdm, T imkac /** * Your SMAdapter should override this method if it has this functionality - * @param mkdm - * @param skdm - * @param imkac - * @param accountNo - * @param acctSeqNo - * @param arqc - * @param atc - * @param upn - * @param transData - * @param arpcMethod - * @param arc - * @param propAuthData + * @param mkdm see method description + * @param skdm — see method description + * @param imkac see method description + * @param accountNo — see method description + * @param acctSeqNo see method description + * @param arqc — see method description + * @param atc see method description + * @param upn — see method description + * @param transData see method description + * @param arpcMethod — see method description + * @param arc see method description + * @param propAuthData see method description * @return calculated ARPC - * @throws SMException + * @throws SMException on security module error */ protected byte[] verifyARQCGenerateARPCImpl(MKDMethod mkdm, SKDMethod skdm, T imkac ,String accountNo, String acctSeqNo, byte[] arqc, byte[] atc, byte[] upn @@ -2098,16 +2113,16 @@ protected byte[] verifyARQCGenerateARPCImpl(MKDMethod mkdm, SKDMethod skdm, T im /** * Your SMAdapter should override this method if it has this functionality - * @param mkdm - * @param skdm - * @param imksmi - * @param accountNo - * @param acctSeqNo - * @param atc - * @param arqc - * @param data + * @param mkdm see method description + * @param skdm — see method description + * @param imksmi see method description + * @param accountNo — see method description + * @param acctSeqNo see method description + * @param atc — see method description + * @param arqc see method description + * @param data see method description * @return generated 8 bytes MAC - * @throws SMException + * @throws SMException on security module error */ protected byte[] generateSM_MACImpl(MKDMethod mkdm, SKDMethod skdm ,T imksmi, String accountNo, String acctSeqNo @@ -2117,23 +2132,23 @@ protected byte[] generateSM_MACImpl(MKDMethod mkdm, SKDMethod skdm /** * Your SMAdapter should override this method if it has this functionality - * @param mkdm - * @param skdm - * @param padm - * @param imksmi - * @param accountNo - * @param acctSeqNo - * @param atc - * @param arqc - * @param data - * @param currentPIN - * @param newPIN - * @param kd1 - * @param imksmc - * @param imkac - * @param destinationPINBlockFormat + * @param mkdm see method description + * @param skdm — see method description + * @param padm see method description + * @param imksmi — see method description + * @param accountNo see method description + * @param acctSeqNo — see method description + * @param atc see method description + * @param arqc — see method description + * @param data see method description + * @param currentPIN — see method description + * @param newPIN see method description + * @param kd1 — see method description + * @param imksmc see method description + * @param imkac — see method description + * @param destinationPINBlockFormat see method description * @return Pair of values, encrypted PIN and 8 bytes MAC - * @throws SMException + * @throws SMException on security module error */ protected Pair translatePINGenerateSM_MACImpl(MKDMethod mkdm ,SKDMethod skdm, PaddingMethod padm, T imksmi @@ -2146,12 +2161,12 @@ protected Pair translatePINGenerateSM_MACImpl(MKDMethod mkd /** * Your SMAdapter should override this method if it has this functionality - * @param cipherMode - * @param kd - * @param data - * @param iv + * @param cipherMode see method description + * @param kd — see method description + * @param data see method description + * @param iv see method description * @return encrypted data - * @throws SMException + * @throws SMException on security module error */ protected byte[] encryptDataImpl(CipherMode cipherMode, SecureDESKey kd ,byte[] data, byte[] iv) throws SMException { @@ -2160,12 +2175,12 @@ protected byte[] encryptDataImpl(CipherMode cipherMode, SecureDESKey kd /** * Your SMAdapter should override this method if it has this functionality - * @param cipherMode - * @param kd - * @param data - * @param iv + * @param cipherMode see method description + * @param kd — see method description + * @param data see method description + * @param iv see method description * @return decrypted data - * @throws SMException + * @throws SMException on security module error */ protected byte[] decryptDataImpl(CipherMode cipherMode, SecureDESKey kd ,byte[] data, byte[] iv) throws SMException { @@ -2174,10 +2189,10 @@ protected byte[] decryptDataImpl(CipherMode cipherMode, SecureDESKey kd /** * Your SMAdapter should override this method if it has this functionality - * @param data - * @param kd + * @param data see method description + * @param kd see method description * @return generated CBC-MAC - * @throws SMException + * @throws SMException on security module error */ protected byte[] generateCBC_MACImpl(byte[] data, T kd) throws SMException { throw new SMException("Operation not supported in: " + this.getClass().getName()); @@ -2185,10 +2200,10 @@ protected byte[] generateCBC_MACImpl(byte[] data, T kd) throws SMException { /** * Your SMAdapter should override this method if it has this functionality - * @param data - * @param kd + * @param data see method description + * @param kd see method description * @return generated EDE-MAC - * @throws SMException + * @throws SMException on security module error */ protected byte[] generateEDE_MACImpl(byte[] data, T kd) throws SMException { throw new SMException("Operation not supported in: " + this.getClass().getName()); @@ -2209,8 +2224,8 @@ protected SecureDESKey translateKeyFromOldLMKImpl(SecureDESKey kd) throws SMExce /** * Your SMAdapter should override this method if it has this functionality. * - * @param key - * @param keySpec + * @param key see method description + * @param keySpec see method description * @return key encrypted under the new LMK * @throws SMException if the parity of the imported key is not adjusted AND checkParity = true */ @@ -2222,7 +2237,7 @@ protected SecureKey translateKeyFromOldLMKImpl(SecureKey key, SecureKeySpec keyS * Your SMAdapter should override this method if it has this functionality * @param spec algorithm specific parameters (contains e.g. key size) * @return key pair generated according to passed parameters - * @throws SMException + * @throws SMException on security module error */ protected Pair generateKeyPairImpl(AlgorithmParameterSpec spec) throws SMException { @@ -2232,9 +2247,9 @@ protected Pair generateKeyPairImpl(AlgorithmParamet /** * Your SMAdapter should override this method if it has this functionality. * - * @param keySpec + * @param keySpec see method description * @return key pair generated according to passed parameters - * @throws SMException + * @throws SMException on security module error */ protected Pair generateKeyPairImpl(SecureKeySpec keySpec) throws SMException { @@ -2247,7 +2262,7 @@ protected Pair generateKeyPairImpl(SecureKeySpec keySpec) * @param privateKey private key used to compute data signature. * @param data data to be sifned. * @return signature of passed data. - * @throws SMException + * @throws SMException on security module error */ protected byte[] calculateSignatureImpl(MessageDigest hash, SecureKey privateKey ,byte[] data) throws SMException { @@ -2262,7 +2277,7 @@ protected byte[] calculateSignatureImpl(MessageDigest hash, SecureKey privateKey * @param algspec algorithm specification * @param iv the inital vector * @return encrypted data block - * @throws SMException + * @throws SMException on security module error */ protected byte[] encryptDataImpl(SecureKey encKey, byte[] data , AlgorithmParameterSpec algspec, byte[] iv) @@ -2278,7 +2293,7 @@ protected byte[] encryptDataImpl(SecureKey encKey, byte[] data * @param algspec algorithm specification * @param iv the inital vector * @return decrypted data block - * @throws SMException + * @throws SMException on security module error */ protected byte[] decryptDataImpl(SecureKey decKey, byte[] data , AlgorithmParameterSpec algspec, byte[] iv) @@ -2292,7 +2307,7 @@ protected byte[] decryptDataImpl(SecureKey decKey, byte[] data * It is recommended that this command is used after keys stored * by the Host have been translated from old to new LMKs. * - * @throws SMException + * @throws SMException on security module error */ protected void eraseOldLMKImpl () throws SMException { throw new SMException("Operation not supported in: " + this.getClass().getName()); diff --git a/jpos/src/main/java/org/jpos/security/CipherMode.java b/jpos/src/main/java/org/jpos/security/CipherMode.java index 5ec990ba8b..afd6586919 100644 --- a/jpos/src/main/java/org/jpos/security/CipherMode.java +++ b/jpos/src/main/java/org/jpos/security/CipherMode.java @@ -21,7 +21,7 @@ /** * Block cipher modes. * - * @author Grzegorz Wieczorek + * @author Grzegorz Wieczorek (grw1@wp.pl) */ public enum CipherMode { diff --git a/jpos/src/main/java/org/jpos/security/CryptographicServiceMessage.java b/jpos/src/main/java/org/jpos/security/CryptographicServiceMessage.java index 9fc3b6226c..d0eee30841 100644 --- a/jpos/src/main/java/org/jpos/security/CryptographicServiceMessage.java +++ b/jpos/src/main/java/org/jpos/security/CryptographicServiceMessage.java @@ -31,7 +31,6 @@ * It is typically the contents of ISOField(123). * For more information refer to ANSI X9.17: Financial Institution Key Mangement * (Wholesale). - *

      * @author Hani S. Kirollos * @version $Revision$ $Date$ */ @@ -41,19 +40,31 @@ public class CryptographicServiceMessage implements Loggeable { Map fields = new LinkedHashMap<>(); String mcl; + /** Message Class Label for RSI. */ public static final String MCL_RSI = "RSI"; + /** Message Class Label for KSM (Key Service Message). */ public static final String MCL_KSM = "KSM"; + /** Message Class Label for RSM. */ public static final String MCL_RSM = "RSM"; + /** Message Class Label for ESM. */ public static final String MCL_ESM = "ESM"; + /** Tag name for Receiver. */ public static final String TAG_RCV = "RCV"; + /** Tag name for Originator. */ public static final String TAG_ORG = "ORG"; + /** Tag name for Server. */ public static final String TAG_SVR = "SVR"; + /** Tag name for Key Data. */ public static final String TAG_KD = "KD" ; + /** Tag name for Clear Text PIN. */ public static final String TAG_CTP = "CTP"; + /** Tag name for Counter. */ public static final String TAG_CTR = "CTR"; + /** Tag name for Error Flag. */ public static final String TAG_ERF = "ERF"; + /** Exception thrown when CSM parsing fails. */ public static class ParsingException extends Exception { private static final long serialVersionUID = 6984718759445061L; @@ -65,6 +76,7 @@ public ParsingException(String detail) { } } + /** Default constructor. */ public CryptographicServiceMessage() { } @@ -76,10 +88,18 @@ public CryptographicServiceMessage(String mcl) { setMCL(mcl); } + /** + * Sets the message class label. + * @param mcl the message class label (e.g. MCL_KSM, MCL_RSM) + */ public void setMCL(String mcl) { this.mcl = mcl; } + /** + * Returns the message class label. + * @return the message class label + */ public String getMCL() { return mcl; } @@ -134,6 +154,7 @@ public String getFieldContent(String tag) { * This is the inverse of parse * @return the CSM in string format */ + /** {@inheritDoc} */ @Override public String toString() { StringBuilder csm = new StringBuilder(); @@ -159,6 +180,7 @@ public String toString() { * @see org.jpos.util.Loggeable */ @Override + /** {@inheritDoc} */ public void dump (PrintStream p, String indent) { String inner = indent + " "; p.print(indent + " * Each value repesents byte 11 of the Keyblok Header. - *

      */ public enum Exportability { diff --git a/jpos/src/main/java/org/jpos/security/KeyScheme.java b/jpos/src/main/java/org/jpos/security/KeyScheme.java index 5a616c5b52..c7bc4357c3 100644 --- a/jpos/src/main/java/org/jpos/security/KeyScheme.java +++ b/jpos/src/main/java/org/jpos/security/KeyScheme.java @@ -57,7 +57,7 @@ public enum KeyScheme { T, /** - * Encryption of single/double/triple-length DES & AES keys using the ANSI + * Encryption of single/double/triple-length DES & AES keys using the ANSI * X9 TR-31 Key Block methods. *

      * Only used for exporting keys (e.g. under a KEK). @@ -70,7 +70,7 @@ public enum KeyScheme { R, /** - * Encryption of all DES, AES, HMAC & RSA keys using proprietary Key Block + * Encryption of all DES, AES, HMAC & RSA keys using proprietary Key Block * methods. *

      * Used for encrypting keys for local use (under a Key Block LMK) or diff --git a/jpos/src/main/java/org/jpos/security/KeySerialNumber.java b/jpos/src/main/java/org/jpos/security/KeySerialNumber.java index ac0797d885..6517c0f379 100644 --- a/jpos/src/main/java/org/jpos/security/KeySerialNumber.java +++ b/jpos/src/main/java/org/jpos/security/KeySerialNumber.java @@ -101,7 +101,7 @@ public String getDeviceID () { /** * Returns the deviceID as an array of bytes. * - * @ return a 3 bytes array representing the deviceID + * @return a 3 bytes array representing the deviceID */ public byte[] getDeviceIDBytes () { ByteBuffer buf = ByteBuffer.allocate(8); @@ -124,7 +124,7 @@ public String getTransactionCounter () { /** * Returns the transaction counter as an array of bytes. * - * @ return a 3 byte array representing the transaction counter. + * @return a 3 byte array representing the transaction counter. */ public byte[] getTransactionCounterBytes () { ByteBuffer buf = ByteBuffer.allocate(4); diff --git a/jpos/src/main/java/org/jpos/security/ModeOfUse.java b/jpos/src/main/java/org/jpos/security/ModeOfUse.java index 22e82b0a27..0bd367998a 100644 --- a/jpos/src/main/java/org/jpos/security/ModeOfUse.java +++ b/jpos/src/main/java/org/jpos/security/ModeOfUse.java @@ -35,7 +35,7 @@ public enum ModeOfUse { ENCDEC ('B', "Encryption and Decryption"), /** - * The key may be used to perform MAC calculation (both generate & + * The key may be used to perform MAC calculation (both generate & * verify) operations. */ GENVER ('C', "Verification and Generation of MAC, CVD"), diff --git a/jpos/src/main/java/org/jpos/security/SMAdapter.java b/jpos/src/main/java/org/jpos/security/SMAdapter.java index fe52acd143..40eeb04ced 100644 --- a/jpos/src/main/java/org/jpos/security/SMAdapter.java +++ b/jpos/src/main/java/org/jpos/security/SMAdapter.java @@ -41,6 +41,8 @@ * @author Hani S. Kirollos * @author Robert Demski * @version $Revision$ $Date$ + + * @param the SecureKey implementation type */ public interface SMAdapter { /** @@ -231,7 +233,7 @@ public interface SMAdapter { /** * PIN Block Format 35 is the required by Europay/MasterCard - * for their Pay Now & Pay Later products. + * for their Pay Now & Pay Later products. */ byte FORMAT35 = (byte)35; @@ -271,7 +273,7 @@ public interface SMAdapter { * @param keyType type of the key to be generated (TYPE_ZMK, TYPE_TMK...etc) * @param keyLength bit length of the key to be generated (LENGTH_DES, LENGTH_DES3_2KEY...) * @return the random key secured by the security module
      - * @throws SMException + * @throws SMException on security module error */ SecureDESKey generateKey(short keyLength, String keyType) throws SMException; @@ -281,7 +283,7 @@ public interface SMAdapter { * @param keySpec the specification of the key to be generated * (length, type, usage, algorithm, etc) * @return the random key secured by the security module - * @throws SMException + * @throws SMException on security module error * @see SecureKeySpec */ SecureKey generateKey(SecureKeySpec keySpec) throws SMException; @@ -292,7 +294,7 @@ public interface SMAdapter { * * @param kd the key with untrusted or fake Key Check Value * @return key check value bytes - * @throws SMException + * @throws SMException on security module error */ byte[] generateKeyCheckValue(T kd) throws SMException; @@ -307,7 +309,7 @@ public interface SMAdapter { * @param key key to be translated to {@code destKeyScheme} scheme * @param keyScheme destination key scheme * @return translated key with {@code destKeyScheme} scheme - * @throws SMException + * @throws SMException on security module error */ SecureDESKey translateKeyScheme(SecureDESKey key, KeyScheme keyScheme) throws SMException; @@ -352,7 +354,7 @@ SecureKey importKey(SecureKey kek, SecureKey key, SecureKeySpec keySpec, boolean * @param key the secure key to be exported * @param kek the key-encrypting key * @return the exported key (key encrypted under kek) - * @throws SMException + * @throws SMException on security module error */ byte[] exportKey(SecureDESKey key, SecureDESKey kek) throws SMException; @@ -364,7 +366,7 @@ SecureKey importKey(SecureKey kek, SecureKey key, SecureKeySpec keySpec, boolean * @param keySpec the specification of the key to be exported. It allows * passing or change key block attributes. * @return the exported key (key encrypted under kek) - * @throws SMException + * @throws SMException on security module error */ SecureKey exportKey(SecureKey kek, SecureKey key, SecureKeySpec keySpec) throws SMException; @@ -376,7 +378,7 @@ SecureKey exportKey(SecureKey kek, SecureKey key, SecureKeySpec keySpec) * @param pin clear pin as entered by card holder * @param accountNumber account number, including BIN and the check digit * @return PIN under LMK - * @throws SMException + * @throws SMException on security module error */ EncryptedPIN encryptPIN(String pin, String accountNumber) throws SMException; @@ -389,7 +391,7 @@ SecureKey exportKey(SecureKey kek, SecureKey key, SecureKeySpec keySpec) * or if parameter extract is true then 12 right-most digits of the account number, excluding the check digit * @param extract true to extract 12 right-most digits off the account number * @return PIN under LMK - * @throws SMException + * @throws SMException on security module error */ EncryptedPIN encryptPIN(String pin, String accountNumber, boolean extract) throws SMException; @@ -401,16 +403,16 @@ SecureKey exportKey(SecureKey kek, SecureKey key, SecureKeySpec keySpec) * @param accountNumber account number, including BIN and the check digit. * @param pek PIN encryption key. * @return Return PIN under PEK. - * @throws SMException + * @throws SMException on security module error */ EncryptedPIN encryptPIN(String pin, String accountNumber, T pek) throws SMException; /** * Decrypts an Encrypted PIN (under LMK). *

      CAUTION: The use of clear pin presents a significant security risk - * @param pinUnderLmk + * @param pinUnderLmk the encrypted PIN under LMK * @return clear pin as entered by card holder - * @throws SMException + * @throws SMException on security module error */ String decryptPIN(EncryptedPIN pinUnderLmk) throws SMException; @@ -421,7 +423,7 @@ SecureKey exportKey(SecureKey kek, SecureKey key, SecureKeySpec keySpec) * @param pinUnderKd1 the encrypted PIN * @param kd1 Data Key under which the pin is encrypted * @return pin encrypted under LMK - * @throws SMException + * @throws SMException on security module error */ EncryptedPIN importPIN(EncryptedPIN pinUnderKd1, T kd1) throws SMException; @@ -435,7 +437,7 @@ SecureKey exportKey(SecureKey kek, SecureKey key, SecureKeySpec keySpec) * @param kd2 the destination Data Key 2 under which the pin will be encrypted * @param destinationPINBlockFormat the PIN Block Format of the exported encrypted PIN * @return pin encrypted under KD2 - * @throws SMException + * @throws SMException on security module error */ EncryptedPIN translatePIN(EncryptedPIN pinUnderKd1, T kd1, T kd2, byte destinationPINBlockFormat) throws SMException; @@ -452,7 +454,7 @@ EncryptedPIN translatePIN(EncryptedPIN pinUnderKd1, T kd1, * @param ksn Key Serial Number (also called Key Name, in ANSI X9.24) needed to derive the transaction key * @param bdk Base Derivation Key, used to derive the transaction key underwhich the pin is encrypted * @return pin encrypted under LMK - * @throws SMException + * @throws SMException on security module error */ @Deprecated EncryptedPIN importPIN(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, T bdk) @@ -468,7 +470,7 @@ EncryptedPIN importPIN(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, T bdk) * @param bdk Base Derivation Key, used to derive the transaction key underwhich the pin is encrypted * @param tdes Use Triple DES to calculate derived transaction key. * @return pin encrypted under LMK - * @throws SMException + * @throws SMException on security module error */ EncryptedPIN importPIN(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, T bdk, boolean tdes) throws SMException; @@ -487,7 +489,7 @@ EncryptedPIN importPIN(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, * @param kd2 the destination Data Key (also called session key) under which the pin will be encrypted * @param destinationPINBlockFormat the PIN Block Format of the translated encrypted PIN * @return pin encrypted under kd2 - * @throws SMException + * @throws SMException on security module error */ @Deprecated EncryptedPIN translatePIN(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, @@ -506,7 +508,7 @@ EncryptedPIN translatePIN(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, * @param destinationPINBlockFormat the PIN Block Format of the translated encrypted PIN * @param tdes Use Triple DES to calculate derived transaction key. * @return pin encrypted under kd2 - * @throws SMException + * @throws SMException on security module error */ EncryptedPIN translatePIN(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, T bdk, T kd2, byte destinationPINBlockFormat, boolean tdes) throws SMException; @@ -521,7 +523,7 @@ EncryptedPIN translatePIN(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, * @param kd2 the destination data key (also called session key) under which the pin will be encrypted * @param destinationPINBlockFormat the PIN Block Format of the exported encrypted PIN * @return pin encrypted under kd2 - * @throws SMException + * @throws SMException on security module error */ EncryptedPIN exportPIN(EncryptedPIN pinUnderLmk, T kd2, byte destinationPINBlockFormat) throws SMException; @@ -534,7 +536,7 @@ EncryptedPIN translatePIN(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, * @param pinLen length of the pin, usually in range 4-12. * Value 0 means that default length is assumed by HSM (usually 4) * @return generated PIN under LMK - * @throws SMException + * @throws SMException on security module error */ EncryptedPIN generatePIN(String accountNumber, int pinLen) throws SMException; @@ -550,7 +552,7 @@ EncryptedPIN generatePIN(String accountNumber, int pinLen) * @param excludes list of pins which won't be generated. * Each pin has to be pinLen length * @return generated PIN under LMK - * @throws SMException + * @throws SMException on security module error */ EncryptedPIN generatePIN(String accountNumber, int pinLen, List excludes) throws SMException; @@ -573,7 +575,7 @@ EncryptedPIN generatePIN(String accountNumber, int pinLen, List excludes * map argument except PIN which is passed in argument {@code pinUnderKd1}. * @param fields map of tags values representing solicitation data to include * in template. null if no solicitation data are passed - * @throws SMException + * @throws SMException on security module error */ void printPIN(String accountNo, EncryptedPIN pinUnderKd1, T kd1 , String template, Map fields) throws SMException; @@ -610,7 +612,7 @@ String calculatePVV(EncryptedPIN pinUnderLmk, T pvkA, T pvkB, int pvkIdx) * @param excludes list of pins which won't be generated. * Each pin has to be pinLen length * @return PVV (VISA PIN Verification Value) - * @throws SMException + * @throws SMException on security module error */ String calculatePVV(EncryptedPIN pinUnderLmk, T pvkA, T pvkB, int pvkIdx, List excludes) throws SMException; @@ -628,7 +630,7 @@ String calculatePVV(EncryptedPIN pinUnderLmk, T pvkA, T pvkB, int pvkIdx, * @param pvkB second key PVK in PVK pair * @param pvkIdx index of the PVK, in range 0-6, if not present 0 is assumed * @return PVV (VISA PIN Verification Value) - * @throws SMException + * @throws SMException on security module error */ String calculatePVV(EncryptedPIN pinUnderKd1, T kd1, T pvkA, T pvkB, int pvkIdx) throws SMException; @@ -649,7 +651,7 @@ String calculatePVV(EncryptedPIN pinUnderKd1, T kd1, T pvkA, T pvkB, int pvkIdx) * Each pin has to be pinLen length * @return PVV (VISA PIN Verification Value) * @throws WeakPINException if passed PIN is on {@code excludes} list - * @throws SMException + * @throws SMException on security module error */ String calculatePVV(EncryptedPIN pinUnderKd1, T kd1, T pvkA, T pvkB, int pvkIdx, List excludes) throws SMException; @@ -668,7 +670,7 @@ String calculatePVV(EncryptedPIN pinUnderKd1, T kd1, T pvkA, T pvkB, int pvkIdx, * @param pvki index of the PVK, in range 0-6, if not present 0 is assumed * @param pvv (VISA PIN Verification Value) * @return true if pin is valid false if not - * @throws SMException + * @throws SMException on security module error */ boolean verifyPVV(EncryptedPIN pinUnderKd1, T kd1, T pvkA, T pvkB, int pvki, String pvv) throws SMException; @@ -690,7 +692,7 @@ boolean verifyPVV(EncryptedPIN pinUnderKd1, T kd1, T pvkA, * the first digits of the card number * @param minPinLen pin minimal length * @return IBM PIN Offset - * @throws SMException + * @throws SMException on security module error */ String calculateIBMPINOffset(EncryptedPIN pinUnderLmk, T pvk, String decTab, String pinValData, @@ -717,7 +719,7 @@ String calculateIBMPINOffset(EncryptedPIN pinUnderLmk, T pvk, * Each pin has to be pinLen length * @return IBM PIN Offset * @throws WeakPINException if passed PIN is on {@code excludes} list - * @throws SMException + * @throws SMException on security module error */ String calculateIBMPINOffset(EncryptedPIN pinUnderLmk, T pvk, String decTab, String pinValData, int minPinLen, @@ -742,7 +744,7 @@ String calculateIBMPINOffset(EncryptedPIN pinUnderLmk, T pvk, * the first digits of the card number * @param minPinLen pin minimal length * @return IBM PIN Offset - * @throws SMException + * @throws SMException on security module error */ String calculateIBMPINOffset(EncryptedPIN pinUnderKd1, T kd1, T pvk, String decTab, String pinValData, @@ -770,7 +772,7 @@ String calculateIBMPINOffset(EncryptedPIN pinUnderKd1, T kd1, * Each pin has to be pinLen length * @return IBM PIN Offset * @throws WeakPINException if passed PIN is on {@code excludes} list - * @throws SMException + * @throws SMException on security module error */ String calculateIBMPINOffset(EncryptedPIN pinUnderKd1, T kd1, T pvk, String decTab, String pinValData, @@ -794,7 +796,7 @@ String calculateIBMPINOffset(EncryptedPIN pinUnderKd1, T kd1, * the first digits of the card number * @param minPinLen min pin length * @return true if pin offset is valid false if not - * @throws SMException + * @throws SMException on security module error */ boolean verifyIBMPINOffset(EncryptedPIN pinUnderKd1, T kd1, T pvk, String offset, String decTab, String pinValData, @@ -822,7 +824,7 @@ boolean verifyIBMPINOffset(EncryptedPIN pinUnderKd1, T kd1, T pvk, * @param minPinLen min pin length * @param offset IBM PIN Offset * @return PIN under LMK - * @throws SMException + * @throws SMException on security module error */ EncryptedPIN deriveIBMPIN(String accountNo, T pvk , String decTab, String pinValData, int minPinLen @@ -848,7 +850,7 @@ EncryptedPIN deriveIBMPIN(String accountNo, T pvk *

    • "999" for inclusion iCVV/Chip CVC on EMV chip card
      • *
    * @return Card Verification Code/Value - * @throws SMException + * @throws SMException on security module error * @deprecated Issuers do not always follow the recommended 'yyMM' format. * Using the {@code java.util.Date} prevents from format manipulating to * solve problem. Use {@link #calculateCVD} with string version of {@code expDate} @@ -877,7 +879,7 @@ String calculateCVV(String accountNo, T cvkA, T cvkB, *
  • "999" for inclusion iCVV/Chip CVC on EMV chip card
    • *
* @return Card Verification Digit (Code/Value) - * @throws SMException + * @throws SMException on security module error */ String calculateCVD(String accountNo, T cvkA, T cvkB, String expDate, String serviceCode) throws SMException; @@ -908,7 +910,7 @@ String calculateCVD(String accountNo, T cvkA, T cvkB, * A 2 decimal digits value must be suppiled. * @return Cardholder Authentication Verification Value/Accountholder * Authentication Value - * @throws SMException + * @throws SMException on security module error */ String calculateCAVV(String accountNo, T cvk, String upn, String authrc, String sfarc) throws SMException; @@ -932,7 +934,7 @@ String calculateCAVV(String accountNo, T cvk, String upn, *
  • "999" for verifing iCVV/Chip CVC included on EMV chip card
    • * * @return true if CVV/CVC is valid or false if not - * @throws SMException + * @throws SMException on security module error * @deprecated Issuers do not always follow the recommended 'yyMM' format. * Using the {@code java.util.Date} prevents from format manipulating to * solve problem. Use {@link #verifyCVD} with string version of {@code expDate} @@ -961,7 +963,7 @@ boolean verifyCVV(String accountNo, T cvkA, T cvkB, *
  • "999" for verifing iCVV/Chip CVC included on EMV chip card
    • * * @return {@code true} if CVV/CVC is valid or {@code false} otherwise - * @throws SMException + * @throws SMException on security module error */ boolean verifyCVD(String accountNo, T cvkA, T cvkB, String cvv, String expDate, String serviceCode) throws SMException; @@ -992,7 +994,7 @@ boolean verifyCVD(String accountNo, T cvkA, T cvkB, * A value based on the result of second factor authentication. * A 2 decimal digits value must be suppiled. * @return true if CAVV/AAV is valid or false if not - * @throws SMException + * @throws SMException on security module error */ boolean verifyCAVV(String accountNo, T cvk, String cavv, String upn, String authrc, String sfarc) throws SMException; @@ -1004,11 +1006,13 @@ boolean verifyCAVV(String accountNo, T cvk, String cavv, *

    The EMV "Track 2 Equivalent Data", provided in the authorisation * message and originating from the contactless smart card, is the source * for the following data elements used in this function: + *

      *
    • {@code accountNo} *
    • {@code expDate} *
    • {@code serviceCode} *
    • {@code atc} *
    • {@code dCVV} + *
    * * @param accountNo The account number including BIN and the check digit * @param imkac the issuer master key for generating and verifying Application Cryptograms @@ -1020,7 +1024,7 @@ boolean verifyCAVV(String accountNo, T cvk, String cavv, * @param mkdm ICC Master Key Derivation Method. If {@code null} specified * is assumed. * @return {@code true} if {@code dcvv} is valid, or {@code false} if not - * @throws SMException + * @throws SMException on security module error * @deprecated Issuers do not always follow the recommended 'yyMM' format. * Using the {@code java.util.Date} prevents from format manipulating to * solve problem. Use {@link #verifydCVV} with string version of {@code expDate} @@ -1054,7 +1058,7 @@ boolean verifydCVV(String accountNo, T imkac, String dcvv, * @param mkdm ICC Master Key Derivation Method. If {@code null} specified * is assumed. * @return {@code true} if {@code dcvv} is valid, or {@code false} if not - * @throws SMException + * @throws SMException on security module error */ boolean verifydCVV(String accountNo, T imkac, String dcvv, String expDate, String serviceCode, byte[] atc, MKDMethod mkdm) @@ -1090,10 +1094,10 @@ boolean verifydCVV(String accountNo, T imkac, String dcvv, * provided in the authorisation message and originating from * the contactless smart card. Usually variable part of * Discreditionary Data are replased by some static value. - *
  • precomputed Initial Vector for CVC3 calculation - * (IVCVC3) which is a MAC calculated over + *
  • precomputed Initial Vector for {@code CVC3} calculation + * {@code (IVCVC3)} which is a {@code MAC} calculated over * the static part of Track1 or Track2 data using the key derived - * from MK-CVC3. + * from {@code MK-CVC3}. * * @param mkdm ICC Master Key Derivation Method. If {@code null} specified * is assumed. @@ -1102,7 +1106,7 @@ boolean verifydCVV(String accountNo, T imkac, String dcvv, * of 2 byte value). Is possible to pass shorter cvc3 value e.g. * {@code "789"} matches with calcuated CVC3 {@code "04789"} * @return true if cvc3 is valid false if not - * @throws SMException + * @throws SMException on security module error */ boolean verifyCVC3(T imkcvc3, String accountNo, String acctSeqNo, byte[] atc, byte[] upn, byte[] data, MKDMethod mkdm, String cvc3) @@ -1139,7 +1143,7 @@ boolean verifyCVC3(T imkcvc3, String accountNo, String acctSeqNo, * If alternative padding methods are required, it have to be * applied before. * @return true if ARQC/TC/AAC is passed or false if not - * @throws SMException + * @throws SMException on security module error */ boolean verifyARQC(MKDMethod mkdm, SKDMethod skdm, T imkac , String accountNo, String acctSeqNo, byte[] arqc, byte[] atc @@ -1177,7 +1181,7 @@ boolean verifyARQC(MKDMethod mkdm, SKDMethod skdm, T imkac * {@link ARPCMethod#METHOD_2} in other case is ignored. * @return calculated 8 bytes ARPC or if {@code arpcMethod} equals * {@link ARPCMethod#METHOD_2} 4 bytes ARPC - * @throws SMException + * @throws SMException on security module error */ byte[] generateARPC(MKDMethod mkdm, SKDMethod skdm, T imkac , String accoutNo, String acctSeqNo, byte[] arqc, byte[] atc, byte[] upn @@ -1228,7 +1232,7 @@ byte[] generateARPC(MKDMethod mkdm, SKDMethod skdm, T imkac * @return if ARQC/TC/AAC verification passed then calculated 8 bytes ARPC * or for {@code arpcMethod} equals {@link ARPCMethod#METHOD_2} * 4 bytes ARPC, null in other case - * @throws SMException + * @throws SMException on security module error */ byte[] verifyARQCGenerateARPC(MKDMethod mkdm, SKDMethod skdm, T imkac , String accountNo, String acctSeqNo, byte[] arqc, byte[] atc, byte[] upn @@ -1261,7 +1265,7 @@ byte[] verifyARQCGenerateARPC(MKDMethod mkdm, SKDMethod skdm, T imkac * APDU command e.g. PIN Unblock, Application block/unblock * with some additional application dependent data * @return generated 8 bytes MAC - * @throws SMException + * @throws SMException on security module error */ byte[] generateSM_MAC(MKDMethod mkdm, SKDMethod skdm , T imksmi, String accountNo, String acctSeqNo @@ -1288,6 +1292,7 @@ byte[] generateSM_MAC(MKDMethod mkdm, SKDMethod skdm * @param padm padding method. If null {@code padm} is derived as follow: *
    * + * * * * @@ -1329,7 +1334,7 @@ byte[] generateSM_MAC(MKDMethod mkdm, SKDMethod skdm *
    {@link SMAdapter#FORMAT42} Visa/Amex format using Current PIN * * @return Pair of values, encrypted PIN and 8 bytes MAC - * @throws SMException + * @throws SMException on security module error */ Pair translatePINGenerateSM_MAC(MKDMethod mkdm , SKDMethod skdm, PaddingMethod padm, T imksmi @@ -1352,7 +1357,7 @@ Pair translatePINGenerateSM_MAC(MKDMethod mkdm * will contain new iv value. Not used for {@link CipherMode#ECB}. * @return encrypted data. In {@code iv} array refference new value of * initial vector value will be placed. - * @throws SMException + * @throws SMException on security module error */ byte[] encryptData(CipherMode cipherMode, SecureDESKey kd , byte[] data, byte[] iv) throws SMException; @@ -1370,7 +1375,7 @@ byte[] encryptData(CipherMode cipherMode, SecureDESKey kd * will contain new iv value. Not used for {@link CipherMode#ECB}. * @return decrypted data. In {@code iv} array refference new value of * initial vector value will be placed. - * @throws SMException + * @throws SMException on security module error */ byte[] decryptData(CipherMode cipherMode, SecureDESKey kd , byte[] data, byte[] iv) throws SMException; @@ -1384,7 +1389,7 @@ byte[] decryptData(CipherMode cipherMode, SecureDESKey kd * @param data the data to be MACed * @param kd the key used for MACing * @return the MAC - * @throws SMException + * @throws SMException on security module error */ byte[] generateCBC_MAC(byte[] data, T kd) throws SMException; @@ -1395,7 +1400,7 @@ byte[] decryptData(CipherMode cipherMode, SecureDESKey kd * @param data the data to be MACed * @param kd the key used for MACing * @return the MAC - * @throws SMException + * @throws SMException on security module error */ byte[] generateEDE_MAC(byte[] data, T kd) throws SMException; @@ -1405,7 +1410,7 @@ byte[] decryptData(CipherMode cipherMode, SecureDESKey kd * * @param kd the key encrypted under old LMK * @return key encrypted under the new LMK - * @throws SMException + * @throws SMException on security module error */ SecureDESKey translateKeyFromOldLMK(SecureDESKey kd) throws SMException; @@ -1418,7 +1423,7 @@ byte[] decryptData(CipherMode cipherMode, SecureDESKey kd * @param keySpec the specification of the key to be translated. It allows * passing new key block attributes. * @return key encrypted under the new LMK - * @throws SMException + * @throws SMException on security module error */ SecureKey translateKeyFromOldLMK(SecureKey key, SecureKeySpec keySpec) throws SMException; @@ -1429,7 +1434,7 @@ byte[] decryptData(CipherMode cipherMode, SecureDESKey kd * @param spec algorithm specific parameters, e.g. algorithm, key size, * public key exponent. * @return key pair generated according to passed parameters - * @throws SMException + * @throws SMException on security module error */ Pair generateKeyPair(AlgorithmParameterSpec spec) throws SMException; @@ -1443,7 +1448,7 @@ Pair generateKeyPair(AlgorithmParameterSpec spec) * NOTE: For pass an extra key usage of the RSA key, possible is use * e.g. {@code keySpec.setVariant()} or {@code keySpec.setReserved()} * @return key pair generated according to passed parameters - * @throws SMException + * @throws SMException on security module error */ Pair generateKeyPair(SecureKeySpec keySpec) throws SMException; @@ -1455,7 +1460,7 @@ Pair generateKeyPair(AlgorithmParameterSpec spec) * @param privateKey private key used to compute data signature. * @param data data to be signed. * @return signature of passed data. - * @throws SMException + * @throws SMException on security module error */ byte[] calculateSignature(MessageDigest hash, SecureKey privateKey ,byte[] data) throws SMException; @@ -1481,7 +1486,7 @@ byte[] calculateSignature(MessageDigest hash, SecureKey privateKey * cipher or ECB mode). If used, after operation will contain new * {@code iv} value. * @return encrypted data block - * @throws SMException + * @throws SMException on security module error */ byte[] encryptData(SecureKey encKey, byte[] data , AlgorithmParameterSpec algspec, byte[] iv) throws SMException; @@ -1507,7 +1512,7 @@ byte[] encryptData(SecureKey encKey, byte[] data * cipher or ECB mode). If used, after operation will contain new * {@code iv} value. * @return decrypted data block - * @throws SMException + * @throws SMException on security module error */ byte[] decryptData(SecureKey decKey, byte[] data , AlgorithmParameterSpec algspec, byte[] iv) throws SMException; @@ -1519,7 +1524,7 @@ byte[] decryptData(SecureKey decKey, byte[] data * It is recommended that this command is used after keys stored * by the Host have been translated from old to new LMKs. * - * @throws SMException + * @throws SMException on security module error */ void eraseOldLMK() throws SMException; @@ -1528,6 +1533,7 @@ byte[] decryptData(SecureKey decKey, byte[] data * @param bdk base derivation key * @param clearText clear Text * @return cyphertext + * @throws SMException on security module error */ byte[] dataEncrypt(T bdk, byte[] clearText) throws SMException; @@ -1536,6 +1542,7 @@ byte[] decryptData(SecureKey decKey, byte[] data * @param bdk base derivation key * @param cypherText clear Text * @return cleartext + * @throws SMException on security module error */ byte[] dataDecrypt(T bdk, byte[] cypherText) throws SMException; @@ -1546,15 +1553,15 @@ byte[] decryptData(SecureKey decKey, byte[] data * @param keyType possible values are those defined in the SecurityModule inteface. e.g., ZMK, TMK,... * @param clearComponent up to three HexStrings containing key components * @return forms an SecureDESKey from two clear components - * @throws SMException + * @throws SMException on security module error */ SecureDESKey formKEYfromClearComponents(short keyLength, String keyType, String... clearComponent) throws SMException; /** * Generates a random clear key component. - * @param keyLength + * @param keyLength the length of the key in bits * @return clear key componenet - * @throws SMException + * @throws SMException on security module error */ default String generateClearKeyComponent(short keyLength) throws SMException { throw new SMException("Operation not supported in: " + this.getClass().getName()); diff --git a/jpos/src/main/java/org/jpos/security/jceadapter/Console.java b/jpos/src/main/java/org/jpos/security/jceadapter/Console.java index 3947b4b596..2d15a50854 100644 --- a/jpos/src/main/java/org/jpos/security/jceadapter/Console.java +++ b/jpos/src/main/java/org/jpos/security/jceadapter/Console.java @@ -37,18 +37,26 @@ * @author Hani Samuel Kirollos * @version $Revision$ $Date$ */ +/** Simple command-line console for testing the JCE security module. */ public class Console { + /** Default constructor. */ public Console () { } /** - * @param args + * @param args command-line arguments passed to {@link #exec} */ public static void main (String[] args) { new Console().exec(System.out,System.err,args); } + /** + * Runs the JCE security module console with the given I/O streams. + * @param outPS output stream + * @param errPS error stream + * @param args command-line arguments + */ public void exec(PrintStream outPS,PrintStream errPS,String[] args) { JCESecurityModule sm = new JCESecurityModule(); diff --git a/jpos/src/main/java/org/jpos/security/jceadapter/JCEHandler.java b/jpos/src/main/java/org/jpos/security/jceadapter/JCEHandler.java index f255910df2..bb81ae9ce1 100644 --- a/jpos/src/main/java/org/jpos/security/jceadapter/JCEHandler.java +++ b/jpos/src/main/java/org/jpos/security/jceadapter/JCEHandler.java @@ -41,7 +41,7 @@ * Provides some higher level methods that are needed by the JCE Security Module, yet they are generic and can be used elsewhere. *

    *

    - * It depends on the JavaTM Cryptography Extension (JCE). + * It depends on the Java™ Cryptography Extension (JCE). *

    * * @author Hani S. Kirollos diff --git a/jpos/src/main/java/org/jpos/security/jceadapter/JCESecurityModule.java b/jpos/src/main/java/org/jpos/security/jceadapter/JCESecurityModule.java index 4fc75bf952..9150fab193 100644 --- a/jpos/src/main/java/org/jpos/security/jceadapter/JCESecurityModule.java +++ b/jpos/src/main/java/org/jpos/security/jceadapter/JCESecurityModule.java @@ -715,11 +715,11 @@ private static byte[] formatPANPSNOptionB(String pan, String psn){ * Derive ICC Master Key from Issuer Master Key and preformated PAN/PANSeqNo * * Compute two 8-byte numbers: - *
  • left part is a result of Tripple-DES encription {@code panpsn} - * with {@code imk} as the key - *
  • right part is a result of Tripple-DES binary inverted - * {@code panpsn} with {@code imk} as the key - *
  • concatenate left and right parts + *
      + *
    • left part is a result of Triple-DES encryption of {@code panpsn} with {@code imk} as the key
      • + *
    • right part is a result of Triple-DES encryption of binary-inverted {@code panpsn} with {@code imk} as the key
      • + *
    • concatenate left and right parts
      • + *
    *
    * Described in EMV v4.2 Book 2, Annex A1.4.1 Master Key Derivation point 2 * diff --git a/jpos/src/main/java/org/jpos/space/JDBMSpace.java b/jpos/src/main/java/org/jpos/space/JDBMSpace.java index 5d577f5810..2af3503ee9 100644 --- a/jpos/src/main/java/org/jpos/space/JDBMSpace.java +++ b/jpos/src/main/java/org/jpos/space/JDBMSpace.java @@ -41,6 +41,9 @@ * @author Kris Leite * @version $Revision$ $Date$ * @since 1.4.7 + + * @param the key type + * @param the value type */ @SuppressWarnings("unchecked") public class JDBMSpace extends TimerTask implements Space, PersistentSpace { diff --git a/jpos/src/main/java/org/jpos/space/JESpace.java b/jpos/src/main/java/org/jpos/space/JESpace.java index e10bbe02bc..a22394e0ed 100644 --- a/jpos/src/main/java/org/jpos/space/JESpace.java +++ b/jpos/src/main/java/org/jpos/space/JESpace.java @@ -50,6 +50,9 @@ * * @author Alejandro Revilla * @since 1.6.5 + + * @param the key type + * @param the value type */ @SuppressWarnings("unchecked") public class JESpace extends Log implements LocalSpace, PersistentSpace, Loggeable, Runnable { diff --git a/jpos/src/main/java/org/jpos/space/LSpace.java b/jpos/src/main/java/org/jpos/space/LSpace.java index 00b439d711..843d0ad9aa 100644 --- a/jpos/src/main/java/org/jpos/space/LSpace.java +++ b/jpos/src/main/java/org/jpos/space/LSpace.java @@ -49,7 +49,6 @@ *
  • Full LocalSpace compatibility: Drop-in replacement with same API and behavior
    • *
  • JFR instrumentation: All operations emit SpaceEvent for monitoring
    • * - *

    * * Concurrency notes (core safety invariants): * - Never remove a KeyEntry from entries while threads are waiting on that entry's hasValue Condition, @@ -59,6 +58,9 @@ * @author Alejandro Revilla * @version $Revision$ $Date$ * @since 3.0 + + * @param the key type + * @param the value type */ @SuppressWarnings("unchecked") public class LSpace implements LocalSpace, Loggeable, Runnable { diff --git a/jpos/src/main/java/org/jpos/space/LocalSpace.java b/jpos/src/main/java/org/jpos/space/LocalSpace.java index 1015e3621d..eccf1ebe04 100644 --- a/jpos/src/main/java/org/jpos/space/LocalSpace.java +++ b/jpos/src/main/java/org/jpos/space/LocalSpace.java @@ -21,8 +21,12 @@ import java.util.Set; /** + * Extension of {@link Space} with blocking read/take operations and space-listener support. * @author Kris, Bharavi, Alejandro * @version $Revision$ $Date$ + + * @param the key type + * @param the value type */ public interface LocalSpace extends Space { /** diff --git a/jpos/src/main/java/org/jpos/space/Space.java b/jpos/src/main/java/org/jpos/space/Space.java index 2e569756b5..48b5b54fda 100644 --- a/jpos/src/main/java/org/jpos/space/Space.java +++ b/jpos/src/main/java/org/jpos/space/Space.java @@ -37,6 +37,9 @@ * @see TSpace * @see SpaceError * @see The Linda Coordination Language + + * @param the key type + * @param the value type */ public interface Space extends AutoCloseable { diff --git a/jpos/src/main/java/org/jpos/space/SpaceFactory.java b/jpos/src/main/java/org/jpos/space/SpaceFactory.java index 2a4c822bf4..e7e3a8a08e 100644 --- a/jpos/src/main/java/org/jpos/space/SpaceFactory.java +++ b/jpos/src/main/java/org/jpos/space/SpaceFactory.java @@ -34,8 +34,6 @@ *
  • optional parameter * *

    - *

    - * * Examples: * * 

    diff --git a/jpos/src/main/java/org/jpos/space/SpaceInterceptor.java b/jpos/src/main/java/org/jpos/space/SpaceInterceptor.java
index 4e784d5e36..20b42f04b8 100644
--- a/jpos/src/main/java/org/jpos/space/SpaceInterceptor.java
+++ b/jpos/src/main/java/org/jpos/space/SpaceInterceptor.java
@@ -23,6 +23,9 @@
  *
  * @author Alejandro Revilla
  * @since  1.4.7
+
+ * @param  the key type
+ * @param  the value type
  */
 public class SpaceInterceptor implements Space {
     protected Space sp;
diff --git a/jpos/src/main/java/org/jpos/space/SpaceListener.java b/jpos/src/main/java/org/jpos/space/SpaceListener.java
index a3a3fad613..d06c16b47c 100644
--- a/jpos/src/main/java/org/jpos/space/SpaceListener.java
+++ b/jpos/src/main/java/org/jpos/space/SpaceListener.java
@@ -19,10 +19,14 @@
 package org.jpos.space;
 
 /**
+ * Callback interface for objects that wish to be notified when entries are added to a {@link Space}.
  * @author Alejandro Revilla
  * @version $Revision$ $Date$
  * @since 2.0
  * @see Space
+
+ * @param  the key type
+ * @param  the value type
  */
 public interface SpaceListener {
     /**
diff --git a/jpos/src/main/java/org/jpos/space/TSpace.java b/jpos/src/main/java/org/jpos/space/TSpace.java
index 7efc6265ac..c103753080 100644
--- a/jpos/src/main/java/org/jpos/space/TSpace.java
+++ b/jpos/src/main/java/org/jpos/space/TSpace.java
@@ -31,6 +31,9 @@
  * @author Alejandro Revilla
  * @version $Revision$ $Date$
  * @since !.4.9
+
+ * @param  the key type
+ * @param  the value type
  */
 
 @SuppressWarnings("unchecked")
diff --git a/jpos/src/main/java/org/jpos/tlv/BinaryTagValue.java b/jpos/src/main/java/org/jpos/tlv/BinaryTagValue.java
index d6c2f8fc68..f6636aed2e 100644
--- a/jpos/src/main/java/org/jpos/tlv/BinaryTagValue.java
+++ b/jpos/src/main/java/org/jpos/tlv/BinaryTagValue.java
@@ -19,10 +19,19 @@
 package org.jpos.tlv;
 
 /**
+ * TLV tag value implementation backed by a binary (byte[]) payload.
  * @author Vishnu Pillai
  */
+/**
+ * A TLV tag-value pair whose value is a raw byte array.
+ */
 public class BinaryTagValue extends TagValueBase {
 
+    /**
+     * Creates a BinaryTagValue with the given tag and byte-array value.
+     * @param tag the hex string tag identifier
+     * @param value the raw byte value
+     */
     public BinaryTagValue(String tag, byte[] value) {
         super(tag, value);
     }
diff --git a/jpos/src/main/java/org/jpos/tlv/CharTag.java b/jpos/src/main/java/org/jpos/tlv/CharTag.java
index 813a5096da..11b2da398e 100644
--- a/jpos/src/main/java/org/jpos/tlv/CharTag.java
+++ b/jpos/src/main/java/org/jpos/tlv/CharTag.java
@@ -25,15 +25,16 @@
  * 
    
  * Processing format:
  * 
      
- *   
    • TAG - the identifier of the tag
      • 
- *   
    • LEN - the length (encoded as decimal digits) of the tag value
      • 
- *   
    • VAL - the value of the tag or missing if length is 0
      • 
+ *   
    • {@code TAG} - the identifier of the tag
      • 
+ *   
    • {@code LEN} - the length (encoded as decimal digits) of the tag value
      • 
+ *   
    • {@code VAL} - the value of the tag or missing if length is 0
      • 
  * 
    
  *
  * @author Robert Demski <drdemsey@gmail.com>
  */
 public class CharTag {
 
+    /** Number of bytes used to encode the tag length. */
     protected int lengthSize = 0x03;
 
     private final String tagId;
diff --git a/jpos/src/main/java/org/jpos/tlv/CharTagMap.java b/jpos/src/main/java/org/jpos/tlv/CharTagMap.java
index fd730d1fa2..1d190452b4 100644
--- a/jpos/src/main/java/org/jpos/tlv/CharTagMap.java
+++ b/jpos/src/main/java/org/jpos/tlv/CharTagMap.java
@@ -33,9 +33,15 @@
  *   
  • length is encoded as decimal characters
  * 
  *
- * @author Grzegorz Wieczorek 
+ * @author Grzegorz Wieczorek (grw1@wp.pl)
+ */
+/** A map of tag identifiers to {@link CharTag} instances. */
+/**
+ * A map of tag identifiers to {@link CharTag} instances.
  */
 public class CharTagMap extends HashMap {
+    /** Default constructor. */
+    public CharTagMap() { super(); }
 
     static final String EXCEPTION_PREFIX = "BAD TLV FORMAT:";
 
@@ -50,11 +56,11 @@ public class CharTagMap extends HashMap {
      * This method creates default TLV tag map which works on TLV data with
      * followng parameters:
      * 
      
-     *   
    • TT - 2 ASCII characters of tag identifier
-     *   
    • LLL - 3 ASCII encoded decimal digits represents
+     *   
    • TT - 2 {@code ASCII} characters of tag identifier
+     *   
    • LLL - 3 {@code ASCII} encoded decimal digits represents
      *      tag value length
      *   
      • 
-     *   
    • VAL - 0 or more (up to 999) ASCII
+     *   
    • VAL - 0 or more (up to 999) {@code ASCII}
      *      encoded characters represents tag value
      *   
      • 
      * 
    
@@ -175,6 +181,11 @@ public CharTag createTLV(String tagId, String value) throws IllegalArgumentExcep
         return tag;
     }
 
+    /**
+     * Validates that the given tag identifier is registered in this map.
+     * @param tagId the tag identifier to validate
+     * @throws IllegalArgumentException if tagId is not a known tag
+     */
     protected void validateTag(String tagId) throws IllegalArgumentException {
         if (tagId == null)
             throw new IllegalArgumentException("Tag identifier have to be specified");
diff --git a/jpos/src/main/java/org/jpos/tlv/CharTagMapBuilder.java b/jpos/src/main/java/org/jpos/tlv/CharTagMapBuilder.java
index e0f62d9d78..eee842937d 100644
--- a/jpos/src/main/java/org/jpos/tlv/CharTagMapBuilder.java
+++ b/jpos/src/main/java/org/jpos/tlv/CharTagMapBuilder.java
@@ -24,13 +24,17 @@
  * Using {@code withTagLengthSwap(true)} while creating the builder causes
  * switchs {@code CharTagMap} in LTV mode.
  *
- * @author Robert Demski 
+ * @author Robert Demski (drdemsey@gmail.com)
  */
+/** Builder for constructing {@link CharTagMap} instances from raw character data. */
 public class CharTagMapBuilder {
 
+    /** Size of the tag field in characters. */
     protected Integer tagSize;
+    /** Size of the length field in characters. */
     protected Integer lengthSize;
 
+    /** Whether tag and length positions are swapped. */
     protected boolean swapTagWithLength;
 
     /**
diff --git a/jpos/src/main/java/org/jpos/tlv/GenericTagSequence.java b/jpos/src/main/java/org/jpos/tlv/GenericTagSequence.java
index 495c8ae170..dee75cc2e2 100644
--- a/jpos/src/main/java/org/jpos/tlv/GenericTagSequence.java
+++ b/jpos/src/main/java/org/jpos/tlv/GenericTagSequence.java
@@ -21,6 +21,7 @@
 import org.jpos.iso.ISOException;
 
 /**
+ * A generic ordered sequence of {@link TagValue} elements.
  * @author Vishnu Pillai
  */
 public class GenericTagSequence extends TagSequenceBase {
diff --git a/jpos/src/main/java/org/jpos/tlv/ISOMsgRef.java b/jpos/src/main/java/org/jpos/tlv/ISOMsgRef.java
index 9331aa9137..4087cd95f7 100644
--- a/jpos/src/main/java/org/jpos/tlv/ISOMsgRef.java
+++ b/jpos/src/main/java/org/jpos/tlv/ISOMsgRef.java
@@ -33,6 +33,7 @@
 
 
 /**
+ * A {@link TagValue} whose value is a reference to an {@link org.jpos.iso.ISOMsg}.
  * @author Vishnu Pillai
  */
 public class ISOMsgRef {
diff --git a/jpos/src/main/java/org/jpos/tlv/ISOMsgTagValue.java b/jpos/src/main/java/org/jpos/tlv/ISOMsgTagValue.java
index 1e5b1ec23e..3374628bec 100644
--- a/jpos/src/main/java/org/jpos/tlv/ISOMsgTagValue.java
+++ b/jpos/src/main/java/org/jpos/tlv/ISOMsgTagValue.java
@@ -21,6 +21,7 @@
 import org.jpos.iso.ISOMsg;
 
 /**
+ * A {@link TagValue} that wraps an {@link org.jpos.iso.ISOMsg} as its value.
  * @author Vishnu Pillai
  *
  */
diff --git a/jpos/src/main/java/org/jpos/tlv/ISOTaggedField.java b/jpos/src/main/java/org/jpos/tlv/ISOTaggedField.java
index 6e2310f26f..704954abf9 100644
--- a/jpos/src/main/java/org/jpos/tlv/ISOTaggedField.java
+++ b/jpos/src/main/java/org/jpos/tlv/ISOTaggedField.java
@@ -31,6 +31,7 @@
 
 
 /**
+ * An {@link org.jpos.iso.ISOComponent} that carries a tagged (TLV) field.
  * @author Vishnu Pillai
  *
  */
diff --git a/jpos/src/main/java/org/jpos/tlv/LiteralTagValue.java b/jpos/src/main/java/org/jpos/tlv/LiteralTagValue.java
index f41bbedb8f..4e5f9ad79b 100644
--- a/jpos/src/main/java/org/jpos/tlv/LiteralTagValue.java
+++ b/jpos/src/main/java/org/jpos/tlv/LiteralTagValue.java
@@ -19,6 +19,7 @@
 package org.jpos.tlv;
 
 /**
+ * A {@link TagValue} backed by a literal string value.
  * @author Vishnu Pillai
  *
  */
diff --git a/jpos/src/main/java/org/jpos/tlv/OffsetIndexedComposite.java b/jpos/src/main/java/org/jpos/tlv/OffsetIndexedComposite.java
index 72d24ce9c1..dbc87c1699 100644
--- a/jpos/src/main/java/org/jpos/tlv/OffsetIndexedComposite.java
+++ b/jpos/src/main/java/org/jpos/tlv/OffsetIndexedComposite.java
@@ -19,6 +19,7 @@
 package org.jpos.tlv;
 
 /**
+ * A composite TLV structure that supports offset-based indexed access to its elements.
  * @author Vishnu Pillai
  *         Date: 1/24/14
  */
diff --git a/jpos/src/main/java/org/jpos/tlv/TLVDataFormat.java b/jpos/src/main/java/org/jpos/tlv/TLVDataFormat.java
index 3ed0784635..dfb66d4a06 100644
--- a/jpos/src/main/java/org/jpos/tlv/TLVDataFormat.java
+++ b/jpos/src/main/java/org/jpos/tlv/TLVDataFormat.java
@@ -20,6 +20,7 @@
 
 
 /**
+ * Describes the data format (encoding, length type) of a TLV field.
  * @author Vishnu Pillai
  */
 public enum TLVDataFormat {
diff --git a/jpos/src/main/java/org/jpos/tlv/TLVList.java b/jpos/src/main/java/org/jpos/tlv/TLVList.java
index fdac5672cd..a9f0a09cb2 100644
--- a/jpos/src/main/java/org/jpos/tlv/TLVList.java
+++ b/jpos/src/main/java/org/jpos/tlv/TLVList.java
@@ -32,6 +32,7 @@
 import java.util.Objects;
 
 /**
+ * An ordered list of TLV (Tag-Length-Value) records.
  * @author bharavi
  */
 
@@ -319,7 +320,7 @@ public TLVMsg findNextTLV() throws IllegalStateException {
      * @param index zero based index of TLV message
      * @return TLV message instance
      * @throws IndexOutOfBoundsException if the index is out of range
-     * (index < 0 || index >= size())
+     * (index < 0 || index >= size())
      */
     public TLVMsg index(int index) throws IndexOutOfBoundsException {
         return tags.get(index);
diff --git a/jpos/src/main/java/org/jpos/tlv/TLVMsg.java b/jpos/src/main/java/org/jpos/tlv/TLVMsg.java
index 0c778f3fdd..e8bd9c7017 100644
--- a/jpos/src/main/java/org/jpos/tlv/TLVMsg.java
+++ b/jpos/src/main/java/org/jpos/tlv/TLVMsg.java
@@ -25,6 +25,7 @@
 import org.jpos.util.Loggeable;
 
 /**
+ * A single TLV (Tag-Length-Value) message element.
  * @author bharavi
  */
 public class TLVMsg implements Loggeable {
diff --git a/jpos/src/main/java/org/jpos/tlv/TagSequence.java b/jpos/src/main/java/org/jpos/tlv/TagSequence.java
index 950bf3b5f8..fdac22e5dc 100644
--- a/jpos/src/main/java/org/jpos/tlv/TagSequence.java
+++ b/jpos/src/main/java/org/jpos/tlv/TagSequence.java
@@ -25,8 +25,11 @@
 import java.util.Map;
 
 /**
+ * An ordered sequence of {@link TagValue} elements of type {@code T}.
  * @author Vishnu Pillai
  *         Date: 4/11/14
+
+ * @param  the tag value type
  */
 public interface TagSequence extends TagValue {
 
diff --git a/jpos/src/main/java/org/jpos/tlv/TagSequenceBase.java b/jpos/src/main/java/org/jpos/tlv/TagSequenceBase.java
index daae2b66e3..df082b2291 100644
--- a/jpos/src/main/java/org/jpos/tlv/TagSequenceBase.java
+++ b/jpos/src/main/java/org/jpos/tlv/TagSequenceBase.java
@@ -30,6 +30,7 @@
 import java.util.TreeMap;
 
 /**
+ * Abstract base for {@link TagSequence} implementations.
  * @author Vishnu Pillai
  */
 public abstract class TagSequenceBase implements TagSequence {
diff --git a/jpos/src/main/java/org/jpos/tlv/TagValue.java b/jpos/src/main/java/org/jpos/tlv/TagValue.java
index b50dd1c164..a6da737cd9 100644
--- a/jpos/src/main/java/org/jpos/tlv/TagValue.java
+++ b/jpos/src/main/java/org/jpos/tlv/TagValue.java
@@ -21,7 +21,10 @@
 import org.jpos.iso.ISOException;
 
 /**
+ * A typed tag-value pair used in TLV (Tag-Length-Value) processing.
  * @author Vishnu Pillai
+
+ * @param  the tag value type
  */
 public interface TagValue {
 
diff --git a/jpos/src/main/java/org/jpos/tlv/TagValueBase.java b/jpos/src/main/java/org/jpos/tlv/TagValueBase.java
index 7d11f76ed4..8707f43302 100644
--- a/jpos/src/main/java/org/jpos/tlv/TagValueBase.java
+++ b/jpos/src/main/java/org/jpos/tlv/TagValueBase.java
@@ -19,7 +19,10 @@
 package org.jpos.tlv;
 
 /**
+ * Abstract base for {@link TagValue} implementations.
  * @author Vishnu Pillai
+
+ * @param  the tag value type
  */
 public abstract class TagValueBase implements TagValue {
 
diff --git a/jpos/src/main/java/org/jpos/tlv/packager/BinaryHexTaggedSequencePackager.java b/jpos/src/main/java/org/jpos/tlv/packager/BinaryHexTaggedSequencePackager.java
index 3627b14cd4..08c58adf3e 100644
--- a/jpos/src/main/java/org/jpos/tlv/packager/BinaryHexTaggedSequencePackager.java
+++ b/jpos/src/main/java/org/jpos/tlv/packager/BinaryHexTaggedSequencePackager.java
@@ -24,10 +24,19 @@
 import org.jpos.iso.ISOUtil;
 
 /**
+ * Packager for tagged TLV sequences where the tag and length are encoded as binary hex.
  * @author Vishnu Pillai
  */
+/** {@link TaggedSequencePackager} variant that uses binary hex encoding for tag-length-value fields. */
+/**
+ * {@link TaggedSequencePackager} variant that encodes tag-value data as binary hex.
+ */
 public class BinaryHexTaggedSequencePackager extends TaggedSequencePackager {
 
+    /**
+     * Default constructor.
+     * @throws ISOException on configuration error
+     */
     public BinaryHexTaggedSequencePackager() throws ISOException {
         super();
     }
@@ -37,8 +46,14 @@ protected ISOFieldPackager getTagPackager() {
         return new TagPackager(this.tag.length(), "Tag");
     }
 
+    /** Field packager for TLV tag fields. */
     public static class TagPackager extends ISOFieldPackager {
 
+        /**
+         * Creates a TagPackager with the given length and description.
+         * @param len tag field length
+         * @param description field description
+         */
         public TagPackager(int len, String description) {
             super(len, description);
         }
diff --git a/jpos/src/main/java/org/jpos/tlv/packager/IFB_LHBINARY.java b/jpos/src/main/java/org/jpos/tlv/packager/IFB_LHBINARY.java
index 2a9213aae2..93813d9244 100644
--- a/jpos/src/main/java/org/jpos/tlv/packager/IFB_LHBINARY.java
+++ b/jpos/src/main/java/org/jpos/tlv/packager/IFB_LHBINARY.java
@@ -23,6 +23,7 @@
 import org.jpos.iso.LiteralBinaryInterpreter;
 
 /**
+ * ISOFieldPackager for a binary field with a binary-hex length prefix.
  * @author Vishnu Pillai
  */
 public class IFB_LHBINARY extends ISOBinaryFieldPackager {
diff --git a/jpos/src/main/java/org/jpos/tlv/packager/IFTA_LLBINARY.java b/jpos/src/main/java/org/jpos/tlv/packager/IFTA_LLBINARY.java
index 1224e07a1c..cbbf11823e 100644
--- a/jpos/src/main/java/org/jpos/tlv/packager/IFTA_LLBINARY.java
+++ b/jpos/src/main/java/org/jpos/tlv/packager/IFTA_LLBINARY.java
@@ -33,6 +33,7 @@
 import java.io.ObjectOutput;
 
 /**
+ * ISOFieldPackager for a 2-digit ASCII-length-prefixed binary tagged field.
  * @author Vishnu Pillai
  */
 public class IFTA_LLBINARY extends IFA_LLBINARY implements TaggedFieldPackager {
diff --git a/jpos/src/main/java/org/jpos/tlv/packager/IFTA_LLCHAR.java b/jpos/src/main/java/org/jpos/tlv/packager/IFTA_LLCHAR.java
index e3a1277749..1b83766a3d 100644
--- a/jpos/src/main/java/org/jpos/tlv/packager/IFTA_LLCHAR.java
+++ b/jpos/src/main/java/org/jpos/tlv/packager/IFTA_LLCHAR.java
@@ -33,6 +33,7 @@
 import java.io.ObjectOutput;
 
 /**
+ * ISOFieldPackager for a 2-digit ASCII-length-prefixed character tagged field.
  * @author Vishnu Pillai
  */
 public class IFTA_LLCHAR extends IFA_LLCHAR implements TaggedFieldPackager {
diff --git a/jpos/src/main/java/org/jpos/tlv/packager/IFTA_LLLBINARY.java b/jpos/src/main/java/org/jpos/tlv/packager/IFTA_LLLBINARY.java
index bd73cffd94..fe4caf13c9 100644
--- a/jpos/src/main/java/org/jpos/tlv/packager/IFTA_LLLBINARY.java
+++ b/jpos/src/main/java/org/jpos/tlv/packager/IFTA_LLLBINARY.java
@@ -33,6 +33,7 @@
 import java.io.ObjectOutput;
 
 /**
+ * ISOFieldPackager for a 3-digit ASCII-length-prefixed binary tagged field.
  * @author Vishnu Pillai
  */
 public class IFTA_LLLBINARY extends IFA_LLLBINARY implements TaggedFieldPackager {
diff --git a/jpos/src/main/java/org/jpos/tlv/packager/IFTA_LLLCHAR.java b/jpos/src/main/java/org/jpos/tlv/packager/IFTA_LLLCHAR.java
index 83495c0e85..a3735fcc0f 100644
--- a/jpos/src/main/java/org/jpos/tlv/packager/IFTA_LLLCHAR.java
+++ b/jpos/src/main/java/org/jpos/tlv/packager/IFTA_LLLCHAR.java
@@ -33,6 +33,7 @@
 import java.io.ObjectOutput;
 
 /**
+ * ISOFieldPackager for a 3-digit ASCII-length-prefixed character tagged field.
  * @author Vishnu Pillai
  */
 public class IFTA_LLLCHAR extends IFA_LLLCHAR implements TaggedFieldPackager {
diff --git a/jpos/src/main/java/org/jpos/tlv/packager/IFTA_LLLNUM.java b/jpos/src/main/java/org/jpos/tlv/packager/IFTA_LLLNUM.java
index 7d3af830be..0ceb61c4bc 100644
--- a/jpos/src/main/java/org/jpos/tlv/packager/IFTA_LLLNUM.java
+++ b/jpos/src/main/java/org/jpos/tlv/packager/IFTA_LLLNUM.java
@@ -33,6 +33,7 @@
 import java.io.ObjectOutput;
 
 /**
+ * ISOFieldPackager for a 3-digit ASCII-length-prefixed numeric tagged field.
  * @author Vishnu Pillai
  */
 public class IFTA_LLLNUM extends IFA_LLLNUM implements TaggedFieldPackager {
diff --git a/jpos/src/main/java/org/jpos/tlv/packager/IFTA_LLNUM.java b/jpos/src/main/java/org/jpos/tlv/packager/IFTA_LLNUM.java
index 9e985c3366..6cd82d9553 100644
--- a/jpos/src/main/java/org/jpos/tlv/packager/IFTA_LLNUM.java
+++ b/jpos/src/main/java/org/jpos/tlv/packager/IFTA_LLNUM.java
@@ -33,6 +33,7 @@
 import java.io.ObjectOutput;
 
 /**
+ * ISOFieldPackager for a 2-digit ASCII-length-prefixed numeric tagged field.
  * @author Vishnu Pillai
  */
 public class IFTA_LLNUM extends IFA_LLNUM implements TaggedFieldPackager {
diff --git a/jpos/src/main/java/org/jpos/tlv/packager/IFTB_LLBINARY.java b/jpos/src/main/java/org/jpos/tlv/packager/IFTB_LLBINARY.java
index ff5165bc43..9adaa8b5bf 100644
--- a/jpos/src/main/java/org/jpos/tlv/packager/IFTB_LLBINARY.java
+++ b/jpos/src/main/java/org/jpos/tlv/packager/IFTB_LLBINARY.java
@@ -33,6 +33,7 @@
 import java.io.ObjectOutput;
 
 /**
+ * ISOFieldPackager for a 2-byte binary-length-prefixed binary tagged field.
  * @author Vishnu Pillai
  */
 public class IFTB_LLBINARY extends IFB_LLBINARY implements TaggedFieldPackager {
diff --git a/jpos/src/main/java/org/jpos/tlv/packager/PackagerErrorHandler.java b/jpos/src/main/java/org/jpos/tlv/packager/PackagerErrorHandler.java
index ecebeec273..c4692b477f 100644
--- a/jpos/src/main/java/org/jpos/tlv/packager/PackagerErrorHandler.java
+++ b/jpos/src/main/java/org/jpos/tlv/packager/PackagerErrorHandler.java
@@ -24,6 +24,7 @@
 
 
 /**
+ * Callback interface invoked when a tagged-sequence packager encounters a packing/unpacking error.
  * @author Vishnu Pillai
  */
 public interface PackagerErrorHandler {
diff --git a/jpos/src/main/java/org/jpos/tlv/packager/PackagerErrorLogger.java b/jpos/src/main/java/org/jpos/tlv/packager/PackagerErrorLogger.java
index 26e2815ca9..bc63cc479f 100644
--- a/jpos/src/main/java/org/jpos/tlv/packager/PackagerErrorLogger.java
+++ b/jpos/src/main/java/org/jpos/tlv/packager/PackagerErrorLogger.java
@@ -33,6 +33,7 @@
 
 
 /**
+ * A {@link PackagerErrorHandler} that logs errors via the jPOS logging framework.
  * @author Vishnu Pillai
  */
 public class PackagerErrorLogger implements PackagerErrorHandler, Configurable, LogSource {
diff --git a/jpos/src/main/java/org/jpos/tlv/packager/TaggedSequencePackager.java b/jpos/src/main/java/org/jpos/tlv/packager/TaggedSequencePackager.java
index 503e842e68..5e5d9a7252 100644
--- a/jpos/src/main/java/org/jpos/tlv/packager/TaggedSequencePackager.java
+++ b/jpos/src/main/java/org/jpos/tlv/packager/TaggedSequencePackager.java
@@ -43,6 +43,7 @@
 import java.util.TreeMap;
 
 /**
+ * Packager for a sequence of tagged (TLV-style) ISO fields, supporting both fixed and variable-length tags.
  * @author Vishnu Pillai
  */
 public class TaggedSequencePackager extends GenericPackager {
@@ -62,11 +63,11 @@ public String getToken() {
 
     /**
      * Specify a placeholder token so that we can determine the tag length.
-     * 
    
+     * 
    
      * If the tags are all numeric and tags do not repeat, a numeric token may be a used like '00'.
      * Else, use a non numeric token e.g.: XX, ##, etc.
      *
-     * @param token
+     * @param token the token string identifying the tag format
      */
     public void setToken(String token) {
         this.tag = token;
@@ -246,6 +247,10 @@ public void setFieldPackager(ISOFieldPackager[] subFieldPackagers) {
         this.tagPackager = getTagPackager();
     }
 
+    /**
+     * Returns the {@link ISOFieldPackager} used for packing/unpacking tag fields.
+     * @return tag field packager
+     */
     protected ISOFieldPackager getTagPackager() {
         IF_CHAR tagPackager = new IF_CHAR(this.tag.length(), "Tag");
         tagPackager.setPadder(LeftPadder.ZERO_PADDER);
diff --git a/jpos/src/main/java/org/jpos/tlv/packager/bertlv/BERTLVAsciiHexPackager.java b/jpos/src/main/java/org/jpos/tlv/packager/bertlv/BERTLVAsciiHexPackager.java
index 3eec55ddc1..ca30a92fb7 100644
--- a/jpos/src/main/java/org/jpos/tlv/packager/bertlv/BERTLVAsciiHexPackager.java
+++ b/jpos/src/main/java/org/jpos/tlv/packager/bertlv/BERTLVAsciiHexPackager.java
@@ -32,6 +32,9 @@
 
 public class BERTLVAsciiHexPackager extends DefaultICCBERTLVPackager {
 
+    /** Default constructor.
+     * @throws ISOException on configuration error
+     */
     public BERTLVAsciiHexPackager() throws ISOException {
         super();
     }
diff --git a/jpos/src/main/java/org/jpos/tlv/packager/bertlv/BERTLVBinaryPackager.java b/jpos/src/main/java/org/jpos/tlv/packager/bertlv/BERTLVBinaryPackager.java
index 61a5b0b375..c95b385150 100644
--- a/jpos/src/main/java/org/jpos/tlv/packager/bertlv/BERTLVBinaryPackager.java
+++ b/jpos/src/main/java/org/jpos/tlv/packager/bertlv/BERTLVBinaryPackager.java
@@ -32,6 +32,9 @@
 
 public class BERTLVBinaryPackager extends DefaultICCBERTLVPackager {
 
+    /** Default constructor.
+     * @throws ISOException on configuration error
+     */
     public BERTLVBinaryPackager() throws ISOException {
         super();
     }
diff --git a/jpos/src/main/java/org/jpos/tlv/packager/bertlv/BERTLVEbcdicHexPackager.java b/jpos/src/main/java/org/jpos/tlv/packager/bertlv/BERTLVEbcdicHexPackager.java
index b424b9d636..003973ab69 100644
--- a/jpos/src/main/java/org/jpos/tlv/packager/bertlv/BERTLVEbcdicHexPackager.java
+++ b/jpos/src/main/java/org/jpos/tlv/packager/bertlv/BERTLVEbcdicHexPackager.java
@@ -32,6 +32,9 @@
 
 public class BERTLVEbcdicHexPackager extends DefaultICCBERTLVPackager {
 
+    /** Default constructor.
+     * @throws ISOException on configuration error
+     */
     public BERTLVEbcdicHexPackager() throws ISOException {
         super();
     }
diff --git a/jpos/src/main/java/org/jpos/tlv/packager/bertlv/BERTLVFormatMapper.java b/jpos/src/main/java/org/jpos/tlv/packager/bertlv/BERTLVFormatMapper.java
index 2703d104cd..a00ab8849d 100644
--- a/jpos/src/main/java/org/jpos/tlv/packager/bertlv/BERTLVFormatMapper.java
+++ b/jpos/src/main/java/org/jpos/tlv/packager/bertlv/BERTLVFormatMapper.java
@@ -24,10 +24,19 @@
 
 
 /**
+ * Maps EMV/BER-TLV tag numbers to their corresponding {@link org.jpos.tlv.TLVDataFormat} descriptors.
  * @author Vishnu Pillai
  */
+/** Maps BER-TLV tag numbers to their data format (binary, ASCII, etc.). */
+/** Maps BER-TLV tag values to their wire format (ASCII hex, binary, EBCDIC hex, etc.). */
 public interface BERTLVFormatMapper {
 
+    /**
+     * Returns the data format for the given BER-TLV tag.
+     * @param tagNumber the numeric tag identifier
+     * @return the data format for the tag
+     * @throws ISOException if the tag is unknown or invalid
+     */
     TLVDataFormat getFormat(Integer tagNumber) throws ISOException;
 
 }
diff --git a/jpos/src/main/java/org/jpos/tlv/packager/bertlv/BERTLVPackager.java b/jpos/src/main/java/org/jpos/tlv/packager/bertlv/BERTLVPackager.java
index f990a05952..4bf4f03016 100644
--- a/jpos/src/main/java/org/jpos/tlv/packager/bertlv/BERTLVPackager.java
+++ b/jpos/src/main/java/org/jpos/tlv/packager/bertlv/BERTLVPackager.java
@@ -66,6 +66,10 @@ public abstract class BERTLVPackager extends GenericPackager {
     private final BinaryInterpreter valueInterpreter;
 
 
+    /**
+     * Default constructor.
+     * @throws ISOException on configuration error
+     */
     public BERTLVPackager() throws ISOException {
         super();
         tagInterpreter = getTagInterpreter();
@@ -73,12 +77,28 @@ public BERTLVPackager() throws ISOException {
         valueInterpreter = getValueInterpreter();
     }
 
+    /**
+     * Returns the interpreter used for encoding/decoding tag bytes.
+     * @return tag byte interpreter
+     */
     protected abstract BinaryInterpreter getTagInterpreter();
 
+    /**
+     * Returns the interpreter used for encoding/decoding length bytes.
+     * @return length byte interpreter
+     */
     protected abstract BinaryInterpreter getLengthInterpreter();
 
+    /**
+     * Returns the interpreter used for encoding/decoding value bytes.
+     * @return value byte interpreter
+     */
     protected abstract BinaryInterpreter getValueInterpreter();
 
+    /**
+     * Returns the format mapper for this packager's tag set.
+     * @return BER-TLV format mapper
+     */
     protected abstract BERTLVFormatMapper getTagFormatMapper();
 
     /**
@@ -89,6 +109,15 @@ public byte[] pack(ISOComponent m) throws ISOException {
         return pack(m, false, getFirstField(), m.getMaxField());
     }
 
+    /**
+     * Packs a subset of sub-fields.
+     * @param m the ISO component to pack
+     * @param nested true if this is a nested (inner) pack
+     * @param startIdx first field index to include
+     * @param endIdx last field index to include
+     * @return packed bytes
+     * @throws ISOException on packing error
+     */
     public byte[] pack(ISOComponent m, boolean nested, int startIdx, int endIdx)
             throws ISOException {
         LogEvent evt = new LogEvent(this, "pack");
@@ -177,6 +206,9 @@ private byte[] packTag(final ISOTaggedField c) {
         return packedTagBytes;
     }
 
+    /** @param valueBytes the value bytes to prefix
+     * @return BER-TLV length-encoded prefix bytes
+     */
     private byte[] packLength(final byte[] valueBytes) {
         final byte[] lengthBytes;
         int length = valueBytes.length;
@@ -203,6 +235,14 @@ public int unpack(ISOComponent m, byte[] b) throws ISOException {
         }
     }
 
+    /**
+     * Unpacks BER-TLV encoded data.
+     * @param m target component
+     * @param b packed bytes
+     * @param nested true for nested unpack
+     * @return consumed bytes
+     * @throws ISOException on unpacking error
+     */
     public int unpack(ISOComponent m, byte[] b, boolean nested) throws ISOException {
         LogEvent evt = new LogEvent(this, "unpack");
         try {
@@ -304,6 +344,10 @@ private UnpackResult unpackTag(final byte[] tlvData, final int offset) {
         return new UnpackResult(tagBytes, tagInterpreter.getPackedLength(tagLength));
     }
 
+    /** @param tlvData data bytes
+     * @param offset start offset
+     * @return UnpackResult containing length bytes and consumed size
+     */
     private UnpackResult unpackLength(final byte[] tlvData, final int offset) {
         byte[] tlvBytesHex =
                 lengthInterpreter.uninterpret(
@@ -328,6 +372,15 @@ private UnpackResult unpackLength(final byte[] tlvData, final int offset) {
         return new UnpackResult(lengthBytes, lengthInterpreter.getPackedLength(lengthLength));
     }
 
+    /**
+     * Packs a single TLV value field.
+     * Packs the value of the given component for the specified tag.
+     * @param tagNameHex the tag name as a hex string
+     * @param c the component to pack
+     * @return packed value bytes
+     * @throws ISOException on packing error
+     * @throws UnknownTagNumberException if the tag is not recognised
+     */
     protected byte[] packValue(String tagNameHex, final ISOComponent c) throws ISOException,
             UnknownTagNumberException {
         final int tagNumber = Integer.parseInt(tagNameHex, 16);
diff --git a/jpos/src/main/java/org/jpos/tlv/packager/bertlv/DefaultICCBERTLVFormatMapper.java b/jpos/src/main/java/org/jpos/tlv/packager/bertlv/DefaultICCBERTLVFormatMapper.java
index 6a4e7f4263..7116cc05ff 100644
--- a/jpos/src/main/java/org/jpos/tlv/packager/bertlv/DefaultICCBERTLVFormatMapper.java
+++ b/jpos/src/main/java/org/jpos/tlv/packager/bertlv/DefaultICCBERTLVFormatMapper.java
@@ -27,6 +27,7 @@
 import org.jpos.iso.ISOException;
 
 /**
+ * Default BER-TLV format mapper for ICC (Integrated Circuit Card) data elements, based on the EMV specification.
  * @author Vishnu Pillai
  */
 public class DefaultICCBERTLVFormatMapper implements BERTLVFormatMapper {
diff --git a/jpos/src/main/java/org/jpos/tlv/packager/bertlv/DefaultICCBERTLVPackager.java b/jpos/src/main/java/org/jpos/tlv/packager/bertlv/DefaultICCBERTLVPackager.java
index f6844e3d5a..c3ad325289 100644
--- a/jpos/src/main/java/org/jpos/tlv/packager/bertlv/DefaultICCBERTLVPackager.java
+++ b/jpos/src/main/java/org/jpos/tlv/packager/bertlv/DefaultICCBERTLVPackager.java
@@ -35,7 +35,7 @@ public abstract class DefaultICCBERTLVPackager extends BERTLVPackager {
     /**
      * Use this method to globally set the BERTLVFormatMapper
      *
-     * @param tagFormatMapper
+     * @param tagFormatMapper — the TLV tag number
      */
     public static void setTagFormatMapper(BERTLVFormatMapper tagFormatMapper) {
         DefaultICCBERTLVPackager.DEFAULT_TAG_FORMAT_MAPPER = tagFormatMapper;
diff --git a/jpos/src/main/java/org/jpos/transaction/Context.java b/jpos/src/main/java/org/jpos/transaction/Context.java
index af1d76acfc..e6f8aefb91 100644
--- a/jpos/src/main/java/org/jpos/transaction/Context.java
+++ b/jpos/src/main/java/org/jpos/transaction/Context.java
@@ -45,12 +45,15 @@ public class Context implements Externalizable, Loggeable, Cloneable, Pausable {
     private CompletableFuture pausedFuture;
     private long timeout;
     private final Lock lock = new ReentrantLock();
+    /** Default constructor. */
     public Context () {
         super ();
     }
 
     /**
-     * puts an Object in the transient Map
+     * Puts an Object in the transient Map.
+     * @param key the map key
+     * @param value the value to store
      */
     public void put (Object key, Object value) {
         if (trace) {
@@ -64,7 +67,10 @@ public void put (Object key, Object value) {
         }
     }
     /**
-     * puts an Object in the transient Map
+     * Puts an Object in the transient or persistent Map.
+     * @param key the map key
+     * @param value the value to store
+     * @param persist true to also store in the persistent map
      */
     public void put (Object key, Object value, boolean persist) {
         if (trace) {
@@ -205,9 +211,11 @@ public boolean hasPersistedKey(Object key) {
 
     /**
      * Move entry to new key name
-     * @param from key
-     * @param to key
-     * @return the entry's value (could be null if 'from' key not present)
+     * Moves the value from one key to another.
+     * @param  the expected type
+     * @param from source key
+     * @param to destination key
+     * @return the moved value (or null if source key not present)
      */
     public synchronized  T move(Object from, Object to) {
         T obj = get(from);
@@ -233,7 +241,10 @@ public  T get(Object key, T defValue) {
     }
 
     /**
-     * Transient remove
+     * Removes the value associated with the given key from both transient and persistent maps.
+     * @param  the expected type
+     * @param key the key to remove
+     * @return the removed value, or null
      */
     public synchronized  T remove(Object key) {
         getPMap().remove(key);
@@ -242,6 +253,11 @@ public synchronized  T remove(Object key) {
         return obj;
     }
 
+    /**
+     * Returns the value as a String, converting it if necessary.
+     * @param key the map key
+     * @return the value as a String, or null
+     */
     public String getString (Object key) {
         Object obj = getMap().get (key);
         if (obj instanceof String)
@@ -250,6 +266,12 @@ else if (obj != null)
             return obj.toString();
         return null;
     }
+    /**
+     * Returns the value as a String, or a default if not found.
+     * @param key the map key
+     * @param defValue default if not found
+     * @return the value as String, or defValue
+     */
     public String getString (Object key, String defValue) {
         Object obj = getMap().get (key);
         if (obj instanceof String)
@@ -419,6 +441,7 @@ public int hashCode() {
     }
 
     /**
+     * Returns the persistent map, creating it lazily.
      * @return persistent map
      */
     private synchronized Map getPMap() {
@@ -427,6 +450,7 @@ private synchronized Map getPMap() {
         return pmap;
     }
     /**
+     * Returns the transient map, creating it lazily.
      * @return transient map
      */
     public synchronized Map getMap() {
@@ -435,6 +459,7 @@ public synchronized Map getMap() {
         return map;
     }
 
+    /** @return a snapshot copy of the transient map */
     @JsonIgnore
     public Map getMapClone() {
         Map cloned = Collections.synchronizedMap (new LinkedHashMap<>());
@@ -444,6 +469,11 @@ public Map getMapClone() {
         return cloned;
     }
 
+    /**
+     * Dumps all map entries to the output stream.
+     * @param p output stream
+     * @param indent indentation prefix
+     */
     protected void dumpMap (PrintStream p, String indent) {
         if (map != null) {
             getMapClone().entrySet().forEach(e -> dumpEntry(p, indent, e));
@@ -544,7 +574,7 @@ synchronized public Result getResult () {
     }
 
     /**
-     * adds a trace message
+     * Adds a trace message to the context log event.
      * @param msg trace information
      */
     public void log (Object msg) {
@@ -552,7 +582,7 @@ public void log (Object msg) {
             getLogEvent().addMessage (msg);
     }
     /**
-     * add a checkpoint to the profiler
+     * Adds a checkpoint to the context profiler.
      */
     public void checkPoint (String detail) {
         getProfiler().checkPoint (detail);
diff --git a/jpos/src/main/java/org/jpos/transaction/ContextConstants.java b/jpos/src/main/java/org/jpos/transaction/ContextConstants.java
index 9254891104..90a808b03e 100644
--- a/jpos/src/main/java/org/jpos/transaction/ContextConstants.java
+++ b/jpos/src/main/java/org/jpos/transaction/ContextConstants.java
@@ -18,29 +18,61 @@
 
 package org.jpos.transaction;
 
+/** Standard key constants for the jPOS {@link Context} transient/persistent maps. */
 public enum ContextConstants {
-    PROFILER, TIMESTAMP,
-    SOURCE, REQUEST, RESPONSE,
+    /** Profiler instance key. */
+    PROFILER, 
+    /** Transaction start timestamp key. */
+    TIMESTAMP,
+    /** Originating ISOSource key. */
+    SOURCE,
+    /** Incoming request ISOMsg key. */
+    REQUEST,
+    /** Outgoing response ISOMsg key. */
+    RESPONSE,
+    /** LogEvent for the current transaction. */
     LOGEVT,
-    DB, TX,
+    /** Database connection key. */
+    DB,
+    /** Database transaction key. */
+    TX,
+    /** Internal result code (IRC) key. */
     IRC,
+    /** Transaction name key. */
     TXNNAME,
+    /** Transaction result key. */
     RESULT,
+    /** Merchant ID key. */
     MID,
+    /** Terminal ID key. */
     TID,
+    /** Processing code key. */
     PCODE,
+    /** Card object key. */
     CARD,
+    /** Transmission timestamp key. */
     TRANSMISSION_TIMESTAMP,
+    /** Transaction timestamp key. */
     TRANSACTION_TIMESTAMP,
+    /** Capture date key. */
     CAPTURE_DATE,
+    /** POS data code key. */
     POS_DATA_CODE,
+    /** Transaction amount key. */
     AMOUNT,
+    /** Local amount key. */
     LOCAL_AMOUNT,
+    /** Original MTI for reversals. */
     ORIGINAL_MTI,
+    /** Original STAN for reversals. */
     ORIGINAL_STAN,
+    /** Original timestamp for reversals. */
     ORIGINAL_TIMESTAMP,
+    /** Original data elements (field 90) key. */
     ORIGINAL_DATA_ELEMENTS,
+    /** Routing destination key. */
     DESTINATION,
+    /** Panic flag key — set to abort the current transaction node. */
     PANIC;
 
     private final String name;
diff --git a/jpos/src/main/java/org/jpos/transaction/GroupSelector.java b/jpos/src/main/java/org/jpos/transaction/GroupSelector.java
index bcf2714edf..2e63160e1b 100644
--- a/jpos/src/main/java/org/jpos/transaction/GroupSelector.java
+++ b/jpos/src/main/java/org/jpos/transaction/GroupSelector.java
@@ -30,6 +30,7 @@
  */
 public interface GroupSelector extends TransactionParticipant {
     /**
+     * Selects the transaction group to execute.
      * @param id transaction id
      * @param context transaction context 
      * @return group name or null for no-action
diff --git a/jpos/src/main/java/org/jpos/transaction/participant/BSHGroupSelector.java b/jpos/src/main/java/org/jpos/transaction/participant/BSHGroupSelector.java
index 9efd51a935..fda48bb1e7 100644
--- a/jpos/src/main/java/org/jpos/transaction/participant/BSHGroupSelector.java
+++ b/jpos/src/main/java/org/jpos/transaction/participant/BSHGroupSelector.java
@@ -27,10 +27,19 @@
 import java.io.Serializable;
 
 /**
+ * A TransactionManager participant that uses BeanShell scripting to determine the next participant group.
  * @author  AMarques
  */
+/**
+ * {@link GroupSelector} implemented via a BeanShell script.
+ * @author AMarques
+ */
 public class BSHGroupSelector extends BSHTransactionParticipant implements GroupSelector {
     
+    /** Default constructor. */
+    public BSHGroupSelector() { super(); }
+
+    /** BeanShell method invoked during group selection. */
     protected BSHMethod selectMethod;
     
     public void setConfiguration(Element e) throws ConfigurationException {
@@ -42,6 +51,10 @@ public void setConfiguration(Element e) throws ConfigurationException {
         }
     }    
     
+    /** @param id transaction id
+     * @param context transaction context
+     * @return selected group name
+     */
     public String select(long id, java.io.Serializable context) {
         LogEvent ev = new LogEvent(this, "select");
         String result = null;
@@ -60,6 +73,11 @@ public String select(long id, java.io.Serializable context) {
         return result;
     }
     
+    /** Default select implementation; returns empty string.
+     * @param id transaction id
+     * @param context transaction context
+     * @return empty string
+     */
     public String defaultSelect(long id, Serializable context) {
         return "";
     }
diff --git a/jpos/src/main/java/org/jpos/transaction/participant/BSHMethod.java b/jpos/src/main/java/org/jpos/transaction/participant/BSHMethod.java
index fdcfda3a0d..2793fea374 100644
--- a/jpos/src/main/java/org/jpos/transaction/participant/BSHMethod.java
+++ b/jpos/src/main/java/org/jpos/transaction/participant/BSHMethod.java
@@ -70,7 +70,11 @@ public class BSHMethod {
      *  Example 2 :
      *          <routing file='cfg\files\routing1.bsh' cache='false'/>
      *
    • - */ + * Creates a BSHMethod from the given XML element configuration. + * @param e the XML element configuration (may be null) + * @return a configured BSHMethod, or null if element is null + * @throws IOException if the script file cannot be read + */ public static BSHMethod createBshMethod(Element e) throws IOException { if (e == null) { return null; @@ -115,27 +119,28 @@ public BSHMethod(String bshData, boolean source) { this.source = source; } - /** Sets the given arguments to the Interpreter, evaluates the script and - * returns the object stored on the variable named resultName. - * - * @param arguments Parameters to set to the Interpreter. For every - * Map.Entry (key, value), interpreter.set(key, value) - * is called. All keys must be Strings. + /** + * Sets the given arguments in the Interpreter, evaluates the script, + * and returns the object stored in the variable named {@code resultName}. + * @param arguments map of variable name to value pairs (all keys must be Strings) + * @param resultName the variable name whose value to return + * @return the value of resultName after script evaluation + * @throws bsh.EvalError on BeanShell evaluation error + * @throws IOException if the script cannot be read */ public Object execute(Map arguments, String resultName) throws EvalError, IOException { Interpreter i = initInterpreter(arguments); return i.get(resultName); } - /** Sets the given arguments to the Interpreter, evaluates the script and - * returns a map that has the Strings of the returnNames collection as keys - * and the objects stored in the variables thus named as values. - * - * @param arguments Parameters to set to the Interpreter. For every - * Map.Entry (key, value), interpreter.set(key, value) - * is called. All keys must be Strings. - * @param returnNames Collection of Strings. The names of the variables - * wich`s contents are to be returned. + /** + * Sets the given arguments in the Interpreter, evaluates the script, + * and returns a map of named result variables. + * @param arguments map of variable name to value pairs (all keys must be Strings) + * @param returnNames collection of variable names to extract from the interpreter + * @return map of variable name to value pairs after script evaluation + * @throws bsh.EvalError on BeanShell evaluation error + * @throws IOException if the script cannot be read */ public Map execute(Map arguments, Collection returnNames) throws EvalError, IOException { Interpreter i = initInterpreter(arguments); @@ -148,6 +153,13 @@ public Map execute(Map arguments, Collection returnNames) throws EvalError, IOEx return result; } + /** + * Initialises a BeanShell Interpreter with the given arguments and evaluates the script. + * @param arguments map of variable name to value pairs to set in the interpreter + * @return a configured Interpreter after script evaluation + * @throws EvalError on script evaluation error + * @throws IOException if the script cannot be read + */ protected Interpreter initInterpreter(Map arguments) throws EvalError, IOException { Interpreter i = new Interpreter(); Map.Entry entry; diff --git a/jpos/src/main/java/org/jpos/transaction/participant/BSHTransactionParticipant.java b/jpos/src/main/java/org/jpos/transaction/participant/BSHTransactionParticipant.java index 5d3c4f5478..fb010f2506 100644 --- a/jpos/src/main/java/org/jpos/transaction/participant/BSHTransactionParticipant.java +++ b/jpos/src/main/java/org/jpos/transaction/participant/BSHTransactionParticipant.java @@ -56,11 +56,16 @@ public class BSHTransactionParticipant extends SimpleLogSource implements TransactionParticipant, AbortParticipant, XmlConfigurable { + /** BeanShell method for the prepare phase. */ protected BSHMethod prepareMethod; + /** BeanShell method for the prepare-for-abort phase. */ protected BSHMethod prepareForAbortMethod; + /** BeanShell method for the commit phase. */ protected BSHMethod commitMethod; + /** BeanShell method for the abort phase. */ protected BSHMethod abortMethod; + /** Whether to log trace events. */ boolean trace; /** Creates a new instance of BSHTransactionParticipant */ @@ -83,6 +88,12 @@ public void abort(long id, java.io.Serializable context) { Logger.log(ev); } + /** + * Default abort handling when no BeanShell abort method is configured (no-op). + * @param id transaction id + * @param context transaction context + * @param ev log event + */ protected void defaultAbort(long id, Serializable context, LogEvent ev) {} public void commit(long id, java.io.Serializable context) { @@ -100,6 +111,11 @@ public void commit(long id, java.io.Serializable context) { Logger.log(ev); } + /** Default commit implementation (no-op). + * @param id transaction id + * @param context transaction context + * @param ev log event + */ protected void defaultCommit(long id, Serializable context, LogEvent ev) {} public int prepare(long id, java.io.Serializable context) { @@ -120,6 +136,7 @@ public int prepare(long id, java.io.Serializable context) { return result; } + /** {@inheritDoc} */ public int prepareForAbort(long id, java.io.Serializable context) { LogEvent ev = new LogEvent(this, "prepare-for-abort"); int result = ABORTED | READONLY; @@ -136,6 +153,12 @@ public int prepareForAbort(long id, java.io.Serializable context) { return result; } + /** Default prepare implementation; returns PREPARED|READONLY. + * @param id transaction id + * @param context transaction context + * @param ev log event + * @return transaction result code + */ protected int defaultPrepare(long id, Serializable context, LogEvent ev) { return PREPARED | READONLY; } @@ -152,6 +175,17 @@ public void setConfiguration(Element e) throws ConfigurationException { } } + /** + * Executes the given BSHMethod with the standard transaction parameters. + * @param m the BSHMethod to execute + * @param id transaction id + * @param context transaction context + * @param evt log event + * @param resultName the result variable name + * @return the value of resultName after execution + * @throws bsh.EvalError on BeanShell evaluation error + * @throws java.io.IOException if the script cannot be read + */ protected Object executeMethod(BSHMethod m, long id, Serializable context, LogEvent evt, String resultName) throws EvalError, IOException { Map params = new HashMap(); diff --git a/jpos/src/main/java/org/jpos/transaction/participant/CheckFields.java b/jpos/src/main/java/org/jpos/transaction/participant/CheckFields.java index f9695cd2ef..6f1e41738b 100644 --- a/jpos/src/main/java/org/jpos/transaction/participant/CheckFields.java +++ b/jpos/src/main/java/org/jpos/transaction/participant/CheckFields.java @@ -36,6 +36,7 @@ import static org.jpos.transaction.ContextConstants.*; +/** TransactionManager participant that checks required context fields are present. */ public class CheckFields implements TransactionParticipant, Configurable { private Configuration cfg; private String request; @@ -51,6 +52,8 @@ public class CheckFields implements TransactionParticipant, Configurable { private Pattern track1Pattern = null; private Pattern track2Pattern = null; + /** Default constructor. */ + public CheckFields() { super(); } public int prepare (long id, Serializable context) { Context ctx = (Context) context; Result rc = ctx.getResult(); diff --git a/jpos/src/main/java/org/jpos/transaction/participant/CheckPoint.java b/jpos/src/main/java/org/jpos/transaction/participant/CheckPoint.java index b05fdf90e5..c6f88b2852 100644 --- a/jpos/src/main/java/org/jpos/transaction/participant/CheckPoint.java +++ b/jpos/src/main/java/org/jpos/transaction/participant/CheckPoint.java @@ -25,8 +25,11 @@ import java.io.Serializable; +/** TransactionManager participant that logs a check-point message. */ public class CheckPoint implements TransactionParticipant, Configurable { Configuration cfg; + /** Default constructor. */ + public CheckPoint() { super(); } public int prepare (long id, Serializable o) { if (o instanceof Context) ((Context)o).checkPoint (cfg.get ("message", "checkpoint")); diff --git a/jpos/src/main/java/org/jpos/transaction/participant/SelectDestination.java b/jpos/src/main/java/org/jpos/transaction/participant/SelectDestination.java index 6ad76d9fa9..c473052ce0 100644 --- a/jpos/src/main/java/org/jpos/transaction/participant/SelectDestination.java +++ b/jpos/src/main/java/org/jpos/transaction/participant/SelectDestination.java @@ -91,12 +91,13 @@ public void setConfiguration (Configuration cfg) { * * * SelectDestination expects an XML configuration in the following format: - * + * 
    {@code
      * 
      *   4000000..499999
      *   4550000..455999
      *   5
      * 
+     * }
    * */ public void setConfiguration(Element xml) throws ConfigurationException { diff --git a/jpos/src/main/java/org/jpos/ui/UI.java b/jpos/src/main/java/org/jpos/ui/UI.java index c47f5512c7..6596a33b22 100644 --- a/jpos/src/main/java/org/jpos/ui/UI.java +++ b/jpos/src/main/java/org/jpos/ui/UI.java @@ -30,6 +30,7 @@ import java.util.*; /** + * Central controller for the jPOS Swing-based GUI; manages UI components and their factories. * @author Alejandro Revilla * *

    jPOS UI main class

    @@ -79,18 +80,24 @@ public void setObjectFactory (UIObjectFactory objFactory) { this.objFactory = objFactory; } /** + * Sets the XML configuration element for this UI. * @param config the Configuration element */ public void setConfig (Element config) { this.config = config; } /** + * Sets the optional Log instance used for diagnostic output. * @param log an optional Log instance * @see org.jpos.util.Log */ public void setLog (Log log) { this.log = log; } + /** + * Returns the Log instance, or null if none was set. + * @return the Log, or null + */ public Log getLog () { return log; } @@ -104,6 +111,7 @@ public Map getRegistrar () { return registrar; } /** + * Returns the component registered under the given id. * @param id Component id ("id" configuration attribute) * @return the Object or null */ @@ -130,13 +138,20 @@ public JComponent create (UI ui, Element e) { * @throws Exception if unable to instantiate * @see #setLog */ + /** + * Instantiates an object by class name using the current thread's context class loader. + * @param clazz fully qualified class name + * @return new instance + * @throws Exception if the class cannot be found or instantiated + */ public Object newInstance (String clazz) throws Exception { ClassLoader cl = Thread.currentThread().getContextClassLoader (); Class type = cl.loadClass (clazz); return type.newInstance(); } /** - * configure this UI object + * Configures this UI from the stored XML element. + * @throws JDOMException on XML processing error */ public void configure () throws JDOMException { configure (config); @@ -187,6 +202,7 @@ JVM running under WinXP (in linux went fine.. I didn't } } /** + * Returns true if this UI object has been disposed. * @return true if this UI object has been disposed and is no longer valid */ public boolean isDestroyed () { @@ -420,6 +436,12 @@ private JComponent createComponent (Element e) { } return component; } + /** + * Applies any script element to the component; default implementation is a no-op. + * @param component the target component + * @param e the script XML element + * @return the component after script application + */ protected JComponent doScript (JComponent component, Element e) { return component; } diff --git a/jpos/src/main/java/org/jpos/ui/UIAware.java b/jpos/src/main/java/org/jpos/ui/UIAware.java index e193c12dd5..119d154b56 100644 --- a/jpos/src/main/java/org/jpos/ui/UIAware.java +++ b/jpos/src/main/java/org/jpos/ui/UIAware.java @@ -21,6 +21,7 @@ import org.jdom2.Element; /** + * Implemented by UI components that need access to the parent {@link UI} controller. * @since 1.4.7 * @author Alejandro Revilla *

    @@ -31,8 +32,9 @@ */ public interface UIAware { /** - * @param ui reference - * @param config action config block + * Configures this UI-aware component. + * @param ui the UI context + * @param config the XML configuration element */ void setUI(UI ui, Element config); } diff --git a/jpos/src/main/java/org/jpos/ui/UIFactory.java b/jpos/src/main/java/org/jpos/ui/UIFactory.java index 6767ed0bb4..192db79e70 100644 --- a/jpos/src/main/java/org/jpos/ui/UIFactory.java +++ b/jpos/src/main/java/org/jpos/ui/UIFactory.java @@ -23,11 +23,18 @@ import javax.swing.*; /** + * Factory interface for creating Swing {@link javax.swing.JComponent} instances from XML configuration elements. * @author Alejandro Revilla * * UI delegates the creation of UI components to an UIFactory. */ public interface UIFactory { - JComponent create(UI ui, Element config); + /** + * Creates a Swing component from the given UI context and XML element. + * @param ui the UI container + * @param e the XML configuration element + * @return a new JComponent + */ + JComponent create(UI ui, Element e); } diff --git a/jpos/src/main/java/org/jpos/ui/UIObjectFactory.java b/jpos/src/main/java/org/jpos/ui/UIObjectFactory.java index 3c8f357fe9..ad65d60f4e 100644 --- a/jpos/src/main/java/org/jpos/ui/UIObjectFactory.java +++ b/jpos/src/main/java/org/jpos/ui/UIObjectFactory.java @@ -19,16 +19,19 @@ package org.jpos.ui; /** + * Factory interface for creating arbitrary objects used within the jPOS UI framework. * @author Alejandro Revilla * * UI delegates object creation to an object factory * (i.e. in Q2, we delegate to an MBeanServer via QFactory) */ +/** Factory interface for instantiating UI objects by class name. */ public interface UIObjectFactory { /** - * @param clazz the Clazzzz + * Instantiates an object by class name. + * @param clazz the class name to instantiate * @return the Object - * @throws throws may throw something + * @throws Exception if the class cannot be instantiated */ Object newInstance(String clazz) throws Exception; } diff --git a/jpos/src/main/java/org/jpos/ui/factory/BorderLayoutFactory.java b/jpos/src/main/java/org/jpos/ui/factory/BorderLayoutFactory.java index 4d079cfa50..ac32848361 100644 --- a/jpos/src/main/java/org/jpos/ui/factory/BorderLayoutFactory.java +++ b/jpos/src/main/java/org/jpos/ui/factory/BorderLayoutFactory.java @@ -26,6 +26,7 @@ import java.awt.*; /** + * UIFactory that creates a {@link java.awt.BorderLayout}-based panel from XML. * @author Alejandro Revilla * * creates a panel with a Border layout @@ -41,7 +42,11 @@ * * @see org.jpos.ui.UIFactory */ +/** {@link UIFactory} that creates a JPanel with a {@link java.awt.BorderLayout}. */ +/** {@link UIFactory} that creates a {@link java.awt.BorderLayout}-based container. */ public class BorderLayoutFactory implements UIFactory { + /** Default constructor. */ + public BorderLayoutFactory() { } UI ui; public JComponent create (UI ui, Element e) { diff --git a/jpos/src/main/java/org/jpos/ui/factory/GridLayoutFactory.java b/jpos/src/main/java/org/jpos/ui/factory/GridLayoutFactory.java index 1f2e906f98..f17b3425f5 100644 --- a/jpos/src/main/java/org/jpos/ui/factory/GridLayoutFactory.java +++ b/jpos/src/main/java/org/jpos/ui/factory/GridLayoutFactory.java @@ -27,6 +27,7 @@ import java.util.Iterator; /** + * UIFactory that creates a {@link java.awt.GridLayout}-based panel from XML. * @author Alejandro Revilla * * creates a panel with a grid layout diff --git a/jpos/src/main/java/org/jpos/ui/factory/HSplitFactory.java b/jpos/src/main/java/org/jpos/ui/factory/HSplitFactory.java index a25a5ad827..2a04c569bb 100644 --- a/jpos/src/main/java/org/jpos/ui/factory/HSplitFactory.java +++ b/jpos/src/main/java/org/jpos/ui/factory/HSplitFactory.java @@ -25,6 +25,7 @@ import javax.swing.*; /** + * UIFactory that creates a horizontal {@link javax.swing.JSplitPane} from XML. * @author Alejandro Revilla * * creates a horizontal split pane diff --git a/jpos/src/main/java/org/jpos/ui/factory/HtmlFactory.java b/jpos/src/main/java/org/jpos/ui/factory/HtmlFactory.java index 6c4d9b1d2e..891b7ac5cc 100644 --- a/jpos/src/main/java/org/jpos/ui/factory/HtmlFactory.java +++ b/jpos/src/main/java/org/jpos/ui/factory/HtmlFactory.java @@ -29,6 +29,7 @@ import javax.swing.text.html.HTMLFrameHyperlinkEvent; /** + * UIFactory that creates an HTML-rendering {@link javax.swing.JEditorPane} from XML. * @author Alejandro Revilla * * Creates an html browser/editor diff --git a/jpos/src/main/java/org/jpos/ui/factory/ISOMeterFactory.java b/jpos/src/main/java/org/jpos/ui/factory/ISOMeterFactory.java index 3ae6e02e7d..8f3b40e2dd 100644 --- a/jpos/src/main/java/org/jpos/ui/factory/ISOMeterFactory.java +++ b/jpos/src/main/java/org/jpos/ui/factory/ISOMeterFactory.java @@ -31,12 +31,13 @@ import java.util.Observable; /** + * UIFactory that creates an {@link org.jpos.iso.gui.ISOMeter} component from XML. * @author Alejandro Revilla * * Creates an ISOMeter component * i.e: * 

    - *  <iso-meter idref="id" scroll="true|false" refresh="nnn"/>
+ *  <iso-meter idref="id" scroll="true|false" refresh="nnn"/>
  *
    * @see org.jpos.ui.UIFactory */ diff --git a/jpos/src/main/java/org/jpos/ui/factory/JButtonFactory.java b/jpos/src/main/java/org/jpos/ui/factory/JButtonFactory.java index 4bf3f3bf71..9b6c114793 100644 --- a/jpos/src/main/java/org/jpos/ui/factory/JButtonFactory.java +++ b/jpos/src/main/java/org/jpos/ui/factory/JButtonFactory.java @@ -27,6 +27,7 @@ import java.awt.*; /** + * UIFactory that creates a {@link javax.swing.JButton} from XML. * @author Alejandro Revilla * * Creates a JButton diff --git a/jpos/src/main/java/org/jpos/ui/factory/JLabelFactory.java b/jpos/src/main/java/org/jpos/ui/factory/JLabelFactory.java index 3e3342239f..26a6d5787b 100644 --- a/jpos/src/main/java/org/jpos/ui/factory/JLabelFactory.java +++ b/jpos/src/main/java/org/jpos/ui/factory/JLabelFactory.java @@ -27,6 +27,7 @@ import java.awt.*; /** + * UIFactory that creates a {@link javax.swing.JLabel} from XML. * @author Alejandro Revilla * * Creates a JLabel diff --git a/jpos/src/main/java/org/jpos/ui/factory/JTabbedPaneFactory.java b/jpos/src/main/java/org/jpos/ui/factory/JTabbedPaneFactory.java index 355d476240..78be2fad7c 100644 --- a/jpos/src/main/java/org/jpos/ui/factory/JTabbedPaneFactory.java +++ b/jpos/src/main/java/org/jpos/ui/factory/JTabbedPaneFactory.java @@ -33,6 +33,7 @@ import java.util.List; /** + * UIFactory that creates a {@link javax.swing.JTabbedPane} from XML. * @author Alejandro Revilla * * creates a tabbed pane diff --git a/jpos/src/main/java/org/jpos/ui/factory/JTreeFactory.java b/jpos/src/main/java/org/jpos/ui/factory/JTreeFactory.java index 85e2222b94..92e3e8efad 100644 --- a/jpos/src/main/java/org/jpos/ui/factory/JTreeFactory.java +++ b/jpos/src/main/java/org/jpos/ui/factory/JTreeFactory.java @@ -35,6 +35,7 @@ import java.util.StringTokenizer; /** + * UIFactory that creates a {@link javax.swing.JTree} from XML. * @author Alejandro Revilla * * Creates a JTree diff --git a/jpos/src/main/java/org/jpos/ui/factory/LogListenerFactory.java b/jpos/src/main/java/org/jpos/ui/factory/LogListenerFactory.java index 78d3dccd13..7d5f9f4bc1 100644 --- a/jpos/src/main/java/org/jpos/ui/factory/LogListenerFactory.java +++ b/jpos/src/main/java/org/jpos/ui/factory/LogListenerFactory.java @@ -30,6 +30,7 @@ import java.io.PrintStream; /** + * UIFactory that creates a log-event viewer component from XML. * @author Alejandro Revilla * * a log listener component diff --git a/jpos/src/main/java/org/jpos/ui/factory/PanelFactory.java b/jpos/src/main/java/org/jpos/ui/factory/PanelFactory.java index 23661e0b1f..b5458e0625 100644 --- a/jpos/src/main/java/org/jpos/ui/factory/PanelFactory.java +++ b/jpos/src/main/java/org/jpos/ui/factory/PanelFactory.java @@ -25,6 +25,7 @@ import javax.swing.*; /** + * UIFactory that creates a {@link javax.swing.JPanel} from XML. * @author Alejandro Revilla * * creates a panel (with an optional "id") diff --git a/jpos/src/main/java/org/jpos/ui/factory/TextFactory.java b/jpos/src/main/java/org/jpos/ui/factory/TextFactory.java index 138cd347c1..3b9c1c1532 100644 --- a/jpos/src/main/java/org/jpos/ui/factory/TextFactory.java +++ b/jpos/src/main/java/org/jpos/ui/factory/TextFactory.java @@ -25,6 +25,7 @@ import javax.swing.*; /** + * UIFactory that creates a text component from XML. * @author Alejandro Revilla * * Creates a text editor diff --git a/jpos/src/main/java/org/jpos/ui/factory/VSplitFactory.java b/jpos/src/main/java/org/jpos/ui/factory/VSplitFactory.java index c9962016ba..80b1b80a79 100644 --- a/jpos/src/main/java/org/jpos/ui/factory/VSplitFactory.java +++ b/jpos/src/main/java/org/jpos/ui/factory/VSplitFactory.java @@ -25,6 +25,7 @@ import javax.swing.*; /** + * UIFactory that creates a vertical {@link javax.swing.JSplitPane} from XML. * @author Alejandro Revilla * * creates a vertical split pane diff --git a/jpos/src/main/java/org/jpos/util/BaseLogEventWriter.java b/jpos/src/main/java/org/jpos/util/BaseLogEventWriter.java index dad0b400fe..a363da9784 100644 --- a/jpos/src/main/java/org/jpos/util/BaseLogEventWriter.java +++ b/jpos/src/main/java/org/jpos/util/BaseLogEventWriter.java @@ -33,6 +33,8 @@ * @since 2.1.4 */ public abstract class BaseLogEventWriter implements LogEventWriter { + /** Default constructor. */ + public BaseLogEventWriter() { } PrintStream p; @Override diff --git a/jpos/src/main/java/org/jpos/util/BlockingQueue.java b/jpos/src/main/java/org/jpos/util/BlockingQueue.java index a2c4d1adf9..53232cb873 100644 --- a/jpos/src/main/java/org/jpos/util/BlockingQueue.java +++ b/jpos/src/main/java/org/jpos/util/BlockingQueue.java @@ -25,27 +25,43 @@ * @see ThreadPool * @since 1.1 */ +/** + * A simple thread-safe blocking queue supporting enqueue, dequeue with optional timeout, and cooperative close. + * @deprecated Use standard {@link java.util.concurrent} classes instead. + */ @SuppressWarnings("unchecked") public class BlockingQueue { private LinkedList queue = new LinkedList(); private boolean closed = false; private int consumers = 0; + /** Default constructor. */ + public BlockingQueue() { } + /** Exception thrown when an operation is attempted on a closed BlockingQueue. */ public static class Closed extends RuntimeException { private static final long serialVersionUID = 3404885702116373450L; + /** Constructs a Closed exception with a default message. */ public Closed() { super ("queue-closed"); } } + /** Adds an object to the tail of the queue. + * @param o the object to enqueue + * @throws Closed if the queue has been closed + */ public synchronized void enqueue (Object o) throws Closed { if (closed) throw new Closed(); queue.addLast (o); notify(); } + /** Adds an object to the head of the queue (priority re-queue). + * @param o the object to re-queue + * @throws Closed if the queue has been closed + */ public synchronized void requeue (Object o) throws Closed { if (closed) throw new Closed(); @@ -53,6 +69,11 @@ public synchronized void requeue (Object o) throws Closed { notify(); } + /** Removes and returns the head of the queue, blocking until one is available. + * @return the dequeued object + * @throws Closed if the queue is closed + * @throws InterruptedException if the thread is interrupted + */ public synchronized Object dequeue() throws InterruptedException, Closed { @@ -69,6 +90,12 @@ public synchronized Object dequeue() return queue.removeFirst(); } + /** Removes and returns the head of the queue, waiting at most {@code timeout} ms. + * @param timeout maximum wait time in milliseconds + * @return the dequeued object, or null on timeout + * @throws Closed if the queue is closed + * @throws InterruptedException if the thread is interrupted + */ public synchronized Object dequeue (long timeout) throws InterruptedException, Closed { @@ -89,27 +116,52 @@ public synchronized Object dequeue (long timeout) } return queue.size() > 0 ? queue.removeFirst() : null; } + /** Closes the queue; pending consumers are released with a {@link Closed} exception. */ public synchronized void close() { closed = true; notifyAll(); } + /** + * Returns the number of threads currently waiting to dequeue. + * @return consumer count + */ public synchronized int consumerCount() { return consumers; } + /** + * Returns the number of additional consumers needed to drain the current backlog. + * @return consumer deficit + */ public synchronized int consumerDeficit() { return queue.size() - consumers; } + /** + * Returns true if there are items ready to be dequeued. + * @return true if items are pending + */ public synchronized boolean ready() { return !closed; } + /** + * Returns the number of items waiting in the queue. + * @return pending item count + */ public synchronized int pending() { return queue.size(); } + /** + * Returns the underlying linked list. + * @return the backing linked list + */ public LinkedList getQueue () { return queue; } + /** + * Sets the underlying linked list. + * @param queue the backing linked list + */ public void setQueue (LinkedList queue) { this.queue = queue; } diff --git a/jpos/src/main/java/org/jpos/util/BufferedExceptionLogListener.java b/jpos/src/main/java/org/jpos/util/BufferedExceptionLogListener.java index a00626db52..bffaa07517 100644 --- a/jpos/src/main/java/org/jpos/util/BufferedExceptionLogListener.java +++ b/jpos/src/main/java/org/jpos/util/BufferedExceptionLogListener.java @@ -18,8 +18,16 @@ package org.jpos.util; +/** + * {@link BufferedLogListener} variant that only buffers events containing exceptions. + */ @SuppressWarnings("unused") public class BufferedExceptionLogListener extends BufferedLogListener { + /** + * Default constructor. + */ + public BufferedExceptionLogListener() { super(); } + /** {@inheritDoc} */ public LogEvent log(LogEvent ev) { if (hasException(ev)) super.log(ev); diff --git a/jpos/src/main/java/org/jpos/util/BufferedLogListener.java b/jpos/src/main/java/org/jpos/util/BufferedLogListener.java index 15a3c3e211..cfba6ca62e 100644 --- a/jpos/src/main/java/org/jpos/util/BufferedLogListener.java +++ b/jpos/src/main/java/org/jpos/util/BufferedLogListener.java @@ -26,9 +26,15 @@ import java.util.concurrent.Executors; import java.util.concurrent.ScheduledExecutorService; +/** + * {@link LogListener} that buffers log events in memory up to a configurable maximum size. + */ public class BufferedLogListener implements LogListener, Configurable, LogProducer { + /** Default constructor. */ + public BufferedLogListener() { } int maxSize; String name; + /** Default maximum number of log events to buffer. */ public static final int DEFAULT_SIZE = 100; List listeners = new ArrayList(); final List events = new ArrayList(); @@ -80,6 +86,10 @@ public void removeAllListeners() { } } + /** + * Returns the maximum number of log events to buffer. + * @return max buffer size + */ public int getMaxSize() { return maxSize; } diff --git a/jpos/src/main/java/org/jpos/util/Caller.java b/jpos/src/main/java/org/jpos/util/Caller.java index 96f8e33453..1432a7b92d 100644 --- a/jpos/src/main/java/org/jpos/util/Caller.java +++ b/jpos/src/main/java/org/jpos/util/Caller.java @@ -24,17 +24,34 @@ /** * Return Caller's short class name, method and line number */ +/** Utility class for obtaining caller information from the current stack trace. */ public class Caller { + /** Private constructor — utility class. */ + private Caller() { } private static String JAVA_ID_PATTERN = "(\\p{javaJavaIdentifierStart}\\p{javaJavaIdentifierPart}*)\\.*"; private static Pattern FQCN = Pattern.compile(JAVA_ID_PATTERN + "(\\." + JAVA_ID_PATTERN + ")*"); + /** + * Returns a string describing the immediate caller (class, method, line). + * @return caller description + */ public static String info() { return info(1); } + /** + * Returns a string describing the caller at the given stack depth. + * @param pos the stack depth + * @return caller description + */ public static String info(int pos) { return info (Thread.currentThread().getStackTrace()[2+pos]); } + /** + * Returns a formatted string for the given stack trace element. + * @param st the element to format + * @return formatted string + */ public static String info (StackTraceElement st) { String clazz = st.getClassName(); Matcher matcher = FQCN.matcher(clazz); @@ -50,6 +67,11 @@ public static String info (StackTraceElement st) { } + /** + * Returns the simple class name from a fully-qualified class name. + * @param clazz the fully-qualified class name + * @return the simple class name + */ public static String shortClassName(String clazz) { Matcher matcher = FQCN.matcher(clazz); StringBuilder sb = new StringBuilder(); diff --git a/jpos/src/main/java/org/jpos/util/ConcurrentUtil.java b/jpos/src/main/java/org/jpos/util/ConcurrentUtil.java index 568c76ad71..2dea34daad 100644 --- a/jpos/src/main/java/org/jpos/util/ConcurrentUtil.java +++ b/jpos/src/main/java/org/jpos/util/ConcurrentUtil.java @@ -20,7 +20,14 @@ import java.util.concurrent.ScheduledThreadPoolExecutor; +/** Utility class for creating pre-configured concurrent executor instances. */ public class ConcurrentUtil { + /** Private constructor — utility class. */ + private ConcurrentUtil() { } + /** + * Creates a {@link ScheduledThreadPoolExecutor} with a daemon thread factory. + * @return a new ScheduledThreadPoolExecutor + */ public static ScheduledThreadPoolExecutor newScheduledThreadPoolExecutor() { ScheduledThreadPoolExecutor stpe = new ScheduledThreadPoolExecutor(1, r -> { diff --git a/jpos/src/main/java/org/jpos/util/Destroyable.java b/jpos/src/main/java/org/jpos/util/Destroyable.java index 0074201bd5..8a50e455d8 100644 --- a/jpos/src/main/java/org/jpos/util/Destroyable.java +++ b/jpos/src/main/java/org/jpos/util/Destroyable.java @@ -20,6 +20,7 @@ /** + * Implemented by objects that require explicit cleanup on shutdown; the container calls {@link #destroy()} during teardown. * @author apr@cs.com.uy * @version $Id$ */ diff --git a/jpos/src/main/java/org/jpos/util/FSDMsg.java b/jpos/src/main/java/org/jpos/util/FSDMsg.java index 7971160287..2b04f4193d 100644 --- a/jpos/src/main/java/org/jpos/util/FSDMsg.java +++ b/jpos/src/main/java/org/jpos/util/FSDMsg.java @@ -48,7 +48,7 @@ /** * General purpose, Field Separator delimited message. * - *

    How to use

    + *

    How to use

    *

    * The message format (or schema) is defined in xml files containing a schema element, with an optional id attribute, and multiple * field elements. A field element is made up of the following attributes: @@ -76,7 +76,6 @@ *

    K
    Constant. The value is specified by the field content. No padding is done.
    *
    N
    Numeric. Padding, if any, is done with zeros to the left.
    * - *

    *

    * Supported field separators are: *

    @@ -90,7 +89,6 @@ *
    DS
    A dummy separator. This is similar to EOF, but the message stream must not end before it is allowed.
    *
    EOM
    End of message separator. This reads all bytes available in the stream. *
    - *

    *

    * Key fields allow you to specify a tree of possible message formats. The key fields are the fork points of the tree. * Multiple key fields are supported. It is also possible to have more key fields specified in appended schemas. diff --git a/jpos/src/main/java/org/jpos/util/FilterLogListener.java b/jpos/src/main/java/org/jpos/util/FilterLogListener.java index f217ce79fa..8493e80035 100644 --- a/jpos/src/main/java/org/jpos/util/FilterLogListener.java +++ b/jpos/src/main/java/org/jpos/util/FilterLogListener.java @@ -30,9 +30,9 @@ /** * A specific log listener that filters logs based on - * their priorities, - * priorities are ordered as follows: TRACE < DEBUG < INFO < WARN < ERROR < FATAL - * default priority is Log.INFO + * their priorities. Priorities are ordered as follows: + * {@code TRACE < DEBUG < INFO < WARN < ERROR < FATAL}. + * Default priority is {@code Log.INFO}. * @author Alireza Taherkordi * @version $Revision$ $Date$ */ diff --git a/jpos/src/main/java/org/jpos/util/LogEvent.java b/jpos/src/main/java/org/jpos/util/LogEvent.java index 2badf444df..dcde47953f 100644 --- a/jpos/src/main/java/org/jpos/util/LogEvent.java +++ b/jpos/src/main/java/org/jpos/util/LogEvent.java @@ -38,6 +38,7 @@ import java.util.*; /** + * A single structured log event that carries a tag, realm, payload items, and optionally a {@link Throwable}. * @author @apr */ public class LogEvent { diff --git a/jpos/src/main/java/org/jpos/util/LogEventWriter.java b/jpos/src/main/java/org/jpos/util/LogEventWriter.java index 411b5a1963..5a137fb014 100644 --- a/jpos/src/main/java/org/jpos/util/LogEventWriter.java +++ b/jpos/src/main/java/org/jpos/util/LogEventWriter.java @@ -30,7 +30,16 @@ * @since 2.1.4 */ public interface LogEventWriter { + /** + * Writes a log event to the underlying output. + * @param ev the log event to write + */ void write(LogEvent ev); + /** + * Sets the print stream used for output. + * @param printStream the destination stream + */ void setPrintStream(PrintStream printStream); + /** Closes the writer and releases any underlying resources. */ void close(); } diff --git a/jpos/src/main/java/org/jpos/util/LogListener.java b/jpos/src/main/java/org/jpos/util/LogListener.java index aded8472f4..14e8d5b010 100644 --- a/jpos/src/main/java/org/jpos/util/LogListener.java +++ b/jpos/src/main/java/org/jpos/util/LogListener.java @@ -22,10 +22,16 @@ import java.util.EventListener; /** + * Implemented by objects that wish to receive and process {@link LogEvent} instances produced by a {@link Logger}. * @author apr@cs.com.uy * @version $Id$ */ public interface LogListener extends EventListener { + /** + * Processes a log event. + * @param ev the log event + * @return the (potentially modified) log event, or null to suppress it + */ LogEvent log(LogEvent ev); default void setLogEventWriter (LogEventWriter w) { // do nothing, for backward compatibility diff --git a/jpos/src/main/java/org/jpos/util/LogProducer.java b/jpos/src/main/java/org/jpos/util/LogProducer.java index 1d8c773d66..91d9f7056b 100644 --- a/jpos/src/main/java/org/jpos/util/LogProducer.java +++ b/jpos/src/main/java/org/jpos/util/LogProducer.java @@ -18,8 +18,18 @@ package org.jpos.util; +/** Interface for objects that produce log events and manage a list of {@link LogListener}s. */ public interface LogProducer { + /** + * Adds a log listener. + * @param l the listener to add + */ void addListener(LogListener l); + /** + * Removes a specific log listener. + * @param l the listener to remove + */ void removeListener(LogListener l); + /** Removes all registered log listeners. */ void removeAllListeners(); } diff --git a/jpos/src/main/java/org/jpos/util/LogSource.java b/jpos/src/main/java/org/jpos/util/LogSource.java index 298ac02925..e86dfa3341 100644 --- a/jpos/src/main/java/org/jpos/util/LogSource.java +++ b/jpos/src/main/java/org/jpos/util/LogSource.java @@ -20,12 +20,26 @@ /** + * Implemented by objects that own a {@link Logger} and can produce {@link LogEvent} instances. * @author apr@cs.com.uy * @version $Id$ */ public interface LogSource { + /** + * Attaches a {@link Logger} and realm to this log source. + * @param logger the logger to use + * @param realm the log realm (diagnostic label) + */ void setLogger(Logger logger, String realm); + /** + * Returns the log realm associated with this source. + * @return log realm + */ String getRealm(); + /** + * Returns the Logger associated with this source. + * @return the Logger + */ Logger getLogger(); } diff --git a/jpos/src/main/java/org/jpos/util/Loggeable.java b/jpos/src/main/java/org/jpos/util/Loggeable.java index 584d702cbc..dba0002041 100644 --- a/jpos/src/main/java/org/jpos/util/Loggeable.java +++ b/jpos/src/main/java/org/jpos/util/Loggeable.java @@ -24,10 +24,16 @@ import java.io.PrintStream; /** + * Implemented by objects that can produce a human-readable log representation via {@link #dump(java.io.PrintStream, String)}. * @author apr@cs.com.uy * @version $Id$ */ public interface Loggeable { + /** + * Dumps a human-readable representation of this object to the print stream. + * @param p the output stream + * @param indent indentation prefix + */ void dump(PrintStream p, String indent); default void dump(PrintStream p, String indent, LogRenderer.Type type) { var renderer = LogRendererRegistry.getRenderer(this.getClass(), type); diff --git a/jpos/src/main/java/org/jpos/util/RealmLogFilter.java b/jpos/src/main/java/org/jpos/util/RealmLogFilter.java index 9ed6bab051..3850a3868f 100644 --- a/jpos/src/main/java/org/jpos/util/RealmLogFilter.java +++ b/jpos/src/main/java/org/jpos/util/RealmLogFilter.java @@ -61,14 +61,14 @@ * will show all LogEvents before RealmLogFilter filters these * according to the list of enabled realms.
    * - * Reads values configured inside or - * to choose elements of which realm to log. - * If is defined, these realms ONLY will be logged. Disabled will not be taken into account. - * If the realms are defined, only this will not be shown, the rest will. + * Reads values configured inside {@code } or + * {@code } to choose elements of which realm to log. + * If {@code } is defined, these realms ONLY will be logged. Disabled will not be taken into account. + * If the {@code } realms are defined, only this will not be shown, the rest will. * If none of them is defined the events will be logged.
    * * Those realms that had events but were filtered will be saved. These are logged at a certain interval defined - * by the property dump-interval in an tag. Once logged these filtered realms are reset. + * by the property dump-interval in an {@code } tag. Once logged these filtered realms are reset. * * @author Santiago Revilla * @author Alejandro Revilla diff --git a/jpos/src/main/java/org/jpos/util/RotateLogListener.java b/jpos/src/main/java/org/jpos/util/RotateLogListener.java index 3da6d59efc..5c38e99eea 100644 --- a/jpos/src/main/java/org/jpos/util/RotateLogListener.java +++ b/jpos/src/main/java/org/jpos/util/RotateLogListener.java @@ -82,7 +82,6 @@ public RotateLogListener () { *

      *
    • h - hostname lookup
      • *
    - *

    *

    * When code replacement fails, the token will be replaced by the code preceded by a # to give an indication * of what failed. This type of failure will not result in a startup failure. diff --git a/jpos/src/main/java/org/jpos/util/SimpleLogListener.java b/jpos/src/main/java/org/jpos/util/SimpleLogListener.java index fb597b196c..a8ee9c18a3 100644 --- a/jpos/src/main/java/org/jpos/util/SimpleLogListener.java +++ b/jpos/src/main/java/org/jpos/util/SimpleLogListener.java @@ -25,6 +25,7 @@ import java.io.PrintStream; /** + * A {@link LogListener} that writes log events to a {@link java.io.PrintStream} (default: {@code System.out}). * @author Alejandro P. Revilla * @version $Revision$ $Date$ * @see org.jpos.core.Configurable diff --git a/jpos/src/main/java/org/jpos/util/TPS.java b/jpos/src/main/java/org/jpos/util/TPS.java index aaaa249e5f..ef8d4ce280 100644 --- a/jpos/src/main/java/org/jpos/util/TPS.java +++ b/jpos/src/main/java/org/jpos/util/TPS.java @@ -39,7 +39,7 @@ *

      *
    • Auto update.
      • *
    • Manual update.
      • - *

    + * * *

    When operating in auto update mode, a shared scheduler is used and the * number of transactions (calls to tick()) is automatically calculated for diff --git a/jpos/src/main/java/org/jpos/util/function/ByteArrayMapper.java b/jpos/src/main/java/org/jpos/util/function/ByteArrayMapper.java index 2909e43458..b173d19ece 100644 --- a/jpos/src/main/java/org/jpos/util/function/ByteArrayMapper.java +++ b/jpos/src/main/java/org/jpos/util/function/ByteArrayMapper.java @@ -21,6 +21,7 @@ import java.util.function.Function; /** + * Functional interface for transforming a {@code byte[]} payload; used by log stream mappers. * @author Alwyn Schoeman * @since 2.1.4 */ diff --git a/jpos/src/main/java/org/jpos/util/function/LogEventMapper.java b/jpos/src/main/java/org/jpos/util/function/LogEventMapper.java index baa45b4d3d..31bf7fe6bf 100644 --- a/jpos/src/main/java/org/jpos/util/function/LogEventMapper.java +++ b/jpos/src/main/java/org/jpos/util/function/LogEventMapper.java @@ -23,6 +23,7 @@ import java.util.function.Function; /** + * Functional interface for transforming a {@link org.jpos.util.LogEvent}; used in log pipeline processing. * @author Alwyn Schoeman * @since 2.1.4 */ diff --git a/jpos/src/main/java/org/jpos/util/function/RemoveNewLinesMapper.java b/jpos/src/main/java/org/jpos/util/function/RemoveNewLinesMapper.java index cfd0bf573d..fdbc2567e6 100644 --- a/jpos/src/main/java/org/jpos/util/function/RemoveNewLinesMapper.java +++ b/jpos/src/main/java/org/jpos/util/function/RemoveNewLinesMapper.java @@ -30,13 +30,13 @@ * Configuration options allow you to optionally combine multiple spaces into a single space and * opting not to add a newline at the end of the data. * - * Example:
    - * 

    - *         
- *             
- *             
+ *         
+ *         
+ *     
+ * }
    * * NB. Do not set combine-spaces to true if you have data where spaces are significant. *
    • padm derivation rules
    {@code skdm} valuederived {@code padm} value