org.jboss.gravia.runtime

Interface ModuleContext

All Known Implementing Classes:

AbstractModuleContext

public interface ModuleContext

A module's execution context within the Runtime. The context is used to grant access to other methods so that this module can interact with the Runtime.

ModuleContext methods allow a module to:

• Subscribe to events published by the Runtime.
• Register service objects with the Runtime service registry.
• Retrieve ServiceReferences from the Runtime service registry.
• Get and release service objects for a referenced service.
• Create File objects for files in a persistent storage area provided for the module by the Runtime.

A ModuleContext object will be created for a module when the module is started. The Module object associated with a ModuleContext object is called the context module.

The ModuleContext object will be passed to the ModuleActivator.start(ModuleContext) method during activation of the context module. The same ModuleContext object will be passed to the ModuleActivator.stop(ModuleContext) method when the context module is stopped. A ModuleContext object is generally for the private use of its associated module and is not meant to be shared with other modules in the environment.

The ModuleContext object is only valid during the execution of its context module; that is, during the period from when the context module is in the STARTING, STOPPING, and ACTIVE module states. If the ModuleContext object is used subsequently, an IllegalStateException must be thrown. The ModuleContext object must never be reused after its context module is stopped.

Two ModuleContext objects are equal if they both refer to the same execution context of a module. The Runtime is the only entity that can create ModuleContext objects and they are only valid within the Runtime that created them.

A Module can be adapted to its ModuleContext.

Since:

27-Sep-2013

Author:

thomas.diesler@jboss.com

Thread Safety: Thread Safe

Method Summary

Modifier and Type	Method and Description
void	addModuleListener(ModuleListener listener) Adds the specified ModuleListener object to the context module's list of listeners if not already present.
void	addServiceListener(ServiceListener listener) Adds the specified ServiceListener object to the context module's list of listeners.
void	addServiceListener(ServiceListener listener, String filter) Adds the specified ServiceListener object with the specified filter to the context module's list of listeners.
Filter	createFilter(String filter) Creates a Filter object.
ServiceReference<?>[]	getAllServiceReferences(String className, String filter) Returns an array of ServiceReference objects.
Module	getModule() Get the module associated with this context
<S> S	getService(ServiceReference<S> reference) Returns the service object referenced by the specified ServiceReference object.
<S> ServiceReference<S>	getServiceReference(Class<S> clazz) Returns a ServiceReference object for a service that implements and was registered under the name of the specified class.
ServiceReference<?>	getServiceReference(String className) Returns a ServiceReference object for a service that implements and was registered under the specified class.
<S> Collection<ServiceReference<S>>	getServiceReferences(Class<S> clazz, String filter) Returns a collection of ServiceReference objects.
ServiceReference<?>[]	getServiceReferences(String className, String filter) Returns an array of ServiceReference objects.
<S> ServiceRegistration<S>	registerService(Class<S> clazz, S service, Dictionary<String,?> properties) Registers the specified service object with the specified properties under the name of the specified class with the Runtime.
ServiceRegistration<?>	registerService(String[] classNames, Object service, Dictionary<String,?> properties) Registers the specified service object with the specified properties under the specified class names into the Runtime.
ServiceRegistration<?>	registerService(String className, Object service, Dictionary<String,?> properties) Registers the specified service object with the specified properties under the specified class name with the Runtime.
void	removeModuleListener(ModuleListener listener) Removes the specified ModuleListener object from the context module's list of listeners.
void	removeServiceListener(ServiceListener listener) Removes the specified ServiceListener object from the context module's list of listeners.
boolean	ungetService(ServiceReference<?> reference) Releases the service object referenced by the specified ServiceReference object.

Method Detail

getModule

Module getModule()

Get the module associated with this context

createFilter

Filter createFilter(String filter)

Creates a Filter object. This Filter object may be used to match a ServiceReference object or a Dictionary object.

