Класс ResourceBundle

java.lang.Object

java.util.ResourceBundle

Прямые известные подклассы:: ListResourceBundle, PropertyResourceBundle

public abstract class ResourceBundle extends Object

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

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

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

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

Каждый ресурсный пакет в семье содержит одни и те же элементы, но элементы были переведены для локали, представленной этим ресурсным пакетом. Например, и "MyResources", и "MyResources_de" могут иметь String, который используется на кнопке для отмены операций. В "MyResources" этот String может содержать "Отмена", а в "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
       };
    }
}

Ключи всегда String. В этом примере ключами являются "OkKey" и "CancelKey". В данном примере значения также являются String — "OK" и "Cancel" — но они не обязательно должны быть таковыми. Значения могут быть любого типа объектов.

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

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

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

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

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

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

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

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

Ресурсные пакеты и именованные модули

Ресурсные пакеты могут быть развернуты в модулях следующим образом:

Ресурсные пакеты вместе с приложением

Ресурсные пакеты могут быть развернуты вместе с приложением в одном модуле. В этом случае ресурсные пакеты загружаются кодом в модуле путём вызова метода getBundle(String) или getBundle(String, Locale).

Ресурсные пакеты как поставщики сервисов

Ресурсные пакеты могут быть развернуты в одном или нескольких модулях поставщиков сервисов, и они могут быть найдены с помощью ServiceLoader. Должен быть определен интерфейс или класс сервиса. Вызывающий модуль объявляет, что он использует сервис, модули поставщиков сервисов объявляют, что они предоставляют реализации сервиса. Обратитесь к ResourceBundleProvider для разработки сервисов ресурсных пакетов и развертывания поставщиков ресурсных пакетов. Модуль, получающий ресурсный пакет, сам может быть поставщиком ресурсных пакетов; в этом случае этот модуль находит ресурсный пакет только через механизм поставщика сервисов.

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

Ресурсные пакеты в других модулях и в пути класса

Ресурсные пакеты в именованном модуле могут быть капсулированы, чтобы код в других модулях не мог их найти. Ресурсные пакеты в безымянных модулях и в пути класса доступны для доступа любому модулю. Ресурсный пакет следует правилам капсулирования ресурсов, как указано в Module.getResourceAsStream(String).

Методы-фабрики getBundle без параметра Control ищут и загружают ресурсные пакеты у поставщиков сервисов. Поиск может продолжаться, как если бы вы вызывали Module.getResourceAsStream(String) для поиска именованного ресурса в заданном модуле и вызывали ClassLoader.getResourceAsStream(String); обратитесь к спецификации метода getBundle для получения подробной информации. Ищутся только некапсулированные ресурсные пакеты форматов "java.class" или "java.properties".

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

В тех случаях, когда метод-фабрика getBundle вызывается из контекста, где в стеке нет кадра вызова (например, когда он вызывается напрямую из нити JNI), вызывающий модуль по умолчанию — безымянный модуль для системного загрузчика классов.

Ресурсные пакеты в автоматических модулях

Распространённый формат ресурсных пакетов — файл в формате .properties. Обычно ресурсные пакеты упаковываются в JAR-файл. JAR-файл, содержащий только ресурсные пакеты, может быть легко развернут как автоматический модуль. Например, если JAR-файл содержит запись "p/q/Foo_ja.properties" и не содержит запись .class, при разрешении и определении в качестве автоматического модуля пакет для этого модуля не выводится. Это позволяет ресурсным пакетам в формате .properties , упакованным в один или несколько JAR-файлов, которые могут содержать записи в одной и той же директории, и успешно разрешаться как автоматические модули.

ResourceBundle.Control

Класс ResourceBundle.Control предоставляет информацию, необходимую для выполнения процесса загрузки пакета методами-фабриками getBundle , которые принимают экземпляр ResourceBundle.Control. Вы можете реализовать свой собственный подкласс, чтобы включить нестандартные форматы ресурсных пакетов, изменить стратегию поиска или определить параметры кеширования. Обратитесь к описаниям класса и метода-фабрики getBundle для получения подробной информации.

