Document that the list of header names will not contain null names.

Added a test to demonstrate missing null headers from the list.

Author: aherbert

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

@@ -555,6 +555,11 @@ public String getFirstEndOfLine() {
      * <p>
      * The map keys are column names. The map values are 0-based indices.
      * </p>
+     * <p>
+     * Note: The map can only provide a one-to-one mapping when the format did not
+     * contain null or duplicate column names.
+     * </p>
+     *
      * @return a copy of the header map.
      */
     public Map<String, Integer> getHeaderMap() {
@@ -577,8 +582,14 @@ Map<String, Integer> getHeaderMapRaw() {
 
     /**
      * Returns a read-only list of header names that iterates in column order.
+     * <p>
+     * Note: The list provides strings that can be used as keys in the header map.
+     * The list will not contain null column names if they were present in the input
+     * format.
+     * </p>
      *
      * @return read-only list of header names that iterates in column order.
+     * @see #getHeaderMap()
      * @since 1.7
      */
     public List<String> getHeaderNames() {

src/test/java/org/apache/commons/csv/CSVParserTest.java

@@ -724,6 +724,20 @@ public void testHeadersMissingOneColumnException() throws Exception {
        assertThrows(IllegalArgumentException.class, () -> CSVFormat.DEFAULT.withHeader().parse(in).iterator());
     }
 
+    @Test
+    public void testHeadersWithNullColumnName() throws IOException {
+        final Reader in = new StringReader("header1,null,header3\n1,2,3\n4,5,6");
+        final Iterator<CSVRecord> records = CSVFormat.DEFAULT
+            .withHeader()
+            .withNullString("null")
+            .withAllowMissingColumnNames()
+            .parse(in).iterator();
+        final CSVRecord record = records.next();
+        // Expect the null header to be missing
+        assertEquals(Arrays.asList("header1", "header3"), record.getParser().getHeaderNames());
+        assertEquals(2, record.getParser().getHeaderMap().size());
+    }
+
     @Test
     public void testIgnoreCaseHeaderMapping() throws Exception {
         final Reader reader = new StringReader("1,2,3");