Charsets.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.apache.commons.io;

  19. import java.nio.charset.Charset;
  20. import java.nio.charset.StandardCharsets;
  21. import java.nio.charset.UnsupportedCharsetException;
  22. import java.util.Collections;
  23. import java.util.SortedMap;
  24. import java.util.TreeMap;

  26. /**
  27.  * Charsets required of every implementation of the Java platform.
  28.  *
  29.  * From the Java documentation <a href="https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html">
  30.  * Standard charsets</a>:
  31.  * <p>
  32.  * <cite>Every implementation of the Java platform is required to support the following character encodings. Consult
  33.  * the release documentation for your implementation to see if any other encodings are supported. Consult the release
  34.  * documentation for your implementation to see if any other encodings are supported. </cite>
  35.  * </p>
  36.  *
  37.  * <ul>
  38.  * <li>{@code US-ASCII}<br>
  39.  * Seven-bit ASCII, a.k.a. ISO646-US, a.k.a. the Basic Latin block of the Unicode character set.</li>
  40.  * <li>{@code ISO-8859-1}<br>
  41.  * ISO Latin Alphabet No. 1, a.k.a. ISO-LATIN-1.</li>
  42.  * <li>{@code UTF-8}<br>
  43.  * Eight-bit Unicode Transformation Format.</li>
  44.  * <li>{@code UTF-16BE}<br>
  45.  * Sixteen-bit Unicode Transformation Format, big-endian byte order.</li>
  46.  * <li>{@code UTF-16LE}<br>
  47.  * Sixteen-bit Unicode Transformation Format, little-endian byte order.</li>
  48.  * <li>{@code UTF-16}<br>
  49.  * Sixteen-bit Unicode Transformation Format, byte order specified by a mandatory initial byte-order mark (either order
  50.  * accepted on input, big-endian used on output.)</li>
  51.  * </ul>
  52.  *
  53.  * @see <a href="https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
  54.  * @since 2.3
  55.  */
  56. public class Charsets {

  58.     //
  59.     // This class should only contain Charset instances for required encodings. This guarantees that it will load
  60.     // correctly and without delay on all Java platforms.
  61.     //

  63.     private static final SortedMap<String, Charset> STANDARD_CHARSET_MAP;

  65.     static {
  66.         final SortedMap<String, Charset> standardCharsetMap = new TreeMap<>(String.CASE_INSENSITIVE_ORDER);
  67.         standardCharsetMap.put(StandardCharsets.ISO_8859_1.name(), StandardCharsets.ISO_8859_1);
  68.         standardCharsetMap.put(StandardCharsets.US_ASCII.name(), StandardCharsets.US_ASCII);
  69.         standardCharsetMap.put(StandardCharsets.UTF_16.name(), StandardCharsets.UTF_16);
  70.         standardCharsetMap.put(StandardCharsets.UTF_16BE.name(), StandardCharsets.UTF_16BE);
  71.         standardCharsetMap.put(StandardCharsets.UTF_16LE.name(), StandardCharsets.UTF_16LE);
  72.         standardCharsetMap.put(StandardCharsets.UTF_8.name(), StandardCharsets.UTF_8);
  73.         STANDARD_CHARSET_MAP = Collections.unmodifiableSortedMap(standardCharsetMap);
  74.     }

  76.     /**
  77.      * CharEncodingISO Latin Alphabet No. 1, a.k.a. ISO-LATIN-1.
  78.      * <p>
  79.      * Every implementation of the Java platform is required to support this character encoding.
  80.      * </p>
  81.      *
  82.      * @see <a href="https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
  83.      * @deprecated Use Java 7's {@link java.nio.charset.StandardCharsets}
  84.      */
  85.     @Deprecated
  86.     public static final Charset ISO_8859_1 = StandardCharsets.ISO_8859_1;

  88.     /**
  89.      * <p>
  90.      * Seven-bit ASCII, also known as ISO646-US, also known as the Basic Latin block of the Unicode character set.
  91.      * </p>
  92.      * <p>
  93.      * Every implementation of the Java platform is required to support this character encoding.
  94.      * </p>
  95.      *
  96.      * @see <a href="https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
  97.      * @deprecated Use Java 7's {@link java.nio.charset.StandardCharsets}
  98.      */
  99.     @Deprecated
  100.     public static final Charset US_ASCII = StandardCharsets.US_ASCII;

  102.     /**
  103.      * <p>
  104.      * Sixteen-bit Unicode Transformation Format, The byte order specified by a mandatory initial byte-order mark
  105.      * (either order accepted on input, big-endian used on output)
  106.      * </p>
  107.      * <p>
  108.      * Every implementation of the Java platform is required to support this character encoding.
  109.      * </p>
  110.      *
  111.      * @see <a href="https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
  112.      * @deprecated Use Java 7's {@link java.nio.charset.StandardCharsets}
  113.      */
  114.     @Deprecated
  115.     public static final Charset UTF_16 = StandardCharsets.UTF_16;

  117.     /**
  118.      * <p>
  119.      * Sixteen-bit Unicode Transformation Format, big-endian byte order.
  120.      * </p>
  121.      * <p>
  122.      * Every implementation of the Java platform is required to support this character encoding.
  123.      * </p>
  124.      *
  125.      * @see <a href="https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
  126.      * @deprecated Use Java 7's {@link java.nio.charset.StandardCharsets}
  127.      */
  128.     @Deprecated
  129.     public static final Charset UTF_16BE = StandardCharsets.UTF_16BE;

  131.     /**
  132.      * <p>
  133.      * Sixteen-bit Unicode Transformation Format, little-endian byte order.
  134.      * </p>
  135.      * <p>
  136.      * Every implementation of the Java platform is required to support this character encoding.
  137.      * </p>
  138.      *
  139.      * @see <a href="https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
  140.      * @deprecated Use Java 7's {@link java.nio.charset.StandardCharsets}
  141.      */
  142.     @Deprecated
  143.     public static final Charset UTF_16LE = StandardCharsets.UTF_16LE;

  145.     /**
  146.      * <p>
  147.      * Eight-bit Unicode Transformation Format.
  148.      * </p>
  149.      * <p>
  150.      * Every implementation of the Java platform is required to support this character encoding.
  151.      * </p>
  152.      *
  153.      * @see <a href="https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
  154.      * @deprecated Use Java 7's {@link java.nio.charset.StandardCharsets}
  155.      */
  156.     @Deprecated
  157.     public static final Charset UTF_8 = StandardCharsets.UTF_8;

  159.     /**
  160.      * Constructs a sorted map from canonical charset names to charset objects required of every implementation of the
  161.      * Java platform.
  162.      * <p>
  163.      * From the Java documentation <a href="https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html">
  164.      * Standard charsets</a>:
  165.      * </p>
  166.      *
  167.      * @return An immutable, case-insensitive map from canonical charset names to charset objects.
  168.      * @see Charset#availableCharsets()
  169.      * @since 2.5
  170.      */
  171.     public static SortedMap<String, Charset> requiredCharsets() {
  172.         return STANDARD_CHARSET_MAP;
  173.     }

  175.     /**
  176.      * Returns the given Charset or the {@link Charset#defaultCharset() default Charset} if the given Charset is null.
  177.      *
  178.      * @param charset
  179.      *            A charset or null.
  180.      * @return the given Charset or the default Charset if the given Charset is null
  181.      * @see Charset#defaultCharset()
  182.      */
  183.     public static Charset toCharset(final Charset charset) {
  184.         return charset == null ? Charset.defaultCharset() : charset;
  185.     }

  187.     /**
  188.      * Returns the given charset if non-null, otherwise return defaultCharset.
  189.      *
  190.      * @param charset The charset to test, may be null.
  191.      * @param defaultCharset The charset to return if charset is null, may be null.
  192.      * @return a Charset.
  193.      * @since 2.12.0
  194.      */
  195.     public static Charset toCharset(final Charset charset, final Charset defaultCharset) {
  196.         return charset == null ? defaultCharset : charset;
  197.     }

  199.     /**
  200.      * Returns a Charset for the named charset. If the name is null, return the {@link Charset#defaultCharset() default Charset}.
  201.      *
  202.      * @param charsetName The name of the requested charset, may be null.
  203.      * @return a Charset for the named charset.
  204.      * @throws UnsupportedCharsetException If the named charset is unavailable (unchecked exception).
  205.      * @see Charset#defaultCharset()
  206.      */
  207.     public static Charset toCharset(final String charsetName) throws UnsupportedCharsetException {
  208.         return toCharset(charsetName, Charset.defaultCharset());
  209.     }

  211.     /**
  212.      * Returns a Charset for the named charset. If the name is null, return the given default Charset.
  213.      *
  214.      * @param charsetName The name of the requested charset, may be null.
  215.      * @param defaultCharset The name charset to return if charsetName is null, may be null.
  216.      * @return a Charset for the named charset.
  217.      * @throws UnsupportedCharsetException If the named charset is unavailable (unchecked exception).
  218.      * @since 2.12.0
  219.      */
  220.     public static Charset toCharset(final String charsetName, final Charset defaultCharset) throws UnsupportedCharsetException {
  221.         return charsetName == null ? defaultCharset : Charset.forName(charsetName);
  222.     }

  224.     /**
  225.      * Construct a new instance.
  226.      *
  227.      * @deprecated Will be private in 4.0
  228.      */
  229.     @Deprecated
  230.     public Charsets() {
  231.         // empty
  232.     }
  233. }
Created with JaCoCo 0.8.12.202403310830