ResourceBundle.Control предназначен для приложения, развернутого в безымянном модуле, например, для поддержки ресурсных пакетов в нестандартных форматах или упаковки локализованных ресурсов в нетрадиционной конвенции. ResourceBundleProvider — замена для ResourceBundle.Control при миграции на модули. UnsupportedOperationException будет выброшен при вызове метода-фабрики, принимающего параметр ResourceBundle.Control.

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

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

Экземпляры ресурсных пакетов, созданные методами-фабриками getBundle, кешируются по умолчанию, и методы-фабрики возвращают один и тот же экземпляр ресурсного пакета несколько раз, если он был помещён в кэш. Клиенты getBundle могут очистить кэш, управлять временем жизни кэшированных экземпляров ресурсного пакета, используя значения времени жизни, или указать, не кешировать экземпляры ресурсных пакетов. Обратитесь к описаниям метода-фабрики getBundle, clearCache, ResourceBundle.Control.getTimeToLive и ResourceBundle.Control.needsReload для получения подробной информации.

Пример

Следующий пример демонстрирует простой класс ResourceBundle подкласса, MyResources, который управляет двумя ресурсами (для большего числа ресурсов, вероятно, вы бы использовали Map). Обратите внимание, что вам не нужно предоставлять значение, если «родительский уровень» ResourceBundle обрабатывает тот же ключ с тем же значением (как в случае с okKey ниже).

// 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"));
    }
}

Вы можете использовать не только один набор ResourceBundle. Например, вы можете иметь набор пакетов для сообщений об ошибках, ExceptionResources (ExceptionResources_fr, ExceptionResources_de, ...), и один для виджетов, WidgetResource (WidgetResources_fr, WidgetResources_de, ...); разбивая ресурсы как вам удобно.

С момента:

1.1

См. также:

Краткое описание вложенных классов

Модификатор и тип	Класс	Описание
`static class`	`ResourceBundle.Control`	`ResourceBundle.Control` определяет набор методов обратного вызова, которые вызываются фабричными методами `ResourceBundle.getBundle` во время процесса загрузки пакета.

Краткое описание полей

Модификатор и тип	Поле	Описание
`protected ResourceBundle`	`parent`	Родительский пакет этого пакета.

Краткое описание конструкторов

Конструктор	Описание
`ResourceBundle()`	Единственный конструктор.

Краткое описание методов

Модификатор и тип	Метод	Описание
`static final void`	`clearCache()`	Удаляет все пакеты ресурсов из кэша, загруженные модулем вызывающего.
`static final void`	`clearCache(ClassLoader loader)`	Удаляет все пакеты ресурсов из кэша, загруженные заданным загрузчиком классов.
`boolean`	`containsKey(String key)`	Определяет, содержится ли указанный `key` в этом `ResourceBundle` или его родительских пакетах.
`String`	`getBaseBundleName()`	Возвращает имя базы пакета, если известно, или `null` в противном случае.
`static final ResourceBundle`	`getBundle(String baseName)`	Получает пакет ресурсов, используя указанное имя базы, локаль по умолчанию и модуль вызывающего.
`static ResourceBundle`	`getBundle(String baseName, Module module)`	Получает пакет ресурсов, используя указанное имя базы и локаль по умолчанию от имени указанного модуля.
`static final ResourceBundle`	`getBundle(String baseName, Locale locale)`	Получает пакет ресурсов, используя указанное имя базы и локаль, а также модуль вызывающего.
`static ResourceBundle`	`getBundle(String baseName, Locale locale, ClassLoader loader)`	Получает пакет ресурсов, используя указанное имя базы, локаль и загрузчик классов.
`static ResourceBundle`	`getBundle(String baseName, Locale targetLocale, ClassLoader loader, ResourceBundle.Control control)`	Возвращает пакет ресурсов, используя указанное имя базы, целевую локаль, загрузчик классов и control.
`static ResourceBundle`	`getBundle(String baseName, Locale targetLocale, Module module)`	Получает пакет ресурсов, используя указанное имя базы и локаль от имени указанного модуля.
`static final ResourceBundle`	`getBundle(String baseName, Locale targetLocale, ResourceBundle.Control control)`	Возвращает пакет ресурсов, используя указанное имя базы, целевую локаль и control, а также загрузчик классов вызывающего.
`static final ResourceBundle`	`getBundle(String baseName, ResourceBundle.Control control)`	Возвращает пакет ресурсов, используя указанное имя базы, локаль по умолчанию и заданный control.
`abstract Enumeration<String>`	`getKeys()`	Возвращает перечисление ключей.
`Locale`	`getLocale()`	Возвращает локаль этого пакета ресурсов.
`final Object`	`getObject(String key)`	Получает объект для заданного ключа из этого пакета ресурсов или одного из его родителей.
`final String`	`getString(String key)`	Получает строку для заданного ключа из этого пакета ресурсов или одного из его родителей.
`final String[]`	`getStringArray(String key)`	Получает массив строк для заданного ключа из этого пакета ресурсов или одного из его родителей.
`protected abstract Object`	`handleGetObject(String key)`	Получает объект для заданного ключа из этого пакета ресурсов.
`protected Set<String>`	`handleKeySet()`	Возвращает `Set` ключей, содержащихся только в этом `ResourceBundle`.
`Set<String>`	`keySet()`	Возвращает `Set` всех ключей, содержащихся в этом `ResourceBundle` и его родительских пакетах.
`protected void`	`setParent(ResourceBundle parent)`	Устанавливает родительский пакет этого пакета.

