[IO-318] Add Charset sister APIs to method that take a String charset name. FileUtils.

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

Author: garydgregory

src/main/java/org/apache/commons/io/Charsets.java

@@ -0,0 +1,56 @@
+/*
+ * 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
+ * 
+ *      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.
+ */
+package org.apache.commons.io;
+
+import java.nio.charset.Charset;
+import java.nio.charset.UnsupportedCharsetException;
+
+/**
+ * Helps use {@link Charset}
+ * 
+ * @version $Id$
+ * @since 2.3
+ */
+public class Charsets {
+
+    /**
+     * Returns the given Charset or the default Charset if the given Charset is null. 
+     * 
+     * @param charset
+     *            A charset or null.
+     * @return the given Charset or the default Charset if the given Charset is null
+     * @since 2.3
+     */
+    public static Charset toCharset(Charset charset) {
+        return charset == null ? Charset.defaultCharset() : charset;
+    }
+
+    /**
+     * Returns a Charset for the named charset. If the name is null, return the default Charset.
+     * 
+     * @param charset
+     *            The name of the requested charset, may be null.
+     * @return a Charset for the named charset
+     * @throws UnsupportedCharsetException
+     *             If the named charset is unavailable
+     * @since 2.3
+     */
+    public static Charset toCharset(String charset) {
+        return charset == null ? Charset.defaultCharset() : Charset.forName(charset);
+    }
+
+}

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

@@ -26,12 +26,14 @@
 import java.io.InputStreamReader;
 import java.io.OutputStream;
 import java.io.Reader;
+import java.io.UnsupportedEncodingException;
 import java.math.BigInteger;
 import java.net.URL;
 import java.net.URLConnection;
 import java.nio.ByteBuffer;
 import java.nio.channels.FileChannel;
 import java.nio.charset.Charset;
