Connecting Apama Applications to External Components Version 10.5.3 May 2020 This document applies to Apama 10.5.3 and to all subsequent releases. Specifications contained herein are subject to change and these changes will be reported in subsequent release notes or new editions. Copyright © 2013-2020 Software AG, Darmstadt, Germany and/or Software AG USA, Inc., Reston, VA, USA, and/or its subsidiaries and/or its affiliates and/or their licensors. The name Software AG and all Software AG product names are either trademarks or registered trademarks of Software AG and/or Software AG USA Inc. and/or its subsidiaries and/or its affiliates and/or their licensors. Other company and product names mentioned herein may be trademarks of their respective owners. Detailed information on trademarks and patents owned by Software AG and/or its subsidiaries is located at http://softwareag.com/licenses/. Use of this software is subject to adherence to Software AG's licensing conditions and terms. These terms are part of the product documentation, located at http://softwareag.com/licenses/ and/or in the root installation directory of the licensed product(s). This software may include portions of third-party products. For third-party copyright notices, license terms, additional rights or restrictions, please refer to "License Texts, Copyright Notices and Disclaimers of Third Party Products". For certain specific third-party license restrictions, please refer to section E of the Legal Notices available under "License Terms and Conditions for Use of Software AG Products / Copyright and Trademark Notices of Software AG Products". These documents are part of the product documentation, located at http://softwareag.com/licenses/ and/or in the root installation directory of the licensed product(s). Document ID: PAM-EXT-1053-20200525 Table of Contents About this Guide........................................................................................................................................9 Documentation roadmap................................................................................................................10 Online Information and Support...................................................................................................11 Data Protection.................................................................................................................................12 I Working with Connectivity Plug-ins.................................................................................................13 1 Getting Started with Connectivity Plug-ins..............................................................................15 Concepts....................................................................................................................................16 Adding the connectivity bundles..........................................................................................19 Specifying the main settings in the properties file..............................................................20 Specifying the settings for the connectivity chains in the YAML file...............................20 Controlling how the correlator interacts with a chain.......................................................21 Using codecs.............................................................................................................................21 Writing EPL..............................................................................................................................21 2 Using Connectivity Plug-ins........................................................................................................23 Overview of using connectivity plug-ins.............................................................................24 Static and dynamic connectivity chains...............................................................................26 Configuration file for connectivity plug-ins........................................................................26 Host plug-ins and configuration...........................................................................................30 Translating EPL events using the apama.eventMap host plug-in....................................32 Using reliable transports.........................................................................................................33 Creating dynamic chains from EPL......................................................................................37 Sending and receiving events with connectivity plug-ins.................................................38 Deploying plug-in libraries....................................................................................................40 3 Developing Connectivity Plug-ins..............................................................................................41 Chain components and messages..........................................................................................42 Requirements of a plug-in class.............................................................................................43 Requirements of a transport chain manager plug-in class................................................47 Building plug-ins.....................................................................................................................49 C++ data types..........................................................................................................................51 Map contents used by the apama.eventMap host plug-in................................................54 Metadata values.......................................................................................................................58 Lifetime of connectivity plug-ins...........................................................................................59 Creating dynamic chains from a chain manager plug-in..................................................62 User-defined status reporting from connectivity plug-ins................................................63 Logging and configuration.....................................................................................................65 Threading..................................................................................................................................66 Developing reliable transports..............................................................................................67 General notes for developing transports..............................................................................70 II Standard Connectivity Plug-ins........................................................................................................71 4 The Universal Messaging Transport Connectivity Plug-in.....................................................73 About the Universal Messaging transport...........................................................................74 Overview of using Universal Messaging in Apama applications....................................74 Connecting Apama Applications to External Components 10.5.3 iii Table of Contents Setting up Universal Messaging for use by Apama...........................................................81 Configuring the Universal Messaging connectivity plug-in.............................................82 EPL and Universal Messaging channels..............................................................................91 Using Universal Messaging connectivity from EPL...........................................................91 Monitoring Apama application use of Universal Messaging...........................................92 5 The MQTT Transport Connectivity Plug-in..............................................................................93 About the MQTT transport....................................................................................................94 Using MQTT connectivity from EPL....................................................................................94 Loading the MQTT transport.................................................................................................95 Configuring the connection to MQTT..................................................................................95 Mapping events between MQTT messages and EPL.........................................................97 Payload for the MQTT message.............................................................................................98 Wildcard topic subscriptions.................................................................................................98 Metadata for the MQTT message..........................................................................................98 Restrictions...............................................................................................................................99 6 The Digital Event Services Transport Connectivity Plug-in..................................................101 About the Digital Event Services transport.......................................................................102 Using Digital Event Services connectivity from EPL.......................................................103 Reliable messaging with Digital Event Services...............................................................104 7 The HTTP Server Transport Connectivity Plug-in.................................................................107 About the HTTP server transport........................................................................................108