Класс ResourceBundle

public abstract class ResourceBundle
extends Object

Пакеты ресурсов содержат объекты, специфичные для локали. Когда вашей программе нужен ресурс, специфичный для локали, например 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
       };
    }
}

Ключи всегда являются 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-платформа предоставляет два подкласса 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".

Если модуль-потребитель является поставщиком пакета ресурсов, он не обращается к поиску по пути класса.

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

Общий формат пакетов ресурсов - файл .properties. Обычно пакеты ресурсов .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 для получения подробностей.

Пример