Apama 10.5.3 | Release Notes | What's New In Apama 10.0 | Connectivity plug-ins enhancements in 10.0
 
Connectivity plug-ins enhancements in 10.0
Apama 10.0 includes the following connectivity plug-ins enhancements.
Reliable messaging
*Connectivity plug-ins can now perform reliable messaging. If you have done APP_CONTROLLED reliable messaging with the Java Message Service (JMS) before, then doing the same with connectivity plug-ins will look very similar. Your old way of doing acknowledgments and flushes in EPL will be quite easy to translate across to the new way of doing this with connectivity plug-ins. For more information, see Using reliable transports.
If you want to write your own transport that supports reliable messaging, see Developing reliable transports.
*The Digital Event Services transport connectivity plug-in now supports reliable sending and receiving of events. For more information, see Reliable messaging with Digital Event Services.
*A new metadata value, sag.messageId, is now available. This is used for reliable receiving. For more information, see Metadata values.
User-defined status reporting
Connectivity plug-ins can now add any number of user-defined status values which are reported as part of the correlator's status information from the REST API, the engine_watch tool, the EngineClient API, and from the EPL Management interface. If the status keys follow the conventions listed in Monitoring the KPIs for EPL applications and connectivity plug-ins, the status and KPIs of your application's connectivity plug-ins can be displayed by Command Central. For more information about how to report status, see User-defined status reporting from connectivity plug-ins. See also the samples\connectivity_plugin\cpp\httpclient and samples\connectivity_plugin\java\HTTPServer directories of your Apama installation for examples of how to report status information from a connectivity plug-in.
Message metadata support for non-string values
The message metadata can now also store non-string values. With previous versions, it was allowed to only store string keys and values.
In both C++ and Java Message implementations, the getMetadataMap() function has been added which returns a view on the metadata which can contain non-string values (map_t for C++ and Map<String,Object> for Java). The getMetadata() function still exists, but is deprecated.
While the changes for Java maintain backwards compatibility for users of the getMetadata() function, the changes for C++ do not. For C++, the metadata_t iterator's key() and value() functions have been changed to return std::string instead of const char*. Only stringifiable values (bool, integer, double, decimal) can be obtained by calling value(), otherwise an exception is thrown. Moreover, for C++, the metadata operator[] has been changed such that it returns std::string instead of const char*. To access the full set of types in C++ metadata, use the new getMetadataMap() function instead.
For the existing connectivity plug-ins (such as the Mapper codec and Classifier codec), the assumption has been removed that only string keys and values can be stored into the metadata.
For more information, see Metadata values.
New dynamic chain managers API
Connectivity chains can be created in three different ways:
*Statically using the startChains section of a YAML file.
*Dynamically by an explicit EPL call to ConnectivityPlugins.createChain.
*Dynamically by a connectivity plug-in. For example, a plug-in could create a chain in response to an EPL application subscribing or sending to a channel with a specific name or prefix.
In the previous release, it was not possible for user-defined connectivity plug-ins to dynamically manage chain creation, although some standard plug-ins shipped with the product (such as Universal Messaging and Digital Event Services) made use of this capability. In 10.0, there is a new chain manager API providing the ability for user-defined plug-ins written in Java to manage chains. In this release, it is not yet possible to do this from C++ plug-ins (it's only Java right now).
A transport plug-in that manages its own chains must provide a subclass of com.softwareag.connectivity.chainmanagers.AbstractChainManager which can create and destroy chains whenever it wishes, by instantiating any dynamic chain definition in the configuration files that contain the transport plug-in managed. A chain manager can register a listener that is notified whenever a new channel is used for the first time by the Apama EPL application, that is, when the application subscribes or sends to a channel, which it can use to create a new chain to send/receive using that channel as needed.
For more information about configuring transport connectivity plug-ins that have a dynamic chain manager for use in your project, see Configuration file for connectivity plug-ins.
For more information about how to create a dynamic chain manager transport plug-in, see Static and dynamic connectivity chains.
Miscellaneous connectivity framework changes
*For Java, it is now also possible to set the classpath by defining a semicolon-delimited list of strings in the configuration file. See also Configuration file for connectivity plug-ins.
*A new helper class called com.softwareag.connectivity.util.MapExtractor is available in the Java API. This class provides an easy and type-safe way to extract values from maps such as those used for plug-in configuration. It has automatic support for generating user-friendly error messages if configuration items are missing or of the wrong type. See the API Reference for Java (Javadoc) for further information.
Enhancements and additions to standard connectivity plug-ins
*A new standard connectivity plug-in, the String codec, is now available. It can be used to translate string payloads to binary payloads, and vice versa. For detailed information, see The String codec connectivity plug-in.
*A C++ implementation of the JSON codec is now available. It behaves in the same way as the already existing Java implementation of that codec. For more information, see The JSON codec connectivity plug-in.
*The JSON codec now has an additional configuration parameter filterOnContentType which allows it to ignore messages which are not encoded with the application/json content type. For more information, see The JSON codec connectivity plug-in.
*The Mapper codec has been enhanced as follows:
*With the defaultValue action, an empty or null value is now treated in the same way as an unset value.
*It is now possible to set metadata or payload fields to lists or maps and top-level payloads to maps, in addition to setting them to strings.
*A new copyFrom action is available. This new action is exactly the same as the mapFrom action except that the source field is not removed after the copy.
For more information, see The Mapper codec connectivity plug-in.
*The Mapper and Classifier codecs can now contain a period (.) for both payload and metadata rules. These correspond to nested maps. Mapper rules for built-in codecs and transports will continue to work without changes, but a mapper which is setting a metadata field containing a period will now produce a nested map structure. Custom codecs and transports may need changes to support this. See also The Mapper codec connectivity plug-in and The Classifier codec connectivity plug-in.
*When mapping nEventProperties to metadata, the Universal Messaging transport connectivity plug-in now uses the prefix um.properties. You can use the Mapper codec to enable the original behavior. In addition, the ability to set nEventProperties while also sending a binary payload has been added. To do this, set um.properties.Key=Value in the metadata. See also Supported payloads.
*With previous versions, only the host that created a Universal Messaging channel was able to publish to the channel created by Apama. As of this version, it is possible to specify ACL permissions for channels that are automatically created by Apama. This can be done by specifying the new createChannelPermissions option in the YAML configuration file for the Universal Messaging connectivity plug-in. See Configuring the connection to Universal Messaging (dynamicChainManagers). This behavior has also been changed in the deprecated native Universal Messaging integration.