Класс ResourceBundle

Обработка ресурсов содержит объекты, специфичные для региональных параметров. Когда вашей программе необходим ресурс, специфичный для региональных параметров, например, String, программа может загрузить его из набора ресурсов, соответствующего текущим региональным параметрам пользователя. Таким образом, вы можете писать код программы, который в значительной степени независим от региональных параметров пользователя, изолируя большую часть, если не все, информации, специфичной для региональных параметров, в наборах ресурсов.

Это позволяет вам писать программы, которые могут:

• легко локализоваться или переводиться на разные языки
• обрабатывать несколько региональных параметров одновременно
• легко изменяться в будущем для поддержки ещё большего числа региональных параметров

Наборы ресурсов принадлежат семействам, члены которых имеют общее базовое имя, но также имеют дополнительные компоненты, которые идентифицируют их региональные параметры. Например, базовое имя семейства наборов ресурсов может быть "MyResources". Семейство должно иметь набор ресурсов по умолчанию, который просто имеет то же имя, что и его семейство — "MyResources", и будет использоваться в качестве набора последней надежды, если конкретный региональный параметр не поддерживается. Затем семейство может предоставить столько регионально-специфичных членов, сколько потребуется, например, немецкий член с именем "MyResources_de".

Каждый набор ресурсов в семействе содержит те же самые элементы, но элементы переведены для регионального параметра, представленного этим набором ресурсов. Например, как "MyResources", так и "MyResources_de" могут иметь String, который используется на кнопке для отмены операций. В "MyResources" String может содержать "Cancel", а в "MyResources_de" — "Abbrechen".

Если существуют различные ресурсы для разных стран, вы можете сделать специализации: например, "MyResources_de_CH" содержит объекты для немецкого языка (de) в Швейцарии (CH). Если вы хотите изменить только некоторые из ресурсов в специализации, вы можете это сделать.

Когда вашей программе нужен объект, специфичный для региональных параметров, она загружает класс ResourceBundle с помощью метода getBundle:

ResourceBundle myResources =
     ResourceBundle.getBundle("MyResources", currentLocale);

Наборы ресурсов содержат пары ключ/значение. Ключи однозначно идентифицируют объект, специфичный для региональных параметров, в наборе. Вот пример набора ListResourceBundle, который содержит две пары ключ/значение:

public class MyResources extends ListResourceBundle {
    protected Object[][] getContents() {
        return new Object[][] {
            // LOCALIZE THE SECOND STRING OF EACH ARRAY (e.g., "OK")
            {"OkKey", "OK"},
            {"CancelKey", "Cancel"},
            // END OF MATERIAL TO LOCALIZE
       };
    }
}

Вы получаете объект из набора ресурсов с помощью соответствующего метода-получателя. Поскольку "OkKey" и "CancelKey" оба являются строками, вы бы использовали getString для их получения:

button1 = new Button(myResources.getString("OkKey"));
button2 = new Button(myResources.getString("CancelKey"));

Помимо getString, ResourceBundle также предоставляет метод для получения массивов строк, getStringArray, а также общий getObject метод для любого другого типа объекта. При использовании getObject, вам нужно будет привести результат к соответствующему типу. Например:

int[] myIntegers = (int[]) myResources.getObject("intList");

Java платформа предоставляет два подкласса ResourceBundle, ListResourceBundle и PropertyResourceBundle, которые предоставляют довольно простой способ создания ресурсов. Как вы кратко видели в предыдущем примере, ListResourceBundle управляет своим ресурсом как списком пар ключ/значение. PropertyResourceBundle использует файл свойств для управления своими ресурсами.

Если ListResourceBundle или PropertyResourceBundle не подходят для ваших нужд, вы можете написать свой собственный подкласс ResourceBundle. Ваши подклассы должны переопределять два метода: handleGetObject и getKeys().

Реализация подкласса ResourceBundle должна быть потокобезопасной, если она одновременно используется несколькими потоками. Стандартные реализации неабстрактных методов в этом классе, а также методы в прямых известных конкретных подклассах ListResourceBundle и PropertyResourceBundle являются потокобезопасными.

