Класс 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 — "ОК" и "Отмена", — но это необязательно. Значениями могут быть объекты любого типа.

Объект извлекается из пакета ресурсов с помощью соответствующего метода получения. Поскольку "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".

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

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

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

Распространённый формат пакетов ресурсов — формат файлов .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 при переходе на модули. При вызове фабричного метода, принимающего параметр ResourceBundle.Control, будет выброшено исключение UnsupportedOperationException.

Для фабричных методов 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)`	Устанавливает родительский пакет ресурсов для этого пакета.

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

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

Модификатор и тип	Метод	Описание
`protected Object`	`clone()`	Создаёт и возвращает копию этого объекта.
`boolean`	`equals(Object obj)`	Указывает, равен ли этот объект какому-либо другому объекту.
`protected void`	`finalize()`	Устарело, будет удалено: этот элемент API может быть удалён в будущей версии. Финализация объявлена устаревшей и будет удалена в одном из будущих выпусков.
`final Class<?>`	`getClass()`	Возвращает класс времени выполнения этого `Object`.
`int`	`hashCode()`	Возвращает хеш-код этого объекта.
`final void`	`notify()`	Пробуждает один поток, ожидающий на мониторе этого объекта.
`final void`	`notifyAll()`	Пробуждает все потоки, ожидающие на мониторе этого объекта.
`String`	`toString()`	Возвращает строковое представление объекта.
`final void`	`wait()`	Приостанавливает текущий поток до пробуждения, обычно в результате вызова notify или interrupt.
`final void`	`wait(long timeoutMillis)`	Приостанавливает текущий поток до пробуждения, обычно в результате вызова notify или interrupt, либо до истечения заданного промежутка реального времени.
`final void`	`wait(long timeoutMillis, int nanos)`	Приостанавливает текущий поток до пробуждения, обычно в результате вызова notify или interrupt, либо до истечения заданного промежутка реального времени.

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

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. Полное описание процесса загрузки пакета ресурсов с помощью ResourceBundle.Control см. в разделе getBundle.

Параметры:: 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

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

С версии:

См. также:

getBundle

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

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

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

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

Параметры:

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

targetLocale — локаль, для которой требуется пакет ресурсов

module — модуль, в котором выполняется поиск пакета ресурсов

Возвращает:

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

Вызывает исключение:

NullPointerException — если baseName, targetLocale или module равно null

MissingResourceException — если пакет ресурсов с заданными базовым именем и локалью не найден в указанном module

С версии:

См. также:

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 выполняется по мере необходимости.; UnsupportedOperationException — если этот метод вызван в именованном модуле
С версии:: 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, если только экземпляр Control не предоставлен SPI ResourceBundleControlProvider. См. описание изменения поведения по умолчанию. Далее описано поведение по умолчанию.

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

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_WIN11" и базовым именем пакета "MyResource" будет создан следующий список кандидатных имён пакетов ресурсов:

MyResource_en_Latn_US_WINDOWS_WIN11
MyResource_en_Latn_US_WINDOWS
MyResource_en_Latn_US
MyResource_en_Latn
MyResource_en_US_WINDOWS_WIN11
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, которому передаётся новый пакет ресурсов. Это продолжается до исчерпания списка имён или до тех пор, пока у текущего пакета уже есть ненулевой родительский пакет.

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

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

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

Пример:

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

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

Содержимое всех файлов корректно (то есть файлы ".class" содержат открытые неабстрактные подклассы ResourceBundle, а файлы ".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:

Если вызывающий код находится в именованном модуле, а заданный 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 вызывается с целевой локалью, чтобы получить список кандидатных локалей Locale, в которых выполняется поиск пакетов ресурсов.

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

сочетания локалей и форматов для 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, чтобы получить резервную локаль (альтернативу текущей целевой локали) для дальнейшего поиска пакета ресурсов. Если метод возвращает локаль, отличную от null, она становится следующей целевой локалью, и процесс загрузки начинается заново с этапа 3. В противном случае, если на предыдущем этапе 5 был найден и отложен базовый пакет, теперь он возвращается вызывающему коду. Если же базовый пакет не был найден, выбрасывается MissingResourceException.
На этом этапе найден пакет ресурсов, не являющийся базовым. Если при создании экземпляра этому пакету был задан родительский пакет, он возвращается вызывающему коду. В противном случае его цепочка родительских пакетов создаётся на основе списка кандидатных локалей, в котором он был найден. Затем пакет возвращается вызывающему коду.

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

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

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

Условия:

Базовое имя пакета: foo.bar.Messages
Запрошенная Locale: Locale.ITALY
Локаль по умолчанию Locale: 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.

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

clearCache

public static final void clearCache()

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

Начиная с:

1.6

См. также:

clearCache

public static final void clearCache(ClassLoader loader)

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

Параметры:

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

Выбрасывает:

NullPointerException — если loader имеет значение null

Начиная с:

1.6

См. также:

handleGetObject

protected abstract Object handleGetObject(String key)

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

Параметры:: key — ключ требуемого объекта
Возвращает:: объект для заданного ключа или null
Выбрасывает:: NullPointerException — если key имеет значение null

getKeys

public abstract Enumeration<String> getKeys()

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

Возвращает:: Enumeration ключей, содержащихся в этом 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 и его родительских пакетах.

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

handleKeySet

protected Set<String> handleKeySet()

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

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

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

© 1993, 2025, 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.