Методы, объявленные в классе java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Подробное описание полей

parent

protected ResourceBundle parent

Базовый пучок данного пучка. Базовый пучок ищется методом getObject, когда данный пучок не содержит определённого ресурса.

Подробное описание конструкторов

ResourceBundle

public ResourceBundle()

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

Подробное описание методов

getBaseBundleName

public String getBaseBundleName()

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

Возвращает:

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

С:

1.8

См. также:

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(), callerModule);

Параметры:

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

Возвращает:

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

Исключения:

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

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

См. также:

getBundle

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

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

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

за исключением того, что getClassLoader() выполняется с привилегиями безопасности ResourceBundle. См. getBundle для полного описания процесса загрузки пучка ресурсов с ResourceBundle.Control.

Параметры:: baseName - базовое имя пучка ресурсов, полностью квалифицированное имя класса; control - контроллер, который предоставляет информацию для процесса загрузки пучка ресурсов
Возвращает:: пучок ресурсов для данного базового имени и локаль по умолчанию
Исключения:: NullPointerException - если baseName или control является null; MissingResourceException - если пучок ресурсов для указанного базового имени не найден; IllegalArgumentException - если данный control не работает должным образом (например, control.getCandidateLocales возвращает null). Обратите внимание, что проверка control выполняется по мере необходимости.; UnsupportedOperationException - если этот метод вызывается в именованном модуле
С:: 1.6

getBundle

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

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

    getBundle(baseName, locale, callerModule);

Параметры:

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

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

Возвращает:

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

Исключения:

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

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

См. также:

getBundle

public static ResourceBundle getBundle(String baseName, Module module)

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

    getBundle(baseName, Locale.getDefault(), module);

Параметры:

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

module - модуль, для которого ищется пучок ресурсов

Возвращает:

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

Исключения:

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

SecurityException - если менеджер безопасности существует и вызывающий не является указанным модулем и не имеет RuntimePermission("getClassLoader")

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

С:

См. также:

getBundle

public static ResourceBundle getBundle(String baseName, Locale targetLocale, Module module)

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

Пакеты ресурсов в именованных модулях могут быть инкапсулированы. Когда пакет ресурсов загружается из провайдера сервиса, вызывающему модулю необходимо иметь соответствующую зависимость в его описании модуля, чтобы объявить, что модуль использует ResourceBundleProvider для указанного пакета ресурсов. В противном случае, он загрузит пакеты ресурсов, которые являются локальными в данном модуле, как если бы он вызывал Module.getResourceAsStream(String), или которые видны загрузчику классов данного модуля, как если бы он вызывал ClassLoader.getResourceAsStream(String). Когда пакет ресурсов загружается из указанного модуля, он подчиняется правилам инкапсуляции, указанным в Module.getResourceAsStream.

