View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *   http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  package org.apache.maven.shared.utils;
20  
21  import javax.annotation.Nonnull;
22  
23  import java.io.File;
24  import java.io.FileInputStream;
25  import java.io.FileNotFoundException;
26  import java.io.FileReader;
27  import java.io.IOException;
28  import java.io.InputStream;
29  import java.io.InputStreamReader;
30  import java.io.Reader;
31  import java.io.UnsupportedEncodingException;
32  import java.net.URL;
33  
34  import org.apache.commons.io.input.XmlStreamReader;
35  
36  /**
37   * Utility to create Readers from streams, with explicit encoding choice: platform default,
38   * XML, or specified.
39   *
40   * @author <a href="mailto:hboutemy@apache.org">Hervé Boutemy</a>
41   * @see java.nio.charset.Charset
42   * @see <a href="https://docs.oracle.com/javase/7/docs/technotes/guides/intl/encoding.doc.html">Supported encodings</a>
43   */
44  public class ReaderFactory {
45      /**
46       * ISO Latin Alphabet #1, also known as ISO-LATIN-1.
47       * Every implementation of the Java platform is required to support this character encoding.
48       *
49       * @deprecated use {@code java.nio.charset.StandardCharset.ISO_8859_1}
50       */
51      @Deprecated
52      public static final String ISO_8859_1 = "ISO-8859-1";
53  
54      /**
55       * Seven-bit ASCII, also known as ISO646-US, also known as the Basic Latin block of the Unicode character set.
56       * Every implementation of the Java platform is required to support this character encoding.
57       *
58       * @deprecated use {@code java.nio.charset.StandardCharset.US_ASCII}
59       */
60      @Deprecated
61      public static final String US_ASCII = "US-ASCII";
62  
63      /**
64       * Sixteen-bit Unicode Transformation Format, byte order specified by a mandatory initial byte-order mark (either
65       * order accepted on input, big-endian used on output).
66       * Every implementation of the Java platform is required to support this character encoding.
67       *
68       * @deprecated use {@code java.nio.charset.StandardCharset.UTF_16}
69       */
70      @Deprecated
71      public static final String UTF_16 = "UTF-16";
72  
73      /**
74       * Sixteen-bit Unicode Transformation Format, big-endian byte order.
75       * Every implementation of the Java platform is required to support this character encoding.
76       *
77       * @deprecated use {@code java.nio.charset.StandardCharset.UTF_16BE}
78       */
79      @Deprecated
80      public static final String UTF_16BE = "UTF-16BE";
81  
82      /**
83       * Sixteen-bit Unicode Transformation Format, little-endian byte order.
84       * Every implementation of the Java platform is required to support this character encoding.
85       *
86       * @deprecated use {@code java.nio.charset.StandardCharset.UTF_16LE}
87       */
88      @Deprecated
89      public static final String UTF_16LE = "UTF-16LE";
90  
91      /**
92       * Eight-bit Unicode Transformation Format.
93       * Every implementation of the Java platform is required to support this character encoding.
94       *
95       * @deprecated use {@code java.nio.charset.StandardCharset.UTF_8}
96       */
97      @Deprecated
98      public static final String UTF_8 = "UTF-8";
99  
100     /**
101      * The <code>file.encoding</code> System Property.
102      */
103     public static final String FILE_ENCODING = System.getProperty("file.encoding");
104 
105     /**
106      * Create a new Reader with XML encoding detection rules.
107      *
108      * @param in not null input stream
109      * @return an XML reader instance for the input stream
110      * @throws IOException if any
111      * @deprecated use org.apache.commons.io.input.XmlStreamReader instead
112      */
113     @Deprecated
114     public static Reader newXmlReader(@Nonnull InputStream in) throws IOException {
115         return new XmlStreamReader(in);
116     }
117 
118     /**
119      * Create a new Reader with XML encoding detection rules.
120      *
121      * @param file not null file
122      * @return an XML reader instance for the input file
123      * @throws IOException if any
124      * @deprecated use org.apache.commons.io.input.XmlStreamReader instead
125      */
126     @Deprecated
127     public static Reader newXmlReader(@Nonnull File file) throws IOException {
128         return new XmlStreamReader(file);
129     }
130 
131     /**
132      * Create a new Reader with XML encoding detection rules.
133      *
134      * @param url not null URL
135      * @return an XML reader instance for the input URL
136      * @throws IOException if any
137      * @deprecated use {@code org.apache.commons.io.input.XmlStreamReader} instead
138      */
139     @Deprecated
140     public static Reader newXmlReader(@Nonnull URL url) throws IOException {
141         return new XmlStreamReader(url);
142     }
143 
144     /**
145      * Create a new Reader with default platform encoding.
146      *
147      * @param file not null file.
148      * @return a reader instance for the input file using the default platform character set
149      * @throws FileNotFoundException if any
150      * @see java.nio.charset.Charset#defaultCharset()
151      * @deprecated always specify an encoding. Do not depend on the default platform character set.
152      */
153     @Deprecated
154     public static Reader newPlatformReader(@Nonnull File file) throws FileNotFoundException {
155         return new FileReader(file);
156     }
157 
158     /**
159      * Create a new Reader with specified encoding.
160      *
161      * @param in       not null input stream
162      * @param encoding not null supported encoding
163      * @return a reader instance for the input stream using the given encoding
164      * @throws UnsupportedEncodingException if any
165      * @see <a href="https://docs.oracle.com/javase/7/docs/technotes/guides/intl/encoding.doc.html">Supported
166      *         encodings</a>
167      */
168     public static Reader newReader(@Nonnull InputStream in, @Nonnull String encoding)
169             throws UnsupportedEncodingException {
170         return new InputStreamReader(in, encoding);
171     }
172 
173     /**
174      * Create a new Reader with specified encoding.
175      *
176      * @param file     not null file
177      * @param encoding not null supported encoding
178      * @return a reader instance for the input file using the given encoding
179      * @throws FileNotFoundException        if any
180      * @throws UnsupportedEncodingException if any
181      * @see <a href="https://docs.oracle.com/javase/7/docs/technotes/guides/intl/encoding.doc.html">Supported
182      *         encodings</a>
183      */
184     public static Reader newReader(@Nonnull File file, @Nonnull String encoding)
185             throws FileNotFoundException, UnsupportedEncodingException {
186         return new InputStreamReader(new FileInputStream(file), encoding);
187     }
188 
189     /**
190      * Create a new Reader with specified encoding.
191      *
192      * @param url      not null URL
193      * @param encoding not null supported encoding
194      * @return a reader instance for the input URL using the given encoding
195      * @throws IOException if any
196      * @see <a href="https://docs.oracle.com/javase/7/docs/technotes/guides/intl/encoding.doc.html">Supported
197      *         encodings</a>
198      */
199     public static Reader newReader(@Nonnull URL url, @Nonnull String encoding) throws IOException {
200         return new InputStreamReader(url.openStream(), encoding);
201     }
202 }