org.glassfish.hk2.osgiresourcelocator

Class ServiceLoader

java.lang.Object

org.glassfish.hk2.osgiresourcelocator.ServiceLoader

Direct Known Subclasses:

ServiceLoaderImpl

public abstract class ServiceLoader
extends Object

This is a gateway to OSGi bundles as far as META-INF/services files are concerned. Since META-INF/services files are not exportable, clients relying on Java SPI mechanism can't discover all providers. This utility helps in such a situation. It provides a utility method lookupProviderInstances(java.lang.Class<T>) which can find META-INF/services being part of OSGi bundles. This class has been carefully coded to avoid any reference to OSGi classes so that it can be called in a non-OSGi environment as well. In such an environment, it simply returns null. In an OSGi environment, we expect the class to be initialized by the bundle activator.

Author:

Sanjeeb.Sahoo@Sun.COM

See Also:

#lookupProviderInstances}

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	ServiceLoader.ProviderFactory<T>

Method Summary

Modifier and Type	Method and Description
static void	initialize(ServiceLoader singleton)
static <T> Iterable<Class>	lookupProviderClasses(Class<T> serviceClass) It is not clear why one needs this method, but it is provided just in case one needs it.
static <T> Iterable<? extends T>	lookupProviderInstances(Class<T> serviceClass) Calling this method is equivalent to calling lookupProviderInstances(Class, ProviderFactory) with a null factory object.
static <T> Iterable<? extends T>	lookupProviderInstances(Class<T> serviceClass, ServiceLoader.ProviderFactory<T> factory)
static void	reset()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

initialize

public static void initialize(ServiceLoader singleton)

reset

public static void reset()

lookupProviderInstances

public static <T> Iterable<? extends T> lookupProviderInstances(Class<T> serviceClass)

Calling this method is equivalent to calling lookupProviderInstances(Class, ProviderFactory) with a null factory object.

See Also:

lookupProviderInstances(Class, org.glassfish.hk2.osgiresourcelocator.ServiceLoader.ProviderFactory)

lookupProviderInstances

public static <T> Iterable<? extends T> lookupProviderInstances(Class<T> serviceClass,
                                                                ServiceLoader.ProviderFactory<T> factory)

Type Parameters:

T -

Parameters:

serviceClass - type of service requested

factory - ProviderFactory used to instantiate provider instance from a provider class. If null is supplied, it calls Class.newInstance to obtain a provider instance from provider class.

Returns:

provider instances implementing the given service class.

lookupProviderClasses

public static <T> Iterable<Class> lookupProviderClasses(Class<T> serviceClass)

It is not clear why one needs this method, but it is provided just in case one needs it. Returns classes found in META-INF/services/serviceClass.getName() in OSGi bundles. This method searches for such named resources in every OSGi bundle. For every resource found, it assumes that the file contains a class name. It loads the class name mentioned in that file using the bundle containing the resource. It does not check if the class mentioned in provider file actually implements/extends service class, because there are cases where it does not. JAXB is an example. JAXBContext provider file contains a class that's used as a factory class for JAXBContext. To handle such issues, yet not return classes that are not class loader compatible, this method will only return those classes which see the same service class as supplied in the parameter. Let's take an example. We have JAXB classes exported by JRE and there is a bundle A which contains JAXB API and implementation. The bundle B is wired to itself for JAXB classes. Assume a user supplied bundle B is wired to JRE's JAXB. When bundle B calls JAXBContext.createContext(JAXBContext.class), JRE's JAXBContext will use this API. The implementation will look for META-INF/services/JAXBContext files and find a file in JAXB bundle. Let's say that file contains com.acme.jaxb.JAXBContextFactory. com.acme.jaxb.ContextFactory does not implement JAXBContext.class. Instead, as per JAXB spec, it must provide some factory methods to create JAXBContext. If our implementation simply returns that class without doing any further tests, a nasty class cast exception is going to be resulted, because user's bundle B uses JAXB from JRE, which means JAXBContext.class is loaded by JRE, yet com.acme.jaxb.JAXBContextFactory uses JAXBContext from bundle A. To avoid such problem, we will try to load JAXBContext using class loader of com.acme.jaxb.JAXBContextFactory and see if that's same as supplied JAXBContext.class. If they are same, we return com.acme.jaxb.JAXBContextFactory, else we don't. In this example, we won't.

Type Parameters:

T -

Parameters:

serviceClass - type of service requested

Returns:

classes corresponding to entries in META-INF/services file for the service class.