Overview  Package   Class  Use  Deprecated  Index
Home >> All >> gnu >> [ classpath overview ]	PREV CLASS  NEXT CLASS
SUMMARY:  JAVADOC |  SOURCE |  DOWNLOAD | NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---

gnu.classpath
Class ServiceFactory  

java.lang.Object
  gnu.classpath.ServiceFactory

---

public final class ServiceFactory

extends java.lang.Object

A factory for plug-ins that conform to a service provider interface. This is a general mechanism that gets used by a number of packages in the Java API. For instance, java.nio.charset.spi.CharsetProvider allows to write custom encoders and decoders for character sets, javax.imageio.spi.ImageReaderSpi allows to support custom image formats, and javax.print.PrintService makes it possible to write custom printer drivers.

The plug-ins are concrete implementations of the service provider interface, which is defined as an interface or an abstract class. The implementation classes must be public and have a public constructor that takes no arguments.

Plug-ins are usually deployed in JAR files. A JAR that provides an implementation of a service must declare this in a resource file whose name is the fully qualified service name and whose location is the directory META-INF/services. This UTF-8 encoded text file lists, on separate lines, the fully qualified names of the concrete implementations. Thus, one JAR file can provide an arbitrary number of implementations for an arbitrary count of service provider interfaces.

Example

For example, a JAR might provide two implementations of the service provider interface org.foo.ThinkService, namely com.acme.QuickThinker and com.acme.DeepThinker. The code for QuickThinker woud look as follows:

 package com.acme;

 /**
 * Provices a super-quick, but not very deep implementation of ThinkService.
 */
 public class QuickThinker
   implements org.foo.ThinkService
 {
   /**
   * Constructs a new QuickThinker. The service factory (which is
   * part of the Java environment) calls this no-argument constructor
   * when it looks up the available implementations of ThinkService.
   *
   * <p>Note that an application might query all available
   * ThinkService providers, but use just one of them. Therefore,
   * constructing an instance should be very inexpensive. For example,
   * large data structures should only be allocated when the service
   * actually gets used.
   */
   public QuickThinker()
   {
   }

   /**
   * Returns the speed of this ThinkService in thoughts per second.
   * Applications can choose among the available service providers
   * based on this value.
   */
   public double getSpeed()
   {
     return 314159.2654;
   }

   /**
   * Produces a thought. While the returned thoughts are not very
   * deep, they are generated in very short time.
   */
   public Thought think()
   {
     return null;
   }
 }
 

The code for com.acme.DeepThinker is left as an exercise to the reader.

Acme’s ThinkService plug-in gets deployed as a JAR file. Besides the bytecode and resources for QuickThinker and DeepThinker, it also contains the text file META-INF/services/org.foo.ThinkService:

 # Available implementations of org.foo.ThinkService
 com.acme.QuickThinker
 com.acme.DeepThinker
 

Thread Safety

It is safe to use ServiceFactory from multiple concurrent threads without external synchronization.

Note for User Applications

User applications that want to load plug-ins should not directly use gnu.classpath.ServiceFactory, because this class is only available in Java environments that are based on GNU Classpath. Instead, it is recommended that user applications call javax.imageio.spi.ServiceRegistry#lookupProviders(Class). This API is actually independent of image I/O, and it is available on every environment.

---

Nested Class Summary
private static class	ServiceFactory.ServiceIterator           An iterator over service providers that are listed in service provider configuration files, which get passed as an Enumeration of URLs.

 

Field Summary
private static java.util.logging.Logger	LOGGER           A logger that gets informed when a service gets loaded, or when there is a problem with loading a service.

 

Constructor Summary
private	ServiceFactory()           Declared private in order to prevent constructing instances of this utility class.

 

Method Summary
(package private) static void	log(java.util.logging.Level level, java.lang.String msg, java.lang.Object param, java.lang.Throwable t)           Passes a log message to the java.util.logging framework.
static java.util.Iterator	lookupProviders(java.lang.Class spi)           Finds service providers that are implementing the specified Service Provider Interface, using the context class loader for loading providers.
static java.util.Iterator	lookupProviders(java.lang.Class spi, java.lang.ClassLoader loader)           Finds service providers that are implementing the specified Service Provider Interface.

 

Methods inherited from class java.lang.Object

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

 

Field Detail

LOGGER

private static final java.util.logging.Logger LOGGER

A logger that gets informed when a service gets loaded, or when there is a problem with loading a service.

Because Logger.getLogger(String)>Logger.getLogger(String) 55 is thread-safe, we do not need to worry about synchronization here.

Constructor Detail

ServiceFactory

private ServiceFactory()

Declared private in order to prevent constructing instances of this utility class.

Method Detail

lookupProviders

public static java.util.Iterator lookupProviders(java.lang.Class spi,
                                                 java.lang.ClassLoader loader)

Finds service providers that are implementing the specified Service Provider Interface.

On-demand loading: Loading and initializing service providers is delayed as much as possible. The rationale is that typical clients will iterate through the set of installed service providers until one is found that matches some criteria (like supported formats, or quality of service). In such scenarios, it might make sense to install only the frequently needed service providers on the local machine. More exotic providers can be put onto a server; the server will only be contacted when no suitable service could be found locally.

Security considerations: Any loaded service providers are loaded through the specified ClassLoader, or the system ClassLoader if classLoader is null. When lookupProviders is called, the current java.security.AccessControlContext gets recorded. This captured security context will determine the permissions when services get loaded via the next() method of the returned Iterator.

---

lookupProviders

public static java.util.Iterator lookupProviders(java.lang.Class spi)

Finds service providers that are implementing the specified Service Provider Interface, using the context class loader for loading providers.

---

log

static void log(java.util.logging.Level level,
                java.lang.String msg,
                java.lang.Object param,
                java.lang.Throwable t)

Passes a log message to the java.util.logging framework. This call returns very quickly if no log message will be produced, so there is not much overhead in the standard case.

---

Overview  Package   Class  Use  Deprecated  Index
Home >> All >> gnu >> [ classpath overview ]	PREV CLASS  NEXT CLASS
SUMMARY:  JAVADOC |  SOURCE |  DOWNLOAD | NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---