ResourceBundle.Control

Для фабричных методов, которые не принимают экземпляр ResourceBundle.Control, их поведение по умолчанию при загрузке наборов ресурсов может быть изменено с помощью установленных реализаций ResourceBundleControlProvider. Любые установленные поставщики обнаруживаются на стадии загрузки класса ResourceBundle. Если какой-либо из поставщиков предоставляет ResourceBundle.Control для данного базового имени, этот ResourceBundle.Control будет использоваться вместо значения по умолчанию ResourceBundle.Control. Если установлено более одного поставщика услуг для поддержки одного и того же базового имени, будет использоваться первый поставщик, возвращенный из ServiceLoader.

Управление кэшем

Пример

// default (English language, United States)
public class MyResources extends ResourceBundle {
    public Object handleGetObject(String key) {
        if (key.equals("okKey")) return "Ok";
        if (key.equals("cancelKey")) return "Cancel";
        return null;
    }

    public Enumeration<String> getKeys() {
        return Collections.enumeration(keySet());
    }

    // Overrides handleKeySet() so that the getKeys() implementation
    // can rely on the keySet() value.
    protected Set<String> handleKeySet() {
        return new HashSet<String>(Arrays.asList("okKey", "cancelKey"));
    }
}

// German language
public class MyResources_de extends MyResources {
    public Object handleGetObject(String key) {
        // don't need okKey, since parent level handles it.
        if (key.equals("cancelKey")) return "Abbrechen";
        return null;
    }

    protected Set<String> handleKeySet() {
        return new HashSet<String>(Arrays.asList("cancelKey"));
    }
}

Поля

parent

protected ResourceBundle parent

Родительский пучок этого пучка. Родительский пучок ищется с помощью getObject, когда в данном пучке отсутствует определённый ресурс.

Конструкторы

ResourceBundle

public ResourceBundle()

Единственный конструктор. (Для вызова конструкторами подклассов, обычно неявный).

Методы

getBaseBundleName

public String getBaseBundleName()

Возвращает базовое имя этого пучка, если известно, или null если неизвестно. Если не null, то это значение параметра baseName, переданного в метод ResourceBundle.getBundle(...), при загрузке пучка ресурсов.

Возвращает:

Базовое имя пучка ресурсов, предоставленное и ожидаемое методами ResourceBundle.getBundle(...).

С:

1.8

См. также:

getBundle(java.lang.String, java.util.Locale, java.lang.ClassLoader)

getString

public final String getString(String key)

Получает строку для заданного ключа из этого пучка ресурсов или из одного из его родительских пучков. Вызов этого метода эквивалентен вызову

(String) getObject(key).

Параметры:

key - ключ для желаемой строки

Возвращает:

строка для заданного ключа

Исключения:

NullPointerException - если key является null

MissingResourceException - если объект для заданного ключа не найден

ClassCastException - если объект, найденный для заданного ключа, не является строкой

getStringArray

public final String[] getStringArray(String key)

Получает массив строк для заданного ключа из этого пучка ресурсов или из одного из его родительских пучков. Вызов этого метода эквивалентен вызову

(String[]) getObject(key).

Параметры:

key - ключ для желаемого массива строк

Возвращает:

массив строк для заданного ключа

Исключения:

NullPointerException - если key является null

MissingResourceException - если объект для заданного ключа не найден

ClassCastException - если объект, найденный для заданного ключа, не является массивом строк

getObject

public final Object getObject(String key)

Получает объект для заданного ключа из этого пучка ресурсов или из одного из его родительских пучков. Этот метод сначала пытается получить объект из этого пучка ресурсов, используя handleGetObject. Если это не удается, и родительский пучок ресурсов не null, он вызывает метод getObject родительского пучка. Если это все ещё не удалось, выбрасывается MissingResourceException.

Параметры:

key - ключ для желаемого объекта

Возвращает:

объект для заданного ключа

Исключения:

NullPointerException - если key является null

MissingResourceException - если объект для заданного ключа не найден

