Класс 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 может содержать "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".

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

Если фабричный метод 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 предназначен для приложений, развернутых в безымянном модуле, например для поддержки пакетов ресурсов в нестандартных форматах или упаковки локализованных ресурсов по нетрадиционным правилам. При переходе на модули вместо ResourceBundle.Control следует использовать ResourceBundleProvider. При вызове фабричного метода, принимающего параметр 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)`	Возвращает пакет ресурсов по заданным базовому имени, целевой локали, загрузчику классов и объекту управления.
`static ResourceBundle`	`getBundle(String baseName, Locale targetLocale, Module module)`	Получает пакет ресурсов по заданным базовому имени и локали от имени указанного модуля.
`static final ResourceBundle`	`getBundle(String baseName, Locale targetLocale, ResourceBundle.Control control)`	Возвращает пакет ресурсов по заданным базовому имени, целевой локали и объекту управления, используя загрузчик классов вызывающего кода.
`static final ResourceBundle`	`getBundle(String baseName, ResourceBundle.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

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

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_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

Содержимое всех файлов корректно (то есть файлы ".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.
https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/ResourceBundle.html