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