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.FileNotFoundException;
24 import java.io.FileOutputStream;
25 import java.io.FileWriter;
26 import java.io.IOException;
27 import java.io.OutputStream;
28 import java.io.OutputStreamWriter;
29 import java.io.UnsupportedEncodingException;
30 import java.io.Writer;
31 import org.apache.maven.shared.utils.xml.XmlStreamWriter;
32
33
34 import javax.annotation.Nonnull;
35
36 /**
37 * Utility to create Writers, with explicit encoding choice: platform default,
38 * XML, or specified.
39 *
40 * @author Hervé Boutemy
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 WriterFactory
45 {
46 /**
47 * ISO Latin Alphabet #1, also known as ISO-LATIN-1.
48 * Every implementation of the Java platform is required to support this character encoding.
49 *
50 * @deprecated use {@code java.nio.charset.StandardCharset.ISO_8859_1}
51 */
52 @Deprecated
53 public static final String ISO_8859_1 = "ISO-8859-1";
54
55 /**
56 * Seven-bit ASCII, also known as ISO646-US, also known as the Basic Latin block of the Unicode character set.
57 * Every implementation of the Java platform is required to support this character encoding.
58 *
59 * @deprecated use {@code java.nio.charset.StandardCharset.US_ASCII}
60 */
61 @Deprecated
62 public static final String US_ASCII = "US-ASCII";
63
64 /**
65 * Sixteen-bit Unicode Transformation Format, byte order specified by a mandatory initial byte-order mark (either
66 * order accepted on input, big-endian used on output).
67 * Every implementation of the Java platform is required to support this character encoding.
68 *
69 * @deprecated use {@code java.nio.charset.StandardCharset.UTF_16}
70 */
71 @Deprecated
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 * @deprecated use {@code java.nio.charset.StandardCharset.UTF_16BE}
79 */
80 @Deprecated
81 public static final String UTF_16BE = "UTF-16BE";
82
83 /**
84 * Sixteen-bit Unicode Transformation Format, little-endian byte order.
85 * Every implementation of the Java platform is required to support this character encoding.
86 *
87 * @deprecated use {@code java.nio.charset.StandardCharset.UTF_16LE}
88 */
89 @Deprecated
90 public static final String UTF_16LE = "UTF-16LE";
91
92 /**
93 * Eight-bit Unicode Transformation Format.
94 * Every implementation of the Java platform is required to support this character encoding.
95 *
96 * @deprecated use {@code java.nio.charset.StandardCharset.UTF_8}
97 */
98 @Deprecated
99 public static final String UTF_8 = "UTF-8";
100
101 /**
102 * The <code>file.encoding</code> System Property.
103 */
104 public static final String FILE_ENCODING = System.getProperty( "file.encoding" );
105
106 /**
107 * Create a new Writer with XML encoding detection rules.
108 *
109 * @param out not null output stream
110 * @return an XML writer instance for the output stream
111 * @throws IOException if any
112 * @see XmlStreamWriter
113 */
114 public static XmlStreamWriter newXmlWriter( @Nonnull OutputStream out )
115 throws IOException
116 {
117 return new XmlStreamWriter( out );
118 }
119
120 /**
121 * Create a new Writer with XML encoding detection rules.
122 *
123 * @param file not null file
124 * @return an XML writer instance for the output file
125 * @throws IOException if any
126 * @see XmlStreamWriter
127 */
128 public static XmlStreamWriter newXmlWriter( @Nonnull File file )
129 throws IOException
130 {
131 return new XmlStreamWriter( file );
132 }
133
134 /**
135 * Create a new Writer with default platform encoding.
136 *
137 * @param out not null output stream
138 * @return a writer instance for the output stream using the default platform charset
139 * @deprecated always specify an encoding. Do not depend on the default platform character set.
140 */
141 @Deprecated
142 public static Writer newPlatformWriter( @Nonnull OutputStream out )
143 {
144 return new OutputStreamWriter( out );
145 }
146
147 /**
148 * Create a new Writer with default platform encoding.
149 *
150 * @param file not null file
151 * @return a writer instance for the output file using the default platform charset
152 * @throws IOException if any
153 * @deprecated always specify an encoding. Do not depend on the default platform character set.
154 */
155 @Deprecated
156 public static Writer newPlatformWriter( @Nonnull File file )
157 throws IOException
158 {
159 return new FileWriter( file );
160 }
161
162 /**
163 * Create a new Writer with specified encoding.
164 *
165 * @param out not null output stream
166 * @param encoding not null supported encoding
167 * @return a writer instance for the output stream using the given encoding
168 * @throws UnsupportedEncodingException if any
169 * @see <a href="https://docs.oracle.com/javase/7/docs/technotes/guides/intl/encoding.doc.html">Supported
170 * encodings</a>
171 */
172 public static Writer newWriter( @Nonnull OutputStream out, @Nonnull String encoding )
173 throws UnsupportedEncodingException
174 {
175 return new OutputStreamWriter( out, encoding );
176 }
177
178 /**
179 * Create a new Writer with specified encoding.
180 *
181 * @param file not null file
182 * @param encoding not null supported encoding
183 * @return a writer instance for the output file using the given encoding
184 * @throws UnsupportedEncodingException if any
185 * @throws FileNotFoundException if any
186 * @see <a href="https://docs.oracle.com/javase/7/docs/technotes/guides/intl/encoding.doc.html">Supported
187 * encodings</a>
188 */
189 public static Writer newWriter( @Nonnull File file, @Nonnull String encoding )
190 throws UnsupportedEncodingException, FileNotFoundException
191 {
192 return newWriter( new FileOutputStream( file ), encoding );
193 }
194 }