Если данный module является безымянным модулем, то этот метод эквивалентен вызову getBundle(baseName, targetLocale, module.getClassLoader() для загрузки пакетов ресурсов, которые видны загрузчику классов данного безымянного модуля. Реализации пользовательского ResourceBundleControlProvider, если они присутствуют, будут вызваны только в случае, если указанный модуль является безымянным.

Parameters:

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

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

module - модуль, в котором ищется пакет ресурсов

Returns:

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

Throws:

NullPointerException - если baseName, targetLocale, или module null

SecurityException - если менеджер безопасности существует и вызывающий элемент не является указанным модулем и не имеет RuntimePermission("getClassLoader")

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

Since:

See Also:

getBundle

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

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

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

, за исключением того, что getClassLoader() выполняется с привилегиями безопасности ResourceBundle. См. getBundle для полного описания процесса загрузки пакета ресурсов с ResourceBundle.Control.

Parameters:: baseName - базовое имя пакета ресурсов, полное имя класса; targetLocale - язык для которого требуется пакет ресурсов; control - обработчик, предоставляющий информацию для процесса загрузки пакета ресурсов
Returns:: пакет ресурсов для данного базового имени и Locale в locales
Throws:: NullPointerException - если baseName, locales или control null; MissingResourceException - если пакет ресурсов для указанного базового имени в любом из locales не найден.; IllegalArgumentException - если данный control не работает должным образом (например, control.getCandidateLocales возвращает null). Обратите внимание, что валидация control выполняется по мере необходимости.; UnsupportedOperationException - если этот метод вызывается в именованном модуле
Since:: 1.6

getBundle

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

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

Когда этот метод вызывается из именованного модуля, и заданный загрузчик является загрузчиком классов вызывающего модуля, это эквивалентно вызову:

    getBundle(baseName, targetLocale, callerModule);

в противном случае, это эквивалентно вызову:

    getBundle(baseName, targetLocale, loader, control);

где control является экземпляром по умолчанию ResourceBundle.Control, если экземпляр ResourceBundleControlProvider SPI не предоставляет другой. Обратитесь к описанию изменения поведения по умолчанию. Ниже описано поведение по умолчанию.

Стратегия поиска и загрузки ресурсных пакетов

getBundle использует базовое имя, заданную локаль и локаль по умолчанию (полученную из Locale.getDefault) для генерации последовательности имен кандидатных пакетов. Если язык, сценарий, страна и вариант заданной локали все являются пустыми строками, тогда базовое имя является единственным именем кандидатного пакета. В противном случае, список кандидатных локалей генерируется из атрибутов заданной локали (язык, сценарий, страна и вариант) и добавляется к базовому имени. Обычно это выглядит следующим образом:

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

Имена кандидатных пакетов, где последний компонент является пустой строкой, опускаются вместе с символом подчеркивания. Например, если страна является пустой строкой, то второе и пятое имена кандидатных пакетов выше будут опущены. Также, если сценарий является пустой строкой, то имена кандидатов, включающие сценарий, опускаются. Например, локаль с языком "de" и вариантом "JAVA" сгенерирует имена кандидатов с базовым именем "MyResource" ниже.

     MyResource_de__JAVA
     MyResource_de

В случае, если вариант содержит одну или несколько подчеркиваний ("_"), последовательность имен пакетов, сгенерированных путем усечения последнего подчеркивания и части, следующей за ним, вставляется после имени кандидатного пакета с исходным вариантом. Например, для локали с языком "en", сценарием "Latn", страной "US" и вариантом "WINDOWS_VISTA" и базовым именем пакета "MyResource" генерируется список имен кандидатных пакетов ниже:

 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

Примечание: Для некоторых Locale список имен кандидатных пакетов содержит дополнительные имена, или порядок имен пакетов немного изменен. Подробности см. в описании реализации по умолчанию getCandidateLocales.

getBundle затем перебирает имена кандидатных пакетов, чтобы найти первое, для которого он может инициализировать фактический ресурсный пакет. Он использует getFormats метод по умолчанию для управления пакетами, который генерирует два имени пакета для каждого сгенерированного имени, первое - имя класса, а второе - имя файла свойств. Для каждого имени кандидатного пакета он пытается создать ресурсный пакет:

Во-первых, он пытается загрузить класс, используя сгенерированное имя класса. Если такой класс можно найти и загрузить с помощью заданного загрузчика классов, он совместим с ResourceBundle, доступен из ResourceBundle и может быть инициализирован, getBundle создает новый экземпляр этого класса и использует его в качестве результата ресурсного пакета.
В противном случае, getBundle пытается найти файл ресурса свойств, используя сгенерированное имя файла свойств. Он генерирует имя пути из имени кандидатного пакета, заменяя все символы "." символом "/" и добавляя строку ".properties". Он пытается найти "ресурс" с этим именем, используя ClassLoader.getResource. (Обратите внимание, что "ресурс" в смысле getResource не имеет отношения к содержимому ресурсного пакета, он просто является контейнером данных, например, файла.) Если он находит "ресурс", он пытается создать новый экземпляр PropertyResourceBundle из его содержимого. При успехе этот экземпляр становится результатом ресурсного пакета.

Это продолжается до тех пор, пока не будет инициализирован ресурсный пакет-результат или список имен кандидатных пакетов не будет исчерпан. Если подходящий ресурсный пакет не найден, вызывается метод getFallbackLocale по умолчанию, который возвращает текущую локаль по умолчанию. Используя эту локаль, генерируется новая последовательность имен кандидатных локалей и поиск выполняется снова, как описано выше.

Если результат пакета все еще не найден, ищется само базовое имя. Если это тоже не удается, выбрасывается MissingResourceException.

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

В противном случае, getBundle проверяет оставшуюся часть списка кандидатных локалей, которая использовалась во время прохода, сгенерировавшего результат ресурсного пакета. (Как и прежде, имена кандидатных пакетов, где конечный компонент является пустой строкой, пропускаются.) Когда доходит до конца списка кандидатов, он пытается создать ресурсный пакет с простым именем пакета. При каждой попытке он пытается инициализировать ресурсный пакет (сначала ищет класс, а затем файл свойств, как описано выше).

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

После завершения цепочки предков пакет возвращается.

Примечание: getBundle кэширует инициализированные ресурсные пакеты и может возвращать тот же экземпляр ресурсного пакета несколько раз.

Примечание: Аргумент baseName должен быть полным именем класса. Однако, для совместимости с предыдущими версиями, среды выполнения Java SE не проверяют это, и поэтому можно получить доступ к PropertyResourceBundle путем указания имени пути (используя "/") вместо полного имени класса (используя ".").

Пример:

Предоставляются следующие класс и файлы свойств:

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

Содержимое всех файлов является корректным (то есть, общедоступные не абстрактные подклассы ResourceBundle для файлов ".class", синтаксически правильные файлы ".properties"). Локаль по умолчанию Locale("en", "GB").

Вызов getBundle с параметрами локали ниже приведет к инициализации ресурсных пакетов следующим образом:

getBundle() соответствие локали и ресурсного пакета
Локаль	Ресурсный пакет
Locale("fr", "CH")	MyResources_fr_CH.class, родитель MyResources_fr.properties, родитель MyResources.class
Locale("fr", "FR")	MyResources_fr.properties, родитель MyResources.class
Locale("de", "DE")	MyResources_en.properties, родитель MyResources.class
Locale("en", "US")	MyResources_en.properties, родитель MyResources.class
Locale("es", "ES")	MyResources_es_ES.class, родитель MyResources.class

Файл MyResources_fr_CH.properties никогда не используется, потому что он скрыт MyResources_fr_CH.class. Аналогично, MyResources.properties также скрыт MyResources.class.

API Note:

Если вызывающий модуль является именованным модулем и заданный loader является загрузчиком классов вызывающего модуля, этот метод эквивалентен getBundle(baseName, locale); в противном случае, он может не найти ресурсные пакеты из именованных модулей. Используйте getBundle(String, Locale, Module) для загрузки ресурсных пакетов от имени конкретного модуля.

Параметры:

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)