getLocale

public Locale getLocale()

Возвращает локаль этого пучка ресурсов. Этот метод можно использовать после вызова getBundle(), чтобы определить, действительно ли возвращаемый пучок ресурсов соответствует запрошенной локали или является резервным вариантом.

Возвращает:

локаль этого пучка ресурсов

setParent

protected void setParent(ResourceBundle parent)

Устанавливает родительский пучок этого пучка. Родительский пучок ищется с помощью getObject, когда в этом пучке отсутствует определённый ресурс.

Параметры:

parent - родительский пучок этого пучка.

getBundle

public static final ResourceBundle getBundle(String baseName)

Получает пучок ресурсов с указанным базовым именем, стандартной локалью и загрузчиком класса вызывающего метода. Вызов этого метода эквивалентен вызову

getBundle(baseName, Locale.getDefault(), this.getClass().getClassLoader()),

Параметры:

baseName - базовое имя пучка ресурсов, полное имя класса

Возвращает:

пучок ресурсов для заданного базового имени и стандартной локали

Исключения:

NullPointerException - если baseName является null

MissingResourceException - если пучок ресурсов для указанного базового имени не найден

getBundle

public static final ResourceBundle getBundle(String baseName,
                                             ResourceBundle.Control control)

Возвращает пучок ресурсов, используя указанное базовое имя, стандартную локаль и заданный контроллер. Вызов этого метода эквивалентен вызову

getBundle(baseName, Locale.getDefault(),
           this.getClass().getClassLoader(), control),

Параметры:

baseName - базовое имя пучка ресурсов, полное имя класса

control - контроллер, предоставляющий информацию для процесса загрузки пучка ресурсов

Возвращает:

пучок ресурсов для заданного базового имени и стандартной локали

Исключения:

NullPointerException - если baseName или control является null

MissingResourceException - если пучок ресурсов для указанного базового имени не найден

IllegalArgumentException - если заданный control работает неправильно (например, control.getCandidateLocales возвращает null). Обратите внимание, что валидация control выполняется по мере необходимости.

С:

1.6

getBundle

public static final ResourceBundle getBundle(String baseName,
                                             Locale locale)

Получает пучок ресурсов, используя указанное базовое имя и локаль, а также загрузчик класса вызывающего метода. Вызов этого метода эквивалентен вызову

getBundle(baseName, locale, this.getClass().getClassLoader()),

Параметры:

baseName - базовое имя пучка ресурсов, полное имя класса

locale - локаль, для которой нужен пучок ресурсов

Возвращает:

пучок ресурсов для заданного базового имени и локали

Исключения:

NullPointerException - если baseName или locale является null

MissingResourceException - если пучок ресурсов для указанного базового имени не найден

getBundle

public static final ResourceBundle getBundle(String baseName,
                                             Locale targetLocale,
                                             ResourceBundle.Control control)

Возвращает пучок ресурсов, используя указанное базовое имя, целевую локаль и контроллер, а также загрузчик класса вызывающего метода. Вызов этого метода эквивалентен вызову

getBundle(baseName, targetLocale, this.getClass().getClassLoader(),
           control),

Параметры:

baseName - базовое имя пучка ресурсов, полное имя класса

targetLocale - локаль, для которой нужен пучок ресурсов

control - контроллер, предоставляющий информацию для процесса загрузки пучка ресурсов

Возвращает:

пучок ресурсов для заданного базового имени и Locale в locales

Исключения:

NullPointerException - если baseName, locales или control является null

MissingResourceException - если пучок ресурсов для указанного базового имени в любом из locales не найден.

IllegalArgumentException - если заданный control работает неправильно (например, control.getCandidateLocales возвращает null). Обратите внимание, что валидация control выполняется по мере необходимости.

С:

1.6

getBundle

public static ResourceBundle getBundle(String baseName,
                                       Locale locale,
                                       ClassLoader loader)

baseName + "_" + language + "_" + script + "_" + country + "_" + variant
     baseName + "_" + language + "_" + script + "_" + country
     baseName + "_" + language + "_" + script
     baseName + "_" + language + "_" + country + "_" + variant
     baseName + "_" + language + "_" + country
     baseName + "_" + language

