jars/icu4j-4_4_2-src/main/classes/core/src/com/ibm/icu/text/UFormat.java

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