jars/icu4j-4_2_1-src/src/com/ibm/icu/text/UFormat.java

   1 /*\r
   2  *******************************************************************************\r
   3  * Copyright (C) 2003-2006, International Business Machines Corporation and    *\r
   4  * others. All Rights Reserved.                                                *\r
   5  *******************************************************************************\r
   6  */\r
   7 package com.ibm.icu.text;\r
   8 \r
   9 import java.text.Format;\r
  10 import com.ibm.icu.util.ULocale;\r
  11 \r
  12 /**\r
  13  * An abstract class that extends {@link java.text.Format} to provide\r
  14  * additional ICU protocol, specifically, the <tt>getLocale()</tt>\r
  15  * API.  All ICU format classes are subclasses of this class.\r
  16  *\r
  17  * @see com.ibm.icu.util.ULocale\r
  18  * @author weiv\r
  19  * @author Alan Liu\r
  20  * @draft ICU 2.8 (retain)\r
  21  * @provisional This API might change or be removed in a future release.\r
  22  */\r
  23 public abstract class UFormat extends Format {\r
  24     // jdk1.4.2 serialver\r
  25     private static final long serialVersionUID = -4964390515840164416L;\r
  26 \r
  27     /**\r
  28      * @draft ICU 2.8 (retain)\r
  29      * @provisional This API might change or be removed in a future release.\r
  30      */\r
  31     public UFormat() {}\r
  32 \r
  33     // -------- BEGIN ULocale boilerplate --------\r
  34 \r
  35     /**\r
  36      * Return the locale that was used to create this object, or null.\r
  37      * This may may differ from the locale requested at the time of\r
  38      * this object's creation.  For example, if an object is created\r
  39      * for locale <tt>en_US_CALIFORNIA</tt>, the actual data may be\r
  40      * drawn from <tt>en</tt> (the <i>actual</i> locale), and\r
  41      * <tt>en_US</tt> may be the most specific locale that exists (the\r
  42      * <i>valid</i> locale).\r
  43      *\r
  44      * <p>Note: This method will be implemented in ICU 3.0; ICU 2.8\r
  45      * contains a partial preview implementation.  The <i>actual</i>\r
  46      * locale is returned correctly, but the <i>valid</i> locale is\r
  47      * not, in most cases.\r
  48      * @param type type of information requested, either {@link\r
  49      * com.ibm.icu.util.ULocale#VALID_LOCALE} or {@link\r
  50      * com.ibm.icu.util.ULocale#ACTUAL_LOCALE}.\r
  51      * @return the information specified by <i>type</i>, or null if\r
  52      * this object was not constructed from locale data.\r
  53      * @see com.ibm.icu.util.ULocale\r
  54      * @see com.ibm.icu.util.ULocale#VALID_LOCALE\r
  55      * @see com.ibm.icu.util.ULocale#ACTUAL_LOCALE\r
  56      * @draft ICU 2.8 (retain)\r
  57      * @provisional This API might change or be removed in a future release.\r
  58      */\r
  59     public final ULocale getLocale(ULocale.Type type) {\r
  60         return type == ULocale.ACTUAL_LOCALE ?\r
  61             this.actualLocale : this.validLocale;\r
  62     }\r
  63 \r
  64     /**\r
  65      * Set information about the locales that were used to create this\r
  66      * object.  If the object was not constructed from locale data,\r
  67      * both arguments should be set to null.  Otherwise, neither\r
  68      * should be null.  The actual locale must be at the same level or\r
  69      * less specific than the valid locale.  This method is intended\r
  70      * for use by factories or other entities that create objects of\r
  71      * this class.\r
  72      * @param valid the most specific locale containing any resource\r
  73      * data, or null\r
  74      * @param actual the locale containing data used to construct this\r
  75      * object, or null\r
  76      * @see com.ibm.icu.util.ULocale\r
  77      * @see com.ibm.icu.util.ULocale#VALID_LOCALE\r
  78      * @see com.ibm.icu.util.ULocale#ACTUAL_LOCALE\r
  79      * @internal\r
  80      */\r
  81     final void setLocale(ULocale valid, ULocale actual) {\r
  82         // Change the following to an assertion later\r
  83         if ((valid == null) != (actual == null)) {\r
  84             ///CLOVER:OFF\r
  85             throw new IllegalArgumentException();\r
  86             ///CLOVER:ON\r
  87         }\r
  88         // Another check we could do is that the actual locale is at\r
  89         // the same level or less specific than the valid locale.\r
  90         this.validLocale = valid;\r
  91         this.actualLocale = actual;\r
  92     }\r
  93 \r
  94     /**\r
  95      * The most specific locale containing any resource data, or null.\r
  96      * @see com.ibm.icu.util.ULocale\r
  97      * @internal\r
  98      */\r
  99     private ULocale validLocale;\r
 100 \r
 101     /**\r
 102      * The locale containing data used to construct this object, or\r
 103      * null.\r
 104      * @see com.ibm.icu.util.ULocale\r
 105      * @internal\r
 106      */\r
 107     private ULocale actualLocale;\r
 108 \r
 109     // -------- END ULocale boilerplate --------\r
 110 }\r