2.3.2 Enterprise Message API Provider Architecture
The Enterprise Message API provider incorporates the Value Added (VA) Reactor component from the EnterpriseTransport API, which provides transport-level functionality. The Enterprise Message API wraps the reactor component in its own class of OmmProvider. OmmProvider provides interfaces to submit item messages as well as handling login, directory, and dictionary domains (depending on Enterprise Message API’s specific provider role). To complete the set of provider functionalities, the OmmProvider class provides the dispatch() method. Depending on its design and configuration, an application might need to call this method to dispatch received messages. The provider configuration class (i.e., OmmNiProviderConfig or OmmIProviderConfig) class configures both the reactor and OmmProvider.
Enterprise Message API sends incoming messages to the application using the OmmProviderClient callback mechanism. To receive and process messages, the application needs to implement a class that inherits from the OmmProviderClient class. By default, OmmProviderClient callback methods are executed in Enterprise Message API's thread of control. However, you can use either the OmmNiProviderConfig::operationModel() or OmmIProviderConfig::operationModel() interface to execute callback methods on the application’s thread, in which case the application must also call the OmmProvider::dispatch() method to dispatch received messages.
While the OmmProvider class throws an OmmException to report error conditions, the OmmProviderErrorClient class provides an alternate reporting mechanism via callbacks. To use the alternate error reporting, pass the OmmProviderErrorClient on the constructor of the OmmProvider class, which switches the error reporting from exception throwing to callbacks. In addition to its error-reporting mechanisms, Enterprise Message API provides a logger mechanism which you can use to monitor Enterprise Message API behavior and debug any issues that arise.
An Enterprise Message API provider must always have at least one thread, which is implemented by the VA Reactor and runs the internal, VA Reactor logic. For details on this thread, refer to the Transport API C++ Edition Value Added Component Developers Guide. Additionally, you can configure Enterprise Message API to create a second internal thread over which to dispatch received messages:
• For non-interactive providers, set the OmmNiProviderConfig operation model to OmmNiProviderConfig::ApiDispatchEnum. If the operation model is set to OmmNiProviderConfig::UserDispatchEnum, Enterprise Message API will not run a second thread.
• For interactive providers, set the OmmIProviderConfig operation model to OmmIProviderConfig::ApiDispatchEnum. If the operation model is set to OmmIProviderConfig::UserDispatchEnum, Enterprise Message API will not run a second thread.
Without running a second thread, the application is responsible for calling the OmmProvider::dispatch() method to dispatch all received messages.
The Enterprise Message API provider includes an internal, hard-coded, and configurable initial source directory refresh message. The application can either use the internal hard-coded source directory, configure its own internal one via the EmaConfig.xml file, or programmatically create one and/or disable the internal one. To disable the internal source directory message:
• When running Enterprise Message API as a non-interactive provider: the application must set OmmNiProviderConfig::UserControlEnum through the OmmNiProviderConfig::adminControlDirectory() method.
• When running Enterprise Message API as an interactive provider: the application must set OmmIProviderConfig::UserControlEnum through the OmmIProviderConfig::adminControlDirectory() method. Additionally, you can configure the ability to disable internal dictionary responses by setting OmmIProviderConfig::UserControlEnum through the OmmIProviderConfig::adminControlDictionary() method.
NOTE: If the user control is enabled, the application is responsible for sending the response messages.
An Enterprise Message API provider also supports the programmatic configuration of a source directory refresh of dictionary information, which overrides any configuration in EmaConfig.xml. To programmatically configure a source directory refresh:
• When running Enterprise Message API as a non-interactive provider: the application must set OmmNiProviderConfig::ApiControlEnum through the OmmNiProviderConfig::adminControlDirectory() method. An Enterprise Message API non-interactive provider does not support programmatically configuring dictionary information.
• When running Enterprise Message API as an interactive provider: the application must set OmmIProviderConfig::ApiControlEnum through the OmmIProviderConfig::adminControlDirectory() method. Additionally, you can programmatically configure dictionary information, which overrides any dictionary information defined from EmaConfig.xml. To programmatically configure dictionary information, set OmmIProviderConfig::ApiControlEnum through the OmmIProviderConfig::adminControlDictionary() method.