|
| | ~ModuleContext () |
| |
| Module * | GetModule () const |
| |
| Module * | GetModule (long id) const |
| |
| Module * | GetModule (const std::string &name) |
| |
| std::vector< Module * > | GetModules () const |
| |
| ServiceRegistrationU | RegisterService (const InterfaceMap &service, const ServiceProperties &properties=ServiceProperties()) |
| |
| template<class S > |
| ServiceRegistration< S > | RegisterService (S *service, const ServiceProperties &properties=ServiceProperties()) |
| |
| template<class I1 , class I2 , class Impl > |
| ServiceRegistration< I1, I2 > | RegisterService (Impl *impl, const ServiceProperties &properties=ServiceProperties()) |
| |
| template<class I1 , class I2 , class I3 , class Impl > |
| ServiceRegistration< I1, I2, I3 > | RegisterService (Impl *impl, const ServiceProperties &properties=ServiceProperties()) |
| |
| template<class S > |
| ServiceRegistration< S > | RegisterService (ServiceFactory *factory, const ServiceProperties &properties=ServiceProperties()) |
| |
| template<class I1 , class I2 > |
| ServiceRegistration< I1, I2 > | RegisterService (ServiceFactory *factory, const ServiceProperties &properties=ServiceProperties()) |
| |
| template<class I1 , class I2 , class I3 > |
| ServiceRegistration< I1, I2, I3 > | RegisterService (ServiceFactory *factory, const ServiceProperties &properties=ServiceProperties()) |
| |
| std::vector< ServiceReferenceU > | GetServiceReferences (const std::string &clazz, const std::string &filter=std::string()) |
| |
| template<class S > |
| std::vector< ServiceReference< S > > | GetServiceReferences (const std::string &filter=std::string()) |
| |
| ServiceReferenceU | GetServiceReference (const std::string &clazz) |
| |
| template<class S > |
| ServiceReference< S > | GetServiceReference () |
| |
| void * | GetService (const ServiceReferenceBase &reference) |
| |
| InterfaceMap | GetService (const ServiceReferenceU &reference) |
| |
| template<class S > |
| S * | GetService (const ServiceReference< S > &reference) |
| |
| template<class S > |
| ServiceObjects< S > | GetServiceObjects (const ServiceReference< S > &reference) |
| |
| bool | UngetService (const ServiceReferenceBase &reference) |
| |
| 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()) |
| |
| template<class R > |
| void | RemoveServiceListener (R *receiver, void(R::*callback)(const ServiceEvent)) |
| |
| template<class R > |
| void | AddModuleListener (R *receiver, void(R::*callback)(const ModuleEvent)) |
| |
| template<class R > |
| void | RemoveModuleListener (R *receiver, void(R::*callback)(const ModuleEvent)) |
| |
| std::string | GetDataFile (const std::string &filename) const |
| |
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:
-
Subscribe to events published by the framework.
-
Register service objects with the framework service registry.
-
Retrieve
ServiceReferences from the framework service registry.
-
Get and release service objects for a referenced service.
-
Get the list of modules loaded in the framework.
-
Get the Module object for a module.
A ModuleContext object will be created and provided to the module associated with this context when it is loaded using the us::ModuleActivator::Load method. The same ModuleContext object will be passed to the module associated with this context when it is unloaded using the us::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.
Definition at line 91 of file usModuleContext.h.
template<class R >
| void ModuleContext::AddModuleListener |
( |
R * |
receiver, |
|
|
void(R::*)(const ModuleEvent) |
callback |
|
) |
| |
|
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.
- Template Parameters
-
| R | The type of the receiver (containing the member function to be called) |
- Parameters
-
| receiver | The object to connect to. |
| callback | The member function pointer to call. |
- Exceptions
-
- See also
- ModuleEvent
Definition at line 786 of file usModuleContext.h.
template<class R >
| void ModuleContext::AddServiceListener |
( |
R * |
receiver, |
|
|
void(R::*)(const ServiceEvent) |
callback, |
|
|
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 us::ServiceConstants::OBJECTCLASS() property. If filter is empty, all services are considered to match the filter.
When using a filter, it is possible that the ServiceEvents 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.
- Template Parameters
-
| R | The type of the receiver (containing the member function to be called) |
- Parameters
-
| receiver | The object to connect to. |
| callback | The member function pointer to call. |
| filter | The filter criteria. |
- Exceptions
-
| std::invalid_argument | If filter contains an invalid filter string that cannot be parsed. |
| std::logic_error | If this ModuleContext is no longer valid. |
- See also
- ServiceEvent
-
RemoveServiceListener()
Definition at line 739 of file usModuleContext.h.
| 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:
-
If the service has been unregistered,
0 is returned.
-
The context module's use count for this service is incremented by one.
-
If the context module's use count for the service is currently one and the service was registered with an object implementing the
ServiceFactory interface, the us::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.
If the ServiceFactory object throws an exception, 0 is returned and a warning is logged.
-
The service object for the service is returned.
- Parameters
-
| reference | A reference to the service. |
- Returns
- A service object for the service associated with
reference or 0 if the service is not registered or the ServiceFactory threw an exception.
- Exceptions
-
| std::logic_error | If this ModuleContext is no longer valid. |
| std::invalid_argument | If the specified ServiceReferenceBase is invalid (default constructed). |
- See also
- UngetService(const ServiceReferenceBase&)
-
ServiceFactory
| 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 us::ServiceConstants::SERVICE_RANKING() property) is returned.
If there is a tie in ranking, the service with the lowest service ID (as specified in its us::ServiceConstants::SERVICE_ID() property); that is, the service that was registered first is returned.
- Parameters
-
| clazz | The class name with which the service was registered. |
- Returns
- A
ServiceReference object, or an invalid ServiceReference if no services are registered which implement the named class.
- Exceptions
-
| std::logic_error | If this ModuleContext is no longer valid. |
| ServiceException | If no service was registered under the given class name. |
- See also
- GetServiceReferences(const std::string&, const std::string&)
| 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:
-
If the specified class name,
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 us::ServiceConstants::OBJECTCLASS() property.
-
If the specified
filter is not empty, the filter expression must match the service.
- Parameters
-
| 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. |
- Returns
- A list of
ServiceReference objects or an empty list if no services are registered which satisfy the search.
- Exceptions
-
| 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. |
template<class I1 , class I2 , class Impl >
| ServiceRegistration<I1,I2> ModuleContext::RegisterService |
( |
Impl * |
impl, |
|
|
const ServiceProperties & |
properties = ServiceProperties() |
|
) |
| |
|
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:
class MyService2 : public InterfaceA, public InterfaceB
{};
MyService2* myService = new MyService2;
context->RegisterService<InterfaceA, InterfaceB>(myService);
- Template Parameters
-
| I1 | The first interface type under which the service can be located. |
| I2 | The second interface type under which the service can be located. |
- Parameters
-
| impl | 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.
- Exceptions
-
| std::logic_error | If this ModuleContext is no longer valid. |
| ServiceException | If the service type S is invalid or the service object is nullptr. |
- See also
- RegisterService(const InterfaceMap&, const ServiceProperties&)
Definition at line 266 of file usModuleContext.h.
template<class I1 , class I2 , class I3 , class Impl >
| ServiceRegistration<I1,I2,I3> ModuleContext::RegisterService |
( |
Impl * |
impl, |
|
|
const ServiceProperties & |
properties = ServiceProperties() |
|
) |
| |
|
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.
- Template Parameters
-
| 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. |
- Parameters
-
| impl | 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.
- Exceptions
-
| std::logic_error | If this ModuleContext is no longer valid. |
| ServiceException | If the service type S is invalid or the service object is nullptr. |
- See also
- RegisterService(const InterfaceMap&, const ServiceProperties&)
Definition at line 295 of file usModuleContext.h.
template<class I1 , class I2 >
| ServiceRegistration<I1,I2> ModuleContext::RegisterService |
( |
ServiceFactory * |
factory, |
|
|
const ServiceProperties & |
properties = ServiceProperties() |
|
) |
| |
|
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:
class MyService2 : public InterfaceA, public InterfaceB
{};
class MyServiceFactory : public ServiceFactory
{
{
MyService2* myService = new MyService2;
return MakeInterfaceMap<InterfaceA,InterfaceB>(myService);
}
{
delete ExtractInterface<InterfaceA>(service);
}
};
MyServiceFactory* myServiceFactory = new MyServiceFactory;
context->RegisterService<InterfaceA,InterfaceB>(static_cast<ServiceFactory*>(myServiceFactory));
- Template Parameters
-
| I1 | The first interface type under which the service can be located. |
| I2 | The second interface type under which the service can be located. |
- Parameters
-
| factory | The ServiceFactory or PrototypeServiceFactory 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.
- Exceptions
-
| std::logic_error | If this ModuleContext is no longer valid. |
| ServiceException | If the service type S is invalid or the service factory object is nullptr. |
- See also
- RegisterService(const InterfaceMap&, const ServiceProperties&)
Definition at line 360 of file usModuleContext.h.
template<class I1 , class I2 , class I3 >
| ServiceRegistration<I1,I2,I3> ModuleContext::RegisterService |
( |
ServiceFactory * |
factory, |
|
|
const ServiceProperties & |
properties = ServiceProperties() |
|
) |
| |
|
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.
- Template Parameters
-
| 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. |
- Parameters
-
| factory | The ServiceFactory or PrototypeServiceFactory 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.
- Exceptions
-
| std::logic_error | If this ModuleContext is no longer valid. |
| ServiceException | If the service type S is invalid or the service factory object is nullptr. |
- See also
- RegisterService(const InterfaceMap&, const ServiceProperties&)
Definition at line 389 of file usModuleContext.h.
| 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:
-
If the context module's use count for the service is zero or the service has been unregistered,
false is returned.
-
The context module's use count for this service is decremented by one.
-
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 method is called to release the service object for the context module.
-
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.
- Exceptions
-
- See also
- GetService
-
ServiceFactory
1.8.17