View Javadoc

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