001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 *
017 */
018
019 package org.apache.commons.compress.utils;
020
021 import java.nio.charset.Charset;
022 import java.nio.charset.UnsupportedCharsetException;
023
024 /**
025 * Charsets required of every implementation of the Java platform.
026 *
027 * From the Java documentation <a href="http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard
028 * charsets</a>:
029 * <p>
030 * <cite>Every implementation of the Java platform is required to support the following character encodings. Consult the
031 * release documentation for your implementation to see if any other encodings are supported. Consult the release
032 * documentation for your implementation to see if any other encodings are supported. </cite>
033 * </p>
034 *
035 * <ul>
036 * <li><code>US-ASCII</code><br/>
037 * Seven-bit ASCII, a.k.a. ISO646-US, a.k.a. the Basic Latin block of the Unicode character set.</li>
038 * <li><code>ISO-8859-1</code><br/>
039 * ISO Latin Alphabet No. 1, a.k.a. ISO-LATIN-1.</li>
040 * <li><code>UTF-8</code><br/>
041 * Eight-bit Unicode Transformation Format.</li>
042 * <li><code>UTF-16BE</code><br/>
043 * Sixteen-bit Unicode Transformation Format, big-endian byte order.</li>
044 * <li><code>UTF-16LE</code><br/>
045 * Sixteen-bit Unicode Transformation Format, little-endian byte order.</li>
046 * <li><code>UTF-16</code><br/>
047 * Sixteen-bit Unicode Transformation Format, byte order specified by a mandatory initial byte-order mark (either order
048 * accepted on input, big-endian used on output.)</li>
049 * </ul>
050 *
051 * This class best belongs in the Commons Lang or IO project. Even if a similar class is defined in another Commons component, it is
052 * not foreseen that Commons Compress would be made to depend on another Commons component.
053 *
054 * @see <a href="http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
055 * @since 1.4
056 * @version $Id: Charsets.java 1309643 2012-04-05 04:01:32Z ggregory $
057 */
058 public class Charsets {
059
060 //
061 // This class should only contain Charset instances for required encodings. This guarantees that it will load correctly and
062 // without delay on all Java platforms.
063 //
064
065 /**
066 * Returns the given Charset or the default Charset if the given Charset is null.
067 *
068 * @param charset
069 * A charset or null.
070 * @return the given Charset or the default Charset if the given Charset is null
071 */
072 public static Charset toCharset(Charset charset) {
073 return charset == null ? Charset.defaultCharset() : charset;
074 }
075
076 /**
077 * Returns a Charset for the named charset. If the name is null, return the default Charset.
078 *
079 * @param charset
080 * The name of the requested charset, may be null.
081 * @return a Charset for the named charset
082 * @throws UnsupportedCharsetException
083 * If the named charset is unavailable
084 */
085 public static Charset toCharset(String charset) {
086 return charset == null ? Charset.defaultCharset() : Charset.forName(charset);
087 }
088
089 /**
090 * CharsetNamesISO Latin Alphabet No. 1, a.k.a. ISO-LATIN-1. </p>
091 * <p>
092 * Every implementation of the Java platform is required to support this character encoding.
093 * </p>
094 *
095 * @see <a href="http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
096 */
097 public static final Charset ISO_8859_1 = Charset.forName(CharsetNames.ISO_8859_1);
098
099 /**
100 * <p>
101 * Seven-bit ASCII, also known as ISO646-US, also known as the Basic Latin block of the Unicode character set.
102 * </p>
103 * <p>
104 * Every implementation of the Java platform is required to support this character encoding.
105 * </p>
106 *
107 * @see <a href="http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
108 */
109 public static final Charset US_ASCII = Charset.forName(CharsetNames.US_ASCII);
110
111 /**
112 * <p>
113 * Sixteen-bit Unicode Transformation Format, The byte order specified by a mandatory initial byte-order mark
114 * (either order accepted on input, big-endian used on output)
115 * </p>
116 * <p>
117 * Every implementation of the Java platform is required to support this character encoding.
118 * </p>
119 *
120 * @see <a href="http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
121 */
122 public static final Charset UTF_16 = Charset.forName(CharsetNames.UTF_16);
123
124 /**
125 * <p>
126 * Sixteen-bit Unicode Transformation Format, big-endian byte order.
127 * </p>
128 * <p>
129 * Every implementation of the Java platform is required to support this character encoding.
130 * </p>
131 *
132 * @see <a href="http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
133 */
134 public static final Charset UTF_16BE = Charset.forName(CharsetNames.UTF_16BE);
135
136 /**
137 * <p>
138 * Sixteen-bit Unicode Transformation Format, little-endian byte order.
139 * </p>
140 * <p>
141 * Every implementation of the Java platform is required to support this character encoding.
142 * </p>
143 *
144 * @see <a href="http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
145 */
146 public static final Charset UTF_16LE = Charset.forName(CharsetNames.UTF_16LE);
147
148 /**
149 * <p>
150 * Eight-bit Unicode Transformation Format.
151 * </p>
152 * <p>
153 * Every implementation of the Java platform is required to support this character encoding.
154 * </p>
155 *
156 * @see <a href="http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
157 */
158 public static final Charset UTF_8 = Charset.forName(CharsetNames.UTF_8);
159 }