org.freecompany.util.services

Class ServiceInfo

public class ServiceInfo extends 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 Propertiesproperties
protected Stringsystem
Constructor Summary
protected ServiceInfo()
Constructs a service information object without an associated system identifier.
protected ServiceInfo(String system)
Constructs a service information object with the given system identifier.
Method Summary
protected static Stringclean(String line)
Utility method to remove comments from service descriptors.
protected static <T> TcreateInstance(ClassLoader loader, String name, Class<T> service)
Attempts to create an instance of the named class using the provided class loader.
<T> TfindService(Class<T> service)
Finds the first known implementation of the given service class (or interface) using the current class loader.
<T> TfindService(ClassLoader loader, Class<T> service)
Finds the first known implementation of the given service class (or interface) using the provided class loader.
<T> Iterable<T>findServices(Class<T> service)
Finds all known implementations of the given service class using the current class loader.
<T> Iterable<T>findServices(ClassLoader loader, Class<T> service)
Finds all known implementations of the given service class using the provided class loader.
StringgetSystem()
Gets the system name, used to find system wide service properties.
protected static <T> Collection<T>searchClassPath(ClassLoader loader, Class<T> service)
Finds all service descriptors that contain an implementation of the given service.

Field Detail

properties

protected final Properties properties

system

protected final String system

Constructor Detail

ServiceInfo

protected ServiceInfo()
Constructs a service information object without an associated system identifier.

ServiceInfo

protected ServiceInfo(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. {@code net}, for which properties should be parsed.

See Also:

Method Detail

clean

protected static final String clean(String line)
Utility method to remove comments from service descriptors. This method removes any whitespace as well as comments beginning with {@code #} 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.

createInstance

protected static <T> T createInstance(ClassLoader loader, String name, Class<T> service)
Attempts to create an instance of the named class using the provided class loader. If the given class loader is {@code 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 {@code 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 {@code name}.

Throws: ClassCastException if the named class is not a subclass of {@code service}.

findService

public <T> T findService(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 with {@code 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 {@code null} if none is found.

findService

public <T> T findService(ClassLoader loader, 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 {@code 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 {@code null} if none is found.

Throws: ClassCastException if a found provider class is not a subclass of {@code service}.

findServices

public <T> Iterable<T> findServices(Class<T> service)
Finds all known implementations of the given service class using the current class loader. This is equivalent to calling findServices with {@code 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: ClassCastException if a found provider class is not a subclass of {@code service}.

findServices

public <T> Iterable<T> findServices(ClassLoader loader, 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 {@code 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: ClassCastException if a found provider class is not a subclass of {@code service}.

getSystem

public String getSystem()
Gets the system name, used to find system wide service properties.

Returns: the system name, or {@code null} if none was set.

searchClassPath

protected static <T> Collection<T> searchClassPath(ClassLoader loader, 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 {@code 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: ClassCastException if a found provider class is not a subclass of {@code service}.