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