Класс ServiceRegistry

java.lang.Object

javax.imageio.spi.ServiceRegistry

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

public class ServiceRegistry extends Object

Реестр экземпляров поставщиков служб для типов служб Image I/O.

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

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

Попытка загрузить поставщика, не являющегося подтипом одного из указанных выше типов, приведёт к 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)`	Удаляет объект поставщика служб из указанной категории.
`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)`	Задаёт попарный порядок между двумя объектами поставщиков служб в указанной категории.

Методы, объявленные в классе Object

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

Модификатор и тип	Метод	Описание
`protected Object`	`clone()`	Создаёт и возвращает копию этого объекта.
`boolean`	`equals(Object obj)`	Показывает, равен ли этот объект другому объекту.
`protected void`	`finalize()`	Устарело, будет удалено: этот элемент API может быть удалён в будущей версии. Финализация объявлена устаревшей и будет удалена в одном из будущих выпусков.
`final Class<?>`	`getClass()`	Возвращает класс времени выполнения этого `Object`.
`int`	`hashCode()`	Возвращает хеш-код этого объекта.
`final void`	`notify()`	Пробуждает один поток, ожидающий на мониторе этого объекта.
`final void`	`notifyAll()`	Пробуждает все потоки, ожидающие на мониторе этого объекта.
`String`	`toString()`	Возвращает строковое представление объекта.
`final void`	`wait()`	Заставляет текущий поток ожидать пробуждения, обычно в результате уведомления или прерывания.
`final void`	`wait(long timeoutMillis)`	Заставляет текущий поток ожидать пробуждения, обычно в результате уведомления или прерывания, либо до истечения заданного промежутка реального времени.
`final void`	`wait(long timeoutMillis, int nanos)`	Заставляет текущий поток ожидать пробуждения, обычно в результате уведомления или прерывания, либо до истечения заданного промежутка реального времени.

Подробное описание конструкторов

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, этот метод может возвращать разные результаты при каждом вызове.

Параметры типа:: 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)

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

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

Параметры:: provider — объект поставщика служб для регистрации.
Исключения:: IllegalArgumentException — если provider равен null.

registerServiceProviders

public void registerServiceProviders(Iterator<?> providers)

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

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

Параметры:: providers — Iterator, содержащий объекты поставщиков служб для регистрации.
Исключения:: 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()

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

Если приложение создаёт новый экземпляр ServiceRegistry и регистрирует поставщиков, но в какой-то момент он становится больше не нужен, приложению следует вызвать этот метод, чтобы все поставщики, являющиеся экземплярами RegisterableService, получили обратный вызов RegisterableService.onDeregistration(ServiceRegistry, Class<?>) до того, как экземпляр будет собран сборщиком мусора.

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