Refactor and add comments

scripts/make-javadoc.bat

@@ -5,7 +5,7 @@ cd %~dp0..
 
 SET output_dir=build\javadoc
 
-IF "%1" == "" (
+IF NOT "%1" == "" (
     SET visibility=%1
     SET output_dir="!output_dir!-!visibility!"
     IF "!visibility!" EQU "private" SET linksrc=-linksource

src/com/illcode/hl7/HL7Encoder.java

@@ -1,7 +1,5 @@
 package com.illcode.hl7;
 
-import org.apache.commons.lang3.StringUtils;
-
 import java.util.Collection;
 import java.util.List;
 
@@ -50,31 +48,45 @@ public void setParams(HL7Params params) {
      */
     public String encode(Message m) {
         final Collection<List<Segment>> segments = m.segmentMap.values();
-        StringBuilder sb = new StringBuilder(segments.size() * 100);
+        final StringBuilder sb = new StringBuilder(segments.size() * 100);
         for (List<Segment> segReps : segments) {
-            for (Segment s : segReps) {
-                sb.append(s.id);
-                final int numFields = s.fieldValues.size();
-                int fieldNo = 0;
-                if (s.id.equals("MSH")) {
-                    // output MSH.1 and MSH.2 specially
-                    sb.append(params.fieldSeparator);
-                    sb.append(params.componentSeparator).append(params.repetitionSeparator)
-                      .append(params.escapeChar).append(params.subcomponentSeparator);
-                    fieldNo = 2;
-                }
-                for (; fieldNo < numFields; fieldNo++) {
-                    sb.append(params.fieldSeparator);
-                    List<FieldValue> repList = s.fieldValues.get(fieldNo);
-                    encodeHelper(sb, repList, 0);
-                }
-                sb.append('\r');
-            }
+            for (Segment s : segReps)
+                encodeHelper(sb, s);
         }
         return sb.toString();
     }
 
-    private void encodeHelper(StringBuilder sb, List<FieldValue> values, int level) {
+    /**
+     * Encode a segment into HL7v2 format
+     * @param s Segment to encode
+     * @return HL7v2 text (including the carriage-return '\r' at the end)
+     */
+    public String encode(Segment s) {
+        final StringBuilder sb = new StringBuilder(100);
+        encodeHelper(sb, s);
+        return sb.toString();
+    }
+
+    private void encodeHelper(StringBuilder sb, Segment s) {
+        sb.append(s.id);
+        final int numFields = s.fieldValues.size();
+        int fieldNo = 0;
+        if (s.id.equals("MSH")) {
+            // output MSH.1 and MSH.2 specially
+            sb.append(params.fieldSeparator);
+            sb.append(params.componentSeparator).append(params.repetitionSeparator)
+              .append(params.escapeChar).append(params.subcomponentSeparator);
+            fieldNo = 2;
+        }
+        for (; fieldNo < numFields; fieldNo++) {
+            sb.append(params.fieldSeparator);
+            List<FieldValue> repList = s.fieldValues.get(fieldNo);
+            encodeFieldValues(sb, repList, 0);
+        }
+        sb.append('\r');
+    }
+
+    private void encodeFieldValues(StringBuilder sb, List<FieldValue> values, int level) {
         if (values == null || level >= params.fieldValueSeparators.length)
             return;
         boolean first = true;
@@ -89,7 +101,7 @@ private void encodeHelper(StringBuilder sb, List<FieldValue> values, int level)
                         sb.append(params.escape(v.value));
                 }
             } else {
-                encodeHelper(sb, v.children, level + 1);
+                encodeFieldValues(sb, v.children, level + 1);
             }
         }
     }

src/com/illcode/hl7/Message.java

@@ -4,6 +4,10 @@
 
 import java.util.*;
 
+/**
+ * An HL7v2 message. A message is represent as a map from a segment ID to a list of {@link Segment}S
+ * (with entries in the list being the repetitions of segments in the message).
+ */
 public final class Message
 {
     // Segment ID -> repetitions of segment
@@ -25,40 +29,50 @@ public boolean containsSegment(String id) {
     }
 
     /**
-     * Return a list of repetitions for a given segment ID, or null if no segment with
-     * that ID is in the message.
+     * Return a collection of all the repetitions of segments in the message.
+     * <p>
+     * Note that the iteration order of the returned collection is the order in which the
+     * segment lists were added to the message, so to get a well-formed HL7 message, you'll
+     * either need to:
+     * <ol>
+     *     <li>Insert segments in the correct order (i.e. MSH first, etc.), or</li>
+     *     <li>Pick out the segments you need in the appropriate order using {@link #getSegment(String)}
+     *         or {@link #getSegment(String, int)} and encode them individually</li>
+     * </ol>
+     * </p>
      */
-    public List<Segment> getSegments(String id) {
-        return segmentMap.get(id);
+    public Collection<List<Segment>> segments() {
+        return segmentMap.values();
     }
 
     /**
-     * Return a collection of all the repetitions of segments in the message.
+     * Return a list of repetitions for a given segment ID, or null if no segment with
+     * that ID is in the message.
      */
-    public Collection<List<Segment>> segments() {
-        return segmentMap.values();
+    public List<Segment> getSegments(String id) {
+        return segmentMap.get(id);
     }
 
     /**
-     * Return the first segment (among any repetitions) with the given ID, or
+     * Return a given reptition of segments with the given ID, or
      * null if no such segment is in the Message.
      */
-    public Segment getSegment(String id) {
+    public Segment getSegment(String id, int repetition) {
         final List<Segment> l = segmentMap.get(id);
-        if (l != null && !l.isEmpty())
-            return l.get(0);
+        if (l != null && l.size() >= repetition)
+            return l.get(repetition - 1);
         else
             return null;
     }
 
     /**
-     * Return a given reptition of segments with the given ID, or
+     * Return the first segment (among any repetitions) with the given ID, or
      * null if no such segment is in the Message.
      */
-    public Segment getSegment(String id, int repetition) {
+    public Segment getSegment(String id) {
         final List<Segment> l = segmentMap.get(id);
-        if (l != null && l.size() >= repetition)
-            return l.get(repetition - 1);
+        if (l != null && !l.isEmpty())
+            return l.get(0);
         else
             return null;
     }

src/com/illcode/hl7/Segment.java

@@ -7,7 +7,7 @@
 import static org.apache.commons.lang3.StringUtils.defaultString;
 
 /**
- * A class representing the field data in a single HL7v2 segment.
+ * Field data in a single HL7v2 segment.
  */
 public final class Segment
 {
@@ -303,9 +303,9 @@ private void toStringHelper(StringBuilder sb, String prefix, FieldValue v) {
     }
 
     /**
-     * A class representing the value of a field (scalar or composite). The value is text that is either
-     * contained in the node itself (if it is a field with no components, or a component with no
-     * subcomponents, or is a subcomponent), or it is the list of the values of its children.
+     * The value of a field (scalar or composite). The value is either text contained in the node itself (if
+     * it is a field with no components, or a component with no subcomponents, or is a subcomponent), or it
+     * is the list of the values of its children.
      */
     public static class FieldValue {
         /** Scalar value of this FieldValue. May be null if the FieldValue has a null-value. */