Класс ServiceRegistry

java.lang.Object
- javax.imageio.spi.ServiceRegistry

Прямые известные подклассы:: IIORegistry

public class ServiceRegistry
extends Object

Регистр для экземпляров поставщиков услуг.

Услуга — это хорошо известный набор интерфейсов и (обычно абстрактных) классов. Поставщик услуг — это конкретная реализация услуги. Классы поставщика обычно реализуют интерфейс или наследуют класс, определённый самой услугой.

Поставщики услуг хранятся в одной или нескольких категориях, каждая из которых определяется классом интерфейса (описанным объектом Class), который должны реализовывать все его члены. Набор категорий может быть изменён динамически.

Может быть зарегистрирован только один экземпляр данного листового класса (то есть фактического класса, возвращаемого getClass(), в отличие от любых наследуемых классов или интерфейсов). То есть, предположим, что класс com.mycompany.mypkg.GreenServiceProvider реализует интерфейс com.mycompany.mypkg.MyService. Если зарегистрирован экземпляр GreenServiceProvider, он будет сохранён в категории, определённой классом MyService. Если зарегистрирован новый экземпляр GreenServiceProvider, он заменит предыдущий экземпляр. На практике объекты поставщиков услуг обычно являются синглтонами, поэтому такое поведение уместно.

Для объявления поставщика услуг подкаталог services размещается внутри каталога META-INF, который присутствует в каждом JAR-файле. Этот каталог содержит файл для каждого интерфейса поставщика услуг, у которого есть один или несколько реализующих классов, присутствующих в JAR-файле. Например, если JAR-файл содержал класс с именем com.mycompany.mypkg.MyServiceImpl, который реализует интерфейс javax.someapi.SomeService, JAR-файл будет содержать файл с именем:

META-INF/services/javax.someapi.SomeService

содержащий строку:

com.mycompany.mypkg.MyService

Классы поставщиков услуг должны быть лёгкими и быстро загружаться. Реализации этих интерфейсов должны избегать сложных зависимостей от других классов и от нативного кода. Обычный шаблон для более сложных услуг — это регистрация лёгкого прокси для тяжёлой услуги.

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

Дополнительные сведения об объявлении поставщиков услуг и формате JAR в целом см. в Спецификации формата JAR-файлов.

См. также:: RegisterableService

Вложенные классы

Модификатор и тип	Класс и описание
`static interface`	`ServiceRegistry.Filter` Простой интерфейс фильтра, используемый `ServiceRegistry.getServiceProviders` для выбора поставщиков, соответствующих произвольному критерию.

Краткое описание конструкторов

Конструктор и описание
`ServiceRegistry(Iterator<Class<?>> categories)` Создаёт экземпляр `ServiceRegistry` с набором категорий, взятых из аргумента `categories`.

Краткое описание методов

Модификатор и тип	Метод и описание
`boolean`	`contains(Object provider)` Возвращает `true`, если `provider` в настоящее время зарегистрирован.
`void`	`deregisterAll()` Отменяет регистрацию всех текущих зарегистрированных поставщиков услуг из всех категорий.
`void`	`deregisterAll(Class<?> category)` Отменяет регистрацию всех объектов поставщиков услуг, которые в настоящее время зарегистрированы в данной категории.
`void`	`deregisterServiceProvider(Object provider)` Удаляет объект поставщика услуг из всех категорий, которые его содержат.
`<T> boolean`	`deregisterServiceProvider(T provider, Class<T> category)` Удаляет объект поставщика услуг из заданной категории.
`void`	`finalize()` Закрывает этот объект перед сборкой мусора.
`Iterator<Class<?>>`	`getCategories()` Возвращает `Iterator` объектов `Class`, указывающих на текущий набор категорий.
`<T> T`	`getServiceProviderByClass(Class<T> providerClass)` Возвращает объект поставщика услуги, который в настоящее время зарегистрирован и имеет данный тип класса.
`<T> Iterator<T>`	`getServiceProviders(Class<T> category, boolean useOrdering)` Возвращает `Iterator`, содержащий всех зарегистрированных поставщиков услуг в данной категории.
`<T> Iterator<T>`	`getServiceProviders(Class<T> category, ServiceRegistry.Filter filter, boolean useOrdering)` Возвращает `Iterator`, содержащий объекты поставщиков услуг в данной категории, которые удовлетворяют критерию, заданному методом `ServiceRegistry.Filter` объекта `filter`.
`static <T> Iterator<T>`	`lookupProviders(Class<T> providerClass)` Выявляет и постепенно создаёт доступных поставщиков данной услуги с использованием контекстного загрузчика классов.
`static <T> Iterator<T>`	`lookupProviders(Class<T> providerClass, ClassLoader loader)` Ищет реализации определённого класса службы, используя указанный загрузчик классов.
`void`	`registerServiceProvider(Object provider)` Добавляет объект поставщика услуг в реестр.
`<T> boolean`	`registerServiceProvider(T provider, Class<T> category)` Добавляет объект поставщика услуг в реестр.
`void`	`registerServiceProviders(Iterator<?> providers)` Добавляет набор объектов поставщиков услуг, взятых из `Iterator` в реестр.
`<T> boolean`	`setOrdering(Class<T> category, T firstProvider, T secondProvider)` Устанавливает парное упорядочение между двумя объектами поставщика услуг в данной категории.
`<T> boolean`	`unsetOrdering(Class<T> category, T firstProvider, T secondProvider)` Устанавливает парное упорядочение между двумя объектами поставщика услуг в данной категории.

