All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.sun.xml.ws.util.ServiceFinder Maven / Gradle / Ivy

There is a newer version: 4.0.3
Show newest version
/*
 * Copyright (c) 1997, 2021 Oracle and/or its affiliates. All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Distribution License v. 1.0, which is available at
 * http://www.eclipse.org/org/documents/edl-v10.php.
 *
 * SPDX-License-Identifier: BSD-3-Clause
 */

package com.sun.xml.ws.util;

import com.sun.istack.NotNull;
import com.sun.istack.Nullable;
import com.sun.xml.ws.api.Component;
import com.sun.xml.ws.api.ComponentEx;
import com.sun.xml.ws.api.server.ContainerResolver;

import java.lang.reflect.Array;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
import java.util.Collections;
import java.util.Iterator;
import java.util.List;
import java.util.NoSuchElementException;
import java.util.Objects;
import java.util.ServiceLoader;


/**
 * A simple service-provider lookup mechanism.  A service is a
 * well-known set of interfaces and (usually abstract) classes.  A service
 * provider is a specific implementation of a service.  The classes in a
 * provider typically implement the interfaces and subclass the classes defined
 * in the service itself.  Service providers may be installed in an
 * implementation of the Java platform in the form of extensions, that is, jar
 * files placed into any of the usual extension directories.  Providers may
 * also be made available by adding them to the applet or application class
 * path or by some other platform-specific means.
 * 
*

In this lookup mechanism a service is represented by an interface or an * abstract class. (A concrete class may be used, but this is not * recommended.) A provider of a given service contains one or more concrete * classes that extend this service class with data and code specific to * the provider. This provider class will typically not be the entire * provider itself but rather a proxy that contains enough information to * decide whether the provider is able to satisfy a particular request together * with code that can create the actual provider on demand. The details of * provider classes tend to be highly service-specific; no single class or * interface could possibly unify them, so no such class has been defined. The * only requirement enforced here is that provider classes must have a * zero-argument constructor so that they may be instantiated during lookup. *
*

A service provider identifies itself by placing a provider-configuration * file in the resource directory {@code META-INF/services}. The file's name * should consist of the fully-qualified name of the abstract service class. * The file should contain a list of fully-qualified concrete provider-class * names, one per line. Space and tab characters surrounding each name, as * well as blank lines, are ignored. The comment character is {@code '#'} * ({@code 0x23}); on each line all characters following the first comment * character are ignored. The file must be encoded in UTF-8. *
*

If a particular concrete provider class is named in more than one * configuration file, or is named in the same configuration file more than * once, then the duplicates will be ignored. The configuration file naming a * particular provider need not be in the same jar file or other distribution * unit as the provider itself. The provider must be accessible from the same * class loader that was initially queried to locate the configuration file; * note that this is not necessarily the class loader that found the file. *
*

Example: Suppose we have a service class named * {@code java.io.spi.CharCodec}. It has two abstract methods: *
*

 *   public abstract CharEncoder getEncoder(String encodingName);
 *   public abstract CharDecoder getDecoder(String encodingName);
 * 
*
* Each method returns an appropriate object or {@code null} if it cannot * translate the given encoding. Typical {@code CharCodec} providers will * support more than one encoding. *
*

If {@code sun.io.StandardCodec} is a provider of the {@code CharCodec} * service then its jar file would contain the file * {@code META-INF/services/java.io.spi.CharCodec}. This file would contain * the single line: *
*

 *   sun.io.StandardCodec    # Standard codecs for the platform
 * 
*
* To locate an codec for a given encoding name, the internal I/O code would * do something like this: *
*
 *   CharEncoder getEncoder(String encodingName) {
 *       for( CharCodec cc : ServiceFinder.find(CharCodec.class) ) {
 *           CharEncoder ce = cc.getEncoder(encodingName);
 *           if (ce != null)
 *               return ce;
 *       }
 *       return null;
 *   }
 * 
*
* The provider-lookup mechanism always executes in the security context of the * caller. Trusted system code should typically invoke the methods in this * class from within a privileged security context. * * @author Mark Reinhold * @version 1.11, 03/12/19 * @param The type of the service to be loaded by this finder * @since 1.3 */ public final class ServiceFinder implements Iterable { private final @NotNull Class serviceClass; private final @NotNull ServiceLoader serviceLoader; private final @Nullable ComponentEx component; public static ServiceFinder find(@NotNull Class service, @Nullable ClassLoader loader, Component component) { ClassLoader cl = loader == null ? Thread.currentThread().getContextClassLoader() : loader; return find(service, component, ServiceLoader.load(service, cl)); } public static ServiceFinder find(@NotNull Class service, Component component, @NotNull ServiceLoader serviceLoader) { Class svc = Objects.requireNonNull(service); ServiceLoader sl = Objects.requireNonNull(serviceLoader); return new ServiceFinder<>(svc, component, sl); } public static ServiceFinder find(@NotNull Class service, Component component) { return find(service, component, ServiceLoader.load(service, Thread.currentThread().getContextClassLoader())); } /** * Locates and incrementally instantiates the available providers of a * given service using the given class loader. *
*

This method transforms the name of the given service class into a * provider-configuration filename as described above and then uses the * {@code getResources} method of the given class loader to find all * available files with that name. These files are then read and parsed to * produce a list of provider-class names. The iterator that is returned * uses the given class loader to lookup and then instantiate each element * of the list. *
*

Because it is possible for extensions to be installed into a running * Java virtual machine, this method may return different results each time * it is invoked.

* * @param The type of the service to be loaded by this finder * @param service The service's abstract service class * @param loader The class loader to be used to load provider-configuration files * and instantiate provider classes, or {@code null} if the system * class loader (or, failing that the bootstrap class loader) is to * be used * @return A new service finder * @throws ServiceConfigurationError If a provider-configuration file violates the specified format * or names a provider class that cannot be found and instantiated * @see #find(Class) */ public static ServiceFinder find(@NotNull Class service, @Nullable ClassLoader loader) { return find(service, loader, ContainerResolver.getInstance().getContainer()); } /** * Locates and incrementally instantiates the available providers of a * given service using the context class loader. This convenience method * is equivalent to *
*

     *   ClassLoader cl = Thread.currentThread().getContextClassLoader();
     *   return Service.providers(service, cl);
     * 
* * @param The type of the service to be loaded by this finder * @param service The service's abstract service class * @return A new service finder * * @throws ServiceConfigurationError If a provider-configuration file violates the specified format * or names a provider class that cannot be found and instantiated * @see #find(Class, ClassLoader) */ public static ServiceFinder find(@NotNull Class service) { return find(service, ServiceLoader.load(service, Thread.currentThread().getContextClassLoader())); } public static ServiceFinder find(@NotNull Class service, @NotNull ServiceLoader serviceLoader) { return find(service, ContainerResolver.getInstance().getContainer(), serviceLoader); } private ServiceFinder(Class service, Component component, ServiceLoader serviceLoader) { this.serviceClass = service; this.component = getComponentEx(component); this.serviceLoader = serviceLoader; } /** * Returns discovered objects incrementally. * * @return An {@code Iterator} that yields provider objects for the given * service, in some arbitrary order. The iterator will throw a * {@code ServiceConfigurationError} if a provider-configuration * file violates the specified format or if a provider class cannot * be found and instantiated. */ @Override @SuppressWarnings("unchecked") public Iterator iterator() { Iterator it = serviceLoader.iterator(); return component != null ? new CompositeIterator<>(component.getIterableSPI(serviceClass).iterator(), it) : it; } /** * Returns discovered objects all at once. * * @return * can be empty but never null. * * @throws ServiceConfigurationError */ public T[] toArray() { List result = new ArrayList<>(); for (T t : this) { result.add(t); } return result.toArray((T[]) Array.newInstance(serviceClass, result.size())); } private static ComponentEx getComponentEx(Component component) { if (component instanceof ComponentEx) { return (ComponentEx) component; } return component != null ? new ComponentExWrapper(component) : null; } private static class ComponentExWrapper implements ComponentEx { private final Component component; public ComponentExWrapper(Component component) { this.component = component; } @Override public S getSPI(Class spiType) { return component.getSPI(spiType); } @Override public Iterable getIterableSPI(Class spiType) { S item = getSPI(spiType); if (item != null) { Collection c = Collections.singletonList(item); return c; } return Collections.emptySet(); } } private static class CompositeIterator implements Iterator { private final Iterator> it; private Iterator current = null; public CompositeIterator(Iterator... iterators) { it = Arrays.asList(iterators).iterator(); } @Override public boolean hasNext() { if (current != null && current.hasNext()) { return true; } while (it.hasNext()) { current = it.next(); if (current.hasNext()) { return true; } } return false; } @Override public T next() { if (!hasNext()) { throw new NoSuchElementException(); } return current.next(); } @Override public void remove() { throw new UnsupportedOperationException(); } } }