Класс ServiceLoader<S>

public final class ServiceLoader<S> extends Object implements Iterable<S>

Утилита для загрузки реализаций службы.

Служба — это известный интерфейс или класс, для которого существуют ноль, одна или несколько служб-поставщиков. Служба-поставщик (или просто поставщик) — это класс, реализующий или наследующий известный интерфейс или класс. Загрузчик служб — это объект, который находит и загружает службы-поставщики, развернутые в среде выполнения в момент, выбранный приложением. Код приложения ссылается только на службу, а не на службы-поставщики, и предполагается, что он способен выбирать между несколькими службами-поставщиками (на основе функций, которые они предоставляют через службу) и обрабатывать возможность того, что службы-поставщики не найдены.

Получение загрузчика служб

Приложение получает загрузчик служб для данной службы, вызвав один из статических методов load класса ServiceLoader. Если приложение является модулем, то его декларация модуля должна содержать директиву uses, которая указывает службу; это помогает найти поставщиков и гарантирует их надёжную работу. Кроме того, если модуль приложения не содержит службу, то его декларация модуля должна содержать директиву requires, которая указывает модуль, экспортирующий службу. Сильно рекомендуется, чтобы модуль приложения не требовал модулей, содержащих поставщиков службы.

Загрузчик служб может быть использован для поиска и создания экземпляров поставщиков службы с помощью метода iterator. ServiceLoader также определяет метод stream для получения потока поставщиков, который можно просмотреть и отфильтровать без создания экземпляров.

Например, предположим, что служба — это com.example.CodecFactory, интерфейс, который определяет методы для создания кодеров и декодеров:

     package com.example;
     public interface CodecFactory {
         Encoder getEncoder(String encodingName);
         Decoder getDecoder(String encodingName);
     }
 

Следующий код получает загрузчик служб для службы CodecFactory, а затем использует его итератор (созданный автоматически усовершенствованным циклом for) для вывода экземпляров служб-поставщиков, которые находятся:

     ServiceLoader<CodecFactory> loader = ServiceLoader.load(CodecFactory.class);
     for (CodecFactory factory : loader) {
         Encoder enc = factory.getEncoder("PNG");
         if (enc != null)
             ... use enc to encode a PNG file
             break;
         }
 

Если этот код находится в модуле, то для ссылки на интерфейс com.example.CodecFactory модуль должен потребовать модуль, который экспортирует этот интерфейс. Декларация модуля также должна указывать использование com.example.CodecFactory:

     requires com.example.codec.core;
     uses com.example.CodecFactory;
 

Иногда приложение может захотеть просмотреть службу-поставщика перед созданием экземпляра, чтобы определить, будет ли экземпляр этой службы-поставщика полезным. Например, служба-поставщик для CodecFactory которая способна создавать кодер "PNG", может быть аннотирована с помощью @PNG. Следующий код использует метод stream загрузчика служб для вывода экземпляров Provider<CodecFactory> в отличие от того, как итератор выводит экземпляры CodecFactory:

     ServiceLoader<CodecFactory> loader = ServiceLoader.load(CodecFactory.class);
     Set<CodecFactory> pngFactories = loader
            .stream()                                              // Note a below
            .filter(p -> p.type().isAnnotationPresent(PNG.class))  // Note b
            .map(Provider::get)                                    // Note c
            .collect(Collectors.toSet());
 

1. Поток объектов Provider<CodecFactory>
2. p.type() возвращает Class<CodecFactory>
3. get() возвращает экземпляр CodecFactory

Разработка служб

Служба — это единственный тип, обычно интерфейс или абстрактный класс. Может быть использован конкретный класс, но это не рекомендуется. Тип может иметь любую доступность. Методы службы сильно зависят от области, поэтому это спецификация API не может дать конкретные рекомендации по их форме или функции. Однако есть два общих руководства:

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

2. Служба должна указывать, предназначены ли её службы-поставщики для прямой реализации службы или для механизма косвенности, такого как "прокси" или "фабрика". Службы-поставщики часто являются механизмами косвенности, когда объекты в конкретной области относительно дорого создавать; в этом случае служба должна быть разработана таким образом, чтобы службы-поставщики были абстракциями, создающими "реальную" реализацию по требованию. Например, служба CodecFactory выражает через своё имя, что её службы-поставщики являются фабриками для кодеков, а не кодеками сами по себе, потому что создание определённых кодеков может быть дорогим или сложным.

Разработка служб-поставщиков

Служба-поставщик — это единственный тип, обычно конкретный класс. Разрешается интерфейс или абстрактный класс, так как он может объявлять статический метод поставщика, который обсуждается позже. Тип должен быть публичным и не должен быть вложенным классом.

Служба-поставщик и её вспомогательный код могут быть разработаны в модуле, который затем развертывается на пути модуля приложения или в модульной образе. В качестве альтернативы, служба-поставщик и её вспомогательный код могут быть упакованы в файл JAR и развернуты на пути класса приложения. Преимущество разработки службы-поставщика в модуле заключается в том, что поставщик может быть полностью инкапсулирован, чтобы скрыть все детали его реализации.

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

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

