Home | History | Annotate | Download | only in net 
      1 /* Licensed to the Apache Software Foundation (ASF) under one or more
      2  * contributor license agreements.  See the NOTICE file distributed with
      3  * this work for additional information regarding copyright ownership.
      4  * The ASF licenses this file to You under the Apache License, Version 2.0
      5  * (the "License"); you may not use this file except in compliance with
      6  * the License.  You may obtain a copy of the License at
      7  *
      8  *     http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 package java.net;
     18 
     19 import libcore.icu.NativeIDN;
     20 
     21 /**
     22  * Converts internationalized domain names between Unicode and the ASCII Compatible Encoding
     23  * (ACE) representation.
     24  *
     25  * <p>See <a href="http://www.ietf.org/rfc/rfc3490.txt">RFC 3490</a> for full details.
     26  *
     27  * @since 1.6
     28  */
     29 public final class IDN {
     30     /**
     31      * When set, allows IDN to process unassigned unicode points.
     32      */
     33     public static final int ALLOW_UNASSIGNED = 1;
     34 
     35     /**
     36      * When set, ASCII strings are checked against
     37      * <a href="http://www.ietf.org/rfc/rfc1122.txt">RFC 1122</a> and
     38      * <a href="http://www.ietf.org/rfc/rfc1123.txt">RFC 1123</a>.
     39      */
     40     public static final int USE_STD3_ASCII_RULES = 2;
     41 
     42     private IDN() {
     43     }
     44 
     45     /**
     46      * Transform a Unicode String to ASCII Compatible Encoding String according
     47      * to the algorithm defined in <a href="http://www.ietf.org/rfc/rfc3490.txt">RFC 3490</a>.
     48      *
     49      * <p>If the transformation fails (because the input is not a valid IDN), an
     50      * exception will be thrown.
     51      *
     52      * <p>This method can handle either an individual label or an entire domain name.
     53      * In the latter case, the separators are: U+002E (full stop), U+3002 (ideographic full stop),
     54      * U+FF0E (fullwidth full stop), and U+FF61 (halfwidth ideographic full stop).
     55      * All of these will become U+002E (full stop) in the result.
     56      *
     57      * @param input the Unicode name
     58      * @param flags 0, {@code ALLOW_UNASSIGNED}, {@code USE_STD3_ASCII_RULES},
     59      *         or {@code ALLOW_UNASSIGNED | USE_STD3_ASCII_RULES}
     60      * @return the ACE name
     61      * @throws IllegalArgumentException if {@code input} does not conform to <a href="http://www.ietf.org/rfc/rfc3490.txt">RFC 3490</a>
     62      */
     63     public static String toASCII(String input, int flags) {
     64         return NativeIDN.toASCII(input, flags);
     65     }
     66 
     67     /**
     68      * Equivalent to {@code toASCII(input, 0)}.
     69      *
     70      * @param input the Unicode name
     71      * @return the ACE name
     72      * @throws IllegalArgumentException if {@code input} does not conform to <a href="http://www.ietf.org/rfc/rfc3490.txt">RFC 3490</a>
     73      */
     74     public static String toASCII(String input) {
     75         return toASCII(input, 0);
     76     }
     77 
     78     /**
     79      * Translates a string from ASCII Compatible Encoding (ACE) to Unicode
     80      * according to the algorithm defined in <a href="http://www.ietf.org/rfc/rfc3490.txt">RFC 3490</a>.
     81      *
     82      * <p>Unlike {@code toASCII}, this transformation cannot fail.
     83      *
     84      * <p>This method can handle either an individual label or an entire domain name.
     85      * In the latter case, the separators are: U+002E (full stop), U+3002 (ideographic full stop),
     86      * U+FF0E (fullwidth full stop), and U+FF61 (halfwidth ideographic full stop).
     87      *
     88      * @param input the ACE name
     89      * @return the Unicode name
     90      * @param flags 0, {@code ALLOW_UNASSIGNED}, {@code USE_STD3_ASCII_RULES},
     91      *         or {@code ALLOW_UNASSIGNED | USE_STD3_ASCII_RULES}
     92      */
     93     public static String toUnicode(String input, int flags) {
     94         return NativeIDN.toUnicode(input, flags);
     95     }
     96 
     97     /**
     98      * Equivalent to {@code toUnicode(input, 0)}.
     99      *
    100      * @param input the ACE name
    101      * @return the Unicode name
    102      */
    103     public static String toUnicode(String input) {
    104         return NativeIDN.toUnicode(input, 0);
    105     }
    106 }
    107