MyResource_de__JAVA
     MyResource_de

MyResource_en_Latn_US_WINDOWS_VISTA
 MyResource_en_Latn_US_WINDOWS
 MyResource_en_Latn_US
 MyResource_en_Latn
 MyResource_en_US_WINDOWS_VISTA
 MyResource_en_US_WINDOWS
 MyResource_en_US
 MyResource_en

Note: For some Locales, the list of candidate bundle names contains extra names, or the order of bundle names is slightly modified. See the description of the default implementation of getCandidateLocales for details.

MyResources.class
     MyResources.properties
     MyResources_fr.properties
     MyResources_fr_CH.class
     MyResources_fr_CH.properties
     MyResources_en.properties
     MyResources_es_ES.class

Параметры:

baseName - базовое имя набора ресурсов, полное имя класса

locale - локаль, для которой требуется набор ресурсов

loader - загрузчик классов, из которого загрузить набор ресурсов

Возвращает:

набор ресурсов для заданного базового имени и локали

Исключения:

NullPointerException - если baseName, locale, или loader null

MissingResourceException - если набор ресурсов для указанного базового имени не найден

С:

1.2

getBundle

public static ResourceBundle getBundle(String baseName,
                                       Locale targetLocale,
                                       ClassLoader loader,
                                       ResourceBundle.Control control)

Параметры:

baseName - имя базы набора ресурсов, полное имя класса

targetLocale - язык, для которого требуется набор ресурсов

loader - загрузчик классов для загрузки набора ресурсов

control - управление, предоставляющее информацию для процесса загрузки набора ресурсов

Возвращает:

набор ресурсов для данного имени базы и языка

Исключения:

NullPointerException - если baseName, targetLocale, loader, или control null

MissingResourceException - если набор ресурсов для указанного имени базы не найден

IllegalArgumentException - если заданное control работает неправильно (например, control.getCandidateLocales возвращает null). Обратите внимание, что валидация control выполняется по мере необходимости.

С:

1.6

clearCache

public static final void clearCache()

Удаляет все наборы ресурсов из кэша, загруженные с помощью загрузчика классов вызывающего метода.

С:

1.6

См. также:

ResourceBundle.Control.getTimeToLive(String,Locale)

clearCache

public static final void clearCache(ClassLoader loader)

Удаляет все наборы ресурсов из кэша, загруженные с помощью указанного загрузчика классов.

Параметры:

loader - загрузчик классов

Исключения:

NullPointerException - если loader равно null

С:

1.6

См. также:

ResourceBundle.Control.getTimeToLive(String,Locale)

handleGetObject

protected abstract Object handleGetObject(String key)

Получает объект для заданного ключа из этого набора ресурсов. Возвращает null, если этот набор ресурсов не содержит объекта для заданного ключа.

Параметры:

key - ключ искомого объекта

Возвращает:

объект для заданного ключа или null

Исключения:

NullPointerException - если key null

getKeys

public abstract Enumeration<String> getKeys()

Возвращает перечисление ключей.

Возвращает:

перечисление ключей, содержащихся в этом ResourceBundle и его родительских наборах.

containsKey

public boolean containsKey(String key)

Определяет, содержится ли заданный key в этом ResourceBundle или его родительских наборах.

Параметры:

key — ресурс key

Возвращает:

true в случае, если заданный key содержится в этом ResourceBundle или его родительских наборах ресурсов; false в противном случае.

Исключение:

NullPointerException — если key является null

С:

1.6

keySet

public Set<String> keySet()

Возвращает Set всех ключей, содержащихся в этом ResourceBundle и его родительских наборах ресурсов.

Возвращает:

a Set всех ключей, содержащихся в этом ResourceBundle и его родительских наборах ресурсов.

С:

1.6

handleKeySet

protected Set<String> handleKeySet()

Возвращает:

a Set ключей, содержащихся только в этом ResourceBundle

С:

1.6