If the filter cannot be parsed, an IllegalArgumentException will be thrown with a human readable message where the filter became unparsable.

Parameters:

filter - The filter string.

Returns:

A Filter object encapsulating the filter string.

addModuleListener

void addModuleListener(ModuleListener listener)

Adds the specified ModuleListener object to the context module's list of listeners if not already present. ModuleListener objects are notified when a module has a lifecycle state change.

If the context module's list of listeners already contains a listener l such that (l==listener), this method does nothing.

Parameters:

listener - The ModuleListener to be added.

Throws:

IllegalStateException - If this ModuleContext is no longer valid.

See Also:

ModuleEvent, ModuleListener

removeModuleListener

void removeModuleListener(ModuleListener listener)

Removes the specified ModuleListener object from the context module's list of listeners.

If listener is not contained in the context module's list of listeners, this method does nothing.

Parameters:

listener - The ModuleListener object to be removed.

Throws:

IllegalStateException - If this ModuleContext is no longer valid.

addServiceListener

void addServiceListener(ServiceListener listener,
                        String filter)

Adds the specified ServiceListener object with the specified filter to the context module's list of listeners. See Filter for a description of the filter syntax. ServiceListener objects are notified when a service has a lifecycle state change.

If the context module's list of listeners already contains a listener l such that (l==listener), then this method replaces that listener's filter (which may be null) with the specified one (which may be null).

The listener is called if the filter criteria is met. To filter based upon the class of the service, the filter should reference the Constants.OBJECTCLASS property. If filter is null , all services are considered to match the filter.

When using a filter, it is possible that the ServiceEvent s for the complete lifecycle of a service will not be delivered to the listener. For example, if the filter only matches when the property x has the value 1, the listener will not be called if the service is registered with the property x not set to the value 1. Subsequently, when the service is modified setting property x to the value 1, the filter will match and the listener will be called with a ServiceEvent of type MODIFIED. Thus, the listener will not be called with a ServiceEvent of type REGISTERED.

Parameters:

listener - The ServiceListener object to be added.

filter - The filter criteria.

Throws:

IllegalArgumentException - If filter contains an invalid filter string that cannot be parsed.

IllegalStateException - If this ModuleContext is no longer valid.

See Also:

ServiceEvent, ServiceListener

addServiceListener

void addServiceListener(ServiceListener listener)

Adds the specified ServiceListener object to the context module's list of listeners.

This method is the same as calling ModuleContext.addServiceListener(ServiceListener listener, String filter) with filter set to null.

Parameters:

listener - The ServiceListener object to be added.

Throws:

IllegalStateException - If this ModuleContext is no longer valid.

See Also:

addServiceListener(ServiceListener, String)

removeServiceListener

void removeServiceListener(ServiceListener listener)

Removes the specified ServiceListener object from the context module's list of listeners.

If listener is not contained in this context module's list of listeners, this method does nothing.

Parameters:

listener - The ServiceListener to be removed.

Throws:

IllegalStateException - If this ModuleContext is no longer valid.

registerService

<S> ServiceRegistration<S> registerService(Class<S> clazz,
                                           S service,
                                           Dictionary<String,?> properties)

Registers the specified service object with the specified properties under the name of the specified class with the Runtime.

This method is otherwise identical to registerService(String, Object, Dictionary) and is provided to return a type safe ServiceRegistration.

Type Parameters:

S - Type of Service.

Parameters:

clazz - The class under whose name the service can be located.

service - The service object or a ServiceFactory object.

properties - The properties for this service.

Returns:

A ServiceRegistration object for use by the module registering the service to update the service's properties or to unregister the service.

Throws:

IllegalStateException - If this ModuleContext is no longer valid.

See Also:

registerService(String, Object, Dictionary)

registerService

ServiceRegistration<?> registerService(String className,
                                       Object service,
                                       Dictionary<String,?> properties)

Registers the specified service object with the specified properties under the specified class name with the Runtime.

