Merge branch 'master' into testCSVRecord

Author: dota17

NOTICE.txt

@@ -1,5 +1,5 @@
 Apache Commons CSV
-Copyright 2005-2019 The Apache Software Foundation
+Copyright 2005-2020 The Apache Software Foundation
 
 This product includes software developed at
-The Apache Software Foundation (http://www.apache.org/).
+The Apache Software Foundation (https://www.apache.org/).

README.md

@@ -46,10 +46,9 @@ Apache Commons CSV
 [![Build Status](https://travis-ci.org/apache/commons-csv.svg)](https://travis-ci.org/apache/commons-csv)
 [![Coverage Status](https://coveralls.io/repos/apache/commons-csv/badge.svg)](https://coveralls.io/r/apache/commons-csv)
 [![Maven Central](https://maven-badges.herokuapp.com/maven-central/org.apache.commons/commons-csv/badge.svg)](https://maven-badges.herokuapp.com/maven-central/org.apache.commons/commons-csv/)
-[![Javadocs](https://javadoc.io/badge/org.apache.commons/commons-csv/1.7.svg)](https://javadoc.io/doc/org.apache.commons/commons-csv/1.7)
+[![Javadocs](https://javadoc.io/badge/org.apache.commons/commons-csv/1.8.svg)](https://javadoc.io/doc/org.apache.commons/commons-csv/1.8)
 
-The Apache Commons CSV library provides a simple interface for reading and writing
-CSV files of various types.
+The Apache Commons CSV library provides a simple interface for reading and writing CSV files of various types.
 
 Documentation
 -------------
@@ -68,7 +67,7 @@ Alternatively you can pull it from the central Maven repositories:
 <dependency>
   <groupId>org.apache.commons</groupId>
   <artifactId>commons-csv</artifactId>
-  <version>1.7</version>
+  <version>1.8</version>
 </dependency>
 ```
 

RELEASE-NOTES.txt

@@ -1,3 +1,66 @@
+                        Apache Commons CSV
+                        Version 1.8
+                        Release Notes
+
+
+INTRODUCTION:
+
+This document contains the release notes for the 1.8-SNAPSHOT version of Apache Commons CSV.
+Commons CSV reads and writes files in variations of the Comma Separated Value (CSV) format.
+
+Commons CSV requires at least Java 6.
+
+The Apache Commons CSV library provides a simple interface for reading and writing CSV files of various types.
+
+Feature and bug fix release (Java 8).
+This release fixes serialization compatibility of CSVRecord with versions 1.0 to 1.6. New fields added since 
+1.7 are not serialized. Support for Serializable is scheduled to be removed in version 2.0.
+
+Changes in this version include:
+
+NEW FEATURES
+==============
+
+o CSV-255:  Add CSVRecord.isSet(int) method #52. Thanks to 0x100.
+
+FIXED BUGS
+============
+
+o CSV-135:  Char escape doesn't work properly with quoting. Thanks to Mateusz Zakarczemny.
+o CSV-244:  Test case failures following CSVFormat#equals() update.
+o CSV-243:  CSVFormat withTrim() and withIgnoreSurroundingSpaces() need better docs.
+o CSV-242:  CSVFormat equals() and hashCode() don't use all fields.
+o CSV-241:  CSVFormat#validate() does not account for allowDuplicateHeaderNames #43. Thanks to LuckyIlam, Gary Gregory.
+o CSV-245:  Post 1.7 release fixes. Thanks to Alex Herbert.
+o CSV-252:  Upgrade test framework to JUnit 5 Jupiter #49, #50. Thanks to Alex Herbert.
+o CSV-247:  A single empty header is allowed when not allowing empty column headers. #47. Thanks to Alex Herbert, Gary Gregory.
+o CSV-248:  CSVRecord is not Serializable. Thanks to Alex Herbert.
+o           Use test scope for supercsv #48. Thanks to Alex Herbert.
+
+CHANGES
+=========
+
+o           Update tests from H2 1.4.199 to 1.4.200. Thanks to Gary Gregory.
+o           Update tests from Hamcrest 2.1 to 2.2. Thanks to Gary Gregory.
+o           Update tests from Mockito 3.1.0 to 3.2.4. Thanks to Gary Gregory.
+o           Fix typos in site and test #53. Thanks to Chen.
+o           Fix typo performance test #55. Thanks to Chen.
+
+
+Historical list of changes: https://commons.apache.org/proper/commons-csv/changes-report.html
+
+For complete information on Apache Commons CSV, including instructions on how to submit bug reports,
+patches, or suggestions for improvement, see the Apache Apache Commons CSV website:
+
+https://commons.apache.org/proper/commons-csv/
+
+Download page: https://commons.apache.org/proper/commons-csv/download_csv.cgi
+
+Have fun!
+-Apache Commons CSV team
+
+------------------------------------------------------------------------------
+
                         Apache Commons CSV
                         Version 1.7
                         Release Notes
@@ -50,7 +113,6 @@ Have fun!
 
 ------------------------------------------------------------------------------
 
-
                         Apache Commons CSV
                         Version 1.6
                         Release Notes

pom.xml

@@ -20,22 +20,19 @@
   <parent>
     <groupId>org.apache.commons</groupId>
     <artifactId>commons-parent</artifactId>
-    <version>48</version>
+    <version>50</version>
   </parent>
   <artifactId>commons-csv</artifactId>
   <version>1.8-SNAPSHOT</version>
   <name>Apache Commons CSV</name>
   <url>https://commons.apache.org/proper/commons-csv/</url>
-  <description>
-The Apache Commons CSV library provides a simple interface for reading and writing
-CSV files of various types.
-  </description>
+  <description>The Apache Commons CSV library provides a simple interface for reading and writing CSV files of various types.</description>
 
   <dependencies>
     <dependency>
       <groupId>org.junit.jupiter</groupId>
       <artifactId>junit-jupiter</artifactId>
-      <version>5.5.2</version>
+      <version>5.6.0</version>
       <scope>test</scope>
     </dependency>
     <dependency>
@@ -143,7 +140,7 @@ CSV files of various types.
     <commons.release.version>1.8</commons.release.version>
     <commons.release.desc>(Java 8)</commons.release.desc>
     <!-- The RC version used in the staging repository URL. -->
-    <commons.rc.version>RC1</commons.rc.version>
+    <commons.rc.version>RC2</commons.rc.version>
     <commons.bc.version>1.7</commons.bc.version>
     <commons.componentid>csv</commons.componentid>
     <commons.module.name>org.apache.commons.csv</commons.module.name>
@@ -261,6 +258,7 @@ CSV files of various types.
             <!-- The ferc.gov files are included discussion in https://issues.apache.org/jira/browse/LEGAL-175. -->
             <exclude>src/test/resources/ferc.gov/contract.txt</exclude>
             <exclude>src/test/resources/ferc.gov/transaction.txt</exclude>
+            <exclude>src/test/resources/**/*.bin</exclude>
           </excludes>
         </configuration>
       </plugin>
@@ -337,7 +335,7 @@ CSV files of various types.
                 </tags>
               </tagClass>
               <tagClass>
-                <displayName>Noteable Markers</displayName>
+                <displayName>Notable Markers</displayName>
                 <tags>
                   <tag>
                     <matchString>NOTE</matchString>
@@ -379,59 +377,14 @@ CSV files of various types.
             <exclude>src/test/resources/CSVFileParser/testCSV85_ignoreEmpty.txt</exclude>
             <exclude>src/test/resources/ferc.gov/contract.txt</exclude>
             <exclude>src/test/resources/ferc.gov/transaction.txt</exclude>
+            <exclude>src/test/resources/**/*.bin</exclude>
           </excludes>
         </configuration>
       </plugin>
     </plugins>
   </reporting>
 
   <profiles>
-    <profile>
-      <id>setup-checkout</id>
-      <activation>
-        <file>
-          <missing>site-content</missing>
-        </file>
-      </activation>
-      <build>
-        <plugins>
-          <plugin>
-            <groupId>org.apache.maven.plugins</groupId>
-            <artifactId>maven-antrun-plugin</artifactId>
-            <version>1.8</version>
-            <executions>
-              <execution>
-                <id>prepare-checkout</id>
-                <phase>pre-site</phase>
-                <goals>
-                  <goal>run</goal>
-                </goals>
-                <configuration>
-                  <tasks>
-                    <exec executable="svn">
-                      <arg line="checkout --depth immediates ${commons.scmPubUrl} ${commons.scmPubCheckoutDirectory}" />
-                    </exec>
-
-                    <exec executable="svn">
-                      <arg line="update --set-depth exclude ${commons.scmPubCheckoutDirectory}/javadocs" />
-                    </exec>
-
-                    <pathconvert pathsep=" " property="dirs">
-                      <dirset dir="${commons.scmPubCheckoutDirectory}" includes="*" />
-                    </pathconvert>
-                    <exec executable="svn">
-                      <arg line="update --set-depth infinity ${dirs}" />
-                    </exec>
-                  </tasks>
-                </configuration>
-              </execution>
-            </executions>
-          </plugin>
-        </plugins>
-      </build>
-    </profile>
-
-
     <!-- Profile to build and run the benchmarks. Use 'mvn test -Pbenchmark', and add '-Dbenchmark=foo' to run only the foo benchmark -->
     <profile>
       <id>benchmark</id>

src/changes/changes.xml

@@ -38,7 +38,12 @@
     <title>Apache Commons CSV Release Notes</title>
   </properties>
   <body>
-    <release version="1.8" date="2019-MM-DD" description="Feature and bug fix release (Java 8)">
+    <release version="1.8" date="2019-02-01" description="Feature and bug fix release (Java 8).
+
+This release fixes serialization compatibility of CSVRecord with versions 1.0 to 1.6.
+New fields added since 1.7 are not serialized. Support for Serializable is scheduled to be
+removed in version 2.0.
+">
       <action issue="CSV-255" type="add" dev="ggregory" due-to="0x100">Add CSVRecord.isSet(int) method #52.</action>
       <action issue="CSV-135" type="fix" dev="sebb" due-to="Mateusz Zakarczemny">Char escape doesn't work properly with quoting.</action>
       <action issue="CSV-244" type="fix" dev="sebb">Test case failures following CSVFormat#equals() update.</action>
@@ -48,10 +53,13 @@
       <action issue="CSV-245" type="fix" dev="ggregory" due-to="Alex Herbert">Post 1.7 release fixes.</action>
       <action issue="CSV-252" type="fix" dev="ggregory" due-to= "Alex Herbert">Upgrade test framework to JUnit 5 Jupiter #49, #50.</action>
       <action issue="CSV-247" type="fix" dev="ggregory" due-to="Alex Herbert, Gary Gregory">A single empty header is allowed when not allowing empty column headers. #47.</action>
+      <action issue="CSV-248" type="fix" dev="ggregory" due-to="Alex Herbert">CSVRecord is not Serializable.</action>
       <action                 type="fix" dev="ggregory" due-to="Alex Herbert">Use test scope for supercsv #48.</action>
       <action                 type="update" dev="ggregory" due-to="Gary Gregory">Update tests from H2 1.4.199 to 1.4.200.</action>
       <action                 type="update" dev="ggregory" due-to="Gary Gregory">Update tests from Hamcrest 2.1 to 2.2.</action>
       <action                 type="update" dev="ggregory" due-to="Gary Gregory">Update tests from Mockito 3.1.0 to 3.2.4.</action>
+      <action                 type="update" dev="ggregory" due-to="Chen">Fix typos in site and test #53.</action>
+      <action                 type="update" dev="ggregory" due-to="Chen">Fix typo performance test #55.</action>
     </release>
     <release version="1.7" date="2019-06-01" description="Feature and bug fix release (Java 8)">
       <action issue="CSV-233" type="add" dev="ggregory" due-to="Gary Gregory">Add predefined CSVFormats for printing MongoDB CSV and TSV.</action>

src/changes/release-notes.vm

@@ -25,7 +25,7 @@ INTRODUCTION:
 This document contains the release notes for the ${version} version of Apache Commons CSV.
 Commons CSV reads and writes files in variations of the Comma Separated Value (CSV) format.
 
-CSV requires at least Java 6.
+Commons CSV requires at least Java 6.
 
 $introduction.replaceAll("(?<!\015)\012", "
 ").replaceAll("(?m)^ +","")
@@ -122,5 +122,7 @@ patches, or suggestions for improvement, see the Apache ${project.name} website:
 
 ${project.url}
 
+Download page: ${project.url}download_csv.cgi
+
 Have fun!
 -Apache Commons CSV team

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

@@ -2112,9 +2112,8 @@ public CSVFormat withIgnoreSurroundingSpaces() {
     /**
      * Returns a new {@code CSVFormat} with the parser trimming behavior of the format set to the given value.
      *
-     * @param ignoreSurroundingSpaces
-     *            the parser trimming behavior, {@code true} to remove the surrounding spaces, {@code false} to leave the
-     *            spaces as is.
+     * @param ignoreSurroundingSpaces the parser trimming behavior, {@code true} to remove the surrounding spaces,
+     *        {@code false} to leave the spaces as is.
      * @return A new CSVFormat that is equal to this but with the specified trimming behavior.
      */
     public CSVFormat withIgnoreSurroundingSpaces(final boolean ignoreSurroundingSpaces) {

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/main/java/org/apache/commons/csv/CSVRecord.java

@@ -24,9 +24,19 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Map.Entry;
+import java.util.Objects;
 
 /**
  * A CSV record parsed from a CSV file.
+ *
+ * <p>
+ * Note: Support for {@link Serializable} is scheduled to be removed in version 2.0.
+ * In version 1.8 the mapping between the column header and the column index was
+ * removed from the serialised state. The class maintains serialization compatibility
+ * with versions pre-1.8 for the record values; these must be accessed by index
+ * following deserialization. There will be loss of any functionally linked to the header
+ * mapping when transferring serialised forms pre-1.8 to 1.8 and vice versa.
+ * </p>
  */
 public final class CSVRecord implements Serializable, Iterable<String> {
 
@@ -45,8 +55,8 @@ public final class CSVRecord implements Serializable, Iterable<String> {
     /** The values of the record */
     private final String[] values;
 
-    /** The parser that originates this record. */
-    private final CSVParser parser;
+    /** The parser that originates this record. This is not serialized. */
+    private final transient CSVParser parser;
 
     CSVRecord(final CSVParser parser, final String[] values, final String comment, final long recordNumber,
             final long characterPosition) {
@@ -65,7 +75,7 @@ public final class CSVRecord implements Serializable, Iterable<String> {
      * @return the String at the given enum String
      */
     public String get(final Enum<?> e) {
-        return get(e.toString());
+        return get(Objects.toString(e, null));
     }
 
     /**
@@ -82,14 +92,24 @@ public String get(final int i) {
     /**
      * Returns a value by name.
      *
+     * <p>
+     * Note: This requires a field mapping obtained from the original parser.
+     * A check using {@link #isMapped(String)} should be used to determine if a
+     * mapping exists from the provided {@code name} to a field index. In this case an
+     * exception will only be thrown if the record does not contain a field corresponding
+     * to the mapping, that is the record length is not consistent with the mapping size.
+     * </p>
+     *
      * @param name
      *            the name of the column to be retrieved.
      * @return the column value, maybe null depending on {@link CSVFormat#getNullString()}.
      * @throws IllegalStateException
      *             if no header mapping was provided
      * @throws IllegalArgumentException
      *             if {@code name} is not mapped or if the record is inconsistent
+     * @see #isMapped(String)
      * @see #isConsistent()
+     * @see #getParser()
      * @see CSVFormat#withNullString(String)
      */
     public String get(final String name) {
@@ -135,12 +155,17 @@ public String getComment() {
     }
 
     private Map<String, Integer> getHeaderMapRaw() {
-        return parser.getHeaderMapRaw();
+        return parser == null ? null : parser.getHeaderMapRaw();
     }
 
     /**
      * Returns the parser.
      *
+     * <p>
+     * Note: The parser is not part of the serialized state of the record. A null check
+     * should be used when the record may have originated from a serialized form.
+     * </p>
+     *
      * @return the parser.
      * @since 1.7
      */

src/site/site.xml

@@ -39,6 +39,7 @@
       <item name="Issue Tracking"  href="/issue-tracking.html"/>
       <item name="Team"            href="/team.html"/>
       <item name="Javadoc"         href="/apidocs/index.html"/>
+      <item name="Javadoc 1.8"     href="https://javadoc.io/doc/org.apache.commons/commons-csv/1.8"/>
       <item name="Javadoc 1.7"     href="https://javadoc.io/doc/org.apache.commons/commons-csv/1.7"/>
       <item name="Javadoc 1.6"     href="https://javadoc.io/doc/org.apache.commons/commons-csv/1.6"/>
       <item name="Javadoc 1.5"     href="https://javadoc.io/doc/org.apache.commons/commons-csv/1.5"/>