Make methods that create parsers or printers fail early and provide an expressive error messages. Document new behavior in JavaDoc

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/csv/trunk@1518802 13f79535-47bb-0310-9956-ffa450edef68

Author: britter

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

@@ -0,0 +1,19 @@
+package org.apache.commons.csv;
+
+/**
+ * Utility class for input parameter validation
+ *
+ * @version $Id$
+ */
+final class Assertions {
+
+    private Assertions() {
+        // can not be instantiated
+    }
+
+    public static <T> void notNull(T parameter, String parameterName) {
+        if (parameter == null) {
+            throw new IllegalArgumentException("Parameter '" + parameterName + "' must not be null!");
+        }
+    }
+}

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

@@ -96,29 +96,39 @@ public final class CSVParser implements Iterable<CSVRecord>, Closeable {
      * Creates a parser for the given {@link File}.
      *
      * @param file
-     *            a CSV file
+     *            a CSV file. Must not be null.
      * @param format
-     *            the CSVFormat used for CSV parsing
+     *            the CSVFormat used for CSV parsing. Must not be null.
      * @return a new parser
+     * @throws IllegalArgumentException
+     *             If the parameters of the format are inconsistent or if either file or format are null.
      * @throws IOException
      *             If an I/O error occurs
      */
     public static CSVParser parse(File file, final CSVFormat format) throws IOException {
+        Assertions.notNull(file, "file");
+        Assertions.notNull(format, "format");
+
         return new CSVParser(new FileReader(file), format);
     }
 
     /**
      * Creates a parser for the given {@link String}.
      *
      * @param string
-     *            a CSV string
+     *            a CSV string. Must not be null.
      * @param format
-     *            the CSVFormat used for CSV parsing
+     *            the CSVFormat used for CSV parsing. Must not be null.
      * @return a new parser
+     * @throws IllegalArgumentException
+     *             If the parameters of the format are inconsistent or if either string or format are null.
      * @throws IOException
      *             If an I/O error occurs
      */
     public static CSVParser parse(String string, final CSVFormat format) throws IOException {
+        Assertions.notNull(string, "string");
+        Assertions.notNull(format, "format");
+
         return new CSVParser(new StringReader(string), format);
     }
 
@@ -131,17 +141,22 @@ public static CSVParser parse(String string, final CSVFormat format) throws IOEx
      * </p>
      *
      * @param url
-     *            a URL
+     *            a URL. Must not be null.
      * @param charset
      *            the charset for the resource, if {@code null}, uses {@code UTF-8}. UTF-8 is one of the encodings
      *            required by the Java specification.
      * @param format
-     *            the CSVFormat used for CSV parsing
+     *            the CSVFormat used for CSV parsing. Must not be null.
      * @return a new parser
+     * @throws IllegalArgumentException
+     *             If the parameters of the format are inconsistent or if either url or format are null.
      * @throws IOException
      *             If an I/O error occurs
      */
     public static CSVParser parse(URL url, Charset charset, final CSVFormat format) throws IOException {
+        Assertions.notNull(url, "url");
+        Assertions.notNull(format, "format");
+
         return new CSVParser(new InputStreamReader(url.openStream(),
                              charset == null ? Charset.forName("UTF-8") : charset), format);
     }
@@ -169,15 +184,18 @@ public static CSVParser parse(URL url, Charset charset, final CSVFormat format)
      * </p>
      *
      * @param reader
-     *            a Reader containing CSV-formatted input
+     *            a Reader containing CSV-formatted input. Must not be null.
      * @param format
-     *            the CSVFormat used for CSV parsing
+     *            the CSVFormat used for CSV parsing. Must not be null.
      * @throws IllegalArgumentException
-     *             thrown if the parameters of the format are inconsistent
+     *             If the parameters of the format are inconsistent or if either reader or format are null.
      * @throws IOException
      *             If an I/O error occurs
      */
     public CSVParser(final Reader reader, final CSVFormat format) throws IOException {
+        Assertions.notNull(reader, "reader");
+        Assertions.notNull(format, "format");
+
         format.validate();
         this.format = format;
         this.lexer = new Lexer(format, new ExtendedBufferedReader(reader));

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

@@ -49,15 +49,18 @@ public final class CSVPrinter implements Flushable, Closeable {
      * (encapsulation and escaping with a different character) are not supported.
      *
      * @param out
-     *            stream to which to print.
+     *            stream to which to print. Must not be null.
      * @param format
-     *            the CSV format. If null the default format is used ({@link CSVFormat#DEFAULT})
+     *            the CSV format. Must not be null.
      * @throws IllegalArgumentException
-     *             thrown if the parameters of the format are inconsistent
+     *             thrown if the parameters of the format are inconsistent or if either out or format are null.
      */
     public CSVPrinter(final Appendable out, final CSVFormat format) {
+        Assertions.notNull(out, "out");
+        Assertions.notNull(format, "format");
+
         this.out = out;
-        this.format = format == null ? CSVFormat.DEFAULT : format;
+        this.format = format;
         this.format.validate();
     }
 

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

@@ -0,0 +1,19 @@
+package org.apache.commons.csv;
+
+import org.junit.Test;
+
+/**
+ * @version $Id$
+ */
+public class AssertionsTest {
+
+    @Test
+    public void testNotNull() throws Exception {
+        Assertions.notNull(new Object(), "object");
+    }
+
+    @Test(expected = IllegalArgumentException.class)
+    public void testNotNullNull() throws Exception {
+        Assertions.notNull(null, "object");
+    }
+}

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

@@ -28,10 +28,13 @@
 import static org.junit.Assert.assertTrue;
 import static org.junit.Assert.fail;
 
+import java.io.File;
 import java.io.IOException;
 import java.io.Reader;
 import java.io.StringReader;
 import java.io.StringWriter;
+import java.net.URL;
+import java.nio.charset.Charset;
 import java.util.ArrayList;
 import java.util.Iterator;
 import java.util.List;
@@ -721,6 +724,46 @@ public void testInvalidFormat() throws Exception {
         new CSVParser(null, invalidFormat).close();
     }
 
+    @Test(expected = IllegalArgumentException.class)
+    public void testParseNullFileFormat() throws Exception {
+        CSVParser.parse((File) null, CSVFormat.DEFAULT);
+    }
+
+    @Test(expected = IllegalArgumentException.class)
+    public void testParseFileNullFormat() throws Exception {
+        CSVParser.parse(new File(""), null);
+    }
+
+    @Test(expected = IllegalArgumentException.class)
+    public void testParseNullStringFormat() throws Exception {
+        CSVParser.parse((String) null, CSVFormat.DEFAULT);
+    }
+
+    @Test(expected = IllegalArgumentException.class)
+    public void testParseStringNullFormat() throws Exception {
+        CSVParser.parse("csv data", null);
+    }
+
+    @Test(expected = IllegalArgumentException.class)
+    public void testParseNullUrlCharsetFormat() throws Exception {
+        CSVParser.parse(null, Charset.defaultCharset(), CSVFormat.DEFAULT);
+    }
+
+    @Test(expected = IllegalArgumentException.class)
+    public void testParseUrlCharsetNullFormat() throws Exception {
+        CSVParser.parse(new URL("http://commons.apache.org"), Charset.defaultCharset(), null);
+    }
+
+    @Test(expected = IllegalArgumentException.class)
+    public void testNewCSVParserNullReaderFormat() throws Exception {
+        new CSVParser(null, CSVFormat.DEFAULT);
+    }
+
+    @Test(expected = IllegalArgumentException.class)
+    public void testNewCSVParserReaderNullFormat() throws Exception {
+        new CSVParser(new StringReader(""), null);
+    }
+
     private void validateRecordNumbers(final String lineSeparator) throws IOException {
         final CSVParser parser = CSVParser.parse("a" + lineSeparator + "b" + lineSeparator + "c", CSVFormat.DEFAULT.withRecordSeparator(lineSeparator));
         CSVRecord record;

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

@@ -487,6 +487,16 @@ public void testEOLPlain() throws IOException {
     @Test(expected = IllegalArgumentException.class)
     public void testInvalidFormat() throws Exception {
         final CSVFormat invalidFormat = CSVFormat.DEFAULT.withDelimiter(CR);
-        new CSVPrinter(null, invalidFormat).close();
+        new CSVPrinter(new StringWriter(), invalidFormat).close();
+    }
+
+    @Test(expected = IllegalArgumentException.class)
+    public void testNewCSVPrinterNullAppendableFormat() throws Exception {
+        new CSVPrinter(null, CSVFormat.DEFAULT);
+    }
+
+    @Test(expected = IllegalArgumentException.class)
+    public void testNewCsvPrinterAppendableNullFormat() throws Exception {
+        new CSVPrinter(new StringWriter(), null);
     }
 }