Класс ServiceLoader<S>

Простая утилита для загрузки поставщиков сервисов.

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

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

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

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

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

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

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

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

Пример Предположим, у нас есть тип службы com.example.CodecSet, который предназначен для представления наборов пар кодировщик/декодировщик для некоторого протокола. В этом случае это абстрактный класс с двумя абстрактными методами:

public abstract Encoder getEncoder(String encodingName);
public abstract Decoder getDecoder(String encodingName);

Если com.example.impl.StandardCodecs является реализацией службы CodecSet, то её файл jar также содержит файл с именем

META-INF/services/com.example.CodecSet

Этот файл содержит единственную строку:

com.example.impl.StandardCodecs    # Standard codecs

Класс CodecSet создаёт и сохраняет единственный экземпляр службы при инициализации:

private static ServiceLoader<CodecSet> codecSetLoader
    = ServiceLoader.load(CodecSet.class);

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

public static Encoder getEncoder(String encodingName) {
    for (CodecSet cp : codecSetLoader) {
        Encoder enc = cp.getEncoder(encodingName);
        if (enc != null)
            return enc;
    }
    return null;
}

Аналогичным образом определяется метод getDecoder.

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

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

Веб-сервер должен возвращать HTTP-ответ 404 (Не найдено), когда запрашиваемого ресурса не существует. Однако иногда веб-серверы неправильно настроены, чтобы возвращать HTTP-ответ 200 (ОК) вместе с полезной HTML-страницей об ошибке в таких случаях. Это приведёт к выбрасыванию ServiceConfigurationError при попытке этого класса разобрать HTML-страницу в качестве файла конфигурации поставщика. Лучшее решение этой проблемы — исправить неправильно настроенный веб-сервер, чтобы он возвращал правильный код ответа (HTTP 404) вместе с HTML-страницей об ошибке.

Методы

reload

public void reload()

iterator

public Iterator<S> iterator()

Указано в:

iterator в интерфейсе Iterable<S>

Примечание по реализации:

При добавлении поставщиков в кэш, Iterator обрабатывает ресурсы в том порядке, в котором метод ClassLoader.getResources(String) находит файлы конфигурации службы.

Возвращает:

Итератор, который лениво загружает поставщиков для службы этого загрузчика

load

public static <S> ServiceLoader<S> load(Class<S> service,
                                        ClassLoader loader)

Создает новый загрузчик службы для заданного типа службы и загрузчика классов.

Тип параметров:

S - класс типа службы

Параметры:

service - Интерфейс или абстрактный класс, представляющий службу

loader - Загрузчик классов, который будет использоваться для загрузки файлов конфигурации поставщиков и классов поставщиков, или null , если необходимо использовать системный загрузчик классов (или, при его отсутствии, загрузчик базового класса)

Возвращает:

Новый загрузчик службы

load

public static <S> ServiceLoader<S> load(Class<S> service)

ServiceLoader.load(service)

ServiceLoader.load(service,
                   Thread.currentThread().getContextClassLoader())

Тип параметров:

S - класс типа службы

Параметры:

service - Интерфейс или абстрактный класс, представляющий службу

Возвращает:

Новый загрузчик службы

loadInstalled

public static <S> ServiceLoader<S> loadInstalled(Class<S> service)

ServiceLoader.load(service, extClassLoader)

Тип параметров:

S - класс типа службы

Параметры:

service - Интерфейс или абстрактный класс, представляющий службу

Возвращает:

Новый загрузчик службы

toString

public String toString()

Возвращает строку, описывающую эту службу.

Переопределяет:

toString в классе Object

Возвращает:

Описание в виде строки