Класс ServiceLoader<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.