Возвращает набор ресурсов, используя указанное имя базового имени, целевой язык, загрузчик классов и контроллер. В отличие от методов-фабрик getBundle без аргумента control, заданный control определяет способ поиска и создания наборов ресурсов. Концептуально, процесс загрузки набора ресурсов с заданным control выполняется в следующие шаги.

Этот метод-фабрика ищет набор ресурсов в кэше для указанного baseName, targetLocale и loader. Если запрашиваемый экземпляр набора ресурсов найден в кэше, и срок хранения экземпляра и всех его родительских экземпляров не истек, экземпляр возвращается вызывающему методу. В противном случае, этот метод-фабрика продолжает процесс загрузки ниже.
Вызывается метод control.getFormats для получения форматов набора ресурсов для создания имен наборов или ресурсов. Строки "java.class" и "java.properties" обозначают наборы ресурсов на основе класса и на основе свойств, соответственно. Другие строки, начинающиеся с "java.", зарезервированы для будущих расширений и не должны использоваться для форматов, определенных приложением. Другие строки обозначают форматы, определенные приложением.
Вызывается метод control.getCandidateLocales с целевым языком для получения списка кандидатных языков, для которых ищутся наборы ресурсов.

Вызывается метод control.newBundle для создания экземпляра ResourceBundle для имени базового набора, кандидатного языка и формата. (Обратитесь к примечанию о поиске в кэше ниже.) Этот шаг повторяется для всех комбинаций кандидатных языков и форматов, пока метод newBundle не вернёт экземпляр ResourceBundle, или пока все комбинации не будут использованы. Например, если кандидатами являются Locale("de", "DE"), Locale("de") и Locale(""), а форматы — "java.class" и "java.properties", то порядок комбинаций язык-формат для вызова control.newBundle выглядит так:

