Developing Adapters 5.1.0 November 2013 This document applies to Apama 5.1.0 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 Software AG, Darmstadt, Germany and/or Software AG USA Inc., Reston, VA, USA, and/or Terracotta Inc., San Francisco, CA, USA, and/ or Software AG (Canada) Inc., Cambridge, Ontario, Canada, and/or, Software AG (UK) Ltd., Derby, United Kingdom, and/or Software A.G. (Israel) Ltd., Or- Yehuda, Israel 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://documentation.softwareag.com/legal/. Use of this software is subject to adherence to Software AG′s licensing conditions and terms. These terms are located at http://documentation.softwareag.com/ legal/ 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 and license terms, please refer to "License Texts, Copyright Notices and Disclaimers of Third Party Products." This document is located at http://documentation.softwareag.com/legal/ and/or in the root installation directory of the licensed product(s). Document ID: -Developing Adapters 5.1 20131107 Table of Contents Table of Contents Preface.......................................................................................................................................................................7 About this documentation...................................................................................................................................8 How this book is organized................................................................................................................................8 Documentation roadmap.................................................................................................................................... 9 Contacting customer support........................................................................................................................... 11 The Integration Adapter Framework........................................................................................................................13 Overview........................................................................................................................................................... 14 Architecture.......................................................................................................................................................14 The transport layer........................................................................................................................................... 16 The codec layer................................................................................................................................................17 The Semantic Mapper layer.............................................................................................................................17 Contents of the IAF..........................................................................................................................................18 Using the IAF...........................................................................................................................................................21 The IAF runtime................................................................................................................................................22 IAF Management – Managing a running adapter I..........................................................................................23 IAF Management options..........................................................................................................................24 IAF Management exit status..................................................................................................................... 26 IAF Client – Managing a running adapter II.................................................................................................... 26 IAF Watch – Monitoring running adapter status.............................................................................................. 27 The IAF configuration file................................................................................................................................. 28 Including other files................................................................................................................................... 29 Transport and codec plug-in configuration................................................................................................29 Event mappings configuration...................................................................................................................32 Apama event correlator configuration....................................................................................................... 40 Logging configuration (optional)................................................................................................................41 Java configuration (optional)..................................................................................................................... 42 IAF samples......................................................................................................................................................43 C/C++ Transport Plug-in Development................................................................................................................... 47 The C/C++ transport plug-in development specification..................................................................................48 Transport functions to implement..............................................................................................................48 Defining the transport function table.........................................................................................................51 The transport constructor, destructor and info functions...........................................................................55 Other transport definitions.........................................................................................................................56 Transport utilities....................................................................................................................................... 57 Communication with the codec layer........................................................................................................58 Transport Example............................................................................................................................................59 Getting started with transport layer plug-in development................................................................................ 59 C/C++ Codec Plug-in Development........................................................................................................................ 61 The C/C++ codec Plug-in Development Specification.....................................................................................62 Codec functions to implement...................................................................................................................62 Codec encoder functions................................................................................................................... 63 Developing Adapters 5.1.0 3 Table of Contents Codec decoder functions................................................................................................................... 65 Defining the codec function tables............................................................................................................66 The codec function table....................................................................................................................66 The codec encoder function table..................................................................................................... 67 The codec decoder function table..................................................................................................... 69 Registering the codec function tables................................................................................................70 The codec constructor, destructor and info functions...............................................................................71 Other codec definitions............................................................................................................................. 73 Codec utilities............................................................................................................................................ 74 Communication with other layers..............................................................................................................75 Working with normalised events............................................................................................................... 77 The AP_NormalisedEvent structure...................................................................................................78