Add missing JavaDoc comments in package io.xlate.edi.stream (#424)

Signed-off-by: Michael Edgar <[email protected]>

src/main/java/io/xlate/edi/internal/ThrowingRunnable.java

@@ -5,18 +5,46 @@
 /**
  * A {@link Runnable} that can throw exceptions/errors. Internal use only.
  *
+ * @param <T>
+ *            the type of exception that may be thrown
+ *
  * @since 1.24
  */
 public interface ThrowingRunnable<T extends Exception> {
 
+    /**
+     * Run any code provided by an implementation, including code that may throw
+     * an exception.
+     *
+     * @throws T
+     *             any exception thrown by the implementation of this method
+     */
     void run() throws T;
 
-    @SuppressWarnings("unchecked")
+    /**
+     * Execute the provided task and apply the given exceptionWrapper function
+     * on any exception thrown by it.
+     *
+     * @param <T>
+     *            the type of exception that may be thrown
+     * @param <E>
+     *            the type of exception that this method may throw, wrapping any
+     *            thrown by task
+     * @param task
+     *            runnable to execute that may thrown an exception T
+     * @param exceptionWrapper
+     *            wrapper function to wrap/convert an exception T to an
+     *            exception E
+     * @throws E
+     *             exception thrown when task throws an exception T
+     */
     static <T extends Exception, E extends Exception> void run(ThrowingRunnable<T> task, Function<T, E> exceptionWrapper) throws E {
         try {
             task.run();
         } catch (Exception e) {
-            throw exceptionWrapper.apply((T) e);
+            @SuppressWarnings("unchecked")
+            T thrown = (T) e;
+            throw exceptionWrapper.apply(thrown);
         }
     }
 }

src/main/java/io/xlate/edi/stream/EDIInputFactory.java

@@ -22,8 +22,25 @@
 
 import io.xlate.edi.schema.Schema;
 
+/**
+ * Defines an abstract implementation of a factory for getting EDIStreamReaders,
+ * JSON parsers (wrapping an existing EDIStreamReader), and XMLStreamReaders
+ * (wrapping an existing EDIStreamReader). An EDIInputErrorReporter may also be
+ * configured via the factory for use with each new EDIStreamReader created.
+ */
 public abstract class EDIInputFactory extends PropertySupport {
 
+    /**
+     * When set to false, control structures, segments, elements, and codes will
+     * not be validated unless a user-provided control schema has been set using
+     * {@link EDIStreamReader#setControlSchema(Schema)}.
+     *
+     * When set to true AND no user-provided control schema has been set, the
+     * reader will attempt to find a known control schema for the detected EDI
+     * dialect and version to be used for control structure validation.
+     *
+     * Default value: true
+     */
     public static final String EDI_VALIDATE_CONTROL_STRUCTURE = "io.xlate.edi.stream.EDI_VALIDATE_CONTROL_STRUCTURE";
 
     /**
@@ -138,6 +155,12 @@ public static EDIInputFactory newFactory() {
         return new io.xlate.edi.internal.stream.StaEDIInputFactory();
     }
 
+    /**
+     * Default constructor
+     */
+    protected EDIInputFactory() {
+    }
+
     /**
      * Creates a new {@link EDIStreamReader} using the given {@link InputStream}
      * (with default encoding).

src/main/java/io/xlate/edi/stream/EDINamespaces.java

@@ -3,7 +3,15 @@
 import java.util.Arrays;
 import java.util.List;
 
+/**
+ * Defines the constant values of namespaces for each of the XML elements
+ * generated by the XMLStreamReader (created via
+ * {@link EDIInputFactory#createXMLStreamReader(EDIStreamReader)} and consumed
+ * by the XMLStreamWriter (created via
+ * {@link EDIOutputFactory#createXMLStreamWriter(EDIStreamWriter)}.
+ */
 public class EDINamespaces {
+
     private EDINamespaces() {
     }
 
@@ -30,6 +38,11 @@ private EDINamespaces() {
      */
     public static final String ELEMENTS = "urn:xlate.io:staedi:names:elements";
 
+    /**
+     * Obtain a list of all namespace constants declared by {@linkplain EDINamespaces}.
+     *
+     * @return the list of all namespace constants
+     */
     public static final List<String> all() {
         return Arrays.asList(LOOPS, SEGMENTS, COMPOSITES, ELEMENTS);
     }

src/main/java/io/xlate/edi/stream/EDIOutputFactory.java

@@ -19,6 +19,12 @@
 
 import javax.xml.stream.XMLStreamWriter;
 
+/**
+ * Defines an abstract implementation of a factory for getting EDIStreamWriters
+ * and XMLStreamWriters (wrapping an existing EDIStreamWriter). An EDIOutputErrorReporter
+ * may also be configured via the factory for use with each new EDIStreamWriter
+ * created.
+ */
 public abstract class EDIOutputFactory extends PropertySupport {
 
     /**
@@ -67,6 +73,12 @@ public static EDIOutputFactory newFactory() {
         return new io.xlate.edi.internal.stream.StaEDIOutputFactory();
     }
 
+    /**
+     * Default constructor
+     */
+    protected EDIOutputFactory() {
+    }
+
     /**
      * Create a new EDIStreamWriter that writes to a stream
      *

src/main/java/io/xlate/edi/stream/EDIStreamConstants.java

@@ -15,8 +15,17 @@
  ******************************************************************************/
 package io.xlate.edi.stream;
 
+/**
+ * Collection of constant values identifying the several EDI standards and the
+ * delimiters used in processing EDI data streams.
+ */
 public interface EDIStreamConstants {
 
+    /**
+     * Defines the constant values possibly returned by
+     * {@link EDIStreamReader#getStandard()} and
+     * {@link EDIStreamWriter#getStandard()}.
+     */
     public static class Standards {
         private Standards() {
         }
@@ -39,15 +48,50 @@ private Standards() {
         public static final String X12 = "X12";
     }
 
+    /**
+     * Defines the constant values of EDI delimiters present in the maps
+     * returned by
+     * {@link EDIStreamReader#getDelimiters()}/{@link EDIStreamWriter#getDelimiters()}
+     * and accepted as properties for output via
+     * {@link EDIOutputFactory#setProperty(String, Object)}.
+     */
     public static class Delimiters {
         private Delimiters() {
         }
 
+        /**
+         * Key for the delimiter used to terminate/end a segment.
+         */
         public static final String SEGMENT = "io.xlate.edi.stream.delim.segment";
+
+        /**
+         * Key for the delimiter used to terminate/end a simple or composite
+         * data element.
+         */
         public static final String DATA_ELEMENT = "io.xlate.edi.stream.delim.dataElement";
+
+        /**
+         * Key for the delimiter used to terminate/end a component of a
+         * composite element.
+         */
         public static final String COMPONENT_ELEMENT = "io.xlate.edi.stream.delim.componentElement";
+
+        /**
+         * Key for the delimiter used to terminate/end a repeating data element.
+         */
         public static final String REPETITION = "io.xlate.edi.stream.delim.repetition";
+
+        /**
+         * Key for the character used as the decimal point for non-integer
+         * numeric element types.
+         */
         public static final String DECIMAL = "io.xlate.edi.stream.delim.decimal";
+
+        /**
+         * Key for the character used as a release character, allowing the next
+         * character in the EDI stream to be treated as data element text rather
+         * than a delimiter.
+         */
         public static final String RELEASE = "io.xlate.edi.stream.delim.release";
     }
 }

src/main/java/io/xlate/edi/stream/EDIStreamEvent.java

@@ -1,29 +1,101 @@
 package io.xlate.edi.stream;
 
+/**
+ * Enumeration of stream event types that may be encountered by the
+ * EDIStreamReader.
+ *
+ * @see EDIStreamReader#next()
+ * @see EDIStreamReader#nextTag()
+ * @see EDIStreamReader#getEventType()
+ */
 public enum EDIStreamEvent {
+
+    /**
+     * Event for a simple element or component element (within a composite).
+     */
     ELEMENT_DATA,
+
+    /**
+     * Event for binary element data
+     *
+     * @see EDIStreamReader#getBinaryData()
+     */
     ELEMENT_DATA_BINARY,
 
+    /**
+     * Event for the start of a composite element.
+     */
     START_COMPOSITE,
+
+    /**
+     * Event for the end of a composite element.
+     */
     END_COMPOSITE,
 
+    /**
+     * Event for the start of a segment.
+     */
     START_SEGMENT,
+
+    /**
+     * Event for the end of a segment.
+     */
     END_SEGMENT,
 
+    /**
+     * Event for the start of an interchange.
+     */
     START_INTERCHANGE,
+
+    /**
+     * Event for the end of an interchange.
+     */
     END_INTERCHANGE,
 
+    /**
+     * Event for the start of a functional group.
+     */
     START_GROUP,
+
+    /**
+     * Event for the end of a functional group.
+     */
     END_GROUP,
 
+    /**
+     * Event for the start of a transaction.
+     */
     START_TRANSACTION,
+
+    /**
+     * Event for the end of a transaction.
+     */
     END_TRANSACTION,
 
+    /**
+     * Event for the start of a data loop (logical grouping of segments).
+     */
     START_LOOP,
+
+    /**
+     * Event for the end of a data loop (logical grouping of segments).
+     */
     END_LOOP,
 
+    /**
+     * Event for an error relating to a segment
+     */
     SEGMENT_ERROR(true),
+
+    /**
+     * Event for an error relating to the data received in an element.
+     */
     ELEMENT_DATA_ERROR(true),
+
+    /**
+     * Event for an error relating to the an occurrence of an element. E.g. a
+     * missing required element.
+     */
     ELEMENT_OCCURRENCE_ERROR(true);
 
     private final boolean error;
@@ -36,6 +108,13 @@ private EDIStreamEvent() {
         this(false);
     }
 
+    /**
+     * Indicates whether a particular EDIStreamEvent represents a validation
+     * error.
+     *
+     * @return true when the event represents a validation error, otherwise
+     *         false.
+     */
     public boolean isError() {
         return error;
     }

src/main/java/io/xlate/edi/stream/EDIStreamException.java

@@ -15,12 +15,30 @@
  ******************************************************************************/
 package io.xlate.edi.stream;
 
+/**
+ * Checked exception that may be thrown by EDIInputFactory, EDIStreamReader,
+ * EDIOutputFactory, and EDIStreamWriter in the processing of EDI data.
+ */
 public class EDIStreamException extends Exception {
 
     private static final long serialVersionUID = -1232370584780899896L;
 
+    /**
+     * {@linkplain Location} of the exception
+     */
     protected final transient Location location;
 
+    /**
+     * Build a readable message that includes a detail message together with the
+     * location of the exception
+     *
+     * @param message
+     *            detail message for the exception
+     * @param location
+     *            location of the exception
+     * @return concatenation of the detail message and location if the message
+     *         does not already contain the location
+     */
     protected static String buildMessage(String message, Location location) {
         String locationString = location.toString();
         if (message.contains(locationString)) {

src/main/java/io/xlate/edi/stream/EDIStreamReader.java

@@ -26,6 +26,15 @@
 import io.xlate.edi.schema.Schema;
 import io.xlate.edi.schema.implementation.EDITypeImplementation;
 
+/**
+ * The EDIStreamReader interface allows forward, read-only access to EDI. It is
+ * designed to be the lowest level and most efficient way to read EDI data.
+ *
+ * <p>
+ * The EDIStreamReader is designed to iterate over EDI using {@link #next()} and
+ * {@link #hasNext()}. The data can be accessed using methods such as
+ * {@link #getEventType()} and {@link #getText()}.
+ */
 public interface EDIStreamReader extends Closeable, EDIStreamConstants {
 
     /**
@@ -51,7 +60,7 @@ public interface EDIStreamReader extends Closeable, EDIStreamConstants {
     /**
      * Get next parsing event
      *
-     * @return the integer code corresponding to the current parse event
+     * @return the event type corresponding to the current parse event
      * @throws NoSuchElementException
      *             if this is called when hasNext() returns false
      * @throws EDIStreamException