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

Ошибки

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

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

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

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

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

Параллелизм

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

Обработка null

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