[#4818] Add org.jooq.CSVFormat: A parameter object to replace the existing formatCSV overloads

jOOQ/src/main/java/org/jooq/CSVFormat.java

@@ -0,0 +1,183 @@
+/**
+ * Copyright (c) 2009-2015, Data Geekery GmbH (http://www.datageekery.com)
+ * All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * Other licenses:
+ * -----------------------------------------------------------------------------
+ * Commercial licenses for this work are available. These replace the above
+ * ASL 2.0 and offer limited warranties, support, maintenance, and commercial
+ * database integrations.
+ *
+ * For more information, please visit: http://www.jooq.org/licenses
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ */
+package org.jooq;
+
+/**
+ * A CSV formatting type, which can be used to configure CSV imports / exports.
+ *
+ * @author Lukas Eder
+ */
+public final class CSVFormat {
+
+    final String  delimiter;
+    final String  nullString;
+    final boolean header;
+
+    public CSVFormat() {
+        this(
+            ",",
+            "",
+            true
+        );
+    }
+
+    private CSVFormat(
+        String delimiter,
+        String nullString,
+        boolean header
+    ) {
+        this.delimiter = delimiter;
+        this.nullString = nullString;
+        this.header = header;
+    }
+
+    /**
+     * The delimiter to be used between CSV cells, defaulting to
+     * <code>","</code>.
+     * <p>
+     * <table border="1">
+     * <tr>
+     * <td>Using <code>","</code></td>
+     * <td><code>a,b,c</code></td>
+     * </tr>
+     * <tr>
+     * <td>Using <code>";"</code></td>
+     * <td><code>a;b;c</code></td>
+     * </tr>
+     * </table>
+     */
+    public CSVFormat delimiter(String newDelimiter) {
+        return new CSVFormat(
+            newDelimiter,
+            nullString,
+            header
+        );
+    }
+
+    /**
+     * The delimiter to be used between CSV cells, defaulting to
+     * <code>","</code>.
+     * <p>
+     * <table border="1">
+     * <tr>
+     * <td>Using <code>","</code></td>
+     * <td><code>a,b,c</code></td>
+     * </tr>
+     * <tr>
+     * <td>Using <code>";"</code></td>
+     * <td><code>a;b;c</code></td>
+     * </tr>
+     * </table>
+     */
+    public String delimiter() {
+        return delimiter;
+    }
+
+    /**
+     * The string to be used for <code>null</code> values, defaulting to the
+     * empty string.
+     * <p>
+     * <table border="1">
+     * <tr>
+     * <td>Using <code>""</code></td>
+     * <td><code>a,,c</code></td>
+     * </tr>
+     * <tr>
+     * <td>Using <code>"\"\""</code></td>
+     * <td><code>a,"",c</code></td>
+     * </tr>
+     * <tr>
+     * <td>Using <code>"{null}"</code></td>
+     * <td><code>a,{null},c</code></td>
+     * </tr>
+     * </table>
+     */
+    public CSVFormat nullString(String newNullString) {
+        return new CSVFormat(
+            delimiter,
+            newNullString,
+            header
+        );
+    }
+
+    /**
+     * The string to be used for <code>null</code> values, defaulting to the
+     * empty string.
+     * <p>
+     * <table border="1">
+     * <tr>
+     * <td>Using <code>""</code></td>
+     * <td><code>a,,c</code></td>
+     * </tr>
+     * <tr>
+     * <td>Using <code>"\"\""</code></td>
+     * <td><code>a,"",c</code></td>
+     * </tr>
+     * <tr>
+     * <td>Using <code>"{null}"</code></td>
+     * <td><code>a,{null},c</code></td>
+     * </tr>
+     * </table>
+     */
+    public String nullString() {
+        return nullString;
+    }
+
+    /**
+     * Whether to emit a header row with column names, defaulting to
+     * <code>true</code>.
+     */
+    public CSVFormat header(boolean newHeader) {
+        return new CSVFormat(
+            delimiter,
+            nullString,
+            newHeader
+        );
+    }
+
+    /**
+     * Whether to emit a header row with column names, defaulting to
+     * <code>true</code>.
+     */
+    public boolean header() {
+        return header;
+    }
+}

jOOQ/src/main/java/org/jooq/Result.java

@@ -583,6 +583,13 @@ public interface Result<R extends Record> extends List<R>, Attachable {
      */
     String formatCSV(boolean header, char delimiter, String nullString);
 
+    /**
+     * Get a simple formatted representation of this result as CSV.
+     *
+     * @return The formatted result
+     */
+    String formatCSV(CSVFormat format);
+
     /**
      * Get a simple formatted representation of this result as a JSON array of
      * array.
@@ -690,6 +697,13 @@ public interface Result<R extends Record> extends List<R>, Attachable {
      */
     void formatCSV(OutputStream stream, boolean header, char delimiter, String nullString) throws IOException;
 
+    /**
+     * Like {@link #formatCSV(CSVFormat)}, but the data is output onto an {@link OutputStream}.
+     *
+     * @throws IOException - an unchecked wrapper for {@link java.io.IOException}, if anything goes wrong.
+     */
+    void formatCSV(OutputStream stream, CSVFormat format) throws IOException;
+
     /**
      * Like {@link #formatJSON()}, but the data is output onto an {@link OutputStream}.
      *
@@ -781,6 +795,13 @@ public interface Result<R extends Record> extends List<R>, Attachable {
      */
     void formatCSV(Writer writer, boolean header, char delimiter, String nullString) throws IOException;
 
+    /**
+     * Like {@link #formatCSV(CSVFormat)}, but the data is output onto a {@link Writer}.
+     *
+     * @throws IOException - an unchecked wrapper for {@link java.io.IOException}, if anything goes wrong.
+     */
+    void formatCSV(Writer writer, CSVFormat format) throws IOException;
+
     /**
      * Like {@link #formatJSON()}, but the data is output onto a {@link Writer}.
      *

jOOQ/src/main/java/org/jooq/impl/ResultImpl.java

@@ -76,6 +76,7 @@ import javax.xml.parsers.DocumentBuilderFactory;
 import javax.xml.parsers.ParserConfigurationException;
 
 import org.jooq.AttachableInternal;
+import org.jooq.CSVFormat;
 import org.jooq.Configuration;
 import org.jooq.Converter;
 import org.jooq.DSLContext;
@@ -714,6 +715,13 @@ class ResultImpl<R extends Record> implements Result<R>, AttachableInternal {
         return writer.toString();
     }
 
+    @Override
+    public final String formatCSV(CSVFormat format) {
+        StringWriter writer = new StringWriter();
+        formatCSV(writer, format);
+        return writer.toString();
+    }
+
     @Override
     public final void formatCSV(OutputStream stream, char delimiter, String nullString) {
         formatCSV(stream, true, delimiter, nullString);
@@ -724,6 +732,11 @@ class ResultImpl<R extends Record> implements Result<R>, AttachableInternal {
         formatCSV(new OutputStreamWriter(stream), header, delimiter, nullString);
     }
 
+    @Override
+    public final void formatCSV(OutputStream stream, CSVFormat format) {
+        formatCSV(new OutputStreamWriter(stream), format);
+    }
+
     @Override
     public final void formatCSV(Writer writer, char delimiter, String nullString) {
         formatCSV(writer, true, delimiter, nullString);
@@ -731,14 +744,19 @@ class ResultImpl<R extends Record> implements Result<R>, AttachableInternal {
 
     @Override
     public final void formatCSV(Writer writer, boolean header, char delimiter, String nullString) {
+        formatCSV(writer, new CSVFormat().header(header).delimiter("" + delimiter).nullString(nullString));
+    }
+
+    @Override
+    public final void formatCSV(Writer writer, CSVFormat format) {
         try {
-            if (header) {
+            if (format.header()) {
                 String sep1 = "";
                 for (Field<?> field : fields.fields) {
                     writer.append(sep1);
                     writer.append(formatCSV0(field.getName(), ""));
 
-                    sep1 = Character.toString(delimiter);
+                    sep1 = format.delimiter();
                 }
 
                 writer.append("\n");
@@ -749,9 +767,9 @@ class ResultImpl<R extends Record> implements Result<R>, AttachableInternal {
 
                 for (int index = 0; index < fields.fields.length; index++) {
                     writer.append(sep2);
-                    writer.append(formatCSV0(record.getValue(index), nullString));
+                    writer.append(formatCSV0(record.getValue(index), format.nullString()));
 
-                    sep2 = Character.toString(delimiter);
+                    sep2 = format.delimiter();
                 }
 
                 writer.append("\n");