Класс ServiceRegistry

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

Регистр для экземпляров поставщиков услуг для типов сервисов ввода-вывода изображений.

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

Набор поддерживаемых этим классом категорий ограничен следующими стандартными типами сервисов ввода-вывода изображений:

Попытка загрузить поставщика, который не является подтипом одного из указанных типов, приведет к IllegalArgumentException.

Для общего механизма загрузки поставщиков услуг см. ServiceLoader, который является базовым стандартным механизмом, используемым этим классом.

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

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

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

Для получения информации о том, как создавать и развертывать поставщиков услуг, см. документацию по ServiceLoader

См. также:
RegisterableService, ServiceLoader

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

Модификатор и тип Класс Описание
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()

Устарело.

Метод 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, содержащий объекты поставщиков услуг в заданной категории, которые удовлетворяют критерию, заданному методом filter объекта ServiceRegistry.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)

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

Класс службы должен быть одним из типов служб, перечисленных в спецификации класса. Если это не так, будет выброшено исключение IllegalArgumentException.

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

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

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

lookupProviders

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

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

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

Класс службы должен быть одним из типов служб, перечисленных в спецификации класса. Если это не так, будет выброшено исключение IllegalArgumentException.

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

getCategories

public Iterator<Class<?>> getCategories()

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

Returns:
итератор, содержащий объекты Class.

registerServiceProvider

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

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

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

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

registerServiceProvider

public void registerServiceProvider(Object provider)

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

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

Parameters:
provider - объект поставщика услуг, который должен быть зарегистрирован.
Throws:
IllegalArgumentException - если provider имеет значение null.

registerServiceProviders

public void registerServiceProviders(Iterator<?> providers)

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

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

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

deregisterServiceProvider

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

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

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

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

deregisterServiceProvider

public void deregisterServiceProvider(Object provider)

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

Parameters:
provider - объект поставщика услуг, который должен быть удален.
Throws:
IllegalArgumentException - если provider имеет значение null.

contains

public boolean contains(Object provider)

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

Parameters:
provider - объект поставщика услуг, который нужно проверить.
Returns:
true , если заданный поставщик был зарегистрирован.
Throws:
IllegalArgumentException - если provider имеет значение null.

getServiceProviders

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

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

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

getServiceProviders

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

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

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

Type Parameters:
T - тип категории.
Parameters:
category - категория, которая должна быть получена.
filter - экземпляр ServiceRegistry.Filter, чей метод filter будет вызван.
useOrdering - true , если при упорядочении возвращаемых объектов следует учитывать парные упорядочения.
Returns:
итератор, содержащий объекты поставщиков услуг из заданной категории, возможно, в порядке.
Throws:
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

@Deprecated(since="9")
public void finalize()
              throws Throwable
Устарело.
Метод finalize устарел. Подклассы, которые переопределяют finalize для выполнения очистки, должны быть изменены, чтобы использовать альтернативные механизмы очистки и удалить переопределённый метод finalize. При переопределении метода finalize, его реализация должна явно гарантировать вызов super.finalize() как описано в Object.finalize(). См. спецификацию для Object.finalize() для получения дополнительной информации о вариантах миграции.

Завершает работу этого объекта перед сборкой мусора. Метод 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.
https://docs.oracle.com/en/java/javase/11/docs/api/java.desktop/javax/imageio/spi/ServiceRegistry.html

Spec-Zone .ru
спецификации, руководства, описания, API