Don't use deprecated code in examples

Author: garydgregory

src/site/xdoc/user-guide.xml

@@ -70,39 +70,45 @@ for (CSVRecord record : records) {
           <a href="https://commons.apache.org/proper/commons-io/">Apache Commons IO</a>
           for example:
         </p>
-        <source>final URL url = ...;
-try (final Reader reader = new InputStreamReader(new BOMInputStream(url.openStream()), "UTF-8");
-     final CSVParser parser = CSVFormat.EXCEL.builder()
-       .setHeader()
-       .build()
-       .parse(reader)) {
+        <source>
+try (final Reader reader = new InputStreamReader(BOMInputStream.builder()
+        .setPath(path)
+        .get(), "UTF-8");
+        final CSVParser parser = CSVFormat.EXCEL.builder()
+                .setHeader()
+                .get()
+                .parse(reader)) {
     for (final CSVRecord record : parser) {
-        final String string = record.get("SomeColumn");
-        ...
+        final String string = record.get("ColumnA");
+        // ...
     }
 }
         </source>
         <p>
           You might find it handy to create something like this:
         </p>
-        <source>/**
+        <source>
+/**
  * Creates a reader capable of handling BOMs.
+ *
+ * @param path The path to read.
+ * @return a new InputStreamReader for UTF-8 bytes.
+ * @throws IOException if an I/O error occurs.
  */
-public InputStreamReader newReader(final InputStream inputStream) {
-    return new InputStreamReader(new BOMInputStream(inputStream), StandardCharsets.UTF_8);
+public InputStreamReader newReader(final Path path) throws IOException {
+    return new InputStreamReader(BOMInputStream.builder()
+            .setPath(path)
+            .get(), StandardCharsets.UTF_8);
 }
         </source>
       </subsection>
     </section>
-
     <section name="Working with headers">
-
       Apache Commons CSV provides several ways to access record values.
       The simplest way is to access values by their index in the record.
       However, columns in CSV files often have a name, for example: ID, CustomerNo, Birthday, etc.
       The CSVFormat class provides an API for specifying these <i>header</i> names and CSVRecord on
       the other hand has methods to access values by their corresponding header name.
-
       <subsection name="Accessing column values by index">
         To access a record value by index, no special configuration of the CSVFormat is necessary:
         <source>Reader in = new FileReader(&quot;path/to/file.csv&quot;);

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

@@ -0,0 +1,94 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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
+ *
+ *   https://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.
+ */
+package org.apache.commons.csv;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import java.io.IOException;
+import java.io.InputStreamReader;
+import java.io.Reader;
+import java.io.UnsupportedEncodingException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import org.apache.commons.io.input.BOMInputStream;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+/**
+ * Tests for the user guide.
+ */
+public class UserGuideTest {
+
+    @TempDir
+    Path tempDir;
+
+    /**
+     * Creates a reader capable of handling BOMs.
+     *
+     * @param path The path to read.
+     * @return a new InputStreamReader for UTF-8 bytes.
+     * @throws IOException if an I/O error occurs.
+     */
+    public InputStreamReader newReader(final Path path) throws IOException {
+        return new InputStreamReader(BOMInputStream.builder()
+                .setPath(path)
+                .get(), StandardCharsets.UTF_8);
+    }
+
+    @Test
+    public void testBomFull() throws UnsupportedEncodingException, IOException {
+        final Path path = tempDir.resolve("test1.csv");
+        Files.copy(Utils.createUtf8Input("ColumnA, ColumnB, ColumnC\r\nA, B, C\r\n".getBytes(StandardCharsets.UTF_8), true), path);
+        // @formatter:off
+        try (final Reader reader = new InputStreamReader(BOMInputStream.builder()
+                .setPath(path)
+                .get(), "UTF-8");
+                final CSVParser parser = CSVFormat.EXCEL.builder()
+                        .setHeader()
+                        .get()
+                        .parse(reader)) {
+            // @formatter:off
+            for (final CSVRecord record : parser) {
+                final String string = record.get("ColumnA");
+                assertEquals("A", string);
+            }
+        }
+    }
+    
+    @Test
+    public void testBomUtil() throws UnsupportedEncodingException, IOException {
+        final Path path = tempDir.resolve("test2.csv");
+        Files.copy(Utils.createUtf8Input("ColumnA, ColumnB, ColumnC\r\nA, B, C\r\n".getBytes(StandardCharsets.UTF_8), true), path);
+        try (final Reader reader = newReader(path);
+                // @formatter:off
+                final CSVParser parser = CSVFormat.EXCEL.builder()
+                        .setHeader()
+                        .get()
+                        .parse(reader)) {
+            // @formatter:off
+            for (final CSVRecord record : parser) {
+                final String string = record.get("ColumnA");
+                assertEquals("A", string);
+            }
+        }
+    }
+
+}

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

@@ -22,6 +22,8 @@
 import static org.junit.jupiter.api.Assertions.assertArrayEquals;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 
+import java.io.ByteArrayInputStream;
+import java.io.InputStream;
 import java.util.List;
 
 /**
@@ -32,9 +34,9 @@ final class Utils {
     /**
      * Checks if the 2d array has the same contents as the list of records.
      *
-     * @param message the message to be displayed
+     * @param message  the message to be displayed
      * @param expected the 2d array of expected results
-     * @param actual the List of {@link CSVRecord} entries, each containing an array of values
+     * @param actual   the List of {@link CSVRecord} entries, each containing an array of values
      */
     public static void compare(final String message, final String[][] expected, final List<CSVRecord> actual) {
         final int expectedLength = expected.length;
@@ -44,6 +46,21 @@ public static void compare(final String message, final String[][] expected, fina
         }
     }
 
+    /**
+     * Creates an input stream, with or without a BOM.
+     */
+    static InputStream createUtf8Input(final byte[] baseData, final boolean addBom) {
+        byte[] data = baseData;
+        if (addBom) {
+            data = new byte[baseData.length + 3];
+            data[0] = (byte) 0xEF;
+            data[1] = (byte) 0xBB;
+            data[2] = (byte) 0xBF;
+            System.arraycopy(baseData, 0, data, 3, baseData.length);
+        }
+        return new ByteArrayInputStream(data);
+    }
+
     private Utils() {
     }
 }