This method is otherwise identical to registerService(String[], Object, Dictionary) and is provided as a convenience when service will only be registered under a single class name. Note that even in this case the value of the service's Constants.OBJECTCLASS property will be an array of string, rather than just a single string.

Parameters:

className - The class name under which the service can be located.

service - The service object or a ServiceFactory object.

properties - The properties for this service.

Returns:

A ServiceRegistration object for use by the module registering the service to update the service's properties or to unregister the service.

Throws:

IllegalStateException - If this ModuleContext is no longer valid.

See Also:

registerService(String[], Object, Dictionary)

registerService

ServiceRegistration<?> registerService(String[] classNames,
                                       Object service,
                                       Dictionary<String,?> properties)

Registers the specified service object with the specified properties under the specified class names into the Runtime. A ServiceRegistration object is returned. The ServiceRegistration object is for the private use of the module registering the service and should not be shared with other modules. The registering module is defined to be the context module.

A module can register a service object that implements the ServiceFactory interface to have more flexibility in providing service objects to other modules.

The following steps are required to register a service:

1. If service is not a ServiceFactory, an IllegalArgumentException is thrown if service is not an instanceof all the specified class names.
2. The Runtime adds the following service properties to the service properties from the specified Dictionary (which may be null):
   A property named Constants.SERVICE_ID identifying the registration number of the service
   A property named Constants.OBJECTCLASS containing all the specified classes.
   Properties with these names in the specified Dictionary will be ignored.
3. The service is added to the Runtime service registry and may now be used by other modules.
4. A service event of type ServiceEvent.REGISTERED is fired.
5. A ServiceRegistration object for this registration is returned.

Parameters:

classNames - The class names under which the service can be located. The class names in this array will be stored in the service's properties under the key Constants.OBJECTCLASS.

service - The service object or a ServiceFactory object.

properties - The properties for this service. The keys in the properties object must all be String objects. See Constants for a list of standard service property keys. Changes should not be made to this object after calling this method. To update the service's properties the ServiceRegistration.setProperties(Dictionary) method must be called. The set of properties may be null if the service has no properties.

Returns:

A ServiceRegistration object for use by the module registering the service to update the service's properties or to unregister the service.

Throws:

IllegalArgumentException - If one of the following is true:

• service is null.
• service is not a ServiceFactory object and is not an instance of all the named classes in clazzes.
• properties contains case variants of the same key name.

IllegalStateException - If this ModuleContext is no longer valid.

See Also:

ServiceRegistration, ServiceFactory

getServiceReference

<S> ServiceReference<S> getServiceReference(Class<S> clazz)

Returns a ServiceReference object for a service that implements and was registered under the name of the specified class.

The returned ServiceReference object is valid at the time of the call to this method. However as the Runtime is a very dynamic environment, services can be modified or unregistered at any time.

This method is the same as calling getServiceReferences(Class, String) with a null filter expression. It is provided as a convenience for when the caller is interested in any service that implements the specified class.

If multiple such services exist, the service with the highest ranking (as specified in its Constants.SERVICE_RANKING property) is returned.

If there is a tie in ranking, the service with the lowest service ID (as specified in its Constants.SERVICE_ID property); that is, the service that was registered first is returned.

Type Parameters:

S - Type of Service.

Parameters:

clazz - The class under whose name the service was registered. Must not be null.

Returns:

A ServiceReference object, or null if no services are registered which implement the specified class.

Throws:

IllegalStateException - If this ModuleContext is no longer valid.

See Also:

getServiceReferences(Class, String)

getServiceReference

ServiceReference<?> getServiceReference(String className)

Returns a ServiceReference object for a service that implements and was registered under the specified class.

The returned ServiceReference object is valid at the time of the call to this method. However as the Runtime is a very dynamic environment, services can be modified or unregistered at any time.