Служба-поставщик, разработанная в модуле, должна быть указана в директиве provides в декларации модуля. Директива provides указывает как службу, так и службу-поставщика; это помогает найти поставщика, когда другой модуль с директивой uses для службы получает загрузчик служб для этой службы. Сильно рекомендуется, чтобы модуль не экспортировал пакет, содержащий службу-поставщика. Нет поддержки для модуля, указывающего в директиве provides службу-поставщика в другом модуле.

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

• Если служба-поставщик объявляет метод поставщика, то загрузчик служб вызывает этот метод для получения экземпляра службы-поставщика. Метод поставщика — это публичный статический метод с именем "provider" без формальных параметров и типом возвращаемого значения, приводимым к интерфейсу или классу службы.

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

• Если служба-поставщик не объявляет метод поставщика, то служба-поставщик создаётся напрямую через её конструктор поставщика. Конструктор поставщика — это публичный конструктор без формальных параметров.

  В этом случае служба-поставщик должна быть приводимой к интерфейсу или классу службы.

Служба-поставщик, развернутая как автоматический модуль на пути модуля приложения, должна иметь конструктор поставщика. Нет поддержки для метода поставщика в этом случае.

Например, предположим, что модуль указывает следующую директиву:

     provides com.example.CodecFactory with com.example.impl.StandardCodecs,
              com.example.impl.ExtendedCodecsFactory;
 

где

• com.example.CodecFactory — это служба из двух методов, упомянутая ранее.
• com.example.impl.StandardCodecs — это публичный класс, реализующий CodecFactory и имеющий публичный конструктор без аргументов.
• com.example.impl.ExtendedCodecsFactory — это публичный класс, не реализующий CodecFactory, но он объявляет публичный статический метод без аргументов с именем "provider" и типом возвращаемого значения CodecFactory.

Загрузчик служб создаст экземпляр StandardCodecs через его конструктор и создаст экземпляр ExtendedCodecsFactory, вызвав его метод provider. Требование о том, что конструктор поставщика или метод поставщика является публичным, помогает документировать намерение о том, что класс (то есть служба-поставщик) будет создан сущностью (то есть загрузчиком служб), которая находится вне пакета класса.

Развёртывание служб-поставщиков на пути класса

Служба-поставщик, упакованная в файл JAR для пути класса, определяется путём размещения файла конфигурации поставщика в каталоге ресурсов META-INF/services. Имя файла конфигурации поставщика — полностью квалифицированное двоичное имя службы. Файл конфигурации поставщика содержит список полностью квалифицированных двоичных имён служб-поставщиков, по одному на строке.

Например, предположим, что служба-поставщик com.example.impl.StandardCodecs упакована в файл JAR для пути класса. Файл JAR будет содержать файл конфигурации поставщика с именем:

META-INF/services/com.example.CodecFactory

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

com.example.impl.StandardCodecs # Standard codecs

Файл конфигурации поставщика должен быть закодирован в UTF-8. Пробелы и символы табуляции вокруг имени каждой службы-поставщика, а также пустые строки игнорируются. Символ комментария — '#' (U+0023 ДИЕЗ); на каждой строке все символы после первого символа комментария игнорируются. Если имя класса службы-поставщика указано в файле конфигурации поставщика более одного раза, дубликат игнорируется. Если класс службы-поставщика указан в нескольких файлах конфигурации, дубликат игнорируется.

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

Время обнаружения поставщиков

Службы-поставщики загружаются и создаются лениво, то есть по требованию. Загрузчик служб сохраняет кэш загруженных поставщиков. Каждый вызов метода iterator возвращает итератор, который сначала возвращает все элементы, кэшированные из предыдущей итерации, в порядке создания экземпляров, а затем лениво находит и создаёт все оставшиеся поставщики, добавляя каждый из них в кэш по очереди. Аналогично, каждый вызов метода stream возвращает поток, который сначала обрабатывает все поставщики, загруженные предыдущими операциями потока, в порядке загрузки, а затем лениво находит все оставшиеся поставщики. Кэши очищаются с помощью метода reload.

Ошибки

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

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

• Поставщик сервиса не может быть загружен.
• Поставщик сервиса не объявляет метод поставщика, и он не может быть приведён к интерфейсу/классу сервиса или не имеет конструктора поставщика.
• Поставщик сервиса объявляет публичный статический метод без аргументов с именем "provider" и типом возвращаемого значения, который не может быть приведён к интерфейсу или классу сервиса.
• Файл класса поставщика сервиса содержит более одного публичного статического метода без аргументов с именем "provider".
• Поставщик сервиса объявляет метод поставщика, и он завершается, возвращая null или выбрасывая исключение.
• Поставщик сервиса не объявляет метод поставщика, и его конструктор поставщика завершается с ошибкой, выбросив исключение.

При чтении файла конфигурации поставщика или загрузке или создании класса поставщика, указанного в файле конфигурации поставщика, ServiceConfigurationError может быть выброшено по следующим причинам:

• Формат файла конфигурации поставщика нарушает формат, указанный выше;
• Происходит ошибка IOException при чтении файла конфигурации поставщика;
• Поставщик сервиса не может быть загружен;
• Поставщик сервиса не может быть приведён к интерфейсу или классу сервиса, или не определяет конструктор поставщика, или не может быть создан.

Безопасность

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

Конкурентность

Экземпляры этого класса не предназначены для одновременного использования несколькими потоками.

Обработка нулевых значений

Если не указано иное, передача null аргумента любому методу в этом классе приведет к выбросу NullPointerException.