org.freecompany.util.services
Class ServiceInfo

java.lang.Object
  org.freecompany.util.services.ServiceInfo

public class ServiceInfo
extends java.lang.Object

A service information object provides an interface that can be used to query for provider instances defined in system properties, system wide JVM settings, or service descriptors in the class path.

Field Summary

protected java.util.Properties	properties
protected java.lang.String	system

Constructor Summary

protected	ServiceInfo() Constructs a service information object without an associated system identifier.
protected	ServiceInfo(java.lang.String system) Constructs a service information object with the given system identifier.

Method Summary

protected static java.lang.String	clean(java.lang.String line) Utility method to remove comments from service descriptors.
protected static <T> T	createInstance(java.lang.ClassLoader loader, java.lang.String name, java.lang.Class<T> service) Attempts to create an instance of the named class using the provided class loader.
<T> T	findService(java.lang.Class<T> service) Finds the first known implementation of the given service class (or interface) using the current class loader.
<T> T	findService(java.lang.ClassLoader loader, java.lang.Class<T> service) Finds the first known implementation of the given service class (or interface) using the provided class loader.
<T> java.lang.Iterable<T>	findServices(java.lang.Class<T> service) Finds all known implementations of the given service class using the current class loader.
<T> java.lang.Iterable<T>	findServices(java.lang.ClassLoader loader, java.lang.Class<T> service) Finds all known implementations of the given service class using the provided class loader.
java.lang.String	getSystem() Gets the system name, used to find system wide service properties.
protected static <T> java.util.Collection<T>	searchClassPath(java.lang.ClassLoader loader, java.lang.Class<T> service) Finds all service descriptors that contain an implementation of the given service.

Methods inherited from class java.lang.Object

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

Field Detail

properties

protected final java.util.Properties properties

system

protected final java.lang.String system

Constructor Detail

ServiceInfo

protected ServiceInfo()

Constructs a service information object without an associated system identifier.

ServiceInfo

protected ServiceInfo(java.lang.String system)

Constructs a service information object with the given system identifier. This identifier is used to query system specific JVM configuration files which allow a user or system administrator to override provider implementations.

Parameters:

system - the identifier for the particular system, i.e. net, for which properties should be parsed.

See Also:

ServiceDiscovery

Method Detail

getSystem

public java.lang.String getSystem()

Gets the system name, used to find system wide service properties.

Returns:

the system name, or null if none was set.

findService

public <T> T findService(java.lang.Class<T> service)

Finds the first known implementation of the given service class (or interface) using the current class loader. This is equivalent to calling findService(ClassLoader,Class) with null as the first parameter.

Parameters:

service - the service class (or interface) for which a compatible implementation will be returned.

Returns:

a concrete instance, or null if none is found.

findService

public <T> T findService(java.lang.ClassLoader loader,
                         java.lang.Class<T> service)

Finds the first known implementation of the given service class (or interface) using the provided class loader. This method searches, in order, a system property specified by the fully qualified service class name if one exists, the properties file located within the Java home directory if it exists, and finally the provided class loader by fetching all resources named according to the services specification. This method returns the first service implementation it finds.

Parameters:

loader - the class loader to use when searching for service descriptor files, or null to use the current class loader.

service - the service class (or interface) for which compatible implementations will be returned.

Returns:

a concrete instance, or null if none is found.

Throws:

java.lang.ClassCastException - if a found provider class is not a subclass of service.

findServices

public <T> java.lang.Iterable<T> findServices(java.lang.Class<T> service)

Finds all known implementations of the given service class using the current class loader. This is equivalent to calling findServices(ClassLoader,Class) with null as the first parameter.

Parameters:

service - the service class (or interface) for which compatible implementations will be searched.

Returns:

a Collection of concrete instances, or the empty collection is none is found.

Throws:

java.lang.ClassCastException - if a found provider class is not a subclass of service.

findServices

public <T> java.lang.Iterable<T> findServices(java.lang.ClassLoader loader,
                                              java.lang.Class<T> service)

Finds all known implementations of the given service class using the provided class loader. This method searches, in order, a system property specified by the fully qualified service class name if one exists, the properties file located within the Java home directory if it exists, and finally the provided class loader by fetching all resources named according to the services specification. This method returns all compatible service implementations.

Parameters:

loader - the class loader to use when searching for service descriptor files, or null to use the current class loader.

service - the service class (or interface) for which compatible implementations will be searched.

Returns:

a Collection of concrete instances, or the empty collection is none is found.

Throws:

java.lang.ClassCastException - if a found provider class is not a subclass of service.

searchClassPath

protected static <T> java.util.Collection<T> searchClassPath(java.lang.ClassLoader loader,
                                                             java.lang.Class<T> service)

Finds all service descriptors that contain an implementation of the given service. The resulting collection will contain an instance of each concrete provider implementation found through the given class loader, or the current class loader if null is specified.

Parameters:

loader - the class loader within which to search for service descriptors.

service - the service interface for which to find concrete implementations.

Returns:

a Collection of concrete instances of the service class (or interface), or an empty collection if none could be found.

Throws:

java.lang.ClassCastException - if a found provider class is not a subclass of service.

createInstance

protected static <T> T createInstance(java.lang.ClassLoader loader,
                                      java.lang.String name,
                                      java.lang.Class<T> service)

Attempts to create an instance of the named class using the provided class loader. If the given class loader is null then the current class loader is used. This method returns null if the class cannot be found or instantiated with a default constructor.

Parameters:

loader - the class loader to use to load the class definition, may be null.

name - name of the class to load and instantiate.

service - the service class of which the named class is expected to be a subclass.

Returns:

a new instance of the class indicated with name.

Throws:

java.lang.ClassCastException - if the named class is not a subclass of service.

clean

protected static final java.lang.String clean(java.lang.String line)

Utility method to remove comments from service descriptors. This method removes any whitespace as well as comments beginning with # through the end of the line.

Parameters:

line - line including possible extra white space and comment.

Returns:

cleaned line or the empty string if the line is not valid.