1/* GENERATED SOURCE. DO NOT MODIFY. */ 2/* 3 ******************************************************************************* 4 * Copyright (C) 2003-2016, International Business Machines Corporation and * 5 * others. All Rights Reserved. * 6 ******************************************************************************* 7 */ 8 9package android.icu.text; 10 11import java.util.Collections; 12import java.util.EnumSet; 13import java.util.Set; 14 15import android.icu.impl.IDNA2003; 16import android.icu.impl.UTS46; 17 18/** 19 * Abstract base class for IDNA processing. 20 * See http://www.unicode.org/reports/tr46/ 21 * and http://www.ietf.org/rfc/rfc3490.txt 22 * <p> 23 * The IDNA class is not intended for public subclassing. 24 * <p> 25 * The non-static methods implement UTS #46 and IDNA2008. 26 * IDNA2008 is implemented according to UTS #46, see getUTS46Instance(). 27 * <p> 28 * IDNA2003 is obsolete. The static methods implement IDNA2003. They are all deprecated. 29 * <p> 30 * IDNA2003 API Overview: 31 * <p> 32 * The static IDNA API methods implement the IDNA protocol as defined in the 33 * <a href="http://www.ietf.org/rfc/rfc3490.txt">IDNA RFC</a>. 34 * The draft defines 2 operations: ToASCII and ToUnicode. Domain labels 35 * containing non-ASCII code points are required to be processed by 36 * ToASCII operation before passing it to resolver libraries. Domain names 37 * that are obtained from resolver libraries are required to be processed by 38 * ToUnicode operation before displaying the domain name to the user. 39 * IDNA requires that implementations process input strings with 40 * <a href="http://www.ietf.org/rfc/rfc3491.txt">Nameprep</a>, 41 * which is a profile of <a href="http://www.ietf.org/rfc/rfc3454.txt">Stringprep</a> , 42 * and then with <a href="http://www.ietf.org/rfc/rfc3492.txt">Punycode</a>. 43 * Implementations of IDNA MUST fully implement Nameprep and Punycode; 44 * neither Nameprep nor Punycode are optional. 45 * The input and output of ToASCII and ToUnicode operations are Unicode 46 * and are designed to be chainable, i.e., applying ToASCII or ToUnicode operations 47 * multiple times to an input string will yield the same result as applying the operation 48 * once. 49 * ToUnicode(ToUnicode(ToUnicode...(ToUnicode(string)))) == ToUnicode(string) 50 * ToASCII(ToASCII(ToASCII...(ToASCII(string))) == ToASCII(string). 51 * 52 * @author Ram Viswanadha, Markus Scherer 53 */ 54public abstract class IDNA { 55 /** 56 * Default options value: None of the other options are set. 57 * For use in static worker and factory methods. 58 */ 59 public static final int DEFAULT = 0; 60 /** 61 * Option to allow unassigned code points in domain names and labels. 62 * For use in static worker and factory methods. 63 * <p>This option is ignored by the UTS46 implementation. 64 * (UTS #46 disallows unassigned code points.) 65 * @deprecated ICU 55 Use UTS 46 instead via {@link #getUTS46Instance(int)}. 66 * @hide original deprecated declaration 67 */ 68 @Deprecated 69 public static final int ALLOW_UNASSIGNED = 1; 70 /** 71 * Option to check whether the input conforms to the STD3 ASCII rules, 72 * for example the restriction of labels to LDH characters 73 * (ASCII Letters, Digits and Hyphen-Minus). 74 * For use in static worker and factory methods. 75 */ 76 public static final int USE_STD3_RULES = 2; 77 /** 78 * IDNA option to check for whether the input conforms to the BiDi rules. 79 * For use in static worker and factory methods. 80 * <p>This option is ignored by the IDNA2003 implementation. 81 * (IDNA2003 always performs a BiDi check.) 82 */ 83 public static final int CHECK_BIDI = 4; 84 /** 85 * IDNA option to check for whether the input conforms to the CONTEXTJ rules. 86 * For use in static worker and factory methods. 87 * <p>This option is ignored by the IDNA2003 implementation. 88 * (The CONTEXTJ check is new in IDNA2008.) 89 */ 90 public static final int CHECK_CONTEXTJ = 8; 91 /** 92 * IDNA option for nontransitional processing in ToASCII(). 93 * For use in static worker and factory methods. 94 * <p>By default, ToASCII() uses transitional processing. 95 * <p>This option is ignored by the IDNA2003 implementation. 96 * (This is only relevant for compatibility of newer IDNA implementations with IDNA2003.) 97 */ 98 public static final int NONTRANSITIONAL_TO_ASCII = 0x10; 99 /** 100 * IDNA option for nontransitional processing in ToUnicode(). 101 * For use in static worker and factory methods. 102 * <p>By default, ToUnicode() uses transitional processing. 103 * <p>This option is ignored by the IDNA2003 implementation. 104 * (This is only relevant for compatibility of newer IDNA implementations with IDNA2003.) 105 */ 106 public static final int NONTRANSITIONAL_TO_UNICODE = 0x20; 107 /** 108 * IDNA option to check for whether the input conforms to the CONTEXTO rules. 109 * For use in static worker and factory methods. 110 * <p>This option is ignored by the IDNA2003 implementation. 111 * (The CONTEXTO check is new in IDNA2008.) 112 * <p>This is for use by registries for IDNA2008 conformance. 113 * UTS #46 does not require the CONTEXTO check. 114 */ 115 public static final int CHECK_CONTEXTO = 0x40; 116 117 /** 118 * Returns an IDNA instance which implements UTS #46. 119 * Returns an unmodifiable instance, owned by the caller. 120 * Cache it for multiple operations, and delete it when done. 121 * The instance is thread-safe, that is, it can be used concurrently. 122 * <p> 123 * UTS #46 defines Unicode IDNA Compatibility Processing, 124 * updated to the latest version of Unicode and compatible with both 125 * IDNA2003 and IDNA2008. 126 * <p> 127 * The worker functions use transitional processing, including deviation mappings, 128 * unless NONTRANSITIONAL_TO_ASCII or NONTRANSITIONAL_TO_UNICODE 129 * is used in which case the deviation characters are passed through without change. 130 * <p> 131 * Disallowed characters are mapped to U+FFFD. 132 * <p> 133 * Operations with the UTS #46 instance do not support the 134 * ALLOW_UNASSIGNED option. 135 * <p> 136 * By default, the UTS #46 implementation allows all ASCII characters (as valid or mapped). 137 * When the USE_STD3_RULES option is used, ASCII characters other than 138 * letters, digits, hyphen (LDH) and dot/full stop are disallowed and mapped to U+FFFD. 139 * 140 * @param options Bit set to modify the processing and error checking. 141 * @return the UTS #46 IDNA instance, if successful 142 */ 143 public static IDNA getUTS46Instance(int options) { 144 return new UTS46(options); 145 } 146 147 /** 148 * Converts a single domain name label into its ASCII form for DNS lookup. 149 * If any processing step fails, then info.hasErrors() will be true and 150 * the result might not be an ASCII string. 151 * The label might be modified according to the types of errors. 152 * Labels with severe errors will be left in (or turned into) their Unicode form. 153 * 154 * @param label Input domain name label 155 * @param dest Destination string object 156 * @param info Output container of IDNA processing details. 157 * @return dest 158 */ 159 public abstract StringBuilder labelToASCII(CharSequence label, StringBuilder dest, Info info); 160 161 /** 162 * Converts a single domain name label into its Unicode form for human-readable display. 163 * If any processing step fails, then info.hasErrors() will be true. 164 * The label might be modified according to the types of errors. 165 * 166 * @param label Input domain name label 167 * @param dest Destination string object 168 * @param info Output container of IDNA processing details. 169 * @return dest 170 */ 171 public abstract StringBuilder labelToUnicode(CharSequence label, StringBuilder dest, Info info); 172 173 /** 174 * Converts a whole domain name into its ASCII form for DNS lookup. 175 * If any processing step fails, then info.hasErrors() will be true and 176 * the result might not be an ASCII string. 177 * The domain name might be modified according to the types of errors. 178 * Labels with severe errors will be left in (or turned into) their Unicode form. 179 * 180 * @param name Input domain name 181 * @param dest Destination string object 182 * @param info Output container of IDNA processing details. 183 * @return dest 184 */ 185 public abstract StringBuilder nameToASCII(CharSequence name, StringBuilder dest, Info info); 186 187 /** 188 * Converts a whole domain name into its Unicode form for human-readable display. 189 * If any processing step fails, then info.hasErrors() will be true. 190 * The domain name might be modified according to the types of errors. 191 * 192 * @param name Input domain name 193 * @param dest Destination string object 194 * @param info Output container of IDNA processing details. 195 * @return dest 196 */ 197 public abstract StringBuilder nameToUnicode(CharSequence name, StringBuilder dest, Info info); 198 199 /** 200 * Output container for IDNA processing errors. 201 * The Info class is not suitable for subclassing. 202 */ 203 public static final class Info { 204 /** 205 * Constructor. 206 */ 207 public Info() { 208 errors=EnumSet.noneOf(Error.class); 209 labelErrors=EnumSet.noneOf(Error.class); 210 isTransDiff=false; 211 isBiDi=false; 212 isOkBiDi=true; 213 } 214 /** 215 * Were there IDNA processing errors? 216 * @return true if there were processing errors 217 */ 218 public boolean hasErrors() { return !errors.isEmpty(); } 219 /** 220 * Returns a set indicating IDNA processing errors. 221 * @return set of processing errors (modifiable, and not null) 222 */ 223 public Set<Error> getErrors() { return errors; } 224 /** 225 * Returns true if transitional and nontransitional processing produce different results. 226 * This is the case when the input label or domain name contains 227 * one or more deviation characters outside a Punycode label (see UTS #46). 228 * <ul> 229 * <li>With nontransitional processing, such characters are 230 * copied to the destination string. 231 * <li>With transitional processing, such characters are 232 * mapped (sharp s/sigma) or removed (joiner/nonjoiner). 233 * </ul> 234 * @return true if transitional and nontransitional processing produce different results 235 */ 236 public boolean isTransitionalDifferent() { return isTransDiff; } 237 238 private void reset() { 239 errors.clear(); 240 labelErrors.clear(); 241 isTransDiff=false; 242 isBiDi=false; 243 isOkBiDi=true; 244 } 245 246 private EnumSet<Error> errors, labelErrors; 247 private boolean isTransDiff; 248 private boolean isBiDi; 249 private boolean isOkBiDi; 250 } 251 252 // The following protected methods give IDNA subclasses access to the private IDNAInfo fields. 253 // The IDNAInfo also provides intermediate state that is publicly invisible, 254 // avoiding the allocation of another worker object. 255 /** 256 * @deprecated This API is ICU internal only. 257 * @hide original deprecated declaration 258 * @hide draft / provisional / internal are hidden on Android 259 */ 260 @Deprecated 261 protected static void resetInfo(Info info) { 262 info.reset(); 263 } 264 /** 265 * @deprecated This API is ICU internal only. 266 * @hide original deprecated declaration 267 * @hide draft / provisional / internal are hidden on Android 268 */ 269 @Deprecated 270 protected static boolean hasCertainErrors(Info info, EnumSet<Error> errors) { 271 return !info.errors.isEmpty() && !Collections.disjoint(info.errors, errors); 272 } 273 /** 274 * @deprecated This API is ICU internal only. 275 * @hide original deprecated declaration 276 * @hide draft / provisional / internal are hidden on Android 277 */ 278 @Deprecated 279 protected static boolean hasCertainLabelErrors(Info info, EnumSet<Error> errors) { 280 return !info.labelErrors.isEmpty() && !Collections.disjoint(info.labelErrors, errors); 281 } 282 /** 283 * @deprecated This API is ICU internal only. 284 * @hide original deprecated declaration 285 * @hide draft / provisional / internal are hidden on Android 286 */ 287 @Deprecated 288 protected static void addLabelError(Info info, Error error) { 289 info.labelErrors.add(error); 290 } 291 /** 292 * @deprecated This API is ICU internal only. 293 * @hide original deprecated declaration 294 * @hide draft / provisional / internal are hidden on Android 295 */ 296 @Deprecated 297 protected static void promoteAndResetLabelErrors(Info info) { 298 if(!info.labelErrors.isEmpty()) { 299 info.errors.addAll(info.labelErrors); 300 info.labelErrors.clear(); 301 } 302 } 303 /** 304 * @deprecated This API is ICU internal only. 305 * @hide original deprecated declaration 306 * @hide draft / provisional / internal are hidden on Android 307 */ 308 @Deprecated 309 protected static void addError(Info info, Error error) { 310 info.errors.add(error); 311 } 312 /** 313 * @deprecated This API is ICU internal only. 314 * @hide original deprecated declaration 315 * @hide draft / provisional / internal are hidden on Android 316 */ 317 @Deprecated 318 protected static void setTransitionalDifferent(Info info) { 319 info.isTransDiff=true; 320 } 321 /** 322 * @deprecated This API is ICU internal only. 323 * @hide original deprecated declaration 324 * @hide draft / provisional / internal are hidden on Android 325 */ 326 @Deprecated 327 protected static void setBiDi(Info info) { 328 info.isBiDi=true; 329 } 330 /** 331 * @deprecated This API is ICU internal only. 332 * @hide original deprecated declaration 333 * @hide draft / provisional / internal are hidden on Android 334 */ 335 @Deprecated 336 protected static boolean isBiDi(Info info) { 337 return info.isBiDi; 338 } 339 /** 340 * @deprecated This API is ICU internal only. 341 * @hide original deprecated declaration 342 * @hide draft / provisional / internal are hidden on Android 343 */ 344 @Deprecated 345 protected static void setNotOkBiDi(Info info) { 346 info.isOkBiDi=false; 347 } 348 /** 349 * @deprecated This API is ICU internal only. 350 * @hide original deprecated declaration 351 * @hide draft / provisional / internal are hidden on Android 352 */ 353 @Deprecated 354 protected static boolean isOkBiDi(Info info) { 355 return info.isOkBiDi; 356 } 357 358 /** 359 * IDNA error bit set values. 360 * When a domain name or label fails a processing step or does not meet the 361 * validity criteria, then one or more of these error bits are set. 362 */ 363 public static enum Error { 364 /** 365 * A non-final domain name label (or the whole domain name) is empty. 366 */ 367 EMPTY_LABEL, 368 /** 369 * A domain name label is longer than 63 bytes. 370 * (See STD13/RFC1034 3.1. Name space specifications and terminology.) 371 * This is only checked in ToASCII operations, and only if the output label is all-ASCII. 372 */ 373 LABEL_TOO_LONG, 374 /** 375 * A domain name is longer than 255 bytes in its storage form. 376 * (See STD13/RFC1034 3.1. Name space specifications and terminology.) 377 * This is only checked in ToASCII operations, and only if the output domain name is all-ASCII. 378 */ 379 DOMAIN_NAME_TOO_LONG, 380 /** 381 * A label starts with a hyphen-minus ('-'). 382 */ 383 LEADING_HYPHEN, 384 /** 385 * A label ends with a hyphen-minus ('-'). 386 */ 387 TRAILING_HYPHEN, 388 /** 389 * A label contains hyphen-minus ('-') in the third and fourth positions. 390 */ 391 HYPHEN_3_4, 392 /** 393 * A label starts with a combining mark. 394 */ 395 LEADING_COMBINING_MARK, 396 /** 397 * A label or domain name contains disallowed characters. 398 */ 399 DISALLOWED, 400 /** 401 * A label starts with "xn--" but does not contain valid Punycode. 402 * That is, an xn-- label failed Punycode decoding. 403 */ 404 PUNYCODE, 405 /** 406 * A label contains a dot=full stop. 407 * This can occur in an input string for a single-label function. 408 */ 409 LABEL_HAS_DOT, 410 /** 411 * An ACE label does not contain a valid label string. 412 * The label was successfully ACE (Punycode) decoded but the resulting 413 * string had severe validation errors. For example, 414 * it might contain characters that are not allowed in ACE labels, 415 * or it might not be normalized. 416 */ 417 INVALID_ACE_LABEL, 418 /** 419 * A label does not meet the IDNA BiDi requirements (for right-to-left characters). 420 */ 421 BIDI, 422 /** 423 * A label does not meet the IDNA CONTEXTJ requirements. 424 */ 425 CONTEXTJ, 426 /** 427 * A label does not meet the IDNA CONTEXTO requirements for punctuation characters. 428 * Some punctuation characters "Would otherwise have been DISALLOWED" 429 * but are allowed in certain contexts. (RFC 5892) 430 */ 431 CONTEXTO_PUNCTUATION, 432 /** 433 * A label does not meet the IDNA CONTEXTO requirements for digits. 434 * Arabic-Indic Digits (U+066x) must not be mixed with Extended Arabic-Indic Digits (U+06Fx). 435 */ 436 CONTEXTO_DIGITS 437 } 438 439 /** 440 * Sole constructor. (For invocation by subclass constructors, typically implicit.) 441 * @deprecated This API is ICU internal only. 442 * @hide original deprecated declaration 443 * @hide draft / provisional / internal are hidden on Android 444 */ 445 @Deprecated 446 protected IDNA() { 447 } 448 449 /* IDNA2003 API ------------------------------------------------------------- */ 450 451 /** 452 * IDNA2003: This function implements the ToASCII operation as defined in the IDNA RFC. 453 * This operation is done on <b>single labels</b> before sending it to something that expects 454 * ASCII names. A label is an individual part of a domain name. Labels are usually 455 * separated by dots; e.g." "www.example.com" is composed of 3 labels 456 * "www","example", and "com". 457 * 458 * @param src The input string to be processed 459 * @param options A bit set of options: 460 * - IDNA.DEFAULT Use default options, i.e., do not process unassigned code points 461 * and do not use STD3 ASCII rules 462 * If unassigned code points are found the operation fails with 463 * StringPrepParseException. 464 * 465 * - IDNA.ALLOW_UNASSIGNED Unassigned values can be converted to ASCII for query operations 466 * If this option is set, the unassigned code points are in the input 467 * are treated as normal Unicode code points. 468 * 469 * - IDNA.USE_STD3_RULES Use STD3 ASCII rules for host name syntax restrictions 470 * If this option is set and the input does not satisfy STD3 rules, 471 * the operation will fail with ParseException 472 * @return StringBuffer the converted String 473 * @throws StringPrepParseException When an error occurs for parsing a string. 474 * @deprecated ICU 55 Use UTS 46 instead via {@link #getUTS46Instance(int)}. 475 * @hide original deprecated declaration 476 */ 477 @Deprecated 478 public static StringBuffer convertToASCII(String src, int options) 479 throws StringPrepParseException{ 480 UCharacterIterator iter = UCharacterIterator.getInstance(src); 481 return convertToASCII(iter,options); 482 } 483 484 /** 485 * IDNA2003: This function implements the ToASCII operation as defined in the IDNA RFC. 486 * This operation is done on <b>single labels</b> before sending it to something that expects 487 * ASCII names. A label is an individual part of a domain name. Labels are usually 488 * separated by dots; e.g." "www.example.com" is composed of 3 labels 489 * "www","example", and "com". 490 * 491 * @param src The input string as StringBuffer to be processed 492 * @param options A bit set of options: 493 * - IDNA.DEFAULT Use default options, i.e., do not process unassigned code points 494 * and do not use STD3 ASCII rules 495 * If unassigned code points are found the operation fails with 496 * ParseException. 497 * 498 * - IDNA.ALLOW_UNASSIGNED Unassigned values can be converted to ASCII for query operations 499 * If this option is set, the unassigned code points are in the input 500 * are treated as normal Unicode code points. 501 * 502 * - IDNA.USE_STD3_RULES Use STD3 ASCII rules for host name syntax restrictions 503 * If this option is set and the input does not satisfy STD3 rules, 504 * the operation will fail with ParseException 505 * @return StringBuffer the converted String 506 * @deprecated ICU 55 Use UTS 46 instead via {@link #getUTS46Instance(int)}. 507 * @hide original deprecated declaration 508 */ 509 @Deprecated 510 public static StringBuffer convertToASCII(StringBuffer src, int options) 511 throws StringPrepParseException{ 512 UCharacterIterator iter = UCharacterIterator.getInstance(src); 513 return convertToASCII(iter,options); 514 } 515 516 /** 517 * IDNA2003: This function implements the ToASCII operation as defined in the IDNA RFC. 518 * This operation is done on <b>single labels</b> before sending it to something that expects 519 * ASCII names. A label is an individual part of a domain name. Labels are usually 520 * separated by dots; e.g." "www.example.com" is composed of 3 labels 521 * "www","example", and "com". 522 * 523 * @param src The input string as UCharacterIterator to be processed 524 * @param options A bit set of options: 525 * - IDNA.DEFAULT Use default options, i.e., do not process unassigned code points 526 * and do not use STD3 ASCII rules 527 * If unassigned code points are found the operation fails with 528 * ParseException. 529 * 530 * - IDNA.ALLOW_UNASSIGNED Unassigned values can be converted to ASCII for query operations 531 * If this option is set, the unassigned code points are in the input 532 * are treated as normal Unicode code points. 533 * 534 * - IDNA.USE_STD3_RULES Use STD3 ASCII rules for host name syntax restrictions 535 * If this option is set and the input does not satisfy STD3 rules, 536 * the operation will fail with ParseException 537 * @return StringBuffer the converted String 538 * @deprecated ICU 55 Use UTS 46 instead via {@link #getUTS46Instance(int)}. 539 * @hide original deprecated declaration 540 */ 541 @Deprecated 542 public static StringBuffer convertToASCII(UCharacterIterator src, int options) 543 throws StringPrepParseException{ 544 return IDNA2003.convertToASCII(src, options); 545 } 546 547 /** 548 * IDNA2003: Convenience function that implements the IDNToASCII operation as defined in the IDNA RFC. 549 * This operation is done on complete domain names, e.g: "www.example.com". 550 * It is important to note that this operation can fail. If it fails, then the input 551 * domain name cannot be used as an Internationalized Domain Name and the application 552 * should have methods defined to deal with the failure. 553 * 554 * <b>Note:</b> IDNA RFC specifies that a conformant application should divide a domain name 555 * into separate labels, decide whether to apply allowUnassigned and useSTD3ASCIIRules on each, 556 * and then convert. This function does not offer that level of granularity. The options once 557 * set will apply to all labels in the domain name 558 * 559 * @param src The input string as UCharacterIterator to be processed 560 * @param options A bit set of options: 561 * - IDNA.DEFAULT Use default options, i.e., do not process unassigned code points 562 * and do not use STD3 ASCII rules 563 * If unassigned code points are found the operation fails with 564 * ParseException. 565 * 566 * - IDNA.ALLOW_UNASSIGNED Unassigned values can be converted to ASCII for query operations 567 * If this option is set, the unassigned code points are in the input 568 * are treated as normal Unicode code points. 569 * 570 * - IDNA.USE_STD3_RULES Use STD3 ASCII rules for host name syntax restrictions 571 * If this option is set and the input does not satisfy STD3 rules, 572 * the operation will fail with ParseException 573 * @return StringBuffer the converted String 574 * @deprecated ICU 55 Use UTS 46 instead via {@link #getUTS46Instance(int)}. 575 * @hide original deprecated declaration 576 */ 577 @Deprecated 578 public static StringBuffer convertIDNToASCII(UCharacterIterator src, int options) 579 throws StringPrepParseException{ 580 return convertIDNToASCII(src.getText(), options); 581 } 582 583 /** 584 * IDNA2003: Convenience function that implements the IDNToASCII operation as defined in the IDNA RFC. 585 * This operation is done on complete domain names, e.g: "www.example.com". 586 * It is important to note that this operation can fail. If it fails, then the input 587 * domain name cannot be used as an Internationalized Domain Name and the application 588 * should have methods defined to deal with the failure. 589 * 590 * <b>Note:</b> IDNA RFC specifies that a conformant application should divide a domain name 591 * into separate labels, decide whether to apply allowUnassigned and useSTD3ASCIIRules on each, 592 * and then convert. This function does not offer that level of granularity. The options once 593 * set will apply to all labels in the domain name 594 * 595 * @param src The input string as a StringBuffer to be processed 596 * @param options A bit set of options: 597 * - IDNA.DEFAULT Use default options, i.e., do not process unassigned code points 598 * and do not use STD3 ASCII rules 599 * If unassigned code points are found the operation fails with 600 * ParseException. 601 * 602 * - IDNA.ALLOW_UNASSIGNED Unassigned values can be converted to ASCII for query operations 603 * If this option is set, the unassigned code points are in the input 604 * are treated as normal Unicode code points. 605 * 606 * - IDNA.USE_STD3_RULES Use STD3 ASCII rules for host name syntax restrictions 607 * If this option is set and the input does not satisfy STD3 rules, 608 * the operation will fail with ParseException 609 * @return StringBuffer the converted String 610 * @deprecated ICU 55 Use UTS 46 instead via {@link #getUTS46Instance(int)}. 611 * @hide original deprecated declaration 612 */ 613 @Deprecated 614 public static StringBuffer convertIDNToASCII(StringBuffer src, int options) 615 throws StringPrepParseException{ 616 return convertIDNToASCII(src.toString(), options); 617 } 618 619 /** 620 * IDNA2003: Convenience function that implements the IDNToASCII operation as defined in the IDNA RFC. 621 * This operation is done on complete domain names, e.g: "www.example.com". 622 * It is important to note that this operation can fail. If it fails, then the input 623 * domain name cannot be used as an Internationalized Domain Name and the application 624 * should have methods defined to deal with the failure. 625 * 626 * <b>Note:</b> IDNA RFC specifies that a conformant application should divide a domain name 627 * into separate labels, decide whether to apply allowUnassigned and useSTD3ASCIIRules on each, 628 * and then convert. This function does not offer that level of granularity. The options once 629 * set will apply to all labels in the domain name 630 * 631 * @param src The input string to be processed 632 * @param options A bit set of options: 633 * - IDNA.DEFAULT Use default options, i.e., do not process unassigned code points 634 * and do not use STD3 ASCII rules 635 * If unassigned code points are found the operation fails with 636 * ParseException. 637 * 638 * - IDNA.ALLOW_UNASSIGNED Unassigned values can be converted to ASCII for query operations 639 * If this option is set, the unassigned code points are in the input 640 * are treated as normal Unicode code points. 641 * 642 * - IDNA.USE_STD3_RULES Use STD3 ASCII rules for host name syntax restrictions 643 * If this option is set and the input does not satisfy STD3 rules, 644 * the operation will fail with ParseException 645 * @return StringBuffer the converted String 646 * @deprecated ICU 55 Use UTS 46 instead via {@link #getUTS46Instance(int)}. 647 * @hide original deprecated declaration 648 */ 649 @Deprecated 650 public static StringBuffer convertIDNToASCII(String src,int options) 651 throws StringPrepParseException{ 652 return IDNA2003.convertIDNToASCII(src, options); 653 } 654 655 656 /** 657 * IDNA2003: This function implements the ToUnicode operation as defined in the IDNA RFC. 658 * This operation is done on <b>single labels</b> before sending it to something that expects 659 * Unicode names. A label is an individual part of a domain name. Labels are usually 660 * separated by dots; for e.g." "www.example.com" is composed of 3 labels 661 * "www","example", and "com". 662 * 663 * @param src The input string to be processed 664 * @param options A bit set of options: 665 * - IDNA.DEFAULT Use default options, i.e., do not process unassigned code points 666 * and do not use STD3 ASCII rules 667 * If unassigned code points are found the operation fails with 668 * ParseException. 669 * 670 * - IDNA.ALLOW_UNASSIGNED Unassigned values can be converted to ASCII for query operations 671 * If this option is set, the unassigned code points are in the input 672 * are treated as normal Unicode code points. 673 * 674 * - IDNA.USE_STD3_RULES Use STD3 ASCII rules for host name syntax restrictions 675 * If this option is set and the input does not satisfy STD3 rules, 676 * the operation will fail with ParseException 677 * @return StringBuffer the converted String 678 * @deprecated ICU 55 Use UTS 46 instead via {@link #getUTS46Instance(int)}. 679 * @hide original deprecated declaration 680 */ 681 @Deprecated 682 public static StringBuffer convertToUnicode(String src, int options) 683 throws StringPrepParseException{ 684 UCharacterIterator iter = UCharacterIterator.getInstance(src); 685 return convertToUnicode(iter,options); 686 } 687 688 /** 689 * IDNA2003: This function implements the ToUnicode operation as defined in the IDNA RFC. 690 * This operation is done on <b>single labels</b> before sending it to something that expects 691 * Unicode names. A label is an individual part of a domain name. Labels are usually 692 * separated by dots; for e.g." "www.example.com" is composed of 3 labels 693 * "www","example", and "com". 694 * 695 * @param src The input string as StringBuffer to be processed 696 * @param options A bit set of options: 697 * - IDNA.DEFAULT Use default options, i.e., do not process unassigned code points 698 * and do not use STD3 ASCII rules 699 * If unassigned code points are found the operation fails with 700 * ParseException. 701 * 702 * - IDNA.ALLOW_UNASSIGNED Unassigned values can be converted to ASCII for query operations 703 * If this option is set, the unassigned code points are in the input 704 * are treated as normal Unicode code points. 705 * 706 * - IDNA.USE_STD3_RULES Use STD3 ASCII rules for host name syntax restrictions 707 * If this option is set and the input does not satisfy STD3 rules, 708 * the operation will fail with ParseException 709 * @return StringBuffer the converted String 710 * @deprecated ICU 55 Use UTS 46 instead via {@link #getUTS46Instance(int)}. 711 * @hide original deprecated declaration 712 */ 713 @Deprecated 714 public static StringBuffer convertToUnicode(StringBuffer src, int options) 715 throws StringPrepParseException{ 716 UCharacterIterator iter = UCharacterIterator.getInstance(src); 717 return convertToUnicode(iter,options); 718 } 719 720 /** 721 * IDNA2003: Function that implements the ToUnicode operation as defined in the IDNA RFC. 722 * This operation is done on <b>single labels</b> before sending it to something that expects 723 * Unicode names. A label is an individual part of a domain name. Labels are usually 724 * separated by dots; for e.g." "www.example.com" is composed of 3 labels 725 * "www","example", and "com". 726 * 727 * @param src The input string as UCharacterIterator to be processed 728 * @param options A bit set of options: 729 * - IDNA.DEFAULT Use default options, i.e., do not process unassigned code points 730 * and do not use STD3 ASCII rules 731 * If unassigned code points are found the operation fails with 732 * ParseException. 733 * 734 * - IDNA.ALLOW_UNASSIGNED Unassigned values can be converted to ASCII for query operations 735 * If this option is set, the unassigned code points are in the input 736 * are treated as normal Unicode code points. 737 * 738 * - IDNA.USE_STD3_RULES Use STD3 ASCII rules for host name syntax restrictions 739 * If this option is set and the input does not satisfy STD3 rules, 740 * the operation will fail with ParseException 741 * @return StringBuffer the converted String 742 * @deprecated ICU 55 Use UTS 46 instead via {@link #getUTS46Instance(int)}. 743 * @hide original deprecated declaration 744 */ 745 @Deprecated 746 public static StringBuffer convertToUnicode(UCharacterIterator src, int options) 747 throws StringPrepParseException{ 748 return IDNA2003.convertToUnicode(src, options); 749 } 750 751 /** 752 * IDNA2003: Convenience function that implements the IDNToUnicode operation as defined in the IDNA RFC. 753 * This operation is done on complete domain names, e.g: "www.example.com". 754 * 755 * <b>Note:</b> IDNA RFC specifies that a conformant application should divide a domain name 756 * into separate labels, decide whether to apply allowUnassigned and useSTD3ASCIIRules on each, 757 * and then convert. This function does not offer that level of granularity. The options once 758 * set will apply to all labels in the domain name 759 * 760 * @param src The input string as UCharacterIterator to be processed 761 * @param options A bit set of options: 762 * - IDNA.DEFAULT Use default options, i.e., do not process unassigned code points 763 * and do not use STD3 ASCII rules 764 * If unassigned code points are found the operation fails with 765 * ParseException. 766 * 767 * - IDNA.ALLOW_UNASSIGNED Unassigned values can be converted to ASCII for query operations 768 * If this option is set, the unassigned code points are in the input 769 * are treated as normal Unicode code points. 770 * 771 * - IDNA.USE_STD3_RULES Use STD3 ASCII rules for host name syntax restrictions 772 * If this option is set and the input does not satisfy STD3 rules, 773 * the operation will fail with ParseException 774 * @return StringBuffer the converted String 775 * @deprecated ICU 55 Use UTS 46 instead via {@link #getUTS46Instance(int)}. 776 * @hide original deprecated declaration 777 */ 778 @Deprecated 779 public static StringBuffer convertIDNToUnicode(UCharacterIterator src, int options) 780 throws StringPrepParseException{ 781 return convertIDNToUnicode(src.getText(), options); 782 } 783 784 /** 785 * IDNA2003: Convenience function that implements the IDNToUnicode operation as defined in the IDNA RFC. 786 * This operation is done on complete domain names, e.g: "www.example.com". 787 * 788 * <b>Note:</b> IDNA RFC specifies that a conformant application should divide a domain name 789 * into separate labels, decide whether to apply allowUnassigned and useSTD3ASCIIRules on each, 790 * and then convert. This function does not offer that level of granularity. The options once 791 * set will apply to all labels in the domain name 792 * 793 * @param src The input string as StringBuffer to be processed 794 * @param options A bit set of options: 795 * - IDNA.DEFAULT Use default options, i.e., do not process unassigned code points 796 * and do not use STD3 ASCII rules 797 * If unassigned code points are found the operation fails with 798 * ParseException. 799 * 800 * - IDNA.ALLOW_UNASSIGNED Unassigned values can be converted to ASCII for query operations 801 * If this option is set, the unassigned code points are in the input 802 * are treated as normal Unicode code points. 803 * 804 * - IDNA.USE_STD3_RULES Use STD3 ASCII rules for host name syntax restrictions 805 * If this option is set and the input does not satisfy STD3 rules, 806 * the operation will fail with ParseException 807 * @return StringBuffer the converted String 808 * @deprecated ICU 55 Use UTS 46 instead via {@link #getUTS46Instance(int)}. 809 * @hide original deprecated declaration 810 */ 811 @Deprecated 812 public static StringBuffer convertIDNToUnicode(StringBuffer src, int options) 813 throws StringPrepParseException{ 814 return convertIDNToUnicode(src.toString(), options); 815 } 816 817 /** 818 * IDNA2003: Convenience function that implements the IDNToUnicode operation as defined in the IDNA RFC. 819 * This operation is done on complete domain names, e.g: "www.example.com". 820 * 821 * <b>Note:</b> IDNA RFC specifies that a conformant application should divide a domain name 822 * into separate labels, decide whether to apply allowUnassigned and useSTD3ASCIIRules on each, 823 * and then convert. This function does not offer that level of granularity. The options once 824 * set will apply to all labels in the domain name 825 * 826 * @param src The input string to be processed 827 * @param options A bit set of options: 828 * - IDNA.DEFAULT Use default options, i.e., do not process unassigned code points 829 * and do not use STD3 ASCII rules 830 * If unassigned code points are found the operation fails with 831 * ParseException. 832 * 833 * - IDNA.ALLOW_UNASSIGNED Unassigned values can be converted to ASCII for query operations 834 * If this option is set, the unassigned code points are in the input 835 * are treated as normal Unicode code points. 836 * 837 * - IDNA.USE_STD3_RULES Use STD3 ASCII rules for host name syntax restrictions 838 * If this option is set and the input does not satisfy STD3 rules, 839 * the operation will fail with ParseException 840 * @return StringBuffer the converted String 841 * @deprecated ICU 55 Use UTS 46 instead via {@link #getUTS46Instance(int)}. 842 * @hide original deprecated declaration 843 */ 844 @Deprecated 845 public static StringBuffer convertIDNToUnicode(String src, int options) 846 throws StringPrepParseException{ 847 return IDNA2003.convertIDNToUnicode(src, options); 848 } 849 850 /** 851 * IDNA2003: Compare two IDN strings for equivalence. 852 * This function splits the domain names into labels and compares them. 853 * According to IDN RFC, whenever two labels are compared, they are 854 * considered equal if and only if their ASCII forms (obtained by 855 * applying toASCII) match using an case-insensitive ASCII comparison. 856 * Two domain names are considered a match if and only if all labels 857 * match regardless of whether label separators match. 858 * 859 * @param s1 First IDN string as StringBuffer 860 * @param s2 Second IDN string as StringBuffer 861 * @param options A bit set of options: 862 * - IDNA.DEFAULT Use default options, i.e., do not process unassigned code points 863 * and do not use STD3 ASCII rules 864 * If unassigned code points are found the operation fails with 865 * ParseException. 866 * 867 * - IDNA.ALLOW_UNASSIGNED Unassigned values can be converted to ASCII for query operations 868 * If this option is set, the unassigned code points are in the input 869 * are treated as normal Unicode code points. 870 * 871 * - IDNA.USE_STD3_RULES Use STD3 ASCII rules for host name syntax restrictions 872 * If this option is set and the input does not satisfy STD3 rules, 873 * the operation will fail with ParseException 874 * @return 0 if the strings are equal, > 0 if s1 > s2 and < 0 if s1 < s2 875 * @deprecated ICU 55 Use UTS 46 instead via {@link #getUTS46Instance(int)}. 876 * @hide original deprecated declaration 877 */ 878 @Deprecated 879 public static int compare(StringBuffer s1, StringBuffer s2, int options) 880 throws StringPrepParseException{ 881 if(s1==null || s2 == null){ 882 throw new IllegalArgumentException("One of the source buffers is null"); 883 } 884 return IDNA2003.compare(s1.toString(), s2.toString(), options); 885 } 886 887 /** 888 * IDNA2003: Compare two IDN strings for equivalence. 889 * This function splits the domain names into labels and compares them. 890 * According to IDN RFC, whenever two labels are compared, they are 891 * considered equal if and only if their ASCII forms (obtained by 892 * applying toASCII) match using an case-insensitive ASCII comparison. 893 * Two domain names are considered a match if and only if all labels 894 * match regardless of whether label separators match. 895 * 896 * @param s1 First IDN string 897 * @param s2 Second IDN string 898 * @param options A bit set of options: 899 * - IDNA.DEFAULT Use default options, i.e., do not process unassigned code points 900 * and do not use STD3 ASCII rules 901 * If unassigned code points are found the operation fails with 902 * ParseException. 903 * 904 * - IDNA.ALLOW_UNASSIGNED Unassigned values can be converted to ASCII for query operations 905 * If this option is set, the unassigned code points are in the input 906 * are treated as normal Unicode code points. 907 * 908 * - IDNA.USE_STD3_RULES Use STD3 ASCII rules for host name syntax restrictions 909 * If this option is set and the input does not satisfy STD3 rules, 910 * the operation will fail with ParseException 911 * @return 0 if the strings are equal, > 0 if s1 > s2 and < 0 if s1 < s2 912 * @deprecated ICU 55 Use UTS 46 instead via {@link #getUTS46Instance(int)}. 913 * @hide original deprecated declaration 914 */ 915 @Deprecated 916 public static int compare(String s1, String s2, int options) throws StringPrepParseException{ 917 if(s1==null || s2 == null){ 918 throw new IllegalArgumentException("One of the source buffers is null"); 919 } 920 return IDNA2003.compare(s1, s2, options); 921 } 922 /** 923 * IDNA2003: Compare two IDN strings for equivalence. 924 * This function splits the domain names into labels and compares them. 925 * According to IDN RFC, whenever two labels are compared, they are 926 * considered equal if and only if their ASCII forms (obtained by 927 * applying toASCII) match using an case-insensitive ASCII comparison. 928 * Two domain names are considered a match if and only if all labels 929 * match regardless of whether label separators match. 930 * 931 * @param s1 First IDN string as UCharacterIterator 932 * @param s2 Second IDN string as UCharacterIterator 933 * @param options A bit set of options: 934 * - IDNA.DEFAULT Use default options, i.e., do not process unassigned code points 935 * and do not use STD3 ASCII rules 936 * If unassigned code points are found the operation fails with 937 * ParseException. 938 * 939 * - IDNA.ALLOW_UNASSIGNED Unassigned values can be converted to ASCII for query operations 940 * If this option is set, the unassigned code points are in the input 941 * are treated as normal Unicode code points. 942 * 943 * - IDNA.USE_STD3_RULES Use STD3 ASCII rules for host name syntax restrictions 944 * If this option is set and the input does not satisfy STD3 rules, 945 * the operation will fail with ParseException 946 * @return 0 if the strings are equal, > 0 if i1 > i2 and < 0 if i1 < i2 947 * @deprecated ICU 55 Use UTS 46 instead via {@link #getUTS46Instance(int)}. 948 * @hide original deprecated declaration 949 */ 950 @Deprecated 951 public static int compare(UCharacterIterator s1, UCharacterIterator s2, int options) 952 throws StringPrepParseException{ 953 if(s1==null || s2 == null){ 954 throw new IllegalArgumentException("One of the source buffers is null"); 955 } 956 return IDNA2003.compare(s1.getText(), s2.getText(), options); 957 } 958} 959