locale-format combinations for newBundle
Индекс	`Locale`	`format`
1	`Locale("de", "DE")`	`java.class`
2	`Locale("de", "DE")`	`java.properties`
3	`Locale("de")`	`java.class`
4	`Locale("de")`	`java.properties`
5	`Locale("")`	`java.class`
6	`Locale("")`	`java.properties`

Если на предыдущем шаге набор ресурсов не был найден, переходите к шагу 6. Если найден набор ресурсов, являющийся базовым набором (набор для Locale("")), и список кандидатных языков содержал только Locale(""), верните набор вызывающему методу. Если набор ресурсов был найден, являясь базовым набором, но список кандидатных языков содержал языки, отличные от Locale(""), приостановите набор и переходите к шагу 6. Если найден набор ресурсов, который не является базовым, переходите к шагу 7.
Вызывается метод control.getFallbackLocale для получения языка по умолчанию (альтернативы текущему целевому языку) для дальнейшего поиска набора ресурсов. Если метод возвращает ненулевой язык, он становится новым целевым языком, и процесс загрузки начинается снова с шага 3. В противном случае, если базовый набор был найден и приостановлен на предыдущем шаге 5, он возвращается вызывающему методу. В противном случае генерируется исключение MissingResourceException.
В этот момент мы нашли набор ресурсов, который не является базовым. Если этот набор задал родительский набор во время создания, он возвращается вызывающему методу. В противном случае его цепочка предков создается на основе списка кандидатных языков, из которого он был найден. Наконец, набор возвращается вызывающему методу.

