Класс 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()`	Устарело, для удаления: Этот элемент API может быть удален в будущей версии. Финализация устарела для удаления.
`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)

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

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

Получить поставщиков услуг

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

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

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

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

Получить поставщика услуг по классу

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

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

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

Установить порядок

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

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

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

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

Снять порядок

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

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

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

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

Дезарегистрировать все

public void deregisterAll(Class<?> category)

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

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

Дезарегистрировать все

public void deregisterAll()

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

finalize

@Deprecated(since="9", forRemoval=true) public void finalize() throws Throwable

Устарело, для удаления: Этот элемент API может быть удален в будущей версии.

Финализация устарела для удаления. См. Object.finalize() для получения дополнительной информации и деталей по вариантам миграции.

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

Переопределяет:

finalize в классе Object

Исключения:

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

См. также:

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