Класс ResourceBundle

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

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

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

    getBundle(baseName, targetLocale, callerModule);

    getBundle(baseName, targetLocale, loader, control);

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

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
 

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

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

Примечание: 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

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

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

1. Этот метод-фабрика ищет набор ресурсов в кэше для указанного baseName, targetLocale и loader. Если запрашиваемый экземпляр набора ресурсов найден в кэше и периоды времени жизни экземпляра и всех его родительских экземпляров не истекли, экземпляр возвращается вызывающему методу. В противном случае, этот метод-фабрика продолжает процесс загрузки, описанный ниже.
2. Вызывается метод control.getFormats для получения форматов набора ресурсов, чтобы создать имена набора или ресурса. Строки "java.class" и "java.properties" обозначают наборы ресурсов на основе классов и на основе свойств соответственно. Другие строки, начинающиеся с "java.", зарезервированы для будущих расширений и не должны использоваться для форматов, определённых приложением. Другие строки обозначают форматы, определённые приложением.
3. Вызывается метод control.getCandidateLocales с целевым языком, чтобы получить список кандидатных Locale, для которых ищутся наборы ресурсов.
4. Вызывается метод control.newBundle для создания экземпляра ResourceBundle для имени базы набора, кандидатного языка и формата. (См. примечание о поиске в кэше ниже). Этот шаг повторяется для всех комбинаций кандидатных языков и форматов, пока метод newBundle не вернёт экземпляр ResourceBundle или все комбинации не будут исчерпаны. Например, если кандидатные языки — Locale("de", "DE"), Locale("de") и Locale(""), а форматы — "java.class" и "java.properties", то последовательность комбинаций язык-формат, используемая для вызова control.newBundle, будет следующей.

   locale-format combinations for newBundle

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

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

Во время процесса загрузки набора ресурсов выше, этот метод-фабрика ищет в кэше перед вызовом метода 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.

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