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