+import java.nio.charset.UnsupportedCharsetException;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Date;
@@ -1633,18 +1635,37 @@ public static boolean waitFor(File file, int seconds) {
      * @param encoding  the encoding to use, <code>null</code> means platform default
      * @return the file contents, never <code>null</code>
      * @throws IOException in case of an I/O error
-     * @throws java.io.UnsupportedEncodingException if the encoding is not supported by the VM
+     * @since 2.3
      */
-    public static String readFileToString(File file, String encoding) throws IOException {
+    public static String readFileToString(File file, Charset encoding) throws IOException {
         InputStream in = null;
         try {
             in = openInputStream(file);
-            return IOUtils.toString(in, encoding);
+            return IOUtils.toString(in, Charsets.toCharset(encoding));
         } finally {
             IOUtils.closeQuietly(in);
         }
     }
 
+    /**
+     * Reads the contents of a file into a String. The file is always closed.
+     * 
+     * @param file
+     *            the file to read, must not be <code>null</code>
+     * @param encoding
+     *            the encoding to use, <code>null</code> means platform default
+     * @return the file contents, never <code>null</code>
+     * @throws IOException
+     *             in case of an I/O error
+     * @throws UnsupportedCharsetException
+     *             thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not
+     *             supported.
+     * @since 2.3
+     */
+    public static String readFileToString(File file, String encoding) throws IOException {
+        return readFileToString(file, Charsets.toCharset(encoding));
+    }
+
 
     /**
      * Reads the contents of a file into a String using the default encoding for the VM. 
@@ -1656,7 +1677,7 @@ public static String readFileToString(File file, String encoding) throws IOExcep
      * @since 1.3.1
      */
     public static String readFileToString(File file) throws IOException {
-        return readFileToString(file, null);
+        return readFileToString(file, Charset.defaultCharset());
     }
 
     /**
@@ -1686,19 +1707,37 @@ public static byte[] readFileToByteArray(File file) throws IOException {
      * @param encoding  the encoding to use, <code>null</code> means platform default
      * @return the list of Strings representing each line in the file, never <code>null</code>
      * @throws IOException in case of an I/O error
-     * @throws java.io.UnsupportedEncodingException if the encoding is not supported by the VM
-     * @since 1.1
+     * @since 2.3
      */
-    public static List<String> readLines(File file, String encoding) throws IOException {
+    public static List<String> readLines(File file, Charset encoding) throws IOException {
         InputStream in = null;
         try {
             in = openInputStream(file);
-            return IOUtils.readLines(in, encoding);
+            return IOUtils.readLines(in, Charsets.toCharset(encoding));
         } finally {
             IOUtils.closeQuietly(in);
         }
     }
 
+    /**
+     * Reads the contents of a file line by line to a List of Strings. The file is always closed.
+     * 
+     * @param file
+     *            the file to read, must not be <code>null</code>
+     * @param encoding
+     *            the encoding to use, <code>null</code> means platform default
+     * @return the list of Strings representing each line in the file, never <code>null</code>
+     * @throws IOException
+     *             in case of an I/O error
+     * @throws UnsupportedCharsetException
+     *             thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not
+     *             supported.
+     * @since 1.1
+     */
+    public static List<String> readLines(File file, String encoding) throws IOException {
+        return readLines(file, Charsets.toCharset(encoding));
+    }
+
     /**
      * Reads the contents of a file line by line to a List of Strings using the default encoding for the VM.
      * The file is always closed.
@@ -1709,7 +1748,7 @@ public static List<String> readLines(File file, String encoding) throws IOExcept
      * @since 1.3
      */
     public static List<String> readLines(File file) throws IOException {
-        return readLines(file, null);
+        return readLines(file, Charset.defaultCharset());
     }
 
     /**
@@ -1796,10 +1835,9 @@ public static void writeStringToFile(File file, String data, String encoding) th
      * @param append if <code>true</code>, then the String will be added to the
      * end of the file rather than overwriting
      * @throws IOException in case of an I/O error
-     * @throws java.io.UnsupportedEncodingException if the encoding is not supported by the VM
-     * @since 2.1
+     * @since 2.3
      */
-    public static void writeStringToFile(File file, String data, String encoding, boolean append) throws IOException {
+    public static void writeStringToFile(File file, String data, Charset encoding, boolean append) throws IOException {
         OutputStream out = null;
         try {
             out = openOutputStream(file, append);
@@ -1810,6 +1848,24 @@ public static void writeStringToFile(File file, String data, String encoding, bo
         }
     }
 
+    /**
+     * Writes a String to a file creating the file if it does not exist.
+     *
+     * @param file  the file to write
+     * @param data  the content to write to the file
+     * @param encoding  the encoding to use, <code>null</code> means platform default
+     * @param append if <code>true</code>, then the String will be added to the
+     * end of the file rather than overwriting
+     * @throws IOException in case of an I/O error
+     * @throws UnsupportedCharsetException
+     *             thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not
+     *             supported by the VM
+     * @since 2.1
+     */
+    public static void writeStringToFile(File file, String data, String encoding, boolean append) throws IOException {
+        writeStringToFile(file, data, Charsets.toCharset(encoding), append);
+    }
+
     /**
      * Writes a String to a file creating the file if it does not exist using the default encoding for the VM.
      * 
@@ -1818,7 +1874,7 @@ public static void writeStringToFile(File file, String data, String encoding, bo
      * @throws IOException in case of an I/O error
      */
     public static void writeStringToFile(File file, String data) throws IOException {
-        writeStringToFile(file, data, null, false);
+        writeStringToFile(file, data, Charset.defaultCharset(), false);
     }
 
     /**
@@ -1832,7 +1888,7 @@ public static void writeStringToFile(File file, String data) throws IOException
      * @since 2.1
      */
     public static void writeStringToFile(File file, String data, boolean append) throws IOException {
-        writeStringToFile(file, data, null, append);
+        writeStringToFile(file, data, Charset.defaultCharset(), append);
     }
 
     /**
@@ -1844,7 +1900,7 @@ public static void writeStringToFile(File file, String data, boolean append) thr
      * @since 2.0
      */
     public static void write(File file, CharSequence data) throws IOException {
-        write(file, data, null, false);
+        write(file, data, Charset.defaultCharset(), false);
     }
 
     /**
@@ -1858,7 +1914,20 @@ public static void write(File file, CharSequence data) throws IOException {
      * @since 2.1
      */
     public static void write(File file, CharSequence data, boolean append) throws IOException {
-        write(file, data, null, append);
+        write(file, data, Charset.defaultCharset(), append);
+    }
+
+    /**
+     * Writes a CharSequence to a file creating the file if it does not exist.
+     *
+     * @param file  the file to write
+     * @param data  the content to write to the file
+     * @param encoding  the encoding to use, <code>null</code> means platform default
+     * @throws IOException in case of an I/O error
+     * @since 2.3
+     */
+    public static void write(File file, CharSequence data, Charset encoding) throws IOException {
+        write(file, data, encoding, false);
     }
 
     /**
@@ -1884,14 +1953,31 @@ public static void write(File file, CharSequence data, String encoding) throws I
      * @param append if <code>true</code>, then the data will be added to the
      * end of the file rather than overwriting
      * @throws IOException in case of an I/O error
-     * @throws java.io.UnsupportedEncodingException if the encoding is not supported by the VM
-     * @since IO 2.1
+     * @since IO 2.3
      */
-    public static void write(File file, CharSequence data, String encoding, boolean append) throws IOException {
+    public static void write(File file, CharSequence data, Charset encoding, boolean append) throws IOException {
         String str = data == null ? null : data.toString();
         writeStringToFile(file, str, encoding, append);
     }
 
+    /**
+     * Writes a CharSequence to a file creating the file if it does not exist.
+     *
+     * @param file  the file to write
+     * @param data  the content to write to the file
+     * @param encoding  the encoding to use, <code>null</code> means platform default
+     * @param append if <code>true</code>, then the data will be added to the
+     * end of the file rather than overwriting
+     * @throws IOException in case of an I/O error
+     * @throws UnsupportedCharsetException
+     *             thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not
+     *             supported by the VM
+     * @since IO 2.1
+     */
+    public static void write(File file, CharSequence data, String encoding, boolean append) throws IOException {
+        write(file, data, Charsets.toCharset(encoding), append);
+    }
+
     /**
      * Writes a byte array to a file creating the file if it does not exist.
      * <p>