org.omg.dds.core

Class ServiceEnvironment

java.lang.Object

org.omg.dds.core.ServiceEnvironment

All Implemented Interfaces:

DDSObject

public abstract class ServiceEnvironment
extends Object
implements DDSObject

DDS implementations are rooted in this class, a concrete subclass of which can be instantiated based on a system property. All public concrete and abstract methods of this class are reentrant. The reentrancy of any new methods that may be defined by subclasses is unspecified.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	ServiceEnvironment.ServiceProviderInterface This interface is for the use of the DDS implementation, not of DDS applications.

Field Summary

Fields

Modifier and Type	Field and Description
static String	IMPLEMENTATION_CLASS_NAME_PROPERTY

Constructor Summary

Constructors

Constructor and Description
ServiceEnvironment()

Method Summary

Methods

Modifier and Type	Method and Description
static ServiceEnvironment	createInstance(ClassLoader classLoader) Create and return a new instance of a concrete implementation of this class with the given environment.
static ServiceEnvironment	createInstance(String implClassNameProperty, Map<String,Object> environment, ClassLoader classLoader) Look up the system property identified by the given string and load, then instantiate, the ServiceEnvironment implementation class identified by its value.
ServiceEnvironment	getEnvironment()
abstract ServiceEnvironment.ServiceProviderInterface	getSPI() This method is not intended for use by applications.

Methods inherited from class java.lang.Object

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

Field Detail

IMPLEMENTATION_CLASS_NAME_PROPERTY

public static final String IMPLEMENTATION_CLASS_NAME_PROPERTY

See Also:

Constant Field Values

Constructor Detail

ServiceEnvironment

public ServiceEnvironment()

Method Detail

createInstance

public static ServiceEnvironment createInstance(ClassLoader classLoader)

Create and return a new instance of a concrete implementation of this class with the given environment. This method is equivalent to calling: createInstance(IMPLEMENTATION_CLASS_NAME_PROPERTY, null, classLoader);

See Also:

createInstance(String, Map, ClassLoader), IMPLEMENTATION_CLASS_NAME_PROPERTY

createInstance

public static ServiceEnvironment createInstance(String implClassNameProperty,
                                Map<String,Object> environment,
                                ClassLoader classLoader)

Look up the system property identified by the given string and load, then instantiate, the ServiceEnvironment implementation class identified by its value. The class must be accessible and have a public constructor. The public constructors of the implementation class will first be searched for one accepting a single argument of type Map. If one is found, it will be called with the environment map provided to this method as its argument. If no such constructor is found, a no-argument constructor will be used instead, and the provided environment, if any, will be ignored. If the implementation class provides no public constructor with either of these signatures, an exception will be thrown. By default, the class loader for the ServiceEnvironment class will be used to load the indicated class. If this class loader is null -- for instance, if it is the bootstrap class loader -- then the system class loader will be used in its place. If it is also null, a ServiceConfigurationException will be thrown. Neither the class loader nor the loaded class will be cached between invocations of this method. As a result, execution of this method is expected to be relatively expensive. However, as any DDS object can provide a reference to its creating ServiceEnvironment via DDSObject.getEnvironment(), executions of this method are also expected to be rare.

Parameters:

implClassNameProperty - The name of a system property, the value of which will be taken as the name of a ServiceEnvironment implementation class to load.

environment - A collection of name-value pairs to be provided to the concrete ServiceEnvironment subclass. If that class does not provide a constructor that can accept this environment, the environment will be ignored. This argument may be null; a null environment shall be considered equivalent to an empty map.

classLoader - The class loader to use to load the service implementation class. If it is null, this class's class loader will be used if it is accessible; otherwise, the system class loader will be used.

Returns:

A non-null ServiceEnvironment.

Throws:

NullPointerException - If the given property name is null.

IllegalArgumentException - If the given property name is the empty string.

ServiceConfigurationException - If the class could not be loaded because of an issue with the the invocation of this method or the configuration of the runtime environment. For example, the class may not be on the class path, it may require a native library that is not available, or an inappropriate class may have been requested (e.g. one that is not a ServiceEnvironment or that doesn't have a no-argument constructor).

ServiceInitializationException - If the class was found but could not be initialized and/or instantiated because of an error that occurred within its implementation.

See Also:

createInstance(ClassLoader), DDSObject.getEnvironment(), System.getProperty(String), Class.getClassLoader(), ClassLoader.getSystemClassLoader(), ClassLoader.loadClass(String)

getSPI

public abstract ServiceEnvironment.ServiceProviderInterface getSPI()

This method is not intended for use by applications. The DDS-standard classes use it to delegate to a Service implementation.

getEnvironment

public final ServiceEnvironment getEnvironment()

Specified by:

getEnvironment in interface DDSObject

Returns:

the ServiceEnvironment object that directly or indirectly was used to create this object.