Методы, унаследованные от класса java.lang.Object

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

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

ServiceRegistry

public ServiceRegistry(Iterator<Class<?>> categories)

Создаёт экземпляр ServiceRegistry с набором категорий, взятых из аргумента categories.

Параметры:: categories - Iterator содержащий объекты Class, используемые для определения категорий.
Исключения:: IllegalArgumentException - если categories равен null.

Методы

lookupProviders

public static <T> Iterator<T> lookupProviders(Class<T> providerClass,
                                              ClassLoader loader)

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

Этот метод преобразует имя заданного класса службы в имя файла конфигурации провайдера, как описано в комментарии к классу, и затем использует метод getResources заданного загрузчика классов для поиска всех доступных файлов с этим именем. Эти файлы затем читаются и парсятся для получения списка имён классов провайдеров. Итератор, который возвращается, использует заданный загрузчик классов для поиска и создания каждого элемента списка.

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

Параметры типа:: T - тип providerClass.
Параметры:: providerClass - объект Class, указывающий класс или интерфейс служб-поставщиков, которые обнаруживаются.; loader - загрузчик классов, используемый для загрузки файлов конфигурации провайдеров и создания экземпляров классов провайдеров, или null, если необходимо использовать системный загрузчик классов (или, при его отсутствии, загрузчик начальной загрузки).
Возвращает:: Iterator , возвращающий объекты провайдеров для данной службы в произвольном порядке. Итератор выбросит исключение Error, если файл конфигурации провайдера нарушает указанный формат или если класс провайдера не может быть найден и создан.
Исключения:: IllegalArgumentException - если providerClass равен null.

lookupProviders

public static <T> Iterator<T> lookupProviders(Class<T> providerClass)

Находит и поэтапно создаёт экземпляры доступных провайдеров заданной службы, используя контекстный загрузчик классов. Этот удобный метод эквивалентен:

ClassLoader cl = Thread.currentThread().getContextClassLoader();
   return Service.providers(service, cl);

Параметры типа:: T - тип providerClass.
Параметры:: providerClass - объект Class, указывающий класс или интерфейс служб-поставщиков, которые обнаруживаются.
Возвращает:: Iterator, который возвращает объекты провайдеров для данной службы в произвольном порядке. Итератор выбросит исключение Error, если файл конфигурации провайдера нарушает указанный формат или если класс провайдера не может быть найден и создан.
Исключения:: IllegalArgumentException - если providerClass равно null.

getCategories

public Iterator<Class<?>> getCategories()

Возвращает Iterator объектов Class, представляющих текущий набор категорий. Итератор будет пустым, если категории не существуют.

Возвращает:: Iterator , содержащий объекты Class.

registerServiceProvider

public <T> boolean registerServiceProvider(T provider,
                                           Class<T> category)

Добавляет объект провайдера службы в реестр. Провайдер ассоциируется с данной категорией.

Если provider реализует интерфейс RegisterableService, его метод onRegistration будет вызван. Его метод onDeregistration будет вызван каждый раз, когда он отменяется из категории, например, если категория удаляется или реестр собирается мусором.

Параметры типа:: T - тип провайдера.
Параметры:: provider - объект провайдера службы, который необходимо зарегистрировать.; category - категория, в которой необходимо зарегистрировать провайдера.
Возвращает:: true, если ранее в той же категории не был зарегистрирован провайдер того же класса.
Исключения:: IllegalArgumentException - если provider равно null.; IllegalArgumentException - если нет категории, соответствующей category.; ClassCastException - если провайдер не реализует интерфейс Class, определённый category.

registerServiceProvider

public void registerServiceProvider(Object provider)

Добавляет объект провайдера службы в реестр. Провайдер ассоциируется с каждой категорией, присутствующей в реестре, реализующей его интерфейс.

Если provider реализует интерфейс RegisterableService, его метод onRegistration будет вызван для каждой категории, в которой он зарегистрирован. Его метод onDeregistration будет вызван каждый раз, когда он будет отменён из категории или когда реестр завершит работу.

Параметры:: provider - объект провайдера службы, который необходимо зарегистрировать.
Исключения:: IllegalArgumentException - если provider равно null.

registerServiceProviders

public void registerServiceProviders(Iterator<?> providers)

Добавляет набор объектов провайдеров службы, взятых из Iterator, в реестр. Каждый провайдер ассоциируется с каждой категорией, присутствующей в реестре, реализующей его интерфейс.

Для каждого элемента providers, реализующего интерфейс RegisterableService, его метод onRegistration будет вызван один раз для каждой категории, в которой он зарегистрирован. Его метод onDeregistration будет вызван каждый раз, когда он будет отменён из категории или когда реестр завершит работу.

Параметры:: providers - итератор, содержащий объекты провайдеров службы, которые необходимо зарегистрировать.
Исключения:: IllegalArgumentException - если providers равно null или содержит запись null.

deregisterServiceProvider

public <T> boolean deregisterServiceProvider(T provider,
                                             Class<T> category)

Удаляет объект провайдера службы из заданной категории. Если провайдер ранее не был зарегистрирован, ничего не происходит, и возвращается false. В противном случае возвращается true. Если зарегистрирован объект того же класса, что и provider, но не равный ему (используя ==) provider, он не будет удалён.

Если provider реализует интерфейс RegisterableService, его метод onDeregistration будет вызван.

Параметры типа:: T - тип провайдера.
Параметры:: provider - объект провайдера службы, который необходимо удалить.; category - категория, из которой необходимо удалить провайдера.
Возвращает:: true , если провайдер был ранее зарегистрирован в той же категории; false в противном случае.
Исключения:: IllegalArgumentException - если provider равно null.; IllegalArgumentException - если нет категории, соответствующей category.; ClassCastException - если провайдер не реализует класс, определённый category.

deregisterServiceProvider

public void deregisterServiceProvider(Object provider)

Удаляет объект провайдера службы из всех категорий, в которых он содержится.

Параметры:: provider - объект провайдера службы, который необходимо удалить.
Исключения:: IllegalArgumentException - если provider равно null.

contains

public boolean contains(Object provider)

Возвращает true, если provider в настоящее время зарегистрирован.

Параметры:: provider - объект провайдера службы, который необходимо проверить.
Возвращает:: true , если данный провайдер зарегистрирован.
Исключения:: IllegalArgumentException - если provider равно null.

getServiceProviders

public <T> Iterator<T> getServiceProviders(Class<T> category,
                                           boolean useOrdering)

Возвращает Iterator , содержащий все зарегистрированные провайдеры служб в заданной категории. Если useOrdering равно false, итератор вернёт все объекты провайдера сервера в произвольном порядке. В противном случае порядок будет соответствовать установленным парным упорядочиваниям. Если граф парных упорядочений содержит циклы, провайдеры, относящиеся к циклу, не будут возвращены.

Параметры типа:: T - тип категории.
Параметры:: category - категория, из которой необходимо извлечь данные.; useOrdering - true , если при упорядочивании возвращаемых объектов необходимо учитывать парные упорядочивания.
Возвращает:: Iterator , содержащий объекты провайдера службы из заданной категории, возможно, в порядке.
Исключения:: IllegalArgumentException - если нет категории, соответствующей category.

getServiceProviders

public <T> Iterator<T> getServiceProviders(Class<T> category,
                                           ServiceRegistry.Filter filter,
                                           boolean useOrdering)

Возвращает Iterator , содержащий объекты провайдера службы в заданной категории, удовлетворяющие критерию, наложенному методом filter объекта ServiceRegistry.Filter.

Аргумент useOrdering управляет упорядочиванием результатов по тем же правилам, что и getServiceProviders(Class, boolean).

Параметры типа:: T - тип категории.
Параметры:: category - категория, из которой необходимо извлечь данные.; filter - экземпляр ServiceRegistry.Filter, чей метод filter будет вызван.; useOrdering - true , если при упорядочивании возвращаемых объектов необходимо учитывать парные упорядочивания.
Возвращает:: Iterator , содержащий объекты провайдера службы из заданной категории, возможно, в порядке.
Исключения:: IllegalArgumentException - если нет категории, соответствующей category.

getServiceProviderByClass

public <T> T getServiceProviderByClass(Class<T> providerClass)

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

Тип параметров:: T - тип поставщика.
Параметры:: providerClass - Class объекта желаемого объекта поставщика услуг.
Возвращает:: объект текущего зарегистрированного поставщика услуг с желаемым Classтипом или null, если такого объекта нет.
Выбрасывает:: IllegalArgumentException - если providerClass равен null.

setOrdering

public <T> boolean setOrdering(Class<T> category,
                               T firstProvider,
                               T secondProvider)

Устанавливает парное упорядочение между двумя объектами поставщика услуг в заданной категории. Если один или оба объекта не зарегистрированы в данной категории, или если желаемое упорядочение уже установлено, ничего не происходит, и возвращается false. Если поставщики ранее были упорядочены в обратном порядке, это упорядочение удаляется.

Упорядочение будет использоваться методами getServiceProviders при значении аргумента useOrdering равном true.

Тип параметров:: T - тип категории.
Параметры:: category - объект Class, указывающий категорию, в которой необходимо установить предпочтение.; firstProvider - предпочтительный поставщик.; secondProvider - поставщик, которому firstProvider предпочтительнее.
Возвращает:: true , если ранее не установленное упорядочение было установлено.
Выбрасывает:: IllegalArgumentException - если любой из поставщиков null или они являются одним и тем же объектом.; IllegalArgumentException - если нет категории, соответствующей category.

unsetOrdering

public <T> boolean unsetOrdering(Class<T> category,
                                 T firstProvider,
                                 T secondProvider)

Устанавливает парное упорядочение между двумя объектами поставщика услуг в заданной категории. Если один или оба объекта не зарегистрированы в данной категории, или если между ними не установлено никакого упорядочения, ничего не происходит, и возвращается false.

Упорядочение будет использоваться методами getServiceProviders при значении аргумента useOrdering равном true.

Тип параметров:: T - тип категории.
Параметры:: category - объект Class, указывающий категорию, в которой необходимо отменить предпочтение.; firstProvider - ранее предпочтительный поставщик.; secondProvider - поставщик, которому firstProvider был ранее предпочтительнее.
Возвращает:: true , если ранее установленное упорядочение было отменено.
Выбрасывает:: IllegalArgumentException - если любой из поставщиков null или они являются одним и тем же объектом.; IllegalArgumentException - если нет категории, соответствующей category.

deregisterAll

public void deregisterAll(Class<?> category)

Удаляет всех зарегистрированных объектов поставщиков услуг, зарегистрированных в данной категории.

Параметры:: category - категория, которую необходимо очистить.
Выбрасывает:: IllegalArgumentException - если нет категории, соответствующей category.

deregisterAll

public void deregisterAll()

Удаляет все зарегистрированные поставщики услуг из всех категорий.

finalize

public void finalize()
              throws Throwable

Завершает работу этого объекта перед сборкой мусора. Метод deregisterAll вызывается для удаления всех зарегистрированных поставщиков услуг. Этот метод не должен вызываться из кода приложения.

Переопределяет:: finalize в классе Object
Выбрасывает:: Throwable - если произошла ошибка во время завершения работы суперкласса.
См. также:: WeakReference, PhantomReference

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