Add methods to read a FIle/Stream/Reader by lines

rfe 36214

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

Author: Stephen Colebourne

src/java/org/apache/commons/io/FileUtils.java

@@ -16,16 +16,18 @@
 package org.apache.commons.io;
 
 import java.io.File;
+import java.io.FileFilter;
 import java.io.FileInputStream;
 import java.io.FileNotFoundException;
 import java.io.FileOutputStream;
 import java.io.IOException;
 import java.io.InputStream;
-import java.io.FileFilter;
 import java.io.OutputStream;
+import java.io.UnsupportedEncodingException;
 import java.net.URL;
 import java.util.Collection;
 import java.util.Date;
+import java.util.List;
 
 import org.apache.commons.io.filefilter.DirectoryFileFilter;
 import org.apache.commons.io.filefilter.FalseFileFilter;
@@ -741,7 +743,7 @@ public static boolean waitFor(File file, int seconds) {
         return true;
     }
 
-
+    //-----------------------------------------------------------------------
     /**
      * <p>
      * Reads the contents of a file into a String.
@@ -786,6 +788,33 @@ public static byte[] readFileToByteArray(File file) throws IOException {
         }
     }
 
+    /**
+     * <p>
+     * Reads the contents of a file line by line to a List of Strings.
+     * </p>
+     * <p>
+     * There is no readLines method without encoding parameter because
+     * the default encoding can differ between platforms and therefore results
+     * in inconsistent results.
+     * </p>
+     *
+     * @param file  the file to read
+     * @param encoding  the encoding to use
+     * @return the list of Strings representing each line in the file
+     * @throws IOException in case of an I/O error
+     * @throws UnsupportedEncodingException if the encoding is not supported by the VM
+     * @since 1.1
+     */
+    public static List readLines(File file, String encoding) throws IOException {
+        InputStream in = new FileInputStream(file);
+        try {
+            return IOUtils.readLines(in, encoding);
+        } finally {
+            IOUtils.closeQuietly(in);
+        }
+    }
+
+    //-----------------------------------------------------------------------
     /**
      * <p>
      * Writes a String to a file creating the file if it does not exist.

src/java/org/apache/commons/io/IOUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2001-2004 The Apache Software Foundation.
+ * Copyright 2001-2005 The Apache Software Foundation.
  * 
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -27,6 +27,8 @@
 import java.io.Reader;
 import java.io.StringWriter;
 import java.io.Writer;
+import java.util.ArrayList;
+import java.util.List;
 
 import org.apache.commons.io.output.ByteArrayOutputStream;
 
@@ -392,6 +394,77 @@ public static String toString(byte[] input, String encoding)
         }
     }
 
+    // readLines
+    //-----------------------------------------------------------------------
+    /**
+     * Get the contents of an <code>InputStream</code> as a list of Strings,
+     * one entry per line, using the default character encoding of the platform.
+     * <p>
+     * This method buffers the input internally, so there is no need to use a
+     * <code>BufferedInputStream</code>.
+     *
+     * @param input  the <code>InputStream</code> to read from, not null
+     * @return the list of Strings, never null
+     * @throws NullPointerException if the input is null
+     * @throws IOException if an I/O error occurs
+     * @since 1.1
+     */
+    public static List readLines(InputStream input) throws IOException {
+        InputStreamReader reader = new InputStreamReader(input);
+        return readLines(reader);
+    }
+
+    /**
+     * Get the contents of an <code>InputStream</code> as a list of Strings,
+     * one entry per line, using the specified character encoding.
+     * <p>
+     * Character encoding names can be found at
+     * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
+     * <p>
+     * This method buffers the input internally, so there is no need to use a
+     * <code>BufferedInputStream</code>.
+     *
+     * @param input  the <code>InputStream</code> to read from, not null
+     * @param encoding  the encoding to use, null means platform default
+     * @return the list of Strings, never null
+     * @throws NullPointerException if the input is null
+     * @throws IOException if an I/O error occurs
+     * @since 1.1
+     */
+    public static List readLines(InputStream input, String encoding) throws IOException {
+        if (encoding == null) {
+            return readLines(input);
+        } else {
+            InputStreamReader reader = new InputStreamReader(input, encoding);
+            return readLines(reader);
+        }
+    }
+
+    /**
+     * Get the contents of a <code>Reader</code> as a list of Strings,
+     * one entry per line.
+     * <p>
+     * This method buffers the input internally, so there is no need to use a
+     * <code>BufferedReader</code>.
+     *
+     * @param input  the <code>Reader</code> to read from, not null
+     * @return the list of Strings, never null
+     * @throws NullPointerException if the input is null
+     * @throws IOException if an I/O error occurs
+     * @since 1.1
+     */
+    public static List readLines(Reader input) throws IOException {
+        BufferedReader reader = new BufferedReader(input);
+        List list = new ArrayList();
+        String line = reader.readLine();
+        while (line != null) {
+            list.add(line);
+            line = reader.readLine();
+        }
+        return list;
+    }
+
+    //-----------------------------------------------------------------------
     /**
      * Convert the specified string to an input stream, encoded as bytes
      * using the default character encoding of the platform.

src/test/org/apache/commons/io/FileUtilsTestCase.java

@@ -21,7 +21,9 @@
 import java.io.IOException;
 import java.io.OutputStream;
 import java.net.URL;
+import java.util.Arrays;
 import java.util.GregorianCalendar;
+import java.util.List;
 
 import junit.framework.Test;
 import junit.framework.TestSuite;
@@ -665,6 +667,19 @@ public void testReadFileToByteArray() throws Exception {
         assertEquals(31, data[2]);
     }
 
+    public void testReadLines_Reader() throws Exception {
+        File file = newFile("lines.txt");
+        try {
+            String[] data = new String[] {"hello", "/u1234", "", "this is", "some text"};
+            createLineBasedFile(file, data);
+            
+            List lines = FileUtils.readLines(file, "UTF-8");
+            assertEquals(Arrays.asList(data), lines);
+        } finally {
+            deleteFile(file);
+        }
+    }
+
     public void testWriteStringToFile() throws Exception {
         File file = new File(getTestDirectory(), "write.txt");
         FileUtils.writeStringToFile(file, "Hello /u1234", "UTF8");

src/test/org/apache/commons/io/IOUtilsTestCase.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 1999-2004 The Apache Software Foundation.
+ * Copyright 1999-2005 The Apache Software Foundation.
  * 
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -23,9 +23,12 @@
 import java.io.FileWriter;
 import java.io.IOException;
 import java.io.InputStream;
+import java.io.InputStreamReader;
+import java.io.Reader;
 import java.util.Arrays;
+import java.util.List;
 
-import org.apache.commons.io.testtools.*;
+import org.apache.commons.io.testtools.FileBasedTestCase;
 
 // Note: jdk1.2 dependency
 
@@ -348,4 +351,58 @@ public void testReaderToCharArray()
         }
     }
 
+    //-----------------------------------------------------------------------
+    public void testReadLines_InputStream() throws Exception {
+        File file = newFile("lines.txt");
+        InputStream in = null;
+        try {
+            String[] data = new String[] {"hello", "world", "", "this is", "some text"};
+            createLineBasedFile(file, data);
+            
+            in = new FileInputStream(file);
+            List lines = IOUtils.readLines(in);
+            assertEquals(Arrays.asList(data), lines);
+            assertEquals(-1, in.read());
+        } finally {
+            IOUtils.closeQuietly(in);
+            deleteFile(file);
+        }
+    }
+
+    //-----------------------------------------------------------------------
+    public void testReadLines_InputStream_String() throws Exception {
+        File file = newFile("lines.txt");
+        InputStream in = null;
+        try {
+            String[] data = new String[] {"hello", "/u1234", "", "this is", "some text"};
+            createLineBasedFile(file, data);
+            
+            in = new FileInputStream(file);
+            List lines = IOUtils.readLines(in, "UTF-8");
+            assertEquals(Arrays.asList(data), lines);
+            assertEquals(-1, in.read());
+        } finally {
+            IOUtils.closeQuietly(in);
+            deleteFile(file);
+        }
+    }
+
+    //-----------------------------------------------------------------------
+    public void testReadLines_Reader() throws Exception {
+        File file = newFile("lines.txt");
+        Reader in = null;
+        try {
+            String[] data = new String[] {"hello", "/u1234", "", "this is", "some text"};
+            createLineBasedFile(file, data);
+            
+            in = new InputStreamReader(new FileInputStream(file));
+            List lines = IOUtils.readLines(in);
+            assertEquals(Arrays.asList(data), lines);
+            assertEquals(-1, in.read());
+        } finally {
+            IOUtils.closeQuietly(in);
+            deleteFile(file);
+        }
+    }
+
 }

src/test/org/apache/commons/io/testtools/FileBasedTestCase.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2001-2004 The Apache Software Foundation.
+ * Copyright 2001-2005 The Apache Software Foundation.
  * 
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -17,20 +17,23 @@
 
 import java.io.BufferedOutputStream;
 import java.io.File;
+import java.io.FileOutputStream;
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.OutputStream;
+import java.io.OutputStreamWriter;
+import java.io.PrintWriter;
 import java.io.Reader;
 import java.io.Writer;
 import java.util.Arrays;
 
+import junit.framework.AssertionFailedError;
+import junit.framework.TestCase;
+
 import org.apache.commons.io.FileUtils;
 import org.apache.commons.io.IOUtils;
 import org.apache.commons.io.output.ByteArrayOutputStream;
 
-import junit.framework.AssertionFailedError;
-import junit.framework.TestCase;
-
 /**
  * Base class for testcases doing tests with files.
  * 
@@ -87,6 +90,22 @@ protected void generateTestData(OutputStream out, long size)
         }
     }
 
+    protected void createLineBasedFile(File file, String[] data) throws IOException {
+        if (!file.getParentFile().exists()) {
+            throw new IOException("Cannot create file " + file
+                    + " as the parent directory does not exist");
+        }
+        PrintWriter output = new PrintWriter(
+            new OutputStreamWriter(new FileOutputStream(file), "UTF-8"));
+        try {
+            for (int i = 0; i < data.length; i++) {
+                output.println(data[i]);
+            }
+        } finally {
+            IOUtils.closeQuietly(output);
+        }
+    }
+
     protected File newFile(String filename) throws IOException {
         File destination = new File( getTestDirectory(), filename );
         /*