This method is the same as calling getServiceReferences(String, String) with a null filter expression and then finding the reference with the highest priority. It is provided as a convenience for when the caller is interested in any service that implements the specified class.

If multiple such services exist, the service with the highest priority is selected. This priority is defined as the service reference with the highest ranking (as specified in its Constants.SERVICE_RANKING property) is returned.

If there is a tie in ranking, the service with the lowest service ID (as specified in its Constants.SERVICE_ID property); that is, the service that was registered first is returned.

Parameters:

className - The class name with which the service was registered.

Returns:

A ServiceReference object, or null if no services are registered which implement the named class.

Throws:

IllegalStateException - If this ModuleContext is no longer valid.

See Also:

getServiceReferences(String, String)

getServiceReferences

<S> Collection<ServiceReference<S>> getServiceReferences(Class<S> clazz,
                                                         String filter)

Returns a collection of ServiceReference objects. The returned collection of ServiceReference objects contains services that were registered under the name of the specified class, match the specified filter expression, and the packages for the class names under which the services were registered match the context module's packages as defined in ServiceReference.isAssignableTo(Module, String).

The collection is valid at the time of the call to this method. However since the Runtime is a very dynamic environment, services can be modified or unregistered at any time.

The specified filter expression is used to select the registered services whose service properties contain keys and values which satisfy the filter expression. See Filter for a description of the filter syntax. If the specified filter is null, all registered services are considered to match the filter. If the specified filter expression cannot be parsed, an IllegalArgumentException will be thrown with a human readable message where the filter became unparsable.

The result is a collection of ServiceReference objects for all services that meet all of the following conditions:

• The service must have been registered with the name of the specified class. The complete list of class names with which a service was registered is available from the service's objectClass property.
• If the specified filter is not null, the filter expression must match the service.
• For each class name with which the service was registered, calling ServiceReference.isAssignableTo(Module, String) with the context module and the class name on the service's ServiceReference object must return true

Type Parameters:

S - Type of Service

Parameters:

clazz - The class under whose name the service was registered. Must not be null.

filter - The filter expression or null for all services.

Returns:

A collection of ServiceReference objects. May be empty if no services are registered which satisfy the search.

Throws:

IllegalArgumentException - If the specified filter contains an invalid filter expression that cannot be parsed.

IllegalStateException - If this ModuleContext is no longer valid.

getServiceReferences

ServiceReference<?>[] getServiceReferences(String className,
                                           String filter)

Returns an array of ServiceReference objects. The returned array of ServiceReference objects contains services that were registered under the specified class, match the specified filter expression, and the packages for the class names under which the services were registered match the context module's packages as defined in ServiceReference.isAssignableTo(Module, String).

The list is valid at the time of the call to this method. However since the Runtime is a very dynamic environment, services can be modified or unregistered at any time.

The specified filter expression is used to select the registered services whose service properties contain keys and values which satisfy the filter expression. See Filter for a description of the filter syntax. If the specified filter is null, all registered services are considered to match the filter. If the specified filter expression cannot be parsed, an IllegalArgumentException will be thrown with a human readable message where the filter became unparsable.

The result is an array of ServiceReference objects for all services that meet all of the following conditions:

• If the specified class name, clazz, is not null, the service must have been registered with the specified class name. The complete list of class names with which a service was registered is available from the service's objectClass property.
• If the specified filter is not null, the filter expression must match the service.
• For each class name with which the service was registered, calling ServiceReference.isAssignableTo(Module, String) with the context module and the class name on the service's ServiceReference object must return true

Parameters:

className - The class name with which the service was registered or null for all services.

filter - The filter expression or null for all services.

Returns:

An array of ServiceReference objects or null if no services are registered which satisfy the search.

Throws:

IllegalArgumentException - If the specified filter contains an invalid filter expression that cannot be parsed.

IllegalStateException - If this ModuleContext is no longer valid.

getAllServiceReferences

ServiceReference<?>[] getAllServiceReferences(String className,
                                              String filter)

Returns an array of ServiceReference objects. The returned array of ServiceReference objects contains services that were registered under the specified class and match the specified filter expression.

The list is valid at the time of the call to this method. However since the Runtime is a very dynamic environment, services can be modified or unregistered at any time.

The specified filter expression is used to select the registered services whose service properties contain keys and values which satisfy the filter expression. See Filter for a description of the filter syntax. If the specified filter is null, all registered services are considered to match the filter. If the specified filter expression cannot be parsed, an IllegalArgumentException will be thrown with a human readable message where the filter became unparsable.

The result is an array of ServiceReference objects for all services that meet all of the following conditions:

• If the specified class name, clazz, is not null, the service must have been registered with the specified class name. The complete list of class names with which a service was registered is available from the service's objectClass property.
• If the specified filter is not null, the filter expression must match the service.

Parameters:

className - The class name with which the service was registered or null for all services.

filter - The filter expression or null for all services.

Returns:

An array of ServiceReference objects or null if no services are registered which satisfy the search.

Throws:

IllegalArgumentException - If the specified filter contains an invalid filter expression that cannot be parsed.

IllegalStateException - If this ModuleContext is no longer valid.

getService

<S> S getService(ServiceReference<S> reference)

Returns the service object referenced by the specified ServiceReference object.

A module's use of a service is tracked by the module's use count of that service. Each time a service's service object is returned by getService(ServiceReference) the context module's use count for that service is incremented by one. Each time the service is released by ungetService(ServiceReference) the context module's use count for that service is decremented by one.

When a module's use count for a service drops to zero, the module should no longer use that service.

This method will always return null when the service associated with this reference has been unregistered.

The following steps are required to get the service object:

1. If the service has been unregistered, null is returned.
2. If the context module's use count for the service is currently zero and the service was registered with an object implementing the ServiceFactory interface, the ServiceFactory.getService(Module, ServiceRegistration) method is called to create a service object for the context module. If the service object returned by the ServiceFactory object is null, not an instanceof all the classes named when the service was registered or the ServiceFactory object throws an exception or will be recursively called for the context module, null is returned.
   This service object is cached by the Runtime. While the context module's use count for the service is greater than zero, subsequent calls to get the services's service object for the context module will return the cached service object.
3. The context module's use count for this service is incremented by one.
4. The service object for the service is returned.

Type Parameters:

S - Type of Service.

Parameters:

reference - A reference to the service.

Returns:

A service object for the service associated with reference or null if the service is not registered, the service object returned by a ServiceFactory does not implement the classes under which it was registered or the ServiceFactory threw an exception.

Throws:

IllegalStateException - If this ModuleContext is no longer valid.

IllegalArgumentException - If the specified ServiceReference was not created by the same framework instance as this ModuleContext.

See Also:

ungetService(ServiceReference), ServiceFactory

ungetService

boolean ungetService(ServiceReference<?> reference)

Releases the service object referenced by the specified ServiceReference object. If the context module's use count for the service is zero, this method returns false. Otherwise, the context module's use count for the service is decremented by one.

The service's service object should no longer be used and all references to it should be destroyed when a module's use count for the service drops to zero.

The following steps are required to unget the service object:

1. If the context module's use count for the service is zero or the service has been unregistered, false is returned.
2. The context module's use count for this service is decremented by one.
3. If the context module's use count for the service is currently zero and the service was registered with a ServiceFactory object, the ServiceFactory.ungetService(Module, ServiceRegistration, Object) method is called to release the service object for the context module.
4. true is returned.

Parameters:

reference - A reference to the service to be released.

Returns:

false if the context module's use count for the service is zero or if the service has been unregistered; true otherwise.

Throws:

IllegalStateException - If this ModuleContext is no longer valid.

IllegalArgumentException - If the specified ServiceReference was not created by the same framework instance as this ModuleContext.

See Also:

getService(ServiceReference), ServiceFactory