Во время процесса загрузки набора ресурсов выше, этот метод-фабрика ищет в кэше перед вызовом метода control.newBundle. Если срок хранения набора ресурсов, найденного в кэше, истек, метод-фабрика вызывает метод control.needsReload, чтобы определить, требуется ли перезагрузка набора ресурсов. Если перезагрузка требуется, метод-фабрика вызывает control.newBundle для перезагрузки набора ресурсов. Если control.newBundle возвращает null, метод-фабрика помещает фиктивный набор ресурсов в кэш как метку несуществующих наборов ресурсов, чтобы избежать избыточных обращений к поиску для последующих запросов. Такие фиктивные наборы ресурсов находятся под тем же контролем срока действия, что и указанный в control.

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

Ниже приведен пример процесса загрузки набора ресурсов с использованием реализации ResourceBundle.Control по умолчанию.

Условия:

Имя базового набора: foo.bar.Messages
Запрашиваемый язык: Locale.ITALY
Язык по умолчанию: Locale.FRENCH
Доступные наборы ресурсов: foo/bar/Messages_fr.properties и foo/bar/Messages.properties

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

класс foo.bar.Messages_it_IT
файл foo/bar/Messages_it_IT.properties
класс foo.bar.Messages_it
файл foo/bar/Messages_it.properties
класс foo.bar.Messages
файл foo/bar/Messages.properties

В этот момент getBundle находит foo/bar/Messages.properties, который приостанавливается, потому что это базовый набор. getBundle вызывает control.getFallbackLocale("foo.bar.Messages", Locale.ITALY), который возвращает Locale.FRENCH. Далее, getBundle пытается загрузить набор в следующем порядке.

класс foo.bar.Messages_fr
файл foo/bar/Messages_fr.properties
класс foo.bar.Messages
файл foo/bar/Messages.properties

getBundle находит foo/bar/Messages_fr.properties и создает экземпляр ResourceBundle. Затем getBundle устанавливает его цепочку предков из списка кандидатных языков. Только foo/bar/Messages.properties найден в списке и getBundle создает экземпляр ResourceBundle, который становится родителем экземпляра для foo/bar/Messages_fr.properties.

Parameters:: baseName - имя базового набора ресурсов, полное имя класса; targetLocale - язык, для которого требуется набор ресурсов; loader - загрузчик классов, из которого загрузить набор ресурсов; control - контроллер, предоставляющий информацию для процесса загрузки набора ресурсов
Returns:: набор ресурсов для заданного базового имени и языка
Throws:: NullPointerException - если baseName, targetLocale, loader, или control null; MissingResourceException - если для заданного базового имени не найден ни один набор ресурсов; IllegalArgumentException - если заданный control не работает должным образом (например, control.getCandidateLocales возвращает null). Обратите внимание, что валидация control выполняется по мере необходимости.; UnsupportedOperationException - если этот метод вызывается в именованном модуле
Since:: 1.6

clearCache

public static final void clearCache()

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

Since:

1.6

See Also:

clearCache

public static final void clearCache(ClassLoader loader)

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

Parameters:

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

Throws:

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

Since:

1.6

See Also:

handleGetObject

protected abstract Object handleGetObject(String key)

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

Parameters:: key - ключ искомого объекта
Returns:: объект для данного ключа или null
Throws:: NullPointerException - если key null

getKeys

public abstract Enumeration<String> getKeys()

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

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

containsKey

public boolean containsKey(String key)

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

Parameters:: key - ключ ресурса
Returns:: true если данный ключ содержится в этом наборе ресурсов или его родительских наборах; false в противном случае.
Throws:: NullPointerException - если key null
Since:: 1.6

keySet

public Set<String> keySet()

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

Возвращает:: a Set всех ключей, содержащихся в этом ResourceBundle и его родительских пакетах.
С:: 1.6

handleKeySet

protected Set<String> handleKeySet()

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

Реализация по умолчанию возвращает Set ключей, возвращаемых методом getKeys, за исключением тех, для которых метод handleGetObject возвращает null. После создания Set, значение сохраняется в этом ResourceBundle для предотвращения создания тех же Set в последующих вызовах. Подклассы могут переопределить этот метод для более быстрого обращения.

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

© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/ResourceBundle.html