Класс ResourceBundle.Control

ResourceBundle.Control определяет набор методов обратного вызова, которые вызываются методом ResourceBundle.getBundle во время процесса загрузки ресурсов. Другими словами, ResourceBundle.Control взаимодействует с фабричными методами для загрузки ресурсов. По умолчанию методы обратного вызова предоставляют информацию, необходимую фабричным методам для выполнения стандартного поведения.

Помимо методов обратного вызова, методы toBundleName и toResourceName определены в первую очередь для удобства реализации методов обратного вызова. Однако, метод toBundleName можно переопределить, чтобы использовать различные соглашения об организации и упаковке локализованных ресурсов. Метод toResourceName final для избежания использования неправильных разделителей имен ресурсов и классов.

Два фабричных метода, getControl(List) и getNoFallbackControl(List), предоставляют ResourceBundle.Control экземпляры, реализующие общие варианты стандартного процесса загрузки ресурсов.

Форматы, возвращаемые методом getFormats, и кандидаты на локаль, возвращаемые методом getCandidateLocales, должны быть согласованы во всех ResourceBundle.getBundle вызовах для одного и того же базового ресурса. В противном случае, методы ResourceBundle.getBundle могут вернуть нежелаемые ресурсы. Например, если только "java.class" возвращается методом getFormats для первого вызова ResourceBundle.getBundle и только "java.properties" для второго вызова, то второй вызов вернёт кешированный результат, полученный во время первого вызова.

Экземпляр ResourceBundle.Control должен быть потокобезопасным, если используется одновременно несколькими потоками. ResourceBundle.getBundle не синхронизируется для вызовов методов ResourceBundle.Control. Стандартные реализации методов потокобезопасны.

Приложения могут указать ResourceBundle.Control экземпляры, возвращаемые фабричными методами getControl или созданные из подкласса ResourceBundle.Control, для настройки процесса загрузки ресурсов. Ниже приведены примеры изменения стандартного процесса загрузки ресурсов.

Пример 1

Следующий код позволяет ResourceBundle.getBundle искать только ресурсы в формате properties.

import java.util.*;
 import static java.util.ResourceBundle.Control.*;
 ...
 ResourceBundle bundle =
   ResourceBundle.getBundle("MyResources", new Locale("fr", "CH"),
                            ResourceBundle.Control.getControl(FORMAT_PROPERTIES));

Пример 2

Следующий пример демонстрирует загрузку ресурсов в формате XML с помощью Properties.loadFromXML.

ResourceBundle rb = ResourceBundle.getBundle("Messages",
     new ResourceBundle.Control() {
         public List<String> getFormats(String baseName) {
             if (baseName == null)
                 throw new NullPointerException();
             return Arrays.asList("xml");
         }
         public ResourceBundle newBundle(String baseName,
                                         Locale locale,
                                         String format,
                                         ClassLoader loader,
                                         boolean reload)
                          throws IllegalAccessException,
                                 InstantiationException,
                                 IOException {
             if (baseName == null || locale == null
                   || format == null || loader == null)
                 throw new NullPointerException();
             ResourceBundle bundle = null;
             if (format.equals("xml")) {
                 String bundleName = toBundleName(baseName, locale);
                 String resourceName = toResourceName(bundleName, format);
                 InputStream stream = null;
                 if (reload) {
                     URL url = loader.getResource(resourceName);
                     if (url != null) {
                         URLConnection connection = url.openConnection();
                         if (connection != null) {
                             // Disable caches to get fresh data for
                             // reloading.
                             connection.setUseCaches(false);
                             stream = connection.getInputStream();
                         }
                     }
                 } else {
                     stream = loader.getResourceAsStream(resourceName);
                 }
                 if (stream != null) {
                     BufferedInputStream bis = new BufferedInputStream(stream);
                     bundle = new XMLResourceBundle(bis);
                     bis.close();
                 }
             }
             return bundle;
         }
     });

 ...

 private static class XMLResourceBundle extends ResourceBundle {
     private Properties props;
     XMLResourceBundle(InputStream stream) throws IOException {
         props = new Properties();
         props.loadFromXML(stream);
     }
     protected Object handleGetObject(String key) {
         return props.getProperty(key);
     }
     public Enumeration<String> getKeys() {
         ...
     }
 }

Поля

FORMAT_DEFAULT

public static final List<String> FORMAT_DEFAULT

Формат по умолчанию List, который содержит строки "java.class" и "java.properties", в этом порядке. Этот List является неизменяемым.

См. также:

getFormats(String)

FORMAT_CLASS

public static final List<String> FORMAT_CLASS

Формат только для классов List, содержащий "java.class". Этот List является неизменяемым.

См. также:

getFormats(String)

FORMAT_PROPERTIES

public static final List<String> FORMAT_PROPERTIES

Формат только для свойств List, содержащий "java.properties". Этот List является неизменяемым.

См. также:

getFormats(String)

TTL_DONT_CACHE

public static final long TTL_DONT_CACHE

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

См. также:

getTimeToLive(String, Locale), Значения постоянных полей

TTL_NO_EXPIRATION_CONTROL

public static final long TTL_NO_EXPIRATION_CONTROL

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

См. также:

getTimeToLive(String, Locale), Значения постоянных полей

Конструкторы

Control

protected Control()

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

Методы

getControl

public static final ResourceBundle.Control getControl(List<String> formats)

Параметры:

formats - форматы, которые должны возвращаться методом ResourceBundle.Control.getFormats

Возвращает:

ResourceBundle.Control поддерживающий указанные formats

Исключения:

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

IllegalArgumentException - если formats неизвестен

getNoFallbackControl

public static final ResourceBundle.Control getNoFallbackControl(List<String> formats)

Возвращает ResourceBundle.Control, в котором метод getFormats возвращает указанные formats, а метод getFallbackLocale возвращает null. formats должен быть равен одному из FORMAT_PROPERTIES, FORMAT_CLASS или FORMAT_DEFAULT. ResourceBundle.Control экземпляры, возвращаемые этим методом, являются одиночными и потокобезопасными.

Параметры:

formats - форматы, которые должны возвращаться методом ResourceBundle.Control.getFormats

Возвращает:

ResourceBundle.Control поддерживающий указанные formats без поддержки обратного вызова Locale

Исключения:

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

IllegalArgumentException - если formats неизвестен

getFormats

public List<String> getFormats(String baseName)

Параметры:

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

Возвращает:

List String содержащий форматы для загрузки ресурсных пакетов.

Исключения:

NullPointerException - если baseName null

См. также:

FORMAT_DEFAULT, FORMAT_CLASS, FORMAT_PROPERTIES

getCandidateLocales

public List<Locale> getCandidateLocales(String baseName,
                                        Locale locale)

Messages_ja -> Messages

Параметры:

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

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

Возвращает:

List кандидатских Locale для данной locale

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

NullPointerException - если baseName или locale - null

getFallbackLocale

public Locale getFallbackLocale(String baseName,
                                Locale locale)

Параметры:

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

locale - Locale, для которого ResourceBundle.getBundle не смог найти пакеты ресурсов (кроме базового)

Возвращает:

Locale для поиска по умолчанию или null, если дальнейший поиск по умолчанию не требуется.

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

NullPointerException - если baseName или locale - null

newBundle

public ResourceBundle newBundle(String baseName,
                                Locale locale,
                                String format,
                                ClassLoader loader,
                                boolean reload)
                         throws IllegalAccessException,
                                InstantiationException,
                                IOException

Параметры:

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

locale - регион, для которого должен быть инициализирован пакет ресурсов

format - формат пакета ресурсов для загрузки

loader - ClassLoader для загрузки пакета

reload - флаг, указывающий на перезагрузку пакета; true при перезагрузке истекшего пакета ресурсов, false в противном случае

Возвращает:

экземпляр пакета ресурсов или null , если ни один не был найден.

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

NullPointerException - если bundleName, locale, format, или loader имеет значение null, или если null возвращается методом toBundleName

IllegalArgumentException - если format неизвестен или если найденный ресурс для заданных параметров содержит некорректные данные.

ClassCastException - если загруженный класс не может быть преобразован в ResourceBundle

IllegalAccessException - если класс или его конструктор без параметров недоступен.

InstantiationException - если инициализация класса завершается неудачно по другой причине.

ExceptionInInitializerError - если инициализация, вызванная этим методом, завершается неудачно.

SecurityException - Если менеджер безопасности присутствует, и создание новых экземпляров запрещено. См. Class.newInstance() для подробностей.

IOException - если произошла ошибка при чтении ресурсов с использованием операций ввода/вывода

Срок действия

public long getTimeToLive(String baseName,
                          Locale locale)

Параметры:

baseName - базовое имя пакета ресурсов, для которого задаётся значение истечения срока действия.

locale - регион пакета ресурсов, для которого задаётся значение истечения срока действия.

Возвращает:

время (0 или положительный временной сдвиг в миллисекундах от кэшированного времени) для истечения срока действия загруженных пакетов в кэше, TTL_NO_EXPIRATION_CONTROL для отключения контроля истечения срока действия или TTL_DONT_CACHE для отключения кэширования.

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

NullPointerException - если baseName или locale имеет значение null

необходима перезагрузка

public boolean needsReload(String baseName,
                           Locale locale,
                           String format,
                           ClassLoader loader,
                           ResourceBundle bundle,
                           long loadTime)

Параметры:

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

locale - регион, для которого должен быть инициализирован пакет ресурсов

format - формат пакета ресурсов для загрузки

loader - ClassLoader для загрузки пакета

bundle - экземпляр пакета ресурсов, который истек в кэше

loadTime - время загрузки bundle и помещения в кэш

Возвращает:

true , если истекший пакет необходимо перезагрузить; false в противном случае.

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

NullPointerException - если baseName, locale, format, loader, или bundle имеет значение null

toBundleName

public String toBundleName(String baseName,
                           Locale locale)

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

Параметры:

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

locale - регион, для которого должен быть загружен пакет ресурсов

Возвращает:

имя пакета для пакета ресурсов

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

NullPointerException - если baseName или locale имеет значение null

toResourceName

public final String toResourceName(String bundleName,
                                   String suffix)

Преобразует заданный bundleName в форму, требуемую методом ClassLoader.getResource, заменяя все вхождения '.' в bundleName на '/' и добавляя '.' и заданный файл suffix. Например, если bundleName равно "foo.bar.MyResources_ja_JP" и suffix равно "properties", то возвращается "foo/bar/MyResources_ja_JP.properties".

Параметры:

bundleName - имя пакета

suffix - суффикс типа файла

Возвращает:

имя преобразованного ресурса

Исключения:

NullPointerException - если bundleName или suffix равно null