Класс ServiceLoader<S>

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

Средство для загрузки реализаций сервиса.

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

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

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

Ошибки

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

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

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

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

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

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

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

Обработка null

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