CSV-264: CSVParser identifies null, empty or blank headers as 'missing'

Duplicate missing header names are handled consistently between
CSVFormat and CSVParser.

Document that the ignore header case flag is for parser behaviour.

Update CSVDuplicateHeaderTest to add the ignore header case flag to
tests. Add test cases with case insensitive duplicates.

Author: aherbert

src/main/java/org/apache/commons/csv/CSVFormat.java

@@ -289,7 +289,7 @@ public Builder setAllowDuplicateHeaderNames(final boolean allowDuplicateHeaderNa
         }
 
         /**
-         * Sets the missing column names parser behavior, {@code true} to allow missing column names in the header line, {@code false} to cause an
+         * Sets the parser missing column names behavior, {@code true} to allow missing column names in the header line, {@code false} to cause an
          * {@link IllegalArgumentException} to be thrown.
          *
          * @param allowMissingColumnNames the missing column names behavior, {@code true} to allow missing column names in the header line, {@code false} to
@@ -564,7 +564,7 @@ public Builder setIgnoreEmptyLines(final boolean ignoreEmptyLines) {
         }
 
         /**
-         * Sets the case mapping behavior, {@code true} to access name/values, {@code false} to leave the mapping as is.
+         * Sets the parser case mapping behavior, {@code true} to access name/values, {@code false} to leave the mapping as is.
          *
          * @param ignoreHeaderCase the case mapping behavior, {@code true} to access name/values, {@code false} to leave the mapping as is.
          * @return This instance.
@@ -1599,7 +1599,7 @@ public boolean getIgnoreEmptyLines() {
     }
 
     /**
-     * Gets whether header names will be accessed ignoring case.
+     * Gets whether header names will be accessed ignoring case when parsing input.
      *
      * @return {@code true} if header names cases are ignored, {@code false} if they are case sensitive.
      * @since 1.3

src/main/java/org/apache/commons/csv/CSVParser.java

@@ -499,6 +499,8 @@ private Headers createHeaders() throws IOException {
 
             // build the name to index mappings
             if (headerRecord != null) {
+                // Track an occurrence of a null, empty or blank header.
+                boolean observedMissing = false;
                 for (int i = 0; i < headerRecord.length; i++) {
                     final String header = headerRecord[i];
                     final boolean blankHeader = CSVFormat.isBlank(header);
@@ -507,7 +509,7 @@ private Headers createHeaders() throws IOException {
                             "A header name is missing in " + Arrays.toString(headerRecord));
                     }
 
-                    final boolean containsHeader = header != null && hdrMap.containsKey(header);
+                    final boolean containsHeader = blankHeader ? observedMissing : hdrMap.containsKey(header);
                     final DuplicateHeaderMode headerMode = this.format.getDuplicateHeaderMode();
                     final boolean duplicatesAllowed = headerMode == DuplicateHeaderMode.ALLOW_ALL;
                     final boolean emptyDuplicatesAllowed = headerMode == DuplicateHeaderMode.ALLOW_EMPTY;
@@ -518,6 +520,7 @@ private Headers createHeaders() throws IOException {
                                 "The header contains a duplicate name: \"%s\" in %s. If this is valid then use CSVFormat.Builder.setDuplicateHeaderMode().",
                                 header, Arrays.toString(headerRecord)));
                     }
+                    observedMissing |= blankHeader;
                     if (header != null) {
                         hdrMap.put(header, Integer.valueOf(i));
                         if (headerNames == null) {