A module's execution context within the framework. More...
Public Member Functions | |
~ModuleContext () | |
Module * | GetModule () const |
Returns the Module object associated with this ModuleContext . More... | |
Module * | GetModule (long id) const |
Returns the module with the specified identifier. More... | |
Module * | GetModule (const std::string &name) |
Get the module that with the specified module name. More... | |
std::vector< Module * > | GetModules () const |
Returns a list of all known modules. More... | |
ServiceRegistrationU | RegisterService (const InterfaceMap &service, const ServiceProperties &properties=ServiceProperties()) |
Registers the specified service object with the specified properties under the specified class names into the framework. More... | |
template<class S > | |
ServiceRegistration< S > | RegisterService (S *service, const ServiceProperties &properties=ServiceProperties()) |
Registers the specified service object with the specified properties using the specified template argument with the framework. More... | |
template<class I1 , class I2 , class Impl > | |
ServiceRegistration< I1, I2 > | RegisterService (Impl *impl, const ServiceProperties &properties=ServiceProperties()) |
Registers the specified service object with the specified properties using the specified template argument with the framework. More... | |
template<class I1 , class I2 , class I3 , class Impl > | |
ServiceRegistration< I1, I2, I3 > | RegisterService (Impl *impl, const ServiceProperties &properties=ServiceProperties()) |
Registers the specified service object with the specified properties using the specified template argument with the framework. More... | |
template<class S > | |
ServiceRegistration< S > | RegisterService (ServiceFactory *factory, const ServiceProperties &properties=ServiceProperties()) |
Registers the specified service factory as a service with the specified properties using the specified template argument as service interface type with the framework. More... | |
template<class I1 , class I2 > | |
ServiceRegistration< I1, I2 > | RegisterService (ServiceFactory *factory, const ServiceProperties &properties=ServiceProperties()) |
Registers the specified service factory as a service with the specified properties using the specified template argument as service interface type with the framework. More... | |
template<class I1 , class I2 , class I3 > | |
ServiceRegistration< I1, I2, I3 > | RegisterService (ServiceFactory *factory, const ServiceProperties &properties=ServiceProperties()) |
Registers the specified service factory as a service with the specified properties using the specified template argument as service interface type with the framework. More... | |
std::vector< ServiceReferenceU > | GetServiceReferences (const std::string &clazz, const std::string &filter=std::string()) |
Returns a list of ServiceReference objects. More... | |
template<class S > | |
std::vector< ServiceReference < S > > | GetServiceReferences (const std::string &filter=std::string()) |
Returns a list of ServiceReference objects. More... | |
ServiceReferenceU | GetServiceReference (const std::string &clazz) |
Returns a ServiceReference object for a service that implements and was registered under the specified class. More... | |
template<class S > | |
ServiceReference< S > | GetServiceReference () |
Returns a ServiceReference object for a service that implements and was registered under the specified template class argument. More... | |
void * | GetService (const ServiceReferenceBase &reference) |
Returns the service object referenced by the specified ServiceReferenceBase object. More... | |
InterfaceMap | GetService (const ServiceReferenceU &reference) |
template<class S > | |
S * | GetService (const ServiceReference< S > &reference) |
Returns the service object referenced by the specified ServiceReference object. More... | |
template<class S > | |
ServiceObjects< S > | GetServiceObjects (const ServiceReference< S > &reference) |
Returns the ServiceObjects object for the service referenced by the specified ServiceReference object. More... | |
bool | UngetService (const ServiceReferenceBase &reference) |
Releases the service object referenced by the specified ServiceReference object. More... | |
void | AddServiceListener (const ServiceListener &delegate, const std::string &filter=std::string()) |
void | RemoveServiceListener (const ServiceListener &delegate) |
void | AddModuleListener (const ModuleListener &delegate) |
void | RemoveModuleListener (const ModuleListener &delegate) |
template<class R > | |
void | AddServiceListener (R *receiver, void(R::*callback)(const ServiceEvent), const std::string &filter=std::string()) |
Adds the specified callback with the specified filter to the context modules's list of listeners. More... | |
template<class R > | |
void | RemoveServiceListener (R *receiver, void(R::*callback)(const ServiceEvent)) |
Removes the specified callback from the context module's list of listeners. More... | |
template<class R > | |
void | AddModuleListener (R *receiver, void(R::*callback)(const ModuleEvent)) |
Adds the specified callback to the context modules's list of listeners. More... | |
template<class R > | |
void | RemoveModuleListener (R *receiver, void(R::*callback)(const ModuleEvent)) |
Removes the specified callback from the context module's list of listeners. More... | |
std::string | GetDataFile (const std::string &filename) const |
Get the absolute path for a file or directory in the persistent storage area provided for the module. More... | |
A module's execution context within the framework.
The context is used to grant access to other methods so that this module can interact with the Micro Services Framework.
ModuleContext
methods allow a module to:
ServiceReference
s from the framework service registry. A ModuleContext
object will be created and provided to the module associated with this context when it is loaded using the ModuleActivator::Load method. The same ModuleContext
object will be passed to the module associated with this context when it is unloaded using the ModuleActivator::Unload method. 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 module environment.
The Module
object associated with a ModuleContext
object is called the context module.
The ModuleContext
object is only valid during the execution of its context module; that is, during the period when the context module is loaded. If the ModuleContext
object is used subsequently, a std::logic_error
is thrown. The ModuleContext
object is never reused after its context module is unloaded.
The framework is the only entity that can create ModuleContext
objects.
ModuleContext::~ModuleContext | ( | ) |
void ModuleContext::AddModuleListener | ( | const ModuleListener & | delegate | ) |
|
inline |
Adds the specified callback
to the context modules's list of listeners.
Listeners are notified when a module has a lifecycle state change.
If the context module's list of listeners already contains a pair (r,c)
of receiver
and callback
such that (r == receiver && c == callback)
, then this method does nothing.
R | The type of the receiver (containing the member function to be called) |
receiver | The object to connect to. |
callback | The member function pointer to call. |
std::logic_error | If this ModuleContext is no longer valid. |
void ModuleContext::AddServiceListener | ( | const ServiceListener & | delegate, |
const std::string & | filter = std::string() |
||
) |
|
inline |
Adds the specified callback
with the specified filter
to the context modules's list of listeners.
See LDAPFilter for a description of the filter syntax. Listeners are notified when a service has a lifecycle state change.
You must take care to remove registered listeners befor the receiver
object is destroyed. However, the Micro Services framework takes care of removing all listeners registered by this context module's classes after the module is unloaded.
If the context module's list of listeners already contains a pair (r,c)
of receiver
and callback
such that (r == receiver && c == callback)
, then this method replaces that callback's filter (which may be empty) with the specified one (which may be empty).
The callback is called if the filter criteria is met. To filter based upon the class of the service, the filter should reference the ServiceConstants::OBJECTCLASS() property. If filter
is empty, 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 callback. For example, if the filter
only matches when the property x
has the value 1
, the callback 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 callback will be called with a ServiceEvent
of type MODIFIED
. Thus, the callback will not be called with a ServiceEvent
of type REGISTERED
.
R | The type of the receiver (containing the member function to be called) |
receiver | The object to connect to. |
callback | The member function pointer to call. |
filter | The filter criteria. |
std::invalid_argument | If filter contains an invalid filter string that cannot be parsed. |
std::logic_error | If this ModuleContext is no longer valid. |
std::string ModuleContext::GetDataFile | ( | const std::string & | filename | ) | const |
Get the absolute path for a file or directory in the persistent storage area provided for the module.
The returned path might be empty if no storage path has been set previously. If the path is non-empty, it is safe to assume that the path is writable.
filename | A relative name to the file or directory to be accessed. |
Module* ModuleContext::GetModule | ( | ) | const |
Returns the Module
object associated with this ModuleContext
.
This module is called the context module.
Module
object associated with this ModuleContext
. std::logic_error | If this ModuleContext is no longer valid. |
Module* ModuleContext::GetModule | ( | long | id | ) | const |
Returns the module with the specified identifier.
id | The identifier of the module to retrieve. |
Module
object or 0
if the identifier does not match any previously loaded module. Module* ModuleContext::GetModule | ( | const std::string & | name | ) |
Get the module that with the specified module name.
name | The name of the module to get. |
Module
or NULL
. std::vector<Module*> ModuleContext::GetModules | ( | ) | const |
Returns a list of all known modules.
This method returns a list of all modules loaded in the module environment at the time of the call to this method. This list will also contain modules which might already have been unloaded.
Module
objects which will hold one object per known module. void* ModuleContext::GetService | ( | const ServiceReferenceBase & | reference | ) |
Returns the service object referenced by the specified ServiceReferenceBase
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(const ServiceReference<S>&) the context module's use count for that service is incremented by one. Each time the service is released by UngetService(const ServiceReferenceBase&) 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 0
when the service associated with this reference
has been unregistered.
The following steps are taken to get the service object:
0
is returned. ServiceFactory
interface, the ServiceFactory::GetService method is called to create a service object for the context module. This service object is cached by the framework. 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. ServiceFactory
object throws an exception, 0
is returned and a warning is logged. reference | A reference to the service. |
reference
or 0
if the service is not registered or the ServiceFactory
threw an exception. std::logic_error | If this ModuleContext is no longer valid. |
std::invalid_argument | If the specified ServiceReferenceBase is invalid (default constructed). |
InterfaceMap ModuleContext::GetService | ( | const ServiceReferenceU & | reference | ) |
|
inline |
Returns the service object referenced by the specified ServiceReference
object.
This is a convenience method which is identical to void* GetService(const ServiceReferenceBase&) except that it casts the service object to the supplied template argument type
S | The type the service object will be cast to. |
reference
or 0
if the service is not registered, the ServiceFactory
threw an exception or the service could not be casted to the desired type. std::logic_error | If this ModuleContext is no longer valid. |
std::invalid_argument | If the specified ServiceReference is invalid (default constructed). |
|
inline |
Returns the ServiceObjects object for the service referenced by the specified ServiceReference object.
The ServiceObjects object can be used to obtain multiple service objects for services with prototype scope. For services with singleton or module scope, the ServiceObjects::GetService() method behaves the same as the GetService(const ServiceReference<S>&) method and the ServiceObjects::UngetService(const ServiceReferenceBase&) method behaves the same as the UngetService(const ServiceReferenceBase&) method. That is, only one, use-counted service object is available from the ServiceObjects object.
S | Type of Service. |
reference | A reference to the service. |
std::logic_error | If this ModuleContext is no longer valid. |
std::invalid_argument | If the specified ServiceReference is invalid (default constructed or the service has been unregistered) |
ServiceReferenceU ModuleContext::GetServiceReference | ( | const std::string & | clazz | ) |
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 Micro Services framework is a very dynamic environment, services can be modified or unregistered at any time.
This method is the same as calling ModuleContext::GetServiceReferences(const std::string&, const std::string&) with an empty 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 ServiceConstants::SERVICE_RANKING() property) is returned.
If there is a tie in ranking, the service with the lowest service ID (as specified in its ServiceConstants::SERVICE_ID() property); that is, the service that was registered first is returned.
clazz | The class name with which the service was registered. |
ServiceReference
object, or an invalid ServiceReference
if no services are registered which implement the named class. std::logic_error | If this ModuleContext is no longer valid. |
ServiceException | If no service was registered under the given class name. |
|
inline |
Returns a ServiceReference
object for a service that implements and was registered under the specified template class argument.
This method is identical to GetServiceReference(const std::string&) except that the class name for the service object is automatically deduced from the template argument.
S | The type under which the requested service must have been registered. |
ServiceReference
object, or an invalid ServiceReference
if no services are registered which implement the type S
. std::logic_error | If this ModuleContext is no longer valid. |
ServiceException | It no service was registered under the given class name. |
std::vector<ServiceReferenceU> ModuleContext::GetServiceReferences | ( | const std::string & | clazz, |
const std::string & | filter = std::string() |
||
) |
Returns a list of ServiceReference
objects.
The returned list 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 Micro Services framework 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 LDAPFilter for a description of the filter syntax. If the specified filter
is empty, all registered services are considered to match the filter. If the specified filter
expression cannot be parsed, an std::invalid_argument
will be thrown with a human readable message where the filter became unparsable.
The result is a list of ServiceReference
objects for all services that meet all of the following conditions:
clazz
, is not empty, 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. filter
is not empty, the filter expression must match the service. clazz | The class name with which the service was registered or an empty string for all services. |
filter | The filter expression or empty for all services. |
ServiceReference
objects or an empty list if no services are registered which satisfy the search. std::invalid_argument | If the specified filter contains an invalid filter expression that cannot be parsed. |
std::logic_error | If this ModuleContext is no longer valid. |
|
inline |
Returns a list of ServiceReference
objects.
The returned list contains services that were registered under the interface id of the template argument S
and match the specified filter expression.
This method is identical to GetServiceReferences(const std::string&, const std::string&) except that the class name for the service object is automatically deduced from the template argument.
S | The type under which the requested service objects must have been registered. |
filter | The filter expression or empty for all services. |
ServiceReference
objects or an empty list if no services are registered which satisfy the search. std::invalid_argument | If the specified filter contains an invalid filter expression that cannot be parsed. |
std::logic_error | If this ModuleContext is no longer valid. |
ServiceException | If the service type S is invalid. |
ServiceRegistrationU ModuleContext::RegisterService | ( | const InterfaceMap & | service, |
const ServiceProperties & | properties = ServiceProperties() |
||
) |
Registers the specified service object with the specified properties under the specified class names into the framework.
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. Other modules can locate the service by using either the GetServiceReferences or GetServiceReference method.
A module can register a service object that implements the ServiceFactory or PrototypeServiceFactory interface to have more flexibility in providing service objects to other modules.
The following steps are taken when registering a service:
ServiceProperties
(which may be omitted): ServiceProperties
will be ignored. ServiceRegistration
object for this registration is returned. service | The service object, which is a map of interface identifiers to raw service pointers. |
properties | The properties for this service. The keys in the properties object must all be std::string objects. See ServiceConstants 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 method must be called. The set of properties may be omitted if the service has no properties. |
ServiceRegistration
object for use by the module registering the service to update the service's properties or to unregister the service.std::invalid_argument | If one of the following is true:
|
std::logic_error | If this ModuleContext is no longer valid. |
|
inline |
Registers the specified service object with the specified properties using the specified template argument with the framework.
This method is provided as a convenience when service
will only be registered under a single class name whose type is available to the caller. It is otherwise identical to RegisterService(const InterfaceMap&, const ServiceProperties&) but should be preferred since it avoids errors in the string literal identifying the class name or interface identifier.
Example usage:
S | The type under which the service can be located. |
service | The service object or a ServiceFactory object. |
properties | The properties for this service. |
std::logic_error | If this ModuleContext is no longer valid. |
ServiceException | If the service type S is invalid or the service object is NULL. |
|
inline |
Registers the specified service object with the specified properties using the specified template argument with the framework.
This method is provided as a convenience when registering a service under two interface classes whose type is available to the caller. It is otherwise identical to RegisterService(const InterfaceMap&, const ServiceProperties&) but should be preferred since it avoids errors in the string literal identifying the class name or interface identifier.
Example usage:
I1 | The first interface type under which the service can be located. |
I2 | The second interface type under which the service can be located. |
impl | The service object or a ServiceFactory object. |
properties | The properties for this service. |
std::logic_error | If this ModuleContext is no longer valid. |
ServiceException | If the service type S is invalid or the service object is NULL. |
|
inline |
Registers the specified service object with the specified properties using the specified template argument with the framework.
This method is identical to the RegisterService<I1,I2,Impl>(Impl*, const ServiceProperties&) method except that it supports three service interface types.
I1 | The first interface type under which the service can be located. |
I2 | The second interface type under which the service can be located. |
I3 | The third interface type under which the service can be located. |
impl | The service object or a ServiceFactory object. |
properties | The properties for this service. |
std::logic_error | If this ModuleContext is no longer valid. |
ServiceException | If the service type S is invalid or the service object is NULL. |
|
inline |
Registers the specified service factory as a service with the specified properties using the specified template argument as service interface type with the framework.
This method is provided as a convenience when factory
will only be registered under a single class name whose type is available to the caller. It is otherwise identical to RegisterService(const InterfaceMap&, const ServiceProperties&) but should be preferred since it avoids errors in the string literal identifying the class name or interface identifier.
Example usage:
S | The type under which the service can be located. |
factory | The ServiceFactory or PrototypeServiceFactory object. |
properties | The properties for this service. |
std::logic_error | If this ModuleContext is no longer valid. |
ServiceException | If the service type S is invalid or the service factory object is NULL. |
|
inline |
Registers the specified service factory as a service with the specified properties using the specified template argument as service interface type with the framework.
This method is identical to the RegisterService<S>(ServiceFactory*, const ServiceProperties&) method except that it supports two service interface types.
Example usage:
I1 | The first interface type under which the service can be located. |
I2 | The second interface type under which the service can be located. |
factory | The ServiceFactory or PrototypeServiceFactory object. |
properties | The properties for this service. |
std::logic_error | If this ModuleContext is no longer valid. |
ServiceException | If the service type S is invalid or the service factory object is NULL. |
|
inline |
Registers the specified service factory as a service with the specified properties using the specified template argument as service interface type with the framework.
This method is identical to the RegisterService<S>(ServiceFactory*, const ServiceProperties&) method except that it supports three service interface types.
I1 | The first interface type under which the service can be located. |
I2 | The second interface type under which the service can be located. |
I3 | The third interface type under which the service can be located. |
factory | The ServiceFactory or PrototypeServiceFactory object. |
properties | The properties for this service. |
std::logic_error | If this ModuleContext is no longer valid. |
ServiceException | If the service type S is invalid or the service factory object is NULL. |
void ModuleContext::RemoveModuleListener | ( | const ModuleListener & | delegate | ) |
|
inline |
Removes the specified callback
from the context module's list of listeners.
If the (receiver,callback)
pair is not contained in this context module's list of listeners, this method does nothing.
R | The type of the receiver (containing the member function to be removed) |
receiver | The object from which to disconnect. |
callback | The member function pointer to remove. |
std::logic_error | If this ModuleContext is no longer valid. |
void ModuleContext::RemoveServiceListener | ( | const ServiceListener & | delegate | ) |
|
inline |
Removes the specified callback
from the context module's list of listeners.
If the (receiver,callback)
pair is not contained in this context module's list of listeners, this method does nothing.
R | The type of the receiver (containing the member function to be removed) |
receiver | The object from which to disconnect. |
callback | The member function pointer to remove. |
std::logic_error | If this ModuleContext is no longer valid. |
bool ModuleContext::UngetService | ( | const ServiceReferenceBase & | 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 modules'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 taken to unget the service object:
false
is returned. ServiceFactory
object, the ServiceFactory::UngetService method is called to release the service object for the context module. true
is returned. reference | A reference to the service to be released. |
false
if the context module's use count for the service is zero or if the service has been unregistered; true
otherwise. std::logic_error | If this ModuleContext is no longer valid. |