Класс ServiceRegistry

java.lang.Object

javax.imageio.spi.ServiceRegistry

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

public class ServiceRegistry extends Object

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

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

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

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

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

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

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

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

Для получения информации о том, как создавать и развертывать поставщиков сервисов, обратитесь к документации по 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` , содержащий объекты поставщиков сервисов в данной категории, которые удовлетворяют критерию, заданному методом `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, используемые для определения категорий.
Исключения:: IllegalArgumentException - если categories является null, или если одна из категорий не является разрешённым типом сервиса.

Подробности методов

lookupProviders

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

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

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

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

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

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

getCategories

public Iterator<Class<?>> getCategories()

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

Возвращает:: итерируемый объект, содержащий объекты 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)

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

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

getServiceProviders

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

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

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

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

getServiceProviderByClass

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

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

Type Parameters:: T - тип поставщика.
Parameters:: providerClass - Class желаемого объекта поставщика услуг.
Returns:: текущий зарегистрированный объект поставщика услуг с желаемым Class типом или null, если такового нет.
Throws:: IllegalArgumentException - если providerClass является null.

setOrdering

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

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

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

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

unsetOrdering

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

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

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

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

deregisterAll

public void deregisterAll(Class<?> category)

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

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

Overrides:

finalize в классе Object

Throws:

Throwable - если при финализации суперкласса произошла ошибка.

See Also:

© 1993, 2021, 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/17/docs/api/java.desktop/javax/imageio/spi/ServiceRegistry.html