PUBLIC SAP Data Services Document Version: 4.2 Support Package 5 (14.2.5.0) – 2015-05-05 User Guide for Adapter SDK Content 1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.1 Audience and assumptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.2 Related documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.3 Installation contents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.4 Naming Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 2 Adapter SDK Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9 2.1 Adapter SDK components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.2 Installation details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.3 After installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.4 Establishing adapter management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Configuring a Job Server for adapter management on Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . .11 Configuring a Job Server for adapter management on UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 3 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3.1 Adapters and information resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Information resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Adapters and front-end applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Adapters and back-office systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Adapter types and capabilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 3.2 Adapters in the Data Services platform. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Custom adapter usage examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Adapters in the Data Services architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Adapters and Job Servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 3.3 Flexible adapter architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 3.4 Adapter component model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Component overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 System-defined components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 User-defined components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20 3.5 The Adapter SDK API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 com.acta.adapter.sdk. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 com.acta.metadata. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27 Interfaces implemented by the Adapter SDK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28 Interfaces implemented by adapter writers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 3.6 Operation exchange models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Message-oriented exchange model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Stream-oriented exchange model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 2 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Content 3.7 Adapters and operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 3.8 Basic operation models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Interaction style. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Interface styles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34 Basic operation types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 3.9 Adapter start-up sequence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38 Adapter operation execution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 3.10 Adapters in the Data Services Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Data flow sends a message to an adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Adapter invokes real-time service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 3.11 Adapter administration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 4 Creating an Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 4.1 Preliminary considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Determine integration issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Understand your information resource. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 Plan adapter components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 Plan adapter operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 4.2 Write your custom adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46 Adapter writer checklist. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Create an Adapter component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48 Create a Session component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Create Metadata Node component(s). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Create a Metadata Browsing component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Create Metadata Import component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Create an Operation component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Customize presentation of adapter components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Error handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Trace and error logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Statistics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 4.3 Create adapter user documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 4.4 Adapter operation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Compile and package adapter components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78 Prepare configuration templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Configure adapter instance components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Debug the adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Moving the adapter from test to production. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Moving a production adapter to another environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 5 Packaging and deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 6 Configuring and Running an Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 User Guide for Adapter SDK Content PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 3 6.1 Adapter configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Preparing configuration templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Configuring an adapter instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Configuring an adapter operation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 6.2 Starting the Adapter SDK driver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Starting an adapter using the command prompt. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 7 TestAdapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 7.1 Understanding TestAdapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 7.2 TestAdapter and associated files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 7.3 TestAdapter source code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 7.4 Preparing and testing TestAdapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Populate the Data Services repository. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Configure real-time services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Configure adapter (start-up and run-time). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Configuring operations for TestAdapterInstance in the Administrator. . . . . . . . . . . . . . . . . . . . . . . 99 Starting the adapter instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Creating the TestAdapter datastore. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Testing browse and import metadata capabilites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Importing TestAdapter metadata by name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Other options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Starting real-time services for TestAdapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Verify message-oriented adapter operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Verify stream-oriented adapter operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 8 Debugging in Eclipse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 8.1 Debugging in Eclipse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 4 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Content 1 Introduction SAP is committed to providing an open architecture that enables customers and partners to seamlessly integrate the Data Services Platform and its processes with non-SAP and other data and processes. Data Services interfaces use adapters to accomplish this objective. The Data Services Adapter Software Development Kit (SDK) contains tools for creating adapters that integrate Data Services with “information resources” (IRs). An information resource is a producer or consumer of enterprise information. Information resources range from flat files and back-office applications to EAI systems and Web applications. This version of the Adapter SDK provides tools for creating full-capability adapters that support Data Services batch and real-time operations beyond message-oriented operations. This user guide provides Data Services Adapters relationship framework information, instructions to help you install the Adapter SDK, and guidelines for writing full-capability adapters. 1.1 Audience and assumptions This document assumes that you have: ● Access to an Data Services documentation set that is compatible with this version of the Data Services Adapter SDK. ● A basic understanding of how the Data Services Designer is used to design data flows. (To use an adapter, a data flow must contain adapter-related transforms or must use real-time job services.) ● A basic understanding of how the Data Services Management Console Administrator is used to administer Data Services processes. (Adapters are administered from the Data Services Administrator only.) ● Experience writing Java applications in Java programming language. 1.2 Related documentation Table 1: Documentation Description Adapter SDK API documentation The companion to this book, the online API documentation contains detailed information necessary for writing Data Services adapters. After you install the Adapter SDK, you can find the online API documentation in the following location: User Guide for Adapter SDK Introduction ● Windows: <DS_COMMON_DIR>\adapters\sdk\doc\API\index.html ● UNIX: <LINK_DIR>/adapters/sdk/doc/API/index.html PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 5 Documentation Description Data Services documentation Data Services comes with a complete documentation set that describes the Data Services suite of related applications and features. To learn about designing batch and real-time data flows, see the Designer Guide. To learn about administering Data Services processes, see the Administrator Guide 1.3 Installation contents This version of the Data Services Adapter SDK includes: ● Adapter SDK API documentation ● Java libraries to support the Adapter SDK ● Test adapter (basic full-function adapter) with source code and step-by-step instructions on how to use it ● User Guide for Adapter SDK (published in PDF format) 1.4 Naming Conventions In this documentation, the following naming conventions apply: Terminology ● “Data Services system” refers to “SAP Data Services”. ● “BI platform” refers to “SAP BusinessObjects BI platform”. Note The BI platform components required by Data Services may also be provided by SAP BusinessObjects Information platform services (IPS). ● “CMC” refers to the Central Management Console provided by the BI or IPS platform. ● “CMS” refers to the Central Management Server provided by BI or IPS platform. 6 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Introduction Variables Table 2: Variables Description <INSTALL_DIR> The installation directory for the SAP software. Default location: ● For Windows: C:\Program Files (x86)\SAP BusinessObjects ● For UNIX: $HOME/sap businessobjects <BIP_INSTALL_DIR The root directory of the BI or IPS platform. > Default location: ● For Windows: <INSTALL_DIR>\SAP BusinessObjects Enterprise XI 4.0 ● For UNIX:<INSTALL_DIR>/enterprise_xi40 Note These paths are the same for both the SAP BusinessObjects BI platform and SAP BusinessObjects Information platform services. <LINK_DIR> The root directory of the Data Services system. Default location: ● All platforms <INSTALL_DIR>/Data Services This system environment variable is created automatically during installation. <DS_COMMON_DIR> The common configuration directory for the Data Services system. Default location: ● Windows (Vista and newer) ALLUSERSPROFILE\SAP BusinessObjects\Data Services ● Windows (Older versions) ALLUSERSPROFILE\Application Data\SAP BusinessObjects\Data Services ● UNIX systems (for compatibility) <LINK_DIR> This system environment variable is created automatically during installation. User Guide for Adapter SDK Introduction PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 7 Variables Description <DS_USER_DIR> The user-specific configuration directory for the Data Services system. Default location: ● Windows (Vista and newer) USERPROFILE\AppData\Local\SAP BusinessObjects\Data Services ● Windows (Older versions) USERPROFILE\Local Settings\Application Data\SAP BusinessObjects \Data Services This user environment variable is created automatically during installation. Note This variable is used only for Data Services client applications on Windows, such as the Designer. <DS_USER_DIR> is not used on UNIX platforms. 8 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Introduction 2 Adapter SDK Installation 2.1 Adapter SDK components Adapter SDK components include: ● Adapter SDK API documentation. ● Adapter SDK library — acta_adapter_sdk.jar (also called “Adapter run-time jar file”). ○ Interfaces for the adapter components. ○ Supporting classes. ○ Adapter container — This unexposed adapter container instantiates and manages objects for the adapter component classes. ○ Adapter driver — This unexposed adapter driver is the executable java code that creates an instance of the adapter container. ● The broker client — acta_broker_client.jar ● Third party libraries — xerces.jar (the XML parser) ● A test adapter you can use as a design template — acta_test_adapter.jar ● Utilities to support the Adapter SDK — acta_tool.jar ● User Guide for Adapter SDK — This book. Instructions for using the test adapter are included in this document. 2.2 Installation details You can install the Adapter SDK on both Windows and UNIX operating systems. For both Windows and UNIX, the Adapter SDK is installed during a normal Data Services installation. During the Data Services installation procedure, need to select the Message Client component. 2.3 After installation After installing the Adapter SDK on your computer, you should have the following primary directories and files: User Guide for Adapter SDK Adapter SDK Installation PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 9 Table 3: Directory Description adapters This directory contains all information related to adapter start-up and run-time. Besides containing sev­ eral sub-directories, this directory contains the following files: ● AdapterInstallationTemplate.xml: This XML file is a generic template for creating your ● startup_script.xml: This XML start-up script is automatically generated when you run an own adapter start-up installation template adapter for the first time, and automatically updated each time you configure, update, or remove the adapter instance. It contains an entry for each adapter instance configured on the computer where it resides. This file does not appear during initial Adapter SDK installation because no adapter instan­ ces are configured yet. ● rtt.bat: (rtt.sh on UNIX) This is the batch file that generates the adapter run-time configura­ tion template. This directory contains the following software files: lib ● acta_adapter_admin.jar ● acta_adapter_sdk.jar ● acta_broker_client.jar ● acta_test_adapter.jar ● acta_tool.jar Inside the adapters directory, you should have the following sub-directories and associated files: Table 4: Directory Description config For each adapter instance configured on this computer, this sub-directory contains an XML run-time configuration script for that instance. The naming convention for script files is: <adapter_instance_name>.xml. config/ templates For each adapter installed on this computer, this sub-directory contains an XML run-time template re­ lated to that adapter. The naming convention for template files is: <adapter_name>.xml. The scripts in the config sub-directory are generated based on these templates (described below). During initial installation, this directory contains only the TestAdapter.xml run-time template for the test adapter. install Files in this sub-directory are start-up installation templates used by the Data Services Administrator to create the start-up script entry in the startup_script.xml file. This sub-directory contains one XML descriptor file for each installed adapter. The naming convention for descriptor files is <adapter_name>.xml. During initial installation, this directory contains only the TestAdapter.xml descriptor file for the test adapter. This sub-directory is generated automatically when you run an adapter for the first time. It contains up to two (trace and error) log files for each running adapter instance. The naming convention for these log files is <adapter_instance_name>_trace.txt for trace files and log <adapter_instance_name>_error.txt for error files.During initial installation, this directory is empty. sdk/doc/API This directory contains the Adapter SDK API documentation. Open index.html to view the online documentation. sdk/samples 10 This directory contains all information related to the sample adapter included with the Adapter SDK (TestAdapter) and includes the testadapter sub-directory. PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Adapter SDK Installation Directory Description sdk/samples/ testadapter This directory contains batch files, XML documents, DTD files, and the ATL file used by the test adapter as well as the data subdirectory. sdk/samples/ testadapter/ data This directory contains a session data sub-directory (Session1), the sample adapter source file subdirectory (src), and files that TestAdapter uses to demonstrate message-oriented adapter operations. sdk/samples/ testadapter/ data/session1 This directory contains the data files that TestAdapter uses to demonstrate metadata browsing, met­ adata import, and stream-oriented adapter operations. sdk/samples/ This directory contains the sub-directory structure: com/acta/adapter/testadapter. This testadapter/src testadapter sub-directory contains all the java source files used to create TestAdapter. In the <LINK_DIR>/ext/ directory, you should also find the Java Run-Time environment and additional library used by the Adapter SDK (LINK_DIR/ext/lib/xerces.jar and <LINK_DIR> /ext/lib/roguewave.jar). 2.4 Establishing adapter management Before or after installing the Adapter SDK on a computer, you must configure a repository and a Job Server for adapter management. Note You cannot configure or use a Data Services adapter (including the sample TestAdapter) unless adapter management is established. 2.4.1 Configuring a Job Server for adapter management on Windows Choose a Job Server to perform adapter management per computer. The adapter management Job Server brokers messages between Data Services and all adapter instances on that computer. 1. On a Windows operating system, choose Start Programs SAP Data Services 4.2 Server Manager . 2. In the Data Services Server Manager, click the Edit Job Server Config button. 3. In the Job Server Configuration Editor window, do one of the following: ○ Click Add to configure a new a job server ○ Click to select a Job Server already listed, then click Edit. The Job Server Properties window opens. 4. Besides adding/editing the Job Server name, port number, and associated repository information, click to mark the Enable adapter and message broker communication check box. 5. You may need to re-synchronize your Job Server/repository configuration. If so, click the Resync button. You must re-synchronize your Job Server and repository when: User Guide for Adapter SDK Adapter SDK Installation PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 11 ○ You uninstall Data Services then reinstall the same Data Services version without creating a new repository. ○ You create a new repository using the Repository Manager after Data Services is installed. If you re-synchronize a Job Server/repository configuration, you must reassociate this repository with the Administrator and the metadata reporting tool. See the Data Services Administrator Guide for more information. 6. Click OK to save the adapter management setting and return to the Job Server Configuration Editor. Note If another Job Server on this computer is already configured to manage adapters, a warning message appears to let you know that Data Services cannot save your adapter management configuration for the second Job Server. To configure another Job Server for adapter management, you must first de-select the Enable adapter and message broker communication check box for the existing adapter management Job Server. 7. Click OK to return to the Data Services Server Manager window. 8. Click Restart to close the window and restart Data Services services on the computer. 2.4.2 Configuring a Job Server for adapter management on UNIX Choose a Job Server to perform adapter management per computer. The adapter management Job Server brokers messages between Data Services and all adapter instances on that computer. 1. Change directory to <LINK_DIR>/bin. Run the command: $ . ./al_env.sh. 2. Run svrcfg tool. 3. Select Configure Job Server. You can edit an existing Job Server or create a new Job Server. 4. After adding/editing a Job Server configuration, you may need to re-synchronize your Job Server/repository configuration. If so, choose the Resync option. You must re-synchronize your Job Server and repository when: ○ You uninstall Data Services then reinstall the same Data Services version without creating a new repository. ○ You create a new repository using the Repository Manager after Data Services is installed. 5. If you re-synchronize a Job Server/repository configuration, you must reassociate this repository with the Administrator and the metadata reporting tool. See the Managment Console Guide for more information. 12 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Adapter SDK Installation 3 Overview 3.1 Adapters and information resources Each Data Services Adapter is an application you create using the Data Services Adapter SDK. Data Services Adapters are part of the Data Services platform and integrate "information resources" — source or target applications—with Data Services. Each adapter integrates an information resource with the Data Services platform by communicating with that resource and translating the resource's information into a format that the Data Services message broker and the Data Services platform can understand. Data Services adapters can also publish information from the data platform to the resource in a format that the information resource understands. 3.1.1 Information resources Today, information resources are used for in-house data analysis, sell-side e-commerce, supply chain management, customer relationship management, e-procurement, and more. Regardless of whether they are front-end or back-office applications, you can integrate many different information resources with Data Services using custom adapters. Common information resources include: User Guide for Adapter SDK Overview PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 13 Table 5: Resource Description Databases Relational databases such as Oracle, DB2, file system (as the database) EAI Enterprise Application Integration resources such as Tibco, WEB Methods, and Vitria ERP Enterprise Resource Planning systems such as Enterprise SAP and PeopleSoft MOM Message oriented middleware such as IBM MQSeries, Microsoft MSMQ 3.1.2 Adapters and front-end applications For front-end application integration, an adapter bridges the disparate interfaces of the Data Services message broker and the resource. An front-end application adapter is: ● relatively simple to develop ● connectionless ● slow when used for bulk data transfer This type of adapter usually contains a message-oriented interface and is most appropriate for connecting to EAI systems. E-commerce application developers using adapters to integrate data platforms with information resources are shielded from much integration complexity and are able to perform more transparent application design. 3.1.3 Adapters and back-office systems Back-office system adapters can support non-SQL based applications like Manugistics as well as applications like Oracle Financials, Siebel, and Clarify, which contain application level complexity that makes it difficult to extract data using only a SQL interface. A back-office system adapter: ● is complex ● requires connections over a span of time ● is optimized for moving large amounts of relational data This type of adapter usually contains a “stream-oriented” interface appropriate for connecting to bulk data movement systems. 3.1.4 Adapter types and capabilities Using the Data Services Adapter SDK, you can create different types of adapters: message-oriented, steamoriented, or “full capability” containing both message- and stream-oriented behavior. Adapter types depend on the capabilities you include. For example, you can define whether requests can initiate from Data Services, from 14 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Overview the information resource, or from both. Also, you can specify how adapter metadata imported by Data Services is handled. It can be handled by: ● Native Data Services transforms (sources, targets), or ● The adapter's Data Services transforms (sources, targets, function calls) Using the Adapter SDK, you can program an adapter to do some or all of the following: ● Browse resource metadata ● Import resource metadata ● Receive messages from data flow outbound messages and send acknowledgement ● Receive messages from data flow message function calls and send reply ● Invoke real-time services ● Send records to the Data Services adapter table source transform for table metadata imported from the adapter ● Receive records from the Data Services adapter table target transform defined by table metadata imported from the adapter ● Send records to the Data Services adapter document source transform for document metadata imported from the adapter ● Receive records from the Data Services adapter document target transform defined by document metadata imported from the adapter ● Process SQL generated by Data Services table sources 3.2 Adapters in the Data Services platform The Data Services platform provides combined batch and real-time data movement services, enabling companies to leverage ERP and other back-office systems in analytics and e-business. The Adapter SDK significantly extends these services, allowing you to write custom adapters that integrate Data Services with: ● messaging systems (such as EAI) ● other types of EAI systems ● message-oriented middleware ● other real-time information resources With custom adapters, you can design and implement complex business processes across disparate system and messaging environments (such as Siebel, SAP ERP and R/3, and Clarify). 3.2.1 Custom adapter usage examples Example 1 Suppose a customer enters an order through your e-commerce Web site. Data Services collects and augments the order data, transforms fields, and sends the order information to SAP R/3. With a custom adapter, you could extend the use of this data beyond SAP R/3. For example, you can update your data cache and a Siebel instance to keep your entire system synchronized. User Guide for Adapter SDK Overview PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 15 The capability to integrate data and populate a data cache provides flexibility within the integration layer without the need to modify existing systems. Example 2 Perhaps, an application developer wants to use Data Services for populating a data warehouse with Clarify data. Data Services uses SQL to extract data from the underlying database (either Oracle or Microsoft SQL Server). SQL cannot be used for the metadata because Clarify does not use the underlying databases's dictionary to store metadata. With a custom adapter, you can support a batch data flow that extracts the data. In this case, you can use a custom adapter to extract the requisite metadata (such as table descriptions, column descriptions, and table relationships) from Clarify. 3.2.2 Adapters in the Data Services architecture Data Services uses Job Servers to communicate with clients (including the Data Services engine, adapters, and real-time services). Each Data Services adapter fits into the overall architecture as a client of an adapter manager Job Server. This Job Server translates messages between the data format used by Data Services and the format native to the information resource (IR). The following shows one example of Data Services adapters in the Data Services architecture. 16 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Overview 3.2.3 Adapters and Job Servers All adapter instances on a given computer interact with Data Services through a Job Server installed on the same computer. Data Services Job Servers contain message brokering capability and multiple Job Servers can be installed on a single computer. However, only one Job Server is allowed to manage adapters installed on that computer. So, each adapter instance on a computer is a managed by the same Job Server. The Job Server starts the adapter driver application which: ● Manages the adapter's life cycle by starting, stopping, monitoring, and restarting it if necessary ● Performs run-time adapter configuration ● Manages multithreading complexities and hides message broker client complexities (you only need to configure the number of threads for each operation) ● Supports centralized adapter administration (through the Data ServicesAdministrator) ● Manages resource connections based on connection information in the adapter instance configuration file ● Handles and reports errors by responding to exceptions thrown by the developer using the exceptions classes provided by the API ● Performs error and trace logging 3.3 Flexible adapter architecture The Adapter SDK 2.0 is designed so you can implement a single adapter with “message-oriented” interfaces (for real-time operations), "stream-oriented" interfaces (for batch data operations), or interfaces of both orientations for “full capability”. A full-capability adapter would include metadata browsing and import capabilities as well as both types of interfaces. The Adapter SDK 2.0 has sufficient flexibility to accommodate a variety of adapter architectures, based on your adapter requirements. In a full-capability adapter, adapter operations can be presented through the metaphor of a two-lane bridge between Data Services and an information resource (IR). Each lane of the bridge contains bi-directional traffic for a specific orientation: one lane implementing stream-oriented interfaces (Examples: TableSource, TableTarget) and the other lane implementing message-oriented interfaces (Examples: ListenerOperation, PollOperation). See the online API documentation in for interface details. While all adapter operation instances must implement the Operation interface, all metadata capabilities do not necessarily require an operation interface (unless you want to expose operation instance metadata for messageoriented operations to Data Services). To obtain external metadata browsing and import capabilities, implement associated metadata interfaces. User Guide for Adapter SDK Overview PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 17 3.4 Adapter component model The Adapter SDK includes an unexposed adapter container. This container is an internal structure that instantiates and holds all user-defined adapter components. Each component is: ● An instance of a user-defined Java class that implements one or more interfaces exposed by the Adapter SDK ● A Java Bean requiring compliance with Java Bean “properties” and “introspection” specifications 3.4.1 Component overview Each component plays at least one role in an adapter. The following table alphabetically lists each component with how it is defined and what it does. Table 6: Component name Defined by Component role Adapter Adapter writer Connects adapter to the information resource (IR). AdapterEnvironment System Links user-defined components. Adapter Operation Adapter writer Supports adapter stream and message operations. Import by Name Adapter writer Allows users to import IR metadata by name into Data Services. (Requires Meta­ data Import.) Metadata Browsing Adapter writer Allows users to visually browse IR metadata. Metadata Import Adapter writer Allows users to import IR metadata into Data Services. Metadata Node Adapter writer Makes it possible for IR metadata to be visually represented as a node-delimited hierarchy. OperationEnviron­ ment System 18 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Overview Component name Defined by Component role Session Adapter writer Groups components and maintains state (associated with Data Services adapter datastore). 3.4.2 System-defined components The Adapter SDK provides two important, system-defined components: AdapterEnvironment and OperationEnvironment. 3.4.2.1 AdapterEnvironment The AdapterEnvironment component implements the AdapterEnvironment interface provided by the Adapter SDK as a set of methods that: ● Access an adapter's related pre-defined objects ● Access an adapter's configured system properties, for each instance ● Set the link between user-defined components Some methods implemented for this interface include: Table 7: Method Description getInstanceName() Accesses the adapter instance name logTrace(String text) Puts the text string to the adapter's instance trace log file setOperationDescriptor (String[] operationClassNames) Sets the fully qualified class names of the adapter's operation setSessionClassName (String sessionClassName) Sets the fully qualified class names of the adapter's Session interface implementation Related Information Run-time configuration template structure [page 86] 3.4.2.2 OperationEnvironment The OperationEnviroment component implements the OperationEnviroment interface provided by the Adapter SDK as a set of methods that access an adapter operation's: User Guide for Adapter SDK Overview PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 19 ● Configured system properties ● Dynamic properties ● Related pre-defined objects Some methods implemented for this interface include: Table 8: Method Description getInstanceName() Accesses the adapter instance name println(String text); Adds text strings to the adapter instance trace log file when debug trace is activated public void incrementRequestCount() Increments by 1 the number of requests received by the oper­ ation invokeService(String serviceName, String xml, int timeout) Invokes real-time services provided by Data Services The adapter container: ● Creates instances of the AdapterEnvironment and OperationEnvironement components, then ● Passes references for user-defined components (based on initialize method parameters) to these systemdefined components Note All methods implemented by the Adapter SDK are listed in the Adapter SDK API documentation. Related Information Run-time configuration template structure [page 86] 3.4.3 User-defined components You define each component in its own class by implementing the corresponding (and other associated) interface(s) exposed by the Adapter SDK (see online API documentation for details). User-defined components include: ● Adapter ● Adapter Operation (for both stream- and message-oriented operations) ● Session ● Metadata Node (required for Metadata Browsing) ● Metadata Browsing ● Metadata Import (can include the Import by Name component) When an adapter starts, the adapter driver instantiates the adapter container that creates and manages the instances of the user-defined adapter components. The rules governing relationships among instances of userdefined adapter components in an adapter container are: 20 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Overview ● One Adapter component instance allowed per container. ● One or more instances of the Adapter Operation, Session, Metadata Browsing, and Metadata Import components allowed per container. ● One or more Metadata Node and Import By Name components allowed per container. ● The Adapter component is directly or indirectly associated with all other components in its container, referenced inside the initialize() method. Example of Direct Reference: Initialization of the Import object from the TestAdapter (Import.java): public void initialize (Adapter adapter, AdapterEnvironment adapterEnvironment, Session session) { _adapterEnvironment = adapterEnvironment ; _adapter = (TestAdapter)adapter ; _session = (TestSession)session ; } Example of Indirect Reference: Initialization of the Operation interface initialize ()method: public void initialize (OperationEnvironment adapterOperationEnvironment) { _adapterOperationEnvironment=adapterOperationEnvironment; _adapter = (TestAdapter)_adapterOperationEnvironment.getAdapter(); } ● An instance of the Session component can be associated with one or more instances of Adapter Operation, Metadata Browsing, and Metadata Import components. The following diagrams show adapter components and relationships among adapter component instances: User Guide for Adapter SDK Overview PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 21 3.4.3.1 Adapter This component is required for all adapters. To create this component, you must implement the Adapter interface —the core life-cycle interface for all Data Services adapter instances. The Adapter interface includes a set of methods called by the adapter container. All adapters must implement the Adapter interface. An additional interface you can implement for this component is the SQLEnable interface. The Adapter component is configurable and responsible for connecting the adapter to an information resource. A reference to the Adapter component is available for Session, MetadataBrowsing, and Import objects as a parameter of the initialize() method. Adapter operations can access the adapter object through the getAdapter() method of the OperationEnvironment object, which is also a parameter of the initialize() method of the adapter operation. 3.4.3.2 Adapter Operation The Adapter Operation component is optional, configurable, and supports either a message-oriented or a streamoriented exchange model for adapter operations, depending on which additional interfaces you implement. To 22 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Overview create this component, you must implement the Operation interface—the basic life-cycle interface for all Data Services adapter operations. 3.4.3.3 Session The Session component is optional and used by the adapter container for grouping and maintaining state. To create this stream-oriented component, you must implement the Session interface. This component can be associated with every Adapter Operation, Metadata Browsing, and Metadata Import component in the adapter's environment. With a Session component, the adapter container creates a Session object upon request from an adapter client (Data Services Designer or engine). The Session component is associated with the adapter datastore, created and configured in the Data Services Designer. Session property values, configured in the datastore Adapter Properties tab, determine Session state. The Designer allows users to create multiple adapter datastores for each running adapter instance. Each adapter datastore with configured session properties is unique and associated with a unique set of datastore objects, grouped as follows: ● Metadata browsing objects ● Metadata import objects ● Data Services metadata imported from the IR ● Adapter sources, targets, and function calls belonging to the datastore (because they were created from the datastore's metadata) For these Data Services objects, the adapter container creates and manages corresponding stream-oriented Operation, Metadata Browsing, and Metadata Import component instances. All these instances share the same Session state (configured datastore properties) associated with that Data Services object. However, the adapter writer does not have direct control over the Session object life-cycle as it is both created and destroyed on request from an adapter client (Data Services Designer or engine). The Adapter SDK can handle simultaneous Session components. For every component associated with a Session, the Adapter SDK generates a unique ID for that component/Session pair. An adapter client uses use this ID when making metadata browsing and import requests, or when starting a stream-oriented operation. To refer to the Session component from an operation, use the getSession() method from the OperationEnvironment interface implemented by the Adapter SDK . For example: public void initialize (OperationEnvironment OperEnv) { _operEnvironment=operEnvt; _adapter=(TestAdapter)_operEnvironment.getAdapter(); _adapterEnvironment= _operEnvironment.getAdapterEnvironment(); _session= (TestSession)_operEnvironment.getSession(); } To refer to the Session component from another component, like the Metadata Browsing and Metadata Import components, use a parameter within the initialize ( ) method. For example: public void initialize (Adapter adapter, AdapterEnvironment adapterEnvironment, Session session) { _adapterEnvironment = adapterEnvironment; _adapter = (TestAdapter)adapter; _session = (TestSession)session; User Guide for Adapter SDK Overview PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 23 } The Session component is associated with the adapter datastore, which is created and configured in the Data Services Designer. Session properties are configured in the datastore's Adapter Properties tab. 3.4.3.4 Metadata Node The Metadata Node component is optional and supports the external metadata browsing framework by providing an organizational structure for representing IR metadata. You can implement different MetadataNode interfaces if you want your adapter to show hierarchy. The adapter container creates the Metadata Node object upon request from the Data Services Designer. 3.4.3.5 Metadata Browsing The Metadata Browsing component is also optional and, combined with the Metadata Node component, supports the information resource (IR) metadata browsing framework. Implement this interface to give your adapter the ability to visually browse information resource metadata. To create this component, you must implement the MetadataBrowsing interface after you implement the MetadataNode interface. The adapter container creates the Metadata Browsing object upon request from the Data Services Designer. The Metadata Browsing component is not configurable—the Adapter SDK does not introspect its properties. Metadata Browsing relies upon Metadata Node components to organize and hierarchically represent information resource metadata. 3.4.3.6 Metadata Import The Metadata Import component is optional and supports metadata import from information resources to Data Services . Implement this interface if you want your adapter to have metadata import capability. To create this component, you must implement the MetadataImport interface. The adapter container creates the Metadata Import object upon request from the Data Services Designer. The Metadata Import component is not configurable—the Adapter SDK does not introspect its properties. The Metadata Import component supports two methods of obtaining information resource metadata: Table 9: Method Description Import metadata from the browser From the Designer's metadata browsing window, the "import" command imports metadata while browsing a node or group of nodes. Implement the public Vector importMetadata (MetadataNode resourceMetadataNode) method of the MetadataImport interface. 24 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Overview Method Description Import metadata by name Right-click in the Designer's Adapter Datastore to use the Import By Name option. To support an adapter's import-by-name capabilities, create the Import by Name component by imple­ menting the ImportByName interface. Metadata Import uses the instance of this component as a parameter of the importMetadata method to represent the properties the user must define for importing the metadata. For both ways of obtaining metadata, the implementation of the ImportMetadata method returns the vector of AWMetadata objects. AWMetadata is the super class for objects that represent all types of Data Services metadata: ● AWTableMetadata ● AWDocumentMetadata ● AWFunctionCallMetadata ● AWOutboundMessageMetadata ● AWMessageFuctionCallMetadata Each of these objects represents Data Services native metadata. importMetadata() methods of the MetadataImport interface implementation should return the Vector of these objects. Note See the TestAdapter source code for the examples of the importMetadata() implementation. To import metadata from the metadata browser for message-oriented operations, implement the Exportable interface for the adapter operation. The AWMetadata[] exportMetadata() method of this interface should return an array of AWMetadata objects that could be either AWOutboundMessageMetadata or AWMessageFuctionCallMetadata. Another method of this interface, int getMeadataType(), should return the type of the metadata the messageoriented operation can expose: com.acta.metadata.AWMetadata.AWT_OUTBOUND_MESSAGE or com.acta.metadata.AWMetadata.AWT_MESSAGE_FUNCTION_CALL To export metadata belonging to a message-oriented adapter operation implementing the ListenerOperation interface, use the “AW-” classes in the adapter.metadata package. For more information, see CallFromRtdf.java and ReceiveFromRtdf.java implementation details in the TestAdapter source code. See the com/acta/adapter/testadapter directory. 3.4.3.7 Import by Name The Import By Name component is also optional and supports metadata import from information resources to Data Services. Implement this interface if you want your adapter to have metadata import capability. To create this component, you must implement the MetadataImport interface. The adapter driver creates the Metadata Import object upon request from the Data Services Designer. User Guide for Adapter SDK Overview PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 25 3.5 The Adapter SDK API You implement interfaces, classes, and methods exposed by the Adapter SDK API to define adapter components. Interfaces and classes are contained in two Adapter SDK API packages: ● com.acta.adapter.sdk ● com.acta.metadata For detailed information about all Adapter SDK API classes, interfaces, and methods view the online documentation: LINK_DIR/Data Services/adapters/sdk/doc/API/index.html. 3.5.1 com.acta.adapter.sdk Use this package for all adapters. The com.acta.adapter.sdk package includes the following interfaces: Table 10: Interface Description Adapter The core interface required for all adapters; this class has been updated to reflect binary database com­ munication AdapterEnviron­ ment Used to access an adapter's configuration properties and system objects and link adapter components Delimited The interface for stream-oriented adapter operations that must read or write data using a delimited for­ mat. DocumentSource Used for document readers and document loaders, respectively and DocumentTar­ get EnableCDC Exportable Exposes a message-oriented operation's metadata to the Adapter SDK FunctionCall Used for “BAPI-like” function calls made to an information resource GuiAttributes Used for JavaBeans (adapter, operations, import by name and session) customization ImportByName Used for importing metadata by name ListenerOperation Automatically subscribes an operation to the message type derived from the operation instance name MetadataBrowsing Used for browsing and importing metadata, respectively and MetadataIm­ port MetadataNode Required for metadata browsing implementations (objects returned by the MetadataBrowsing interface must implement MetadataNode) Operation Required for message-oriented and stream-oriented operations OperationEnviron­ ment Provides access to adapter and operation properties Pushdown Used for controlling pushdown at the datastore and column levels. 26 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Overview Interface Description PollAdapter and PollOperation Used for adapters that must perform actions periodically QueryInXML Session Optional life-cycle interface providing adapter properties configuration for stream adapters SourceCDC SQLAdapter Used for native, full, or partial SQL calls on an information resource. SQLEnable Returns rows as described by the metadata for the TableSource in the Data Services data flow Statistics Used for collecting and displaying adapter statistics in the Data Services Administrator (for example, adapter status, number of messages processed, and so on) StreamOperation The basic interface for stream-oriented operations Table Supports Table Sources and Table Targets from the Data Services data (a sub-interface for TableSource and TableTarget interfaces) TableSource and TableTarget Used for table sources and table targets, respectively CreateTable Creates a temporary table and then loads data to that table using the TableTarget interface. ExecuteAny Indicates that the adapter can handle commands in the SQL function. DescribeQuery Describes the input SQL to obtain output columns. 3.5.2 com.acta.metadata This package contains optional classes for working with Data Services metadata in stream-oriented adapters. It contains no interfaces, but includes the following classes: Table 11: Class Description AWAttribute Sets attributes for Data Services table metadata AWColumn Sets columns for Data Services table metadata AWDocumentMe­ tadata Defines the Data Services document metadata AWForeignKey Sets foreign keys for Data Services table metadata AWFunctionCall­ Metadata Defines Data Services function call metadata for streams AWIndex Sets the index for Data Services table metadata AWMessageFunc­ tionCallMetadata Defines the Data Services message function call metadata AWMetadata The super class for all Adapter SDK objects representing Data Services metadata User Guide for Adapter SDK Overview PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 27 Class Description AWOutboundMes­ sageMetadata Defines Data Services outbound message metadata AWPkFkPair Sets the primary key/foreign key pairs for the AWForeignKey object AWTableMetadata Defines Data Services table metadata AWUniqueKey Sets the unique key for Data Services table metadata ResourceMetadata Sets user-defined metadata in the Data Services repository 3.5.3 Interfaces implemented by the Adapter SDK The Adapter SDK provides implementations of these interfaces: Table 12: Interface Description AdapterEnviron­ ment A set of methods to access an adapter instance's objects (for example, getInstanceName()). OperationEnviro­ ment A set of methods to access an adapter (for example, getAdapter()) and its operations' properties 3.5.4 (for example, getInstanceName()). Interfaces implemented by adapter writers The only interface you must implement in your adapter is adapter.sdk.Adapter to create the required Adapter component. To expand adapter capabilities, implement other available interfaces. Some capabilities apply to only message-oriented operations, others apply only to stream-oriented operations, some apply to both. This table lists each adapter component with associated Data Services component(s), associated interface(s) capability, and exchange model: Table 13: Component Adapter Data Services Adapter Adapter datastore Interface(s) Capability (w/exchange model) REQUIRED: SQLAdapter Provide support for native SQL OPTIONAL: Pushdown Session Adapter datastore REQUIRED: Session OPTIONAL: EnableCDC 28 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. (import metadata only) or full SQL (stream) Configure adapter datastore prop­ erties in the Designer (stream) User Guide for Adapter SDK Overview Component Adapter Data Services Adapter Opera­ Real-time services tion Interface(s) Capability (w/exchange model) REQUIRED: Operation (use the Opera­ Handle a request from the IR for tionEnvironment.invokeservice real-time service (message) method) OPTIONAL: PollOperation Outbound message or Mes­ REQUIRED: Operation and ListenerOp­ Handle a request from an Data sage function call eration Services real-time service or data OPTIONAL: Exportable Table sources REQUIRED: TableSource OPTIONAL: Delimited, SQLEnable, flow (message) Read operations for use with a Designer table source (stream) QueryInXML, SourceCDC Table targets REQUIRED: TableTarget Designer table target (stream) OPTIONAL: Delimited Document sources Write operations for use with a REQUIRED: DocumentSource Read operations for use with a Designer document source (stream) Document targets REQUIRED: DocumentTarget Write operations for use with a Designer document target (stream) Function calls REQUIRED: FunctionCall Write operations for use with a Designer function call (stream) MetadataBrows­ Browser window ing Metadata Import REQUIRED: MetadataBrowsing and Browse metadata (both) MetadataNode Browser window and Import REQUIRED: MetadataImport Import metadata (both) by name dialog Import by name dialog REQUIRED: ImportByName Import metadata by name (both) Related Information Operation exchange models [page 30] User Guide for Adapter SDK Overview PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 29 3.6 Operation exchange models The Adapter SDK supports two adapter operation exchange models: ● Message-oriented exchange model (real-time) ● Stream-oriented exchange model (batch) Each model is associated with different components (component-exchange model associations are mentioned in the last table of the “Interfaces implemented by adapter writers” section). Both exchange models implement the Operation interface (plus one or more additional interfaces included in the com.acta.adapter.sdk package—they vary depending on exchange model used for your operation). Related Information Interfaces implemented by adapter writers [page 28] 3.6.1 Message-oriented exchange model The message-oriented exchange model associates Data Services with real-time applications. Typically part of a real-time job, a message-oriented operation is designed to stay available and running—either monitoring for messages to be forwarded to Data Services from an information resource (poll() method of the PollOperation interface or start() method of the Operation interface), or monitoring for messages to be forwarded to an information resource from Data Services (ListenerOperation interface). Although message-oriented adapter operations are designed and optimized for real-time connectivity, they can also be used in batch data flows. Message-oriented adapter operations process one real-time message at a time and do not require high throughput movements of data. Otherwise known as "real-time adapter operations", message-oriented adapter operations move relatively small—though semantically rich—amounts of data between external systems and Data Services . Each message handled by a message-oriented adapter operation is complete, independent of any preceding or following message. This type of message does not participate in a "stream." Message "calls" (routed by the Job Server managing adapters) to such adapter operations have no associated context. Therefore, establishing a "session" (usage of the Session object) is not supported for this context. Operations that implement the ListenerOperation interface, associate with the Outbound Message and Message Function objects in the Designer. Operations that implement the PollOperation interface or no additional interfaces associate with the real-time service defined for the Access Server in the Administrator. 3.6.2 Stream-oriented exchange model The stream-oriented exchange model is primarily intended for moving large amounts of data between Data Services and an information resource. For example, you might use a stream-oriented operation to read a high volume of data from an ERP (or non-relational) system and load it into a data cache. 30 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Overview Typically part of a batch data flow, adapters containing a stream-oriented operation are life-cycle dependent on the Data Services engine. When a data flow is executed, the Data Services engine starts the life-cycle of a streamoriented adapter operation. When the data flow completes execution, the engine stops the adapter operation. Though the architecture has been optimized for high data throughput, a stream-oriented operation can also be used in a real-time job. However, since a stream-oriented operation is not constantly available and running, it is not suitable for exchange with EAI systems. Stream-oriented operations require that you implement one of the sub-interfaces associated with the StreamOperation interface. By implementing the appropriate sub-interface, you can write stream-oriented operations for use with a Designer table source or target (TableSource or TableTarget sub-interface), a Designer document source or target (DocumentSource or DocumentTarget sub-interface), or a Designer function call (FunctionCall sub-interface). The stream-oriented exchange model can make use of a Session component to retain context. Context allows stream-oriented operations to maintain the prolonged connections needed to process large batches of rows for a job. You establish a session, carry out operations, and end the session. Each data flow source or target that uses a stream-oriented operation has a dedicated connection (session) with the adapter. The Adapter SDK can run multiple stream-oriented operation instances in parallel. Since stream-oriented operations typically share one or more objects (for example, a Session object), we recommend that you write thread-safe code for stream-oriented operations. In particular, you should synchronize usage of the Session and Adapter objects. 3.7 Adapters and operations For each adapter type you want to develop, you must create an adapter class, and for each operation type you want to develop you must create an operation class. At run-time, the Adapter container instantiates one object for each adapter class and multiple instances of the operation class type. Each instance of the message-oriented operation type must be configured with a unique operation instance name. User Guide for Adapter SDK Overview PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 31 The following example illustrates a simplified adapter model for a hypothetical Clarify x.x adapter. (The illustration does not show relevant metadata and session instances used to support the operations shown.) 32 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Overview 3.8 Basic operation models The Data Services Adapter SDK supports one adapter interaction style and two adapter interface styles. Using the provided API, you can express these interaction and interface styles in the form of two basic operation types (or “business cases”), which are discussed later in this section. 3.8.1 Interaction style Adapter interaction with IRs is always request/reply and the reply is either empty (acknowledgement) or contains data. In any interaction, when the client requests a service, the server must always send a response. An empty reply is sent to the client when an outbound message completes. An empty reply is also the response to an invoke service request. User Guide for Adapter SDK Overview PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 33 3.8.2 Interface styles The two basic adapter interface styles are: the IR requests an interaction with Data Services, and Data Services requests an interaction with the IR. With Data Services adapters, all operation types resolve to one of these two interface styles, with the client initiating the request for service and the server processing the request. 3.8.2.1 IR as client For example, a sales representative creates a sales order for a customer using a Siebel Enterprise System (IR). The order is sent as a message to Data Services. Data Services processes the order through a back-office ERP system application. (Stream-oriented operations do not use this model.) 3.8.2.2 Data Services as client For example, Data Services requests “Available to Promise” (ATP) information from i2. (Stream-oriented operations always use this model.) 3.8.3 Basic operation types The two basic adapter operation types you can create using the Adapter SDK API are: ● Data Services requests IR service and handles reply ● IR requests Data Services real-time service and waits for reply There are also two variations, which are the same as the base case but without a reply. The rest of this section explains base cases and their variations. 34 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Overview 3.8.3.1 Data Services requests IR service and handles reply The following illustration shows a real-time scenario applying “Data Services as client” interface style to messageoriented adapter operations. This scenario could illustrate how a customer using a Web application might make changes to their profile on the company Web site. The data is stored in an information resource (IR0). To process those changes, the Web application sends an XML message to a named real-time service on the Data Services Access Server. The Access Server starts a job that corresponds to the named service. The job runs the appropriate real-time job (IR0) processing the Web application's requested changes. IR sends a request message (using a "message function call" object inside the real-time job) to an adapter (Adapter:IR0). An adapter operation owned by Adapter:IR0 implements a Java interface (ListenerOperation) provided by the API. ListenerOperation listens for and handles the "message function call" that belongs to IR0. To implement the ListenerOperation interface, the developer writes only one method, handleRequest(). Typically, such an implementation would include: ● Receiving the XML request User Guide for Adapter SDK Overview PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 35 ● Providing data mapping between XML and the native format, if necessary ● Any other necessary processing ● Returning the XML reply The XML reply is received by the waiting adapter operation. Adapter:IR0 then passes the XML reply to IR0 and IR0 completes its processing. Note In a variation of this scenario, Data Services requests IR service and receives an acknowledgement. In this variation, IR0 uses an "outbound message," not a message function call. The outbound message just waits for the acknowledgement. In this variation, the ListenerOperation implementation returns a null (empty) message from the handleRequest() method. This variation is for message-oriented adapter operations only. This illustration shows a way (for batch or real-time scenarios) the "Data Services as client" interface style applies to stream-oriented operations. 36 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Overview 3.8.3.2 IR requests Data Services service and handles reply The following illustration shows an example of the “IR as client” interface style. It is for message-oriented adapter operations only. In the illustration, the adapter receives a request message by polling the resource using the poll() or start() method in its native format. The adapter translates the message to XML (if necessary). The Adapter SDK provides implementation of the OperationEnvironment interface and uses the invokeService() method to pass the request data to a named real-time service on the Access Server. The service runs the appropriate real-time job to process the data (perhaps enriching it with cached information) and returns an XML result to the adapter. The adapter completes the operation by translating the XML result to the IR application's native format (if necessary) and sending the information to the IR application, which is waiting for a reply to its request. Note A variation of this scenario is “IR requests Data Services service and receives acknowledgement”. In such a variation, the developer would not code a return for the poll() method (return is null), if used. This variation is for message-oriented adapter operations only. User Guide for Adapter SDK Overview PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 37 3.9 Adapter start-up sequence Configure adapters and adapter operations in the Data Services Administrator . After configuring start-up and run-time information, you can start adapter instances. Starting an adapter instance causes the adapter driver to create an adapter container which runs the following start-up sequence: 1. Create a new instance of your adapter class. 2. Invoke the adapter's initialize() method and set a reference to the AdapterEnvironment object created by the Adapter SDK where it binds adapter components — operations, session, metadata browser, metadata import, statistics (if applicable) — together. See the Adapter SDK API document for details. 3. Introspect the adapter's system and user-defined properties to the values configured for them in the adapter instance run-time configuration. 4. Invoke the start() method, which starts adapter processing. (This is where you write code that connects your adapter to the information resource.) After the start() method exits, the adapter is ready to start its operations and to poll an information resource. 5. Invoke the stop() method to stop adapter message processing when the Job Server gets an adapter shutdown or abort message—for example, from the Data Services Administrator. (This is where you write code to close the connection to the information resource and deinitialize the system.) With a shutdown message, the Adapter SDK gives the adapter an unlimited amount of time to stop gracefully (by completing processing of all outstanding requests). With an abort message, the adapter process stops immediately (without waiting for adapter operations to complete processing outstanding requests). 3.9.1 Adapter operation execution After an adapter starts (when the adapter start() method exits), message-oriented and stream-oriented operations can be started. The Adapter SDK automatically starts all message-oriented operations whose “enable” system property is set to "true". The operator must manually start all other message-oriented operations. Stream-oriented operations are started upon client (Data Services Designer or engine) request. Operators cannot manually start stream-oriented adapter operations from the Administrator. Only a client request to start a stream-oriented adapter operation will cause an unstarted adapter to start. The Adapter SDK runs the following start operation instance sequence which: 1. Creates a new instance of the adapter operation. 2. Invokes the initialize() method and uses your code to initialize the operation instance. For stream-oriented operations, the Adapter SDK will create a new or reuse the existing session object (refer to AdapterOperationEnvironment.getSession() inside the initialize() method). 3. Introspects the operation instance code and sets configurable properties to the values configured for them in the adapter operation instance configuration script from the run-time configuration file (message-oriented operations) or received from the Data Services engine (stream-oriented operations). 4. Invokes the start() method, which starts adapter operation message processing. 38 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Overview Note For message-oriented operations, the Adapter SDK begins to accept messages for the ListenerOperation.handleRequest() method and poll the resource using the PollOperation.poll() method only after the start() method exits. The start() method must exit when the Adapter SDK receives a request from the Data Services Administrator to stop the adapter operation. To catch this event, use the OperationEnvironment.canContinue() method. Note For stream-oriented operations, the pairs of begin() and end() methods can be called repeatedly after start() and before stop() upon engine request to restart data exchange between the adapter and the engine. 5. Invokes the stop() method when it receives a request from the Data Services Administrator to stop the adapter or the operation. The stop() method stops operation instance processing. 3.10 Adapters in the Data Services Designer This section describes how application designers integrate custom adapters into batch jobs and real-time jobs in the Data Services Designer. For more information about the Data Services Designer, see the Data Services Designer Guide. The two basic data flow types used with an adapter are: ● Data flow sends a message to an adapter instance (using adapter-related objects in the data flow) ● Adapter invokes real-time service (the service provider is a real-time job) These basic data flow types are discussed in the following sections. 3.10.1 Data flow sends a message to an adapter Data Services-initiated adapter operation instances are associated with adapter operation-related data flow objects. All adapter operation-related data flow objects must be created using adapter datastore metadata. Import information resource metadata into the adapter datastore using the adapter metadata import framework. Add adapter operation-related data flow objects to Data Services jobs as part of batch or real-time data flows. Operation instances associated with adapter operation-related data flow objects exchange data upon data flow request. Adapter objects in data flows are related to adapter operation instances as follows: User Guide for Adapter SDK Overview PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 39 Table 14: Operation Description Stream-oriented op­ The adapter operation instance is limited to the metadata types shown in the table below for creating erations the data flow's adapter counterpart (source, target, or function call). An adapter can host only one of each stream-oriented operation type. For example, the adapter can host only one operation that imple­ ments the TableSource interface. Multiple instances of a stream-oriented operation can be configured within a data flow (adapter table sources) and created at run-time. Message-oriented operations The adapter operation instance corresponds to the data flow's adapter object counterpart. This object is created by placing metadata with the same name as the adapter operation instance name in the flow. Synchronize the adapter operation instance name with the adapter object in one of two different ways: ● (Recommended) When creating a message-oriented operation, implement the Exportable inter­ face to expose operation metadata through the metadata browsing and import framework. Name the metadata object returned by the Exportable interface by giving the same name as the opera­ tion instance. Extract the operation instance name from the OperationEnvironment object using the getInstanceName() method. Use AWMessageFunctionCallMetadata.setMessageFunctionCall­ Name (String OperationInstanceName) and AWOutboundMessageMetadata.setOutboundMessa­ geName (String operationInstanceName) methods. The operation instance and derived data flow object (message function call or outbound message) are connected at run-time using this name. ● Use the metadata import framework to import information resource metadata. Then, you can con­ figure the message-oriented operation in the Administrator using the imported metadata name as the operation instance name. The data flow outbound message or message function call derived from this metadata sends a message to the adapter operation instance having the same metadata name. When you add metadata importing capabilities to your adapter, Data Services users can: ● Import metadata from your adapter ● Drag and drop imported adapter metadata objects into their (batch or real-time) data flows The metadata importable through an adapter datastore is limited to five metadata types, described in the following table: Table 15: Metadata Used in Data Services as: Documents Document sources or targets in data flows Function calls Function calls inside query transforms Message function calls Function calls inside query transforms Outbound mes­ sages Outbound messages in data flows Tables Table sources or targets in data flows In Data Services , these metadata types (and any metadata objects imported to them) appear under the adapter datastore icon in the Designer's object library. These metadata types are owned by the Adapter class in the Data Services repository. When an Data Services user runs an application with (batch or real-time) data flows containing imported adapter metadata, each imported adapter metadata object behaves as follows: 40 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Overview Table 16: Metadata Object Behavior Document source Asks the adapter operation for a batch of documents in the XML format defined by the operation's meta­ data. Document target Sends the adapter operation a batch of documents in the XML format defined by the operation's meta­ data. Function call Sends an input XML document to the adapter and waits to receive an output XML reply document from the adapter operation. Outbound mes­ sage Sends an input XML document and waits to receive a confirmation message from the adapter operation. Table 17: Table source Asks the adapter operation for a batch of data in the specific XML or delimited format defined in the oper­ ation's metadata. The data that operation receives from the Data Services engine is packed as records separated by getRowDelimiter(), with columns separated by getColumnDelimiter(). If the Delimiter inter­ face is not implemented, the operation uses default values. For XML formats, the operation should pack the data as XML in the following structure: <AWA_BatchWrapper> < AWA_Row> <colname>...</colname> ... <colname>...</colname> </ AWA_Row> ... < AWA_Row> <colname>...</colname> ... <colname>...</colname> </ AWA_Row> </AWA_BatchWrapper> Table target Sends the adapter operation the batch of data in the specific XML or delimited format defined in the oper­ ation's metadata. The data that operation receives from the Data Services engine is packed as records separated by ge­ tRowDelimiter(), with columns separated by getColumnDelimiter(). If the Delimiter interface is not implemented, the engine uses default values. For XML formats, see the Table source row above. In the following example, a real-time job sends a message to an adapter operation instance using an outbound message object. This type of job is useful for testing purposes. User Guide for Adapter SDK Overview PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 41 In the example, the Employment source and target objects represent message schemas in XML format. The "PublishMessageToR..." object represents an outbound message to an adapter operation instance of the same name. The adapter converts the message format and interacts with the resource. Upon completion, the adapter operation sends confirmation (an empty reply) to the data flow. If the adapter operation cannot process the outbound message, it sends an error reply (AdapterException) and the data flow terminates with the error message reply. 3.10.2 Adapter invokes real-time service Data Services users can create real-time jobs for the “IR requests Data Services service and waits for reply” and “IR requests Data Services service with no reply” basic adapter operation types discussed previously. In both cases, the adapter invokes a named real-time service in the Data Services Access Server. The service associates with the appropriate real-time job needed to process the IR's request (relayed by the adapter) and return the XML result to the adapter. In the following real-time job, the adapter is both source and target. Once the adapter receives the results message from the real-time job, it resumes processing. This type of real-time job would be used when the IR waits for a reply or when the IR waits only for an acknowledgement. 3.11 Adapter administration This section discusses adapter administration and summarizes how application designers use the Data Services Administrator to administer adapters. For more information about the Administrator and adapter administration, see the Data Services Administrator Guide. After an adapter is successfully installed, Data Services users can perform the following adapter administration functions from the Administrator: ● Add new adapter instances (configure the adapter start-up) ● Start adapter instances ● Shutdown adapter instances 42 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Overview ● Abort adapter instances ● Start operations ● Stop operations ● Edit start-up configurations ● Remove adapter instances Data Services users must complete adapter start-up and run-time configuration before they can start an adapter instance. For more information, see the “Configure adapter” section. When an adapter is started, the Access Server starts the adapter driver as the Java application runner and passes the fully qualified adapter class name as the parameter. This name appears automatically in the Adapter Class field on the Adapter start-up Configuration page. The adapter driver creates an adapter container. The adapter container creates adapter instances and associated components. The adapter's run-time configuration is provided by its adapter instance configuration file, represented in XML format. This file configures the adapter and one or more instances for each component class the adapter owns. Adapter instances are started from the Adapter Instance Status page. To start an adapter instance in the Management Console, go to Administrator Adapter Instance Job Server . The status page opens. Select one or more adapter instances and click the Start button. To verify which adapter instances started successfully, click the Status tab to refresh the Adapter Instance Status page view, then look for a green indicator next to the adapter instance name and the word “Started” in the Status column. After starting an adapter instance in the Administrator, Data Services users can: ● Start/stop adapter operation instances ● Verify that operation instances are started Configured operations are also listed on the Status page. Administrator users can start adapter operation instances, from the Adapter Instance Status page. To start an adapter operation instance, click to select it, then click the Start button. To verify which adapter operation instances started successfully, click the Status tab to refresh the Adapter Instance Status page view, then look for a green indicator next to the operation instance name. Related Information Configure adapter (start-up and run-time) [page 98] User Guide for Adapter SDK Overview PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 43 4 Creating an Adapter 4.1 Preliminary considerations The Data Services Adapter SDK is designed so that you only need to define classes for your adapter and operation objects. For example: public class MyOperation implements Operation, PollOperation In each class, you implement the appropriate Adapter SDK interfaces, then call or define the appropriate methods for the operations you want to develop. When you compile and package adapter and operation classes and start the adapter, the Adapter SDK instantiates objects for each class you defined. Before writing an adapter to integrate Data Services with an information resource, you must: ● Determine integration issues ● Understand your information resource ● Plan adapter components 4.1.1 Determine integration issues There are various ways to integrate an information resource (IR) with Data Services. First, determine if a custom adapter is necessary. If so, consider what kind of adapter you need. 44 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Creating an Adapter 4.1.2 Understand your information resource Consider adapter/information resource relationship details. In particular, determine: ● Which IR will the adapter integrate and how will the adapter connect to the IR? ● How will the adapter interact with the IR? Java API or JNI is required by the Adapter SDK to access IR data from the adapter (Java program). ● With which IR objects will your adapter interact? For example, determine which database tables your adapter should be able to access. 4.1.3 Plan adapter components The overall purpose of your adapter will be key in determining necessary components and how they work within the adapter. Remember that: ● The Adapter component (the class that implements the Adapter interface) is the only required component. This component binds all other adapter components together on the adapter's initialize method. An adapter instance can have only one Adapter component. The Adapter component is accessible from all other components within the adapter. Because of this, you may want the Adapter component to host information resource initialization. ● If your adapter requires SQL capabilities, you must implement the SQLAdapter interface. 4.1.4 Plan adapter operations Each operation type requires specific planning. However, for all operations, you must: ● Determine the objective for the operation. ● Understand what kind of data transformation should occur inside each adapter operation implementation. Data Services expects certain data formats, and if the IR requires different data formats, data transformation will be necessary. ● Decide how the adapter operation will process IR data for operations initiated by Data Services . Data Services supports five metadata types that can be processed from or sent to the adapter operation. They are: ○ Documents ○ Tables ○ Function Calls ○ Outbound Messages ○ Message Function Calls Imported metadata must be converted to one of these five types. Implement interfaces associated with metadata type(s) you choose. 4.1.4.1 Message-oriented operations Determine whether Data Services or the IR initiates the operation. User Guide for Adapter SDK Creating an Adapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 45 ● If the IR initiates the operation, design real-time services to process IR data. ● If Data Services initiates the operation, design real-time services or data flows that initiate adapter operations from either an Outbound Message or a Message Function Call. See Data Services documentation for more information. 4.1.4.2 Stream-oriented operations ● Stream-oriented operations are always initiated by Data Services. ● Determine if you need a Session component. If you plan to have multiple adapter datastores per adapter instance, include the Session component. ● Choose a data format for exchanging data between the stream-oriented adapter operation and the Data Services engine. This format will dictate what interface you should implement. ● Decide which additional interfaces to implement for the adapter operation class to cover special cases like SQL support for table sources. 4.1.4.3 Plan metadata browsing and import Decide if you want to import resource metadata only and use native Data Services sources and targets (native SQL support), or if your want to map IR metadata to Data Services metadata and use adapter operations associated with this metadata as sources, targets, and function calls. Decide how IR metadata will be imported into Data Services. The MetadataImport interface contains two importMetadata methods, each supporting a different way to import metadata from the Data Services Designer: ● Import metadata from the browsing window ● Import metadata using the Import-By-Name dialog Plan metadata import for message-oriented operations. ● Implement Exported interface to expose metadata from the message-oriented operation (only for operations initiated by Data Services ) ● Use generic metadata import framework and manually configure stream-oriented operations using imported to Data Services metadata ● For message-oriented operations initiated by the information resource, the metadata consists of real-time services configured in the Administrator For document metadata, DTD information can be imported from DTD files and from XML files containing a DTD element. When using DTD files to import metadata, you must define the root XML element. 4.2 Write your custom adapter Clearly defining the characteristics you require in your adapter should make it easy to identify the right components for the adapter. All components are optional, except the Adapter component. 46 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Creating an Adapter After identifying components, you create corresponding classes by implementing interfaces included with the Adapter SDK . For each class, you must: ● Implement appropriate Adapter SDK interfaces ● Define all required methods for your chosen components When writing your adapter, use instructions in this section and detailed information from the Adapter SDK API documentation. For adapter interface sample implementations, see the TestAdapter source code provided with your Adapter SDK . Related Information Interfaces implemented by adapter writers [page 28] Run-time configuration template structure [page 86] 4.2.1 Adapter writer checklist Use this checklist as a guideline for writing your adapter. Table 18: Done? Task Create an Adapter component [page 48] (Required) Create a Session component [page 50] (if needed) Create Metadata Node component(s) [page 51] (if needed) Create a Metadata Browsing component [page 52] (if needed) Create Metadata Import component [page 53] (if needed) Create an Operation component [page 58] for each operation type (if needed) Customize presentation of adapter components [page 66] in the Administrator or Designer (if needed) For each task, did you set up: ● Error handling? ● Trace and error logging? ● Statistics? Usually, very simple code is required to satisfy Adapter SDK requirements. The basic requirement for all adapter components is compliance with the JavaBeans standard regarding “Properties” and “Introspection” specifications. After you write your custom adapter, you will compile and package the components, referring to this package later, during adapter instance configuration. Finally, when you start the adapter, the Adapter SDK will instantiate objects (create the component's instance) for each component you defined. The Adapter SDK will operate with the instances of these classes. User Guide for Adapter SDK Creating an Adapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 47 After writing an adapter, you will need to create documentation for your adapter users. The section “Create adapter user documentation” provides suggestions, outlines naming conventions, and provides a pointer to an included Adapter Documentation template you can use. Related Information http://java.sun.com/products/javabeans/docs/ Create adapter user documentation [page 77] Error handling [page 72] Trace and error logging [page 73] Statistics [page 74] 4.2.2 Create an Adapter component Create your Adapter component by creating the Adapter class and implementing the Adapter interface, which all custom adapters must implement. The Adapter interface is the core life-cycle interface for all Data Services adapters. The Adapter component: ● Starts the adapter instance When we start an adapter, we actually trigger a start-up process that revolves around the Adapter component. When this start process is triggered, the adapter driver creates an instance of the Adapter component. There are three ways to trigger the adapter start process: ○ Automatically — When "Autostart" is set to true and the Data Services Designer is started. ○ Manually — Start from the Administrator. ○ Upon Designer or engine request — When a job or real-time service starts (if not already started manually or automatically). ● Binds together adapter components The adapter is considered "started" after the Adapter component instance binds together all other adapter component instances (the start() method is executed). After it is created and before it is destroyed, the Adapter component can be referenced by operations and other components within the adapter container. ○ Individual operation instances can access the Adapter component as needed using the getAdapter() method defined in the OperationEnvironment interface. ○ For metadata browsing, metadata import, and session instances, the reference is passed as a parameter of the initialize() method. ● Stops the adapter instance When we stop an adapter, we tell the adapter driver to destroy the Adapter component instance. An adapter instance is triggered to stop when: ○ The adapter is stopped or aborted from the Administrator. ○ The Adapter SDK encounters an unrecoverable error. ○ The associated Data Services service is stopped. 48 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Creating an Adapter 4.2.2.1 Adapter component life cycle First, the adapter container creates an Adapter component instance, MyAdapter myAdapter = new MyAdapter();, then it calls associated interface methods. The adapter container then: 1. Calls the initialize method: myAdapter.initialize(AdapterEnvironment environment); This method links the adapter component instance with the AdapterEnvironment object instance (also created by the adapter driver). If needed, store the reference to AdapterEnvironment for later use. (Find AdapterEnvironment interface details in Adapter SDK API documentation.) Also, this method binds the adapter components together. For example: public void initialize(AdapterEnvironment environment) { //always a good idea to save the reference to the AdapterEnvironment object _adapterEnvironment = environment; _adapterEnvironment.setOperationDescriptor(_operationClassNames); _adapterEnvironment.setMetadataBrowsingClassName ("com.acta.adapter.testadapter.Browse"); _adapterEnvironment.setMetadataImportClassName ("com.acta.adapter.testadapter.Import"); _adapterEnvironment.setSessionClassName ("com.acta.adapter.testadapter.TestSession"); } 2. Introspects and sets adapter parameters from the configuration XML script. The configurable adapter properties must be coded as Java Bean properties. Example: private String test = "abc"; public void setTest( String param) { test = param; } public String getTest() { return test ; } The property test will be exposed for adapter configuration. 3. Calls the myAdapter.start() method to start adapter processing. This method is called to connect and initialize all necessary adapter-wide resources after all properties are set. Under Adapter SDK control, the adapter processes data for the adapter operation, metadata browsing, and metadata import. All these objects reference the Adapter component. 4. Calls the myAdapter.stop() method when the adapter is being shut down or aborted. You must close resource connections and de-initialize the adapter. ○ When you make a request to stop the adapter from the Data Services Administrator, the Adapter SDK allows the adapter an unlimited amount of time to stop after processing all outstanding requests. ○ When you abort the adapter from the Administrator or stop the Data Services service, the adapter's process is immediately stopped, without waiting for adapter operations to complete. For details, see online API documentation for this interface. Find an example of this interface implementation in <LINK_DIR>/adapters/sdk/samples/testadapter/ data/src/com/adapter/testadapter/TestAdapter.java. 4.2.2.2 SQL-enabled adapter If your adapter must read/write records from/to the database, implement the SQLEnable interface for your adapter in addition to the Adapter interface. User Guide for Adapter SDK Creating an Adapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 49 For details, see online API documentation for this interface Related Information Interfaces implemented by adapter writers [page 28] 4.2.3 Create a Session component The Session component is optional for Data Services adapters. Create your Session component by implementing the Session interface. Create this component if one or more of the following applies: ● Your adapter will include metadata browsing, metadata import, or stream-oriented operation components. ● You want to create multiple adapter datastores for the same running adapter instance. The Session component (or session object) supports a Data Services user's ability to create multiple datastores for the same adapter instance. Different adapter datastores using the Session component can have different properties configured for the same datastore. ● You want to share the Session component instance with other component instances belonging to the adapter datastore. 4.2.3.1 Session component life cycle Each adapter datastore created in the Data Services Designer is associated with an adapter session object which is also associated with a specific adapter instance. In the Designer, all objects imported into the adapter datastore are also related to that session object. An instance of the Session component is created and destroyed upon request from a Data Services client (Designer for metadata browsing/import or engine for run-time data exchange between Data Services and the adapter). Adapter developers do not have direct control over Session object life-cycle management. Internally, the Designer shares the session object among multiple metadata browsing and import requests. During run-time, the Session object is shared inside the data flow. When you expose Session object properties for configuration, Data Services users see that information and provide configuration values in the Designer by going to the adapter datastore Adapter Properties tab. The Adapter SDK can handle the multiple Session objects simultaneously. Upon client request, the adapter container creates the Session object with a unique session ID. Then, it: 1. Calls the public void initialize(Adapter adapter, AdapterEnvironment environment) method of the session component. 2. Calls the public void start() throws AdapterExceptionmethod. 3. Returns the unique Session ID to the client. 50 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Creating an Adapter The client requests the data using the unique Session ID. The adapter container uses the unique Session ID to access the correct Session object. 4. Calls (upon client request — unique Session ID a parameter of the request) the public void stop() throws AdapterException method for the Session object and destroys it. 4.2.4 Create Metadata Node component(s) The Metadata Node component is optional for Data Services adapters. However, for adapters requiring metadata browsing capability, you must create this component before creating the Metadata Browsing component. Implement the MetadataNode interface to present information resource (IR) metadata as a hierarchy of metadata nodes consisting of known IR metadata types. The basic characteristics of metadata nodes are: ● Some nodes are "root" nodes at the top of the metadata hierarchy. They do not have parent nodes. ● Some nodes can be expanded, producing one or more child nodes for which the expanded node is the parent. ● Some nodes can be imported into Data Services. 4.2.4.1 Metadata browsing nodes The MetadataNode interface requires you implement the following methods: Table 19: Method Description getUniqueName Returns the unique name of the metadata browsing node. public java.lang.String getUniqueName() getDisplayNam e Returns the metadata browsing node display name. getDescriptio n Returns the metadata browsing node description. isRoot Returns true for root node, otherwise, returns false. public java.lang.String getDisplayName() public java.lang.String getDescription() public boolean isRoot() isImportable Returns true for a metadata browsing node that can be imported to Data Services, otherwise returns false. public boolean isImportable() isExpandable Returns true for a metadata browsing node that can be expanded to other child metadata browsing no­ des, otherwise, returns false. public boolean isExpandable() Instances of the Metadata Node component are created by the adapter container in response to metadata browsing requests from the Data Services Designer: User Guide for Adapter SDK Creating an Adapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 51 1. The adapter container first creates instances of root MetadataNode methods (implementations that return true for the IsRoot method) in response to an initial metadata browsing request from the Designer (using the getRootNode method from the MetadataBrowsing interface). 2. The adapter container then creates instances of the non-root MetadataNode methods (they also return true for the IsRoot method) when the Designer sends subsequent requests to expand nodes (using the expandNode method from the MetadataBrowsing interface). For details, see TestAdapter code for MetadataNode interface implementation samples. Look in the following files: ● com.acta.adapter.testadapter.RootNode.java ● com.acta.adapter.testadapter.ColumnNode.java ● com.acta.adapter.testadapter.FileNode.java 4.2.5 Create a Metadata Browsing component The Metadata Browsing component is optional for Data Services adapters. However, to visually present information resource (IR) metadata in the Designer, implement the MetadataBrowsing interface to create the Metadata Browsing component. This component is not configurable from the Designer or from the Administrator. The Adapter SDK does not introspect this component's properties. Note To hierarchically represent visually presented IR metadata in a Data Services metadata browsing window, you must implement both the MetdataBrowsing interface (to create the Metadata Browsing component) and the MetadataNode interface (to create the Metadata Node component which controls metadata browsing nodes that hierarchically present the IR metadata). Related Information Create Metadata Node component(s) [page 51] 4.2.5.1 Metadata Browsing component activity sequence When a Data Services user attempts to browse information resource metadata in the Designer, a request triggers the adapter container to create an instance of the Metadata Browsing component. Then, the adapter container: 1. Initializes the MetadataBrowsing component with the initialize() method: public void initialize (Adapter adapter, AdapterEnvironment adapterEnvironment, Session session) This method is called after the constructor is called and sets references to the Adapter, AdapterEnvironment and Session objects. References to Adapter, AdapterEnvironment and Session objects can be stored for later use, if needed. Reference to the Session object is optional and could be null. 52 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Creating an Adapter 2. Starts metadata browsing by calling the start() method then the getRootNodes() method. 3. For each request from the Designer to expand an information resource metadata node, the adapter container calls the associated expandNode(MetadataNode node) method, which expands the metadata node selected in the Designer (the Metadata Node component that corresponds to the node selected) as a parameter and should return the vector of the expanded metadata nodes. For non-expandable nodes, (when MetadataNode.isExpandable returns false) the method must return null. 4. When the user closes metadata browsing windows in the Designer, the adapter container calls the Metadata Browsing stop() method to destroy the component instance. Note Because an adapter that merely browses metadata is usually impractical, you should include in your adapter the ability to import browsable IR metadata. Related Information Create Metadata Node component(s) [page 51] Create Metadata Import component [page 53] 4.2.6 Create Metadata Import component For each adapter operation initiated by Data Services, the corresponding Data Services metadata must be defined (imported) from the IR using the Metadata Import component. Metadata import functionality and the Metadata Import component are optional for Data Services adapters. 4.2.6.1 Metadata mapping Data Services supports widely used metadata formats such as XML and database records. Often, information resource metadata and Data Services metadata are identical. However, Data Services has proprietary presentation for metadata imported into its repository. So, even if IR metadata matches Data Services metadata, you must still map IR/Data Services metadata. The Adapter SDK presents Data Services metadata with objects instantiated from the classes of the com.acta.metadata package. Use classes derived from the Adapter SDK AWMetadata super class to create Data Services metadata: Table 20: com.acta.metadata class Data Services metadata Use in data flow AWTableMetadata Table Table Source or Table Target AWDocumentMetadata Document Document Source or Document Target User Guide for Adapter SDK Creating an Adapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 53 com.acta.metadata class Data Services metadata Use in data flow AWFunctionCallMetad Function call ata Function call in Query Transform AWOutBoundMessageMe Outbound message tadata Outbound Message Target AWMessageFunctionCa Message function call llMetadata Message function call in Query Transform Helper classes do not directly represent the Data Services metadata, but are used to build the metadata: Table 21: More com.acta.metadata classes Usage in AWMetadata classes AWAttribute Metadata attributes. View these attributes from the metadata property pages in the Designer. AWColumn Column of the AWTableMetadata object. AWForeignKey Foreign key of the AWTableMetadata object. AWIndex Index of the AWTableMetadata object. AWPkFkPair Primary key-foreign key pairs for the AWForeignKey object. AWUniqueKey Unique key of the AWTableMetadata object. ResourceMetadata Use to associate the Data Services and information resource metadata. Example Java code that creates the AWTableMetadata object in the adapter's import metadata code: AWTableMetadata awTable = new AWTableMetadata () ; … AWColumn col1 = new AWColumn(); col1.setDatatype (AWColumn.AWT_VARCHAR); col1.setName ("col1"); col1.setNullable(true); col1.setLength(64); ... AWColumn col2 = new AWColumn(); col2.setDatatype (AWColumn.AWT_INT); col2.setName ("col2"); col2.setNullable(false); col2.setLength(4); col2.setDescription("Order number"); col2.addElement(col); ... AWAttribute attr1 = new AWAttribute("Attribute1", "Attribute value 1") ; AWAttribute attr2 = new AWAttribute("Attribute2", "Attribute value 2") ; ... awTable.setColumns ( new AWColumn [] { col1, col22} ); awTable.setAttributes(new AWAttribute [] { attr1, attr2} ); 54 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Creating an Adapter 4.2.6.2 Data Services XML metadata Several Query metadata types are associated with XML documents and XML data type definition (DTD) documents. Each metadata type corresponds with an AWMetadata object: Table 22: Data Services metadata types Corresponding AWMetadata objects Document AWDocumentMetadata Outbound Message AWOutBoundMessageMetadata Function Call AWFunctionCallMetadata Message Function Call AWMessageFunctionCallMetadata When instantiating the AWMetadata objects, use DTD strings. Set one DTD string each for the AWOutBoundMessageMetadata and AWDocumentMetadata objects. Because functions must both input and output XML, you must use two DTD strings for the AWFunctionCallMetadata and AWMessageFunctionCallMetadata functions. The Adapter SDK accepts DTD strings in both DTD and XML formats. However, when a DTD string is defined in DTD format, the DTD root element must be defined. For example: <!ELEMENT Identifier (#PCDATA)> <!ELEMENT BusinessDescription (#PCDATA)> <!ELEMENT PhysicalAddress (#PCDATA)> <!ELEMENT shipTo (BusinessDescription,PhysicalAddress)> <!ELEMENT OrderQuantity (#PCDATA)> <!ELEMENT ProductLineItem (OrderQuantity,Identifier,shipTo?)> <!ELEMENT CreditCard (#PCDATA)> <!ELEMENT DebitCard (#PCDATA)> <!ELEMENT formOfPayment (CreditCard|DebitCard)> <!ELEMENT PurchaseOrder (Identifier,shipTo?,ProductLineItem*,formOfPayment?)> If this DTD were used for the AWOutboundMessage metadata object, you could use these methods to define the DTD string: AWOutboundMessageMetadata dm = new AWOutboundMessageMetadata (); … String dtd = new String() ; // read dtd from file or hard code it … dm.setOutboundMessageDTD(dtd); dm.setOutboundMessageDTDRoot("PurchaseOrder"); … Note Do not add standard XML headers to the beginning of the DTD (Example:<?xml version='1.0' encoding='utf-8' ?>). DTD formats allowed by the Data Services Designer and the Adapter SDK differ slightly; the Designer allows such a header while the Adapter SDK does not. When you define the DTD string in XML, do not define the DTD root element. Example XML: <?xml version='1.0' encoding='utf-8' ?> <!DOCTYPE PurchaseOrder [ <!ELEMENT Identifier (#PCDATA)> User Guide for Adapter SDK Creating an Adapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 55 <!ELEMENT BusinessDescription (#PCDATA)> <!ELEMENT PhysicalAddress (#PCDATA)> <!ELEMENT shipTo (BusinessDescription,PhysicalAddress)> <!ELEMENT OrderQuantity (#PCDATA)> <!ELEMENT ProductLineItem (OrderQuantity,Identifier,shipTo?)> <!ELEMENT CreditCard (#PCDATA)> <!ELEMENT DebitCard (#PCDATA)> <!ELEMENT formOfPayment (CreditCard|DebitCard)> <!ELEMENT PurchaseOrder (Identifier,shipTo?,ProductLineItem*,formOfPayment?)> ]> So, if this XML-formatted DTD were used for the AWOutboundMessage metadata object, you could use these methods to define the DTD string: AWOutboundMessageMetadata dm = new AWOutboundMessageMetadata () ; … String dtd = new String() ; // read dtd from file or hard code it … dm.setOutboundMessageDTD(dtd); … For specific method details see the online API documentation (com.acta.metadata package). See an example of the Query metadata class usage in <LINK_DIR>/adapters/samples/testadapter/ data/src/com/adapter/TestAdapter/Import.java. 4.2.6.3 Metadata types supported in the Designer Adapters can support some Data Services metadata types. When a metadata type is supported by an adapter, the associated MetadataImport interface method should return true. Methods and associated Data Services metadata types include: Table 23: Metadata type Description public boolean isTables() Returns true if metadata import can return the AWTableMetadata object. public boolean isDocuments() Returns true if metadata import can return the AWDocumentMetadata object. public boolean isFunctionCalls() Returns true if metadata import can return the AWFunctionCallMetadata object. public boolean Returns true if metadata import can return the AWOutboundMessageMetadata object. isOutboundMessages() public boolean isMessageFunctionCalls() 4.2.6.4 Returns true if metadata import can return the AWMessageFunctionCallMeta­ data object. About the MetadataImport interface To support IR metadata import in Data Services, implement the MetadataImport interface. The Adapter SDK creates the MetadataImport object after receiving a request to import metadata. It calls the method that sets references to the Adapter, AdapterEnvironment and Session objects: initialize (Adapter adapter, AdapterEnvironment adapterEnvironment, Session session). 56 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Creating an Adapter Adapter SDK assumes that necessary resources are allocated in the Adapter or Session instances, so start() and stop() methods are not required by the MetadataImport interface. After the Metadata Import component is instantiated and initialized, the Adapter SDK is ready to serve the Designer by fulfilling metadata import requests. The MetadataImport interface supports two types of metadata import in the Designer: ● Import through metadata browsing ● Import through Import-By-Name 4.2.6.5 Import through metadata browsing To support metadata import through the adapter metadata browsing window, you must first implement both the MetadataNode and the MetadataBrowsing interfaces in your adapter. The MetadataBrowsing interface makes it possible for Data Services users to view IR metadata from the Designer. When Data Services users browse IR metadata in the Designer, they navigate through a hierarchy of nodes. Each node is represented in the Adapter SDK by an instance of the MetadataNode interface. Users can select a metadata node and execute the “import” command (if MetadataNode.isImportable implementation returns true for the selected node). Then, the adapter container calls the MetadataImport.importMetadata(MetadataNoderesourceMetadataNode) method, which returns the vector of the Data Services metadata objects. See the com.acta.metadata package for details. Related Information Create Metadata Node component(s) [page 51] Create a Metadata Browsing component [page 52] 4.2.6.6 Import through Import-By-Name For your adapter to include Import-By-Name functionality, you must implement the ImportByName interface. This is an empty interface (no methods are required by the Adapter SDK). For example, if you want to import some IR metadata by name and need two properties (table and owner names) to supply the information necessary to perform the metadata import. ● Enter the value for these properties in the Designer's Import-By-Name dialog. ● Access the entered values in your implementation of the MetadataImport interface. You must define properties for the ImportByName interface implementation. Example code you might add includes: public class MyImportByName implements ImportByName { private String tableName ; public String getTableName() { return tableName }; User Guide for Adapter SDK Creating an Adapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 57 } public void setTableName (string s ) { tableName=s}; private String ownerName ; public String getOwnerName() { return ownerName }; public void setOwnerName (string s ) { ownerName = s}; The Adapter SDK should return the instance of the Import By Name component from the ImportByName method implemented for MetadataImportInterface. Continuing with the example, a typical ImportByNamemethod implementation might include the following code: public MyImportByName importByName() { return new TestImportByName() ; } 4.2.6.7 Link between Data Services and IR metadata Your information resource and Data Services only understand their own metadata, so just as you map IR metadata to Data Services for importing purposes, you must also provide a way for Data Services to send IR metadata back during run-time. At run-time, Data Services must be able to pass IR metadata description information to the adapter operation (which already knows how to work with the information resource). Stream-oriented adapter operations are not directly linked to their Data Services counterparts—the tables, documents, function calls importable through your adapter. So, to create an indirect link between imported adapter metadata and stream-oriented adapter operations: 1. Use the ResourceMetadata object when creating the Metadata Import component. 2. Set the IR metadata object to the Data Services metadata object that the Import method must return. Use ResourceMetadata.setMetadataObject (Object resourceMetadata). Implement the resourceMetadata object as a Java Bean. For more details, see the com.acta.metadata.ResourceMetadata API documentation. During metadata import, Data Services stores a serialized version of the IR object with the imported metadata in the Data Services repository. At run-time, immediately after the stream-oriented adapter operation is initialized, Data Services sends the serialized IR metadata image to the adapter operation. The Adapter SDK de-serializes the IR metadata object. Then, to make the IR metadata object available for the stream-oriented operation, the Adapter SDK calls the com.acta.adapter.sdkStreamOperation.metadata(Object resourceMetadata) method, implemented for all stream-oriented operations. For details, see com.acta.adapter.sdkStreamOperation API documentation. 4.2.7 Create an Operation component All adapter Operation components must implement the Operation interface, either explicitly for messageoriented operations, or implicitly (throwing sub-interfaces of the Operation interface) for all stream-oriented operations. 58 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Creating an Adapter Each class implemented as an adapter operation represents a different operation type. Operation types are similar in that they: ● Implement the Operation interface ● Are coded as JavaBeans with properties configurable from the Administrator or the Designer ● Are associated with one of the Data Services metadata types ● Have the same basic life cycle (create—initialize—start—stop) However, there are substantial differences between stream-oriented and message oriented operations. 4.2.7.1 Operation life-cycle After the Adapter SDK creates an instance of an operation component, the adapter container: 1. Calls the public void initialize (OperationEnvironment operationEnvironment) method immediately after the instance is constructed. You can store a reference to the OperationEnvironment object for future use. The OperationEnvironment object is implemented by the Adapter SDK and contains an important method that accesses adapter and operation properties (references to the Adapter and Session instances, trace and error logs, instance name, and so on). See the Adapter SDK API documentation for more details. 2. Introspects an operation and sets the adapter operation parameters from the adapter instance configuration. You define adapter “get” and “set” configuration properties for the operation component (similar to defining other adapter components). Set values for operation properties in the Administrator (for message-oriented operations) or in the Designer (for stream-oriented operations). 3. Calls the start() method. All initializations must be specific for this operation inside start() because the start() method is called only once per operation life cycle. 4. The operation processes message-oriented or steam-oriented data. What occurs during this part of the lifecycle is specific to the adapter operation type and is discussed in: ○ Message-oriented operations ○ Stream-oriented operations 5. Calls the stop() method triggering the Adapter SDK to destroy the operation instance. De-allocate the operation resources allocated in start(). 4.2.7.2 Message-oriented operations Once created and initialized by the Adapter SDK, the message-oriented operation is ready to process messages from Data Services or an information resource. Normally, a message-oriented operation starts when the adapter starts and stops when the adapter stops. However, you can start and stop individual message-oriented adapter operations from the Administrator. Every class that implements the Operation interface (operation type) for message-oriented operations can be used to configure multiple instances of the adapter operation running in parallel. See the TestAdapter for an example of how to configure two instances of the com.acta.adapter.testadapter.InvokeService.class. See the Adapter SDK API documentation for details. User Guide for Adapter SDK Creating an Adapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 59 4.2.7.3 Message-oriented operations initiated by the IR Metadata for message-oriented operations initiated by information resources is provided from real-time services configured in the Administrator. This metadata is created when you configure the real-time service for a specified Access Server. Each adapter instance can work with only one Access Server. You configure message broker host and port for this Access Server from the adapter instance configuration in the Administrator. To implement adapter operations initiated by an information resource, you can choose one of two options: ● Implement the PollOperation interface and its single method, poll(). Call the invokeService method of the OperationEnvironment interface from poll() . The Adapter SDK calls the poll() method periodically (in "polling interval" milliseconds). Configure polling interval value from the operation configuration form in the Designer. Find a sample implementation of the PollOperation interface in com/acta/adapter/ InvokeServeice.java source code. With this option, the Adapter SDK is responsible for stopping the adapter operation and stops calling the poll() method immediately after receiving a request from the Administrator to stop the operation. ● Loop inside the start() method and call the invokeService method of the OperationEnvironment interface. Note that if you use this more flexible option, you are responsible for providing an exit from the start() method. A stop request from the Administrator tells the Adapter SDK to return "false" for the canContinue() method. Build in a way to check the canContinue() flag periodically as a trigger to exit the start() method. After exiting start(), the Adapter SDK will call the stop() method. public void initialize ( OperationEnvironment adapterOperationEnvironment ) { _adapterOperationEnvironment = adapterOperationEnvironment ; } … public void start() throws AdapterException { while (true) { // do your processing here … String reply = _adapterOperationEnvironment.invokeService ( service2Invoke, inputXml, timeOut) ; … if ( false == _adapterOperationEnvironment.canContinue() ) break ; } 4.2.7.4 Message-oriented operations initiated by Data Services Metadata for the message-oriented operations initiated by Data Services are Outbound Messages or Message Function Calls. You must import the metadata in Data Services and create Outbound Message Targets and Message Function Calls in the data flow before processing messages that the data flow sends to the adapter operation. Implement the ListenerOperation interface. The Adapter SDK automatically subscribes that operation to the message type derived from the operation instance name (the value of the OperationInstanceName element from the adapter instance configuration). 60 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Creating an Adapter Note that the operation instance must have the same name as the Outbound Message or Message Function Call metadata used in the Designer to define the object sending a message to this particular adapter operation instance. To expose IR metadata for import into Data Services message-oriented operations, you can choose either of the following options: ● Implement the optional Exportable interface in addition to the Operation and ListenerOperation interfaces. This option is preferred because it allows you automatically import metadata into Data Services, seamlessly linking this metadata and the operation. ● Use the generic metadata browsing framework described earlier to import the resource Outbound Message or Message Function Call metadata. Then, manually configure the message-oriented operation with the same operation instance name assigned to the imported metadata object. For this option, you must manually link the adapter operation and Data Services metadata. 4.2.7.5 Message-oriented interfaces The Exportable interface has only two methods to implement: ● public int getMetadataType() Returns the metadata type exportable by the adapter operation. Possible return types are: Table 24: com.acta.metadata.AWMetadata.AWT_OUTBOUND_MESSAGE com.acta.metadata.AWMetadata.AWT_MESSAGE_FUNCTION_CALL ● public AWMetadata[] exportMetadata() throws AdapterException Returns the array of com.acta.metadata.AWMetadata objects. The return array can contain one (typical) or more elements. Based on metadata types returned by the getMetadataType() method, the return array can contain: Table 25: com.acta.metadata.AWOutboundMessageMetadata objects for com.acta.metadata.AWMetadata.AWT_OUTBOUND_MESSAGET type, or com.acta.metadata.AWMessageFunctionCallMetadata objects for com.acta.metadata.AWMetadata.AWT_MESSAGE_FUNCTION_CALL type Example implementation of this method: … public int getMetadataType () { return AWMetadata.AWT_OUTBOUND_MESSAGE ; } … public AWMetadata [] exportMetadata() throws AdapterException { if ( null == dtdFileName ) return null ; AWOutboundMessageMetadata dm = new AWOutboundMessageMetadata () ; String metadata = new String() ; // read DTD User Guide for Adapter SDK Creating an Adapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 61 } try { FileInputStream fi = new FileInputStream ( dtdFileName ) ; byte[] buffer = new byte[4096]; int bytes_read; while ( (bytes_read = fi.read(buffer)) != -1 ) metadata += new String (buffer, 0, bytes_read) ; fi.close(); } catch ( Exception e ) { throw new AdapterException (e, "Cannot export the operation metadata.") ; } // Define the return AWOutboundMessageMetadata metadata. dm.setOutboundMessageDTD(metadata); dm.setOutboundMessageDescription("Exposes the DTD for this operation XML."); // Must use the operation instance name as the outbound message name. dm.setOutboundMessageName(_adapterOperationEnvironment.getInstanceName()) ; return new AWMetadata [] { dm } ; The ListenerOperation interface requires that you implement only one method: ● public java.lang.String handleRequest (Operation oper, java.lang.String xml) throws RecoverableOperationAdapterException, AdapterException Handles requests from Data Services data flow. Table 26: Parameter Description oper Reference to the adapter operation using this interface to handle messages from the resource. xml Input XML string sent by the real-time service to the adapter operation. Returns: XML String to send back to service. If the adapter operation processes Message Function Call from the data flow Query transform, the handleRequest method should return an XML message with the DTD defined for the output XML of the metadata for the Message Function Call used in Data Services for this operation. If the adapter operation processes Outbound Message from the data flow, then the handleRequest method must return null. When this happens, the Adapter SDK sends acknowledgment to verify that message processing was successful. Also see API documentation, com/acta/adapter/testadaper/ReceiveFromRTDF.java, and com/acta/ adapter/testadaper/CallFromRTDF.java for reference implementation. 4.2.7.6 Stream-oriented operations The Adapter SDK treats stream-oriented operations differently than message-oriented operations. While instances of message-oriented operations stay in adapter memory ready to process messages from different sources (different data flows and messages from the information resource), stream-oriented operation instances are associated with a single object in a particular data flow. Each stream oriented-operation: ● Is created upon request from the Data Services engine (from an object using metadata associated with the operation) ● Exchanges data between data flow and operation 62 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Creating an Adapter ● Destroyed on data flow request For stream-oriented operations, implement one of five available interfaces: Table 27: Interface Data flow object Returned metadata TableSource Table source AWTableMetadata TableTarget Table target AWTableMetadata DocumentSource Document source AWDocumentMetadata DocumentTarget Document target AWDocumentMetadata FunctionCall Function call AWFunctionCallMetadata All stream-oriented operation classes must implement the Operation and StreamOperation interfaces. The StreamOperation is a subinterface of the Operation interface and requires you to implement three methods in addition to those implemented for the Operation interface: ● begin() ● end() ● metadata() Because of these methods, the implemented StreamOperation interface expands the operation life-cycle for stream-oriented operations. The Adapter SDK: 1. Creates an instance of the stream-oriented operation component when requested from the operation client — data flow target, source, or function call of the running job or real-time service. 2. Calls the public void initialize (OperationEnvironment operationEnvironment) method immediately after the instance is constructed. (You can store a reference to the OperationEnvironment object for future use.) The OperationEnvironment object is implemented by the Adapter SDK and has important methods for accessing the adapter and operation properties (references Adapter and Session instances, trace and error logs, instance name, and so on). See API documentation for the details. 3. Introspects an operation and sets the adapter operation parameters from the adapter instance configuration. You define the "get" and "set" configuration properties for the operation component, same as for the Adapter and other components. You also set values for the operation properties in the Data Services Designer when configuring the adapter operation. 4. Calls the com.acta.adapter.sdkStreamOperation.metadata (Object resourceMetadata) method to make the resource metadata object imported in the Designer available for the stream-oriented operation. 5. Calls the operation's client request start() method. Make all initializations specific for this operation inside start() because the start() method is called once for the operation life time. 6. Calls the operation's client request begin() method. Data Services logic may require the operation to restart processing. For instance, the Data Services engine might make a request to read the same table several times. While you cannot control this in the adapter operation code, it is handled with begin() and end() method implementation. These methods are responsible for re-starting processing. For example, you can reset the cursor if reading the database table. Execution of the begin() and end() method pair can be requested by the operation's client multiple times during the life of an operation. 7. Now operation is ready to process data. This part is specific for the type of adapter operation and will be discussed later. User Guide for Adapter SDK Creating an Adapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 63 8. Calls the operation's client request end() method. See notes for the begin() methods. 9. Calls the stop() method before the Adapter SDK destroys the operation instance, de-allocating the operation resources allocated in start(). Related Information Link between Data Services and IR metadata [page 58] 4.2.7.7 Stream-oriented interfaces The Table interface is the super interface for TableSource and TableTarget interfaces which you must implement to support table sources and table targets in Data Services data flows. Methods for this interface are: ● getDateFormat public java.lang.String getDateFormat() Returns the data format. Use "yyyy.mm.dd hh24:mi:ss" as the default value. For other formats see Data Services technical documentation. ● getRecordFormat public int getRecordFormat() Returns the record format com.acta.adapter.sdk.Table.RecordFormatXml or com.acta.adapter.sdk.Table.RecordFormatDelimited. If com.acta.adapter.sdk.StreamOperation.RecordFormatDelimited is returned for the TableSource interface implementation, the operation should pack the data as records separated by Delimited.getRowDelimiter() with columns separated by Delimited.getColumnDelimiter(). Note If the Delimiter interface is not implemented, the operation must use the default values. If com.acta.adapter.sdk.StreamOperation.RecordFormatDelimited is returned for the TableTarget interface implementation, the data that operation receives from the engine is packed as records separated by the value returned by Delimited.getRowDelimiter(), with columns separated by the value returned from Delimited getColumnDelimiter(). Note See other delimiters in Delimited interface. If the Delimited interface is not implemented, Data Services uses the default values. If com.acta.adapter.sdk.Table.RecordFormatXml is returned for the TableSource interface implementation, the operation should pack the data as XML with the following structure: <AWA_BatchWrapper> < AWA_Row> <colname>...</colname> ... <colname>...</colname> 64 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Creating an Adapter </ AWA_Row> ... < AWA_Row> <colname>...</colname> ... <colname>...</colname> </ AWA_Row> </AWA_BatchWrapper> While you can vary <AWA_BatchWrapper> and <AWA_Row> element names, the <colname> elements must match column names defined in the Data Services metadata imported for the TableSource receiving the data in the Data Services data flow associated with this operation. If com.acta.adapter.sdk.Table.RecordFormatXml is returned for the TableTarget interface implementation, the data that operation receives from Data Services is packed as XML with the following structure: <AWA_BatchWrapper> < AWA_Row> <colname>...</colname> ... <colname>...</colname> </ AWA_Row> ... < AWA_Row> <colname>...</colname> ... <colname>...</colname> </ AWA_Row> </AWA_BatchWrapper> The <AWA_BatchWrapper> and <AWA_Row> element names can be different but <colname> elements must match column names defined in the Data Services metadata to be imported for the TableTarget that sends the data in the Data Services data flow from this operation. Implement the Delimited interface for stream-oriented adapter operations that must read or write data using a custom (not default) delimited format. You may want to implement this interface in addition to TableSource or TableTarget interfaces, for the adapter operation implementation to customize the delimiters for data exchanges between your adapter and the Data Services engine. Methods for this interface are: ● getColumnDelimiter public java.lang.String getColumnDelimiter() Returns the field separator. Default is ",". ● getEscapeChar public java.lang.String getEscapeChar() Returns the escape character. Default is "". ● getRowDelimiter public java.lang.String getRowDelimiter() Returns the record separator. Default is "/n". ● getTextDelimiter public java.lang.String getTextDelimiter() Returns the text delimiter. Default is "". Default data exchange uses the delimited format and the default values documented for each method of this interface. User Guide for Adapter SDK Creating an Adapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 65 For custom-delimited data exchange between your adapter and Data Services, implement this interface. Then, to enable delimiter configuration for each operation instance from the Designer, use the "get" and "set" methods. For instance: String rowDelimiter = ";" // Default value different from the system default. public String getRowDelimiter () { return rowDelimiter ; } public String setRowDelimiter (String delim) { // Allows configuration of this property from the // Designer. rowDelimiter = delim ; } For details see the API documentation for this interface. Implement the SQLEnable interface to complement the TableSource interface if your adapter is SQL-enabled. The SQLAdapter interface implementation of the getSqlSupport() method must return com.acta.adapter.sdk.SQLAdapter.AWA_FullSQL. The Adapter SDK will call the sqlText(String sql) method to set the SQL string generated by Data Services to select data from the database. When executed, this SQL statement returns rows with the columns required by Data Services to continue data transformations. 4.2.8 Customize presentation of adapter components Some component properties for Data Services adapters are exposed and are configurable in the Data Services Management Console Administrator, some in the Designer. To enable users to find and configure adapter component properties, use the following table to map adapter components with the Data Services user interface in which they are exposed and the specific context in which the user will configure properties: Table 28: Component Exposed in Configuration context Adapter Administrator Adapter configuration form Session Designer Adapter datastore tab of datastore window ImportByName Designer Import-By-Name window Message-oriented Administrator Operation configuration form Stream-oriented Designer Adapter sources, targets, function calls MetadataNode Designer Metadata browsing window Statistics Administrator Select a running adapter instance Operation All adapter components are Java Beans compliant with JavaBeans standards for properties and introspection. Java Beans can have configurable properties which you can customize using the BeanInfo class. You can add simple user interfaces to the Administrator or Designer for adapter components quickly by coding set and get methods (see the Adapter SDK API for details). However, to add more customization, such as default values, descriptions, and so forth, create a complimentary BeanInfo class. 66 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Creating an Adapter The following two sections are a configurable properties customization tutorial and include instructions for modifying configurable properties in your sample adapter (TestAdapter) and viewing customized results in both the Administrator and Designer. Use these instructions as a guideline for customizing configurable properties for other adapter components. 4.2.8.1 Customize using get() and set() The following instructions explain how to create an adapter operation with a configurable property. These instructions use TestAdapter as an example. 4.2.8.1.1 Creating an adapter operation component with a configurable property 1. Create your adapter operation component, adding a set method for the configurable property. For the purpose of this exercise, add the following TestOperation class containing a property named "testProperty" to TestAdapter: package com.acta.adapter.testadapter; import com.acta.adapter.sdk.*; public class TestOperation implements Operation { //Configurable property testProperty String testProperty ; public void setTestProperty ( String test ) { testProperty = test ; } //Interface implementation OperationEnvironment _operationEnvironment ; public void initialize ( OperationEnvironment operationEnvironment ) { _operationEnvironment = operationEnvironment ; } public void start() throws AdapterException { _operationEnvironment.println ( "TestAdapter::TestOperation Started." ) ; } public void stop() throws AdapterException { _operationEnvironment.println ( "TestAdapter::TestOperation Stopped." ) ; } } 2. If TestAdapter is running, go to the Data Services Administrator and stop it. 3. Open the TestAdapter.java source code file in the <LINK_DIR>/adapters/sdk/samples/ testadapter/data/src/com/adapter/testadapter directory and update the TestAdapter class by adding a line (indicated below in bold) for the new TestOperation class under operationClassNames: … … … private String[] _operationClassNames = { "com.acta.adapter.testadapter.InvokeService" ,"com.acta.adapter.testadapter.ReceiveFromRtdf" ,"com.acta.adapter.testadapter.WriteDocument" ,"com.acta.adapter.testadapter.FunctionCallTest" ,"com.acta.adapter.testadapter.TestOperation" } ; User Guide for Adapter SDK Creating an Adapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 67 4. Re-create TestAdapter.jar and re-generate the adapter run-time configuration. Use LINK_DIR/ adapters/sdk/samples/testadapter/buildTestAdapter.bat to: ○ Compile the java source code ○ Package TestAdapter in acta_test_adapter.jar file ○ Re-generate the adapter run-time configuration file, LINK_DIR/adapters/config/template/ TestAdapter.xml 5. Start TestAdapter. 6. Use a text editor to open the adapter run-time configuration template located in the LINK_DIR/adapters/ config/templates directory (for this example, TestAdapter.xml). 7. View your new configuration property with the system properties added to all message-oriented operations. <com.acta.adapter.testadapter.TestOperation DisplayName ="TestOperation" SDKVersion ="2.0.0"> <operationInstanceName DisplayName="Operation instance" Description="For the messages that this operation receives from Data Services this name should match the correspondent outbound message or function call name."></operationInstanceName> <threadCount DisplayName="Thread count" Description="Number of copies of this operation to run in parallel.">1</threadCount> <displayName DisplayName="Display name" Description="Display name for metadata browsing."></displayName> <description DisplayName="Description" Description="Description for metadata browsing."></description> <enable DisplayName="Enable" Description="Enable to run operation when adapter starts." Choices="true|false" >true</enable> <testProperty DisplayName ="testProperty"></testProperty> </com.acta.adapter.testadapter.TestOperation> 8. Open the Data Services Administrator and configure a new adapter operation. In the Operation type list, you should see your new operation. 9. From the Operation type list, select TestOperation and click Apply to see the operation configuration form for TestOperation. Here, you can see your newly configured property: testProperty. Please note that: ○ The operation name appearing above the configuration form (TestOperation) is the class name, and it is not very informative. ○ There is no description provided for testProperty. ○ There is no default value for testProperty. 10. Open the TestOperation class file added at the beginning of this procedure and add a default value for testProperty by providing a “get” and assigning an initial value of “ABC”. The new source code will look something like this: package com.acta.adapter.testadapter; import com.acta.adapter.sdk.*; public class TestOperation implements Operation { //Configurable property testProperty String testProperty = "ABC"; public void setTestProperty ( String test ) { testProperty = test ; } public String getTestProperty () { return testProperty ; } //Interface implementation OperationEnvironment _operationEnvironment ; public void initialize ( OperationEnvironment operationEnvironment ) { 68 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Creating an Adapter } _operationEnvironment = operationEnvironment ; } public void start() throws AdapterException { _operationEnvironment.println ( "TestAdapter::TestOperation } public void stop() throws AdapterException { _operationEnvironment.println ( "TestAdapter::TestOperation } Started." ) ; Stopped." ) ; 11. Repeat the deployment procedure described the previous steps to see your TestOperation configuration form changes. The value “ABC” should appear in the text box next to testProperty. To provide a more user-friendly configuration form display name and a property description, you must provide default values and value choices by customizing the Java Bean. 4.2.8.2 Customizing the Java Bean To further customize an adapter component, create the BeanInfo class for that component. So, to further customize your new TestOperation class, you must create the TestOperationBeanInfo class. For more information, see JavaBeans specifications at: http://java.sun.com/products/javabeans/docs/ The code for TestOperationBeanInfo class will look something like this: package com.acta.adapter.testadapter; import java.beans.*; import com.acta.adapter.sdk.*; public class TestOperationBeanInfo extends SimpleBeanInfo { public TestOperationBeanInfo() { super() ; } public BeanDescriptor getBeanDescriptor() { BeanDescriptor bn = new BeanDescriptor (com.acta.adapter.testadapter.TestOperation.class) ; bn.setName("Test Operation." ); bn.setShortDescription ("This is the description for the Test Operation." ); return bn; } public PropertyDescriptor[] getPropertyDescriptors() { PropertyDescriptor[] pd = null; try { PropertyDescriptor testProperty = new PropertyDescriptor ( "testProperty",com.acta.adapter.testadapter.TestOperation.class ) ; testProperty.setDisplayName("Test Property") ; testProperty.setShortDescription("Enter the value for the Test Property.") ; pd = new PropertyDescriptor [] { testProperty } ; } catch (Exception exc) { new AdapterException ( exc, "Introspection error. Cannot construct the property descriptor." ) ; } return pd; } Update your adapter with these changes using the same procedure provided in Customize using get() and set() [page 67]. The new TestOperation configuration form will look like this: User Guide for Adapter SDK Creating an Adapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 69 Customization code essentials include the following (for complete information see JavaBeans documentation): 1. For your adapter component, Foo, create the class FooBeanInfo. 2. Extend the SimpleBeanInfo interface. 3. To customize the component, overwrite the public BeanDescriptor getBeanDescriptor() method. 4. To customize component properties, overwrite PropertyDescriptor[]getPropertyDescriptors() method. The returned PropertyDescriptor[] array will contain PropertyDescriptor for each property. Each PropertyDescriptor can have the standard customizers: ○ Display name ○ Short Description ○ Hidden ○ Attributes. The Designer and Administrator respect the following attributes defined in com.acta.adapter.GuiAttributes: Table 29: Name Value Description Default Echo "true" Echo typing with "*". "false" "false" Do not echo typing. "true" Property can be edited. "false" Cannot edit the property "true" Value required. "false" Value not required. isEditable isRequired Default 70 "true" "false" Attribute associated with the property default value. The attribute value you set be­ comes the default value that initially displays the Data Services Designer and Admin­ istrator. PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. N/A User Guide for Adapter SDK Creating an Adapter Name Value Choices Attribute associated with the choices available for the property. The attribute value should be text with the choices separated by "|". Order Numeric value: "1" = the first property "2" = the second property Description Controls display order of properties in the Designer and Administrator. The property with the value of this attribute equals "2" will be displayed next in order in the configuration form or dialog. Default N/A 0 (Order does not matter.) ... and so on. Below the sample of the customizer for the ImportByName component of the TestAdapter: package com.acta.adapter.testadapter; import java.beans.*; import com.acta.adapter.sdk.*; public class TestImportByNameBeanInfo extends SimpleBeanInfo { public TestImportByNameBeanInfo() { super() ; } public BeanDescriptor getBeanDescriptor() { return null ; } public PropertyDescriptor[] getPropertyDescriptors() { PropertyDescriptor[] pd = null; try { PropertyDescriptor metadataType = new PropertyDescriptor ( "metadataType",com.acta.adapter.testadapter.TestImportByName.class ) ; metadataType.setDisplayName("Metadata Type") ; metadataType.setShortDescription("Enter the metadata type choice") ; metadataType.setValue ( GuiAttributes.ATTR_CHOICES, Browse.METADATA_TABLE + "|" + Browse.METADATA_DOCUMENT + "|" + Browse.METADATA_FUNCTION_CALL ) ; metadataType.setValue(GuiAttributes.ATTR_DEFAULT, Browse.METADATA_TABLE ); PropertyDescriptor metadataName = new PropertyDescriptor ("metadataName",com.acta.adapter.testadapter.TestImportByName.class ) ; metadataName.setDisplayName("Metadata Name") ; metadataName.setShortDescription("Enter the metadata name") ; pd = new PropertyDescriptor [] { metadataType, metadataName } ; } catch (Exception exc) { new AdapterException ( exc, "Introspection error. Cannot construct the property descriptor.") ; } return pd; } } Please note: ● We do not need the description and display name for this component therefore getBeanDescriptor() method returns null. ● We use GuiAttributes.ATTR_CHOICES attribute to provide the choice of values from the Import By Name dialog in the Data Services Designer. The result you will see in the Designer is: User Guide for Adapter SDK Creating an Adapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 71 All get and set methods should be defined as the public methods. If property does not have get or set use the appropriate constructor for PropertyDescription in getPropertyDescriptors() method. For instance when set and get are defined, use: PropertyDescriptor testProperty = new PropertyDescriptor ( "testProperty",com.acta.adapter.testadapter.TestOperation.class ) ; If only "set" is defined, use: PropertyDescriptor testProperty = new PropertyDescriptor ( "testProperty",com.acta.adapter.testadapter.TestOperation.class, null, "settestProperty" ) ; 4.2.9 Error handling Methods implemented by the Adapter SDK throw exceptions that must be caught and processed by the developer. The Adapter SDK logs error text in the error and trace log files. Also, consult the Adapter SDK API documentation for more details. Methods you implement can throw two types of exceptions: ● AdapterException ● RecoverableOperationAdapterException The Adapter SDK catches these exceptions and responds as follows: ● AdapterException: Logs an error and stops the adapter or operation based on where the exception was thrown. ● RecoverableOperationAdapterException: Logs an error and continues adapter operation. (This exception can be thrown only from operation-related classes.) 72 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Creating an Adapter The following code provides an example of both AdapterException and RecoverableOperationAdapterException: public void poll() throws RecoverableOperationAdapterException, AdapterException { ... try { ... // call real-time service reply = _adapterOperationEnvironment.invokeService ( _service2Invoke, inputXml, timeOut) ; ... } catch ( TimeoutAdapterException e ){ //log the error and continue throw new RecoverableOperationAdapterException (e) ; } catch ( RecoverableOperationAdapterException e ) { //log the error and continue throw e ; } ... catch ( AdapterException e ) { //stop operation throw e ; } ... } Related Information Trace and error logging [page 73] 4.2.10 Trace and error logging The Adapter SDK allows you to log error and trace messages. Error messages are stored in error log files and named according to the structure: <adapter instance name>_error.txt. These files appear in the <LINK_DIR>/adapters/log/ directory. Located in the same directory, trace log files use a similar naming convention: <adapter instance name>_trace.txt . These files contain error and trace messages. The Adapter SDK lists error and trace messages in the following format: <date> <time> <message> <new line> Examples: Table 30: 11/16/01 5:20:16 PM TestAdapter::InvokeService Poll() 11/16/01 5:20:29 PM TestAdapter::InvokeService Poll() To log an error or trace message, use the following methods in the AdapterEnvironment interface: User Guide for Adapter SDK Creating an Adapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 73 ● logError(String message) — Send a string to the error log file. ● logTrace(String message) — Send a string to the trace and error log file. ● println(String message) — Send a string to the trace log file, only if Trace mode is set to “true” . You can set the Trace mode in the Data Services Administrator, from the adapter configuration form. From the adapter code, use the AdapterEnvironment interface method isDebug() to check if Trace mode is set to “true”. Use println(String message) method to generate extra output if Trace mode is set to “true” . You can obtain the same results using two slightly different pieces of code: ● adapterEnvironment.println("message to log") Recommendation: use this selection during development and testing of your adapter. ● if(adapterEnvironment.isDebug()) ● adapterEnvironment.printin("message to log"); Recommendation: use this selection for time-critical code. At run-time, Java will not create the extra String object (parameter for printIn) if isDebug() returns “false”. When you debug your adapter, the Adapter SDK duplicates all messages (error and trace) to the system.out(screen). Find log file information for an adapter instance in the Adapter Instance Status page of the Data Services Administrator. Select Status Adpater instances to view all configured adapter instances. Under Log Files, each adapter instance lists a Trace and an Error link. Click a link to see current error or trace information for that instance. To clear the log, scroll to the bottom of the log file and click Truncate. Note The Adapter Operation Status page in the Administrator shows a Last Error status column. However, the last error message does not necessarily correspond to the source of the problem. To analyze an error, always refer to the log files. 4.2.11 Statistics You can accept adapter default statistics or implement the Statistics interface to define your own. If you use the default statistics, you can view them in the Data Services Administrator by selecting a running adapter instance in the Adapter Status tab. 74 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Creating an Adapter Statistics (for example, instance names, status, and last errors) are provided by the Adapter SDK. To provide Request, Processed, and Rejected counter values for message-oriented operations, you can add code for the operation implementation. The semantics for the counters are: ● Request count — Adapter operation received message from information resource or from Data Services. ● Processed count — Adapter operation successfully processed a message from the information resource or from Data Services. ● Rejected count — Error occurred when operation processed a message from the information resource or from Data Services and processing failed. Use the following methods for the OperationEnvironment interface: ● incrementRequestCount public void incrementRequestCount() Increments by 1 the number of requests received by the operation. Call this method after the adapter operation receives a processing request. User Guide for Adapter SDK Creating an Adapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 75 ● incrementProcessedCount public void incrementProcessedCount() Increments by 1 the number of requests processed by the operation. Call this method after an adapter operation successfully processes a request. ● incrementRejectedCount public void incrementRejectedCount() Increments by 1 the number of requests rejected by the operation. Call this method after the adapter operation has rejected the request for processing. ● getRequestCount public int getRequestCount() Returns the number of requests received by the operation. Useful for custom statistics when incrementRequestCount() method is used to track the number of requests received. ● getProcessedCount public int getProcessedCount() Returns the number of requests processed by the operation. Useful for custom statistics when incrementProcessedCount() method is used to track the number of requests processed. ● getRejectedCount public int getRejectedCount() Returns the number of requests rejected by the operation. Useful for custom statistics when incrementRejectedCount() method is used to track the number of requests rejected. The code sample from the previous “Error handling” section is modified (shown in bold) to illustrate. public void poll() throws RecoverableOperationAdapterException, AdapterException { ... try { ... // receive message _adapterOperationEnvironment.incrementRequestCount() ; ... // call real-time service reply = _adapterOperationEnvironment.invokeService ( _service2Invoke, inputXml, timeOut) ; ... // process message _adapterOperationEnvironment.incrementProcessedCount() ; } catch ( TimeoutAdapterException e ){ // reject message _adapterOperationEnvironment.incrementRejectedCount() ; //log the error and continue throw new RecoverableOperationAdapterException (e) ; } catch ( RecoverableOperationAdapterException e ) { // reject message _adapterOperationEnvironment.incrementRejectedCount() ; //log the error and continue throw e ; } ... catch ( AdapterException e ) { // reject message _adapterOperationEnvironment.incrementRejectedCount() ; //stop operation throw e; } ... } 76 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Creating an Adapter To provide custom statistics, implement the Statistics interface and link the implementation in the initialize method of the Adapter interface implementation using the AdapterEnvironment.setStatisticsClassName method. There are only two methods to implement: ● initialize public void initialize (Adapter adapter, AdapterEnvironment environment,Vector sessions, Vector operations,Vector operationEnvironments) throws AdapterException; Sets references to the currently active adapter, adapter environment, sessions, operations, and operation environment objects. ● collect public void collect() throws AdapterException; Collects the statistic. Implementing this method assigns the value to the properties of the custom statistics class. Click the running adapter instance in the adapter Status tab of the Administrator to see Properties. When you click the adapter instance, the Adapter SDK creates the statistics object, then calls the initialize method with the instances of all major adapter components currently available. Save references to the statistics object and use it in the collect method that the Adapter SDK calls next. While not critical, it is important to have the thread save access to these objects because statistics change constantly while the adapter runs and you do not change, but access the data inside the collect method. The collect method should assign values to statistics object properties. These properties are displayed in the Administrator as property name/property value pairs. 4.3 Create adapter user documentation Your adapter is not complete without adapter user documentation. You must create a document to instruct adapter users on how to install, configure, and use your custom adapter. Your document should contain: ● Introduction—Provide any information that would help users understand the rest of the document (include terms, conventions, and so forth). ● Overview—Discuss your information resource, what users can do with your customer adapter, and mention related adapters. ● Installation—Discuss system pre-requisites, introduce adapter file/component architecture, discuss how to prepare the computer environment (both from the Data Services end and the information resource end), and provide explicit installation instructions. ● Use—Explain what can be moved from Data Services to the information resource and what can be moved from the IR to Data Services, explicitly provide adapter configuration instructions, perhaps provide a test/ tutorial use scenario. ● Technical implementation—List any potential limitations of and assumptions about the adapter, describe how to trace and handle errors (including where error information is stored). A sample document called AdapterDocTemplate is provided as a guideline to help you assemble documentation about your custom adapter. When you create your own document, you can duplicate this structure and: User Guide for Adapter SDK Creating an Adapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 77 ● Replace all references to “information resource” and “IR” with the name of your adapter's information resource ● Enter specific details for using your custom adapter 4.4 Adapter operation After writing the adapter code complete the following steps to: ● Compile and package adapter components ● Prepare configuration templates (run-time and start-up) ● Configure adapter instance components (to work with Data Services and the information resource) ● Debug the adapter ● Move the adapter from test to production 4.4.1 Compile and package adapter components Since Data Services custom adapters are Java applications, you must use the available Java compiler and utilities to compile and package your adapter. Use a batch file to: ● Compile adapter source code ● Package classes to the jar file Find the sample batch file for the TestAdapter at: <LINK_DIR>/adapters/sdk/samples/testadapter/ buildTestAdapter.bat. After it is compiled and packaged, you can run your custom adapter as a stand-alone application. However, to run the adapter as part of the Data Services system, you must prepare adapter configuration templates. 4.4.2 Prepare configuration templates Custom adapters cannot work as part of the Data Services system without two necessary files: the adapter startup configuration template and the adapter run-time configuration template. Both configuration templates: ● Are XML files you can manually edit (not recommended) ● Must be installed with your custom adapter The Administrator uses the configuration templates to provide configuration screens where Data Services users can enter information to create configuration scripts during adapter instance configuration. Users can also modify and remove configuration scripts using the Administrator. When you install a custom adapter, these two configuration templates must be provided with the installation. EXAMPLE: If you had created TestAdapter you would manually create <LINK_DIR>/adapters/install/ TestAdapter.xml from <LINK_DIR>/adapters/AdapterInstallationTemplate.xml and by using 78 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Creating an Adapter rtt.bat (rtt.sh on UNIX), would generate <LINK_DIR>/adapters/config/templates/ TestAdapter.xml. 4.4.3 Configure adapter instance components Before using an adapter with Data Services, you must configure components in the Administrator and Designer. In the Data Services Administrator, configure: ● Adapter instance start-up and run-time properties ● Message-oriented operation run-time properties These scripts and message-oriented operations are configured in the Administrator because they are created once and run for the entire adapter life cycle. If you reconfigure an adapter instance or a message-oriented operation, you must restart the adapter instance. In the Data Services Designer, configure: ● Sessions These translate to adapter datastore properties. Set values in the Adapter Properties tab of the Adapter Datastore Editor. ● Stream-oriented adapter operations Sessions and stream-oriented operations are configured in the Data Services Designer because they are created each time the client (Designer or engine) makes a request. These components can be created and configured for each running adapter instance. When you initially create adapter instance and message-oriented operation configurations, you actually convert the adapter configuration templates to configuration scripts by setting values for the adapter instance and operation properties. For Session and stream-oriented operations, the Data Services Designer provides windows in its graphical user interface for configuration of all exposed (public) properties that implement “set” methods. When you configure an adapter instance, the Adapter SDK creates (for the first configured adapter instance) or modifies the <LINK_DIR>/adapters/startup_script.xml that contains startup configuration scrips dor all configured adapter instances. The Adapter SDK also creates the <LINK_DIR>/adapters/config/<Adapter Instance Name>.xml file containing adapter and message-oriented adapter operation configuration scripts. EXAMPLE: For TestAdapter this second file is <LINK_DIR>/adapters/config/TestAdapterInstance.xml. When you update the adapter run-time or start-up configuration you are modifying these two files. When you create a message-oriented adapter operation you actually modify the <LINK_DIR>/adapters/ config/<Adapter Instance Name>.xml file using the adapter run-time configuration template from <LINK_DIR>/adapters/config/tempate<Adapter Type Name>.xml. When configuring Adapter Properties (Sessions) or stream-oriented operations the Data Services Designer provides the windows to configure all exposed (public) properties that implement a “set” method. See the Designer Guide for details on how to use a custom adapter in the Data Services Designer. User Guide for Adapter SDK Creating an Adapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 79 Related Information Configuring an adapter instance [page 90] Configuring an adapter operation [page 91] Creating the TestAdapter datastore [page 101] 4.4.4 Debug the adapter Debug your custom adapter after you have: ● Developed your adapter ● Configured the adapter and operations ● Created an adapter datastore in the Data Services Designer ● Imported adapter metadata ● Created correspondent data flows and real-time data flows ● Configured real-time services ● Configured your information resource Because at least three different applications are involved (resource, adapter, and Data Services) the process of stabilizing a custom adapter for a production environment is not trivial. If data you receive as a result of integrated data processing is incorrect, or if some integrated components fail to run, you can debug your adapter to understand and correct any problems. Two ways to debug include: 1. "Trace mode" — In the Administrator, go to the adapter configuration form and set the value to true (false is default). 2. You can debug the adapter as the Java application. When Trace mode is true, the Adapter SDK will provide verbose output. Methods AdapterEnvironment.println(String message) and OperationEnvironment.println(String message) will output messages to the adapter trace log file. When Trace mode is false these methods do not produce output. AdapterEnvironment.isDebug() returns "true". You can use this flag to code special actions for the custom adapter when Trace mode is true. 4.4.5 Moving the adapter from test to production After testing is complete, you can move your adapter into a production environment. 1. Ensure that a compatible version of Data Services is already installed in the production environment. The Data Services Job Server and Access Server must be installed on the workstation before you install your custom adapter. 2. In the Data Services production environment directory, create the following adapters file structure: 80 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Creating an Adapter 3. Move the custom adapter installation template, configuration template, and jar file to their designated directories: File Directory location Installation template <LINK_DIR>/adapters/install/<adapter_name>.xml configuration template <LINK_DIR>/adapters/config/templates/<adapter_name>.xml adapter jar file <LINK_DIR>/lib/<adapter_name>.jar 4. Stop and re-start Data Services services. 5. If you have not already done so for this environment, configure a “Primary” repository and a Job Server for adapter management. 6. In the Administrator, configure an instance of your adapter, then start the adapter instance. 7. In the Designer, create a corresponding adapter datastore. Manually associate the adapter manager Job Server. Related Information Establishing adapter management [page 11] Configuring an adapter instance [page 90] 4.4.6 Moving a production adapter to another environment To move an existing custom adapter and all associated jobs into another production environment, you will need to use Data Services Designer export capabilities. 1. Install your adapter in the new production environment. (See steps 1 through 5 in Moving the adapter from test to production [page 80] for details.) 2. Open the Administrator and configure an adapter instance using name and attribute values specific to the production environment. User Guide for Adapter SDK Creating an Adapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 81 Note You are not required to use the same adapter instance name you used in the test environment. However, you must use the name you choose to: ○ Configure the adapter instance. ○ Rename the adapter run-time configuration file (copied from the test environment). ○ Update the adapter instance name for the imported adapter datastore in the Designer. 3. Start the adapter instance, verify it runs, then stop the adapter. 4. Move the adapter configuration script file from the old environment to the new environment. 5. Stop the Data Services service, then restart it. 6. Reconfigure all message-oriented operations in the Administrator, or copy the adapter run-time configuration file <LINK_DIR>/adapter/config/<adapter_instance_name>.xml from the old to the new production environment. 7. From the old environment Designer, export any jobs you created using the adapter to the new production repository. See the Designer Guide for details on exporting objects. 8. Open the Designer in the new environment. 9. Reconfigure the adapter datastore. Choose an adapter manager Job Server and adapter instance name for the new environment, if necessary. Save the new configurations. 10. Re-import environment-dependent metadata through the adapter browsing window. 11. If necessary, update the properties of second class objects (sources, targets...)for the new environment. 12. Restart the adapter from the Administrator. This step is particularly important if you run message-oriented operations, and/or associated a new Job Server with the adapter datastore. Related Information Configuring an adapter instance [page 90] 82 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Creating an Adapter 5 Packaging and deployment Data Services provides you with a script file that packages and deploys the new adapter to the Data Services environment. To package and deploy your new adapter, perform the following: 1. Add an entry for the new adapter into the AdaptersLatestVersions.csv file, located at <DS_COMMON_DIR>\adapters\upgrade\. For example: MyAdapter|My Adapter|test.MyAdapter|14.2.0.0|/lib/my_adapter.jar 2. Edit to match your Data Services environment and execute the sample script <DS_COMMON_DIR>\sdk \samples\TestAdapter\buildTestAdapter.bat. This script performs the following: ○ Builds the adapter java files ○ Packages the adapter classes into a .jar ○ Creates both required .xml configuration files (Script automatically creates XML files as shown above) ○ Copies the .jar and .xml files into Data Services environment 3. You can review the error and trace messages of the script in the file below: <DS_COMMON_DIR>\adapters \upgrade\upgrade_trace.txt User Guide for Adapter SDK Packaging and deployment PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 83 6 Configuring and Running an Adapter 6.1 Adapter configuration Before an adapter can integrate an information resource (IR) with the Data Services system, two types of configuration must occur to facilitate communication between Data Services an IR: ● The adapter writer configures the adapter start-up template and generates a run-time configuration template ● Data Services user configures each adapter instance and associated adapter operations 6.1.1 Preparing configuration templates For each adapter, you must prepare two important files: the Adapter start-up configuration template and the Adapter run-time confugration template. Later, when an Data Services user configures adapters from the Administrator, the adapter start-up and run-time XML template files are converted to configuration scripts. The Data Services Administrator configures each instance of an adapter type as an Data Services subsystem using the adapter's start-up configuration script. In addition, each adapter instance has its own configuration file that configures one or more instances of each operation that the adapter owns and acts as the adapter's run-time configuration. Both start-up and run-time configuration scripts are represented in XML format. The Adapter SDK includes a function that automatically generates a template for you to use in creating the adapter instance configuration file. 6.1.1.1 Preparing the adapter start-up configuration template 1. Copy the AdapterInstallationTemplate.xml file provided with the Adapter SDK installation from the <LINK_DIR> \/adapters directory to the LINK_DIR/adapters/install/ directory, then change the name of this file to <<AdapterName>>.xml . 2. Edit this file with a text or XML editor. Change element values: 84 Element name Element value adapterJarFile Adapter directories and zip/jar files separated by semicolons. Show the location relative to <LINK_DIR>. <LINK_DIR> will be attached automatically when a new adapter in­ stance is configured in the Administrator. adapter3PartyJarFiles Adapter directories and zip/jar files separated by semicolons. Will be added to the class­ path without changes when you configure the new adapter instance in the Administrator. PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Configuring and Running an Adapter Element name Element value adapterTypeName The name of the installed adapter. The adapter installation template and the adapter runtime template file names must use this name with the .XML extension. adapterTypeVersion The adapter version number that appears in the Administrator. adapterMainClass The fully qualified adapter class name. adapterAdditionalParame­ ters Additional command line parameters used when starting the adapter. 3. Save the file as <LINK_DIR>/adapters/install/<AdapterName>.xml. When installing the adapter on a workstation, you must include this adapter start-up configuration template. 6.1.1.2 Generating the adapter run-time configuration template After you finish coding an adapter, you can generate the adapter run-time configuration template. At the command prompt, enter: java -classpath <list_of_JAR_files> com.acta.adapter.sdk.AdapterMain -a <adapter_class> -d <configuration_template_file_name> where: <list_of_JAR_files> — all Java libraries necessary to run an adapter type. These are: ● <LINK_DIR>/lib/acta_adapter_sdk.jar; ● <LINK_DIR>/lib/acta_broker_client.jar; ● <LINK_DIR>/lib/acta_tool.jar; ● <LINK_DIR>/ext/lib/xerces.jar; ● <LINK_DIR>/lib/<adapter type name>.jar <<adapter_class>> — the fully qualified name of the adapter type class. <<configuration_template_file_name>> — the name of the file for the generated adapter configuration template. Note For adapter installation, the template file must be saved as <LINK_DIR>/adapters/config/templates/ <AdaperName>.xml. Note that the file name is the same as the adpater installation template, but location and contents are different. The batch file, rtt.bat (rtt.sh on UNIX) generates the adapter run-time configuration template and is provided with the Adapter SDK installation. The syntax for using this file is rtt.bat <Adapter jar file> <Adapter type name> <Adapter main class>. For example: rtt.bat c:/actaworks/lib/acta_test_adapter.jar TestAdapter User Guide for Adapter SDK Configuring and Running an Adapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 85 com.acta.adapter.testadapter.TestAdapter and on UNIX, rtt.sh $LINK_DIR/lib/acta_test_adapter.jar TestAdapter com.acta.adapter.testadapter.TestAdapter 6.1.1.3 Run-time configuration template structure The generated configuration template contains two basic parts: ● The DTD describing required syntax for the XML configuration script ● A DTD-compliant XML script containing definitions of configuration elements and their attributes for the adapter type and its operation types The Administrator uses this template to create the run-time configuration script from the configuration dialog after adding, updating, and removing the adapter and adapter operation instances. This script provides information necessary to configure adapter and message-oriented operations (values for adapter configuration properties). Note Adapter and operaton run-time configuration results are saved in the <LINK_DIR>/adapters/ config<AdapterName>.xml file. Although it is not recommended, you can edit this file manually using an XML or text editor. The TestAdapter (the sample adapter provided with the Adapter SDK) run-time configuration template looks something like this: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE AdapterConfiguration[ <!ELEMENT AdapterConfiguration ( com.acta.adapter.testadapter.TestAdapter*,com.acta.adapter.testadapter.InvokeService *,com.acta.adapter.testadapter.ReceiveFromRtdf*, com.acta.adapter.testadapter.CallFromRtdf*)*> <!ELEMENT com.acta.adapter.testadapter.CallFromRtdf (operationInstanceName,threadCount,displayName,description, enable,responseXmlFileName?,outputDtdFileName?,inputDtdRootElement?, inputDtdFileName?,outputDtdRootElement?)> <!ELEMENT outputDtdRootElement (#PCDATA)> <!ELEMENT inputDtdFileName (#PCDATA)> <!ELEMENT inputDtdRootElement (#PCDATA)> <!ELEMENT outputDtdFileName (#PCDATA)> <!ELEMENT responseXmlFileName (#PCDATA)> <!ELEMENT com.acta.adapter.testadapter.ReceiveFromRtdf (operationInstanceName,threadCount,displayName,description,enable, dtdRootElement?,targetFileName?,dtdFileName?)> <!ELEMENT dtdFileName (#PCDATA)> <!ELEMENT targetFileName (#PCDATA)> <!ELEMENT dtdRootElement (#PCDATA)> <!ELEMENT com.acta.adapter.testadapter.InvokeService (operationInstanceName,pollingIntervalMSec,threadCount,displayName, description,enable,timeOut?,sourceXmlFileName?)> <!ELEMENT sourceXmlFileName (#PCDATA)> <!ELEMENT timeOut (#PCDATA)> 86 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Configuring and Running an Adapter <!ELEMENT enable (#PCDATA)> <!ELEMENT description (#PCDATA)> <!ELEMENT displayName (#PCDATA)> <!ELEMENT threadCount (#PCDATA)> <!ELEMENT pollingIntervalMSec (#PCDATA)> <!ELEMENT operationInstanceName (#PCDATA)> <!ELEMENT com.acta.adapter.testadapter.TestAdapter (rootDirectory?)> <!ELEMENT rootDirectory (#PCDATA)> <!ATTLIST com.acta.adapter.testadapter.CallFromRtdf DisplayName CDATA #IMPLIED Description CDATA #IMPLIED isHidden CDATA #IMPLIED isArray CDATA #IMPLIED SDKVersion CDATA #IMPLIED> <!ATTLIST outputDtdRootElement DisplayName CDATA #IMPLIED Description CDATA #IMPLIED isHidden CDATA #IMPLIED isArray CDATA #IMPLIED Order CDATA #IMPLIED> <!ATTLIST inputDtdFileName DisplayName CDATA #IMPLIED Description CDATA #IMPLIED isHidden CDATA #IMPLIED isArray CDATA #IMPLIED Order CDATA #IMPLIED> <!ATTLIST inputDtdRootElement DisplayName CDATA #IMPLIED Description CDATA #IMPLIED isHidden CDATA #IMPLIED isArray CDATA #IMPLIED Order CDATA #IMPLIED> <!ATTLIST outputDtdFileName DisplayName CDATA #IMPLIED Description CDATA #IMPLIED isHidden CDATA #IMPLIED isArray CDATA #IMPLIED Order CDATA #IMPLIED > <!ATTLIST responseXmlFileName DisplayName CDATA #IMPLIED Description CDATA #IMPLIED isHidden CDATA #IMPLIED isArray CDATA #IMPLIED Order CDATA #IMPLIED> <!ATTLIST com.acta.adapter.testadapter.ReceiveFromRtdf DisplayName CDATA #IMPLIED Description CDATA #IMPLIED isHidden CDATA #IMPLIED isArray CDATA #IMPLIED SDKVersion CDATA #IMPLIED> <!ATTLIST dtdFileName DisplayName CDATA #IMPLIED Description CDATA #IMPLIED isHidden CDATA #IMPLIED isArray CDATA #IMPLIED> <!ATTLIST targetFileName DisplayName CDATA #IMPLIED Description CDATA #IMPLIED isHidden CDATA #IMPLIED isArray CDATA #IMPLIED> <!ATTLIST dtdRootElement DisplayName CDATA #IMPLIED Description CDATA #IMPLIED isHidden CDATA #IMPLIED isArray CDATA #IMPLIED> <!ATTLIST com.acta.adapter.testadapter.InvokeService DisplayName CDATA #IMPLIED Description CDATA #IMPLIED isHidden CDATA #IMPLIED isArray CDATA #IMPLIED SDKVersion CDATA #IMPLIED> <!ATTLIST sourceXmlFileName DisplayName CDATA #IMPLIED Description CDATA #IMPLIED isHidden CDATA #IMPLIED isArray CDATA #IMPLIED Order CDATA #IMPLIED> <!ATTLIST timeOut DisplayName CDATA #IMPLIED Description CDATA #IMPLIED isHidden CDATA #IMPLIED isArray CDATA #IMPLIED Order CDATA #IMPLIED> <!ATTLIST com.acta.adapter.testadapter.TestAdapter DisplayName CDATA #IMPLIED Description CDATA #IMPLIED isHidden CDATA #IMPLIED isArray CDATA #IMPLIED SDKVersion CDATA #IMPLIED> <!ATTLIST rootDirectory DisplayName CDATA #IMPLIED Description CDATA #IMPLIED isHidden CDATA #IMPLIED isArray CDATA #IMPLIED> ]> <AdapterConfiguration> <com.acta.adapter.testadapter.TestAdapter DisplayName ="TestAdapter." Description ="Sample adapter to demonstrate features." SDKVersion ="2.0.0.0.B"> <rootDirectory DisplayName ="Root directory" Description ="Enter the name of root directory where the adapter will wait for files-events to arrive."> C:/Actaworks/adapters/samples/TestAdapter/Data</rootDirectory> </com.acta.adapter.testadapter.TestAdapter> User Guide for Adapter SDK Configuring and Running an Adapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 87 <com.acta.adapter.testadapter.InvokeService DisplayName ="Invoke a RealTime service" Description ="Invoke the configured RealTime service with an XML message extracted from a file." SDKVersion ="2.0.0.0.B"> <operationInstanceName DisplayName="Operation instance" Description="For messages that this operation receives from ActaWorks this name should match the correspondent outbound message or function call name."></operationInstanceName> <pollingIntervalMSec DisplayName="Polling interval" Description="Interval in msec. to call PollOperation.poll() method.">1000</pollingIntervalMSec> <threadCount DisplayName="Thread count" Description="Number of copies of this operation to run in parallel.">1</threadCount> <enable DisplayName="Enable" Description="Enable to run operation when adapter starts." Choices="true|false" >true</enable> <sourceXmlFileName DisplayName ="Source XML File Name" Description ="Enter the name of the source XML file to invoke the RealTime service." Order="1"></ sourceXmlFileName> <timeOut DisplayName ="Timeout value" Description ="Enter the timeout value (in milliseconds)." Order="2"></timeOut> </com.acta.adapter.testadapter.InvokeService> <com.acta.adapter.testadapter.ReceiveFromRtdf DisplayName ="Receive message from ActaWorks." Description ="Process message from the dataflow's outbound message." SDKVersion ="2.0.0.0.B"> <operationInstanceName DisplayName="Operation instance" Description="For the messages that this operation receives from ActaWorks this name should match the correspondent outbound message or function call name."></operationInstanceName> <threadCount DisplayName="Thread count" Description="Number of copies of this operation to run in parallel.">1</threadCount> <displayName DisplayName="Display name" Description="Display name for metadata browsing."></displayName> <description DisplayName="Description" Description="Description for metadata browsing."></description> <enable DisplayName="Enable" Description="Enable to run operation when adapter starts." Choices="true|false" >true</enable> <dtdRootElement DisplayName ="The root element name" Description ="Enter the name of the root element for the DTD for this operation."></dtdRootElement> <targetFileName DisplayName ="Target file" Description ="Enter the name of the target file to store the xml received from the outbound message."></targetFileName> <dtdFileName DisplayName ="File name with DTD" Description ="Enter the file name that contain the DTD fro the xml used in this operation."></dtdFileName> </ com.acta.adapter.testadapter.ReceiveFromRtdf> <com.acta.adapter.testadapter.CallFromRtdf DisplayName ="Receive message from ActaWorks and send response" Description ="Process message from the dataflow's Message Function call." SDKVersion ="2.0.0.0.B"> <operationInstanceName DisplayName="Operation instance" Description="For the messages that this operation receives from ActaWorks this name should match the correspondent outbound message or function call name."></operationInstanceName> <threadCount DisplayName="Thread count" Description="Number of copies of this operation to run in parallel.">1</threadCount> <displayName DisplayName="Display name" Description="Display name for metadata browsing."></displayName> <description DisplayName="Description" Description="Description for metadata browsing."></description> <enable DisplayName="Enable" Description="Enable to run operation when adapter starts." Choices="true|false" >true</enable> <responseXmlFileName DisplayName ="XML Response File" Description ="Enter the name of the file to store the xml response from message function call." Order="1"></ responseXmlFileName> <inputDtdFileName DisplayName ="File name with input DTD" Description ="Enter the file name that contain the input DTD for the xml used in this operation." Order="2"></inputDtdFileName> <inputDtdRootElement DisplayName ="The root element name for input DTD" Description ="Enter the name of the root element for the input DTD for this operation." Order="3"></inputDtdRootElement> <outputDtdFileName DisplayName ="File name with output DTD" Description ="Enter the file name that contain the output DTD for the xml used in this operation." Order="4"></outputDtdFileName> <outputDtdRootElement DisplayName ="The root element name for output DTD" Description ="Enter the name of the root element for the output DTD for this operation." Order="5"></outputDtdRootElement> 88 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Configuring and Running an Adapter </com.acta.adapter.testadapter.CallFromRtdf> </AdapterConfiguration> Adapter type and adapter operation type configuration elements contain system properties and user-defined properties (presented as XML elements), as follows: Table 31: System properties Property Description operationIn­ stanceName The operation instance name. No default value (you must define the value). For adapter operations that im­ plement the ListenerOperation interface, the operation instance name must be the same as the “outbound message” name or the “function call” name defined for the associated real-time job in the Data Services Designer. threadCount The number of copies of the adapter operation to run in parallel. Default value is 1. Use more than one copy for asynchronous (parallel) processing of inbound and outbound messages. If the message sequence is im­ portant, do not use more than one thread; use synchronous processing. For adapter operations that invoke a real-time service, multiple copies of the operation should be supported by an equal number of real-time services. Each operation waits for its associated real-time service to finish processing before the next message can be processed. This makes it impractical to run multiple copies of the adapter operation when not supported by multiple copies of real-time services. For adapter operations that process messages from Data Services, use multiple copies of the operation when: pollingInter­ valMSec ● The same adapter operation receives messages from different real-time services (running in parallel) through “function call” or “outbound message” Designer objects. ● The same adapter operation receives messages from multiple copies of the same real-time services, and real-time processing is faster than information resource (IR) processing in the adapter operation. This system property is generated in the configuration template if the adapter type or adapter operation type implements the PollAdapter or PollOperation interface. It specifies the frequency at which the adapter polls the information resource. The Adapter SDK is guaranteed to poll the resource at a time interval greater than or equal to pollingIntervalMSec. Actual polling intervals can be greater than pollingIntervalMSec because the time necessary to perform the adapter operation may be greater than pollingIntervalMSec. We recommend that you define pollingIntervalMSec to be no more than a few seconds so that the Adapter SDK can periodically regain control from the adapter operation, providing for effective life-cycle management (start/stop). displayName The operation instance display name. View the display name in the Designer's metadata browsing window. description The operation instance description. View this description in the Designer's metadata browsing window. enable True if the Adapter SDK will start this operation instance when adapter starts, otherwise, false. User-defined properties The Adapter SDK generates a configuration property for each public set<Configuration_property> method defined in the adapter class or adapter operation class. <Configuration_property> represents the name of the configuration property. The first character of <Configuration_property> must be in uppercase. The configuration property data type can be any of the following: User Guide for Adapter SDK Configuring and Running an Adapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 89 ● arrays (of any of the following object types) ● boolean ● char ● double ● float ● int ● java.lang.String ● long ● object (any java objects that contain these property types) ● short For example, if the adapter code contains: package com.acta.adapter.testadapter; public class TestAdapter implements Adapter{ ... public String rootDirectory; public void setRootDirectory (String directory){ rootDirectory=directory; } ... } then, the generated adapter configuration template will contain: .... <!ELEMENT com.acta.adapter.testadapter.TestAdapter (rootDirectory?)> .... <!ELEMENT rootDirectory(#PCDATA)> .... <rootDirectory DisplayName=""Description=""></rootDirectory> 6.1.2 Configuring an adapter instance After an adapter is installed, the Data Services user must configure adapter instances using the Administrator in the Management Console. 1. In the Administrator, under Adapter Instances, click on a <Job Server> name. Job Servers are listed under this node after you enable them for use with adapters using the Server Manager. 2. On the Adapter Instance Status page, click the Configuration tab. 3. Click Add. 4. Click the link of the adapter for which you want to create a new instance. Adapters are listed if they are installed on the Job Server's computer. 5. Complete the Adapter instance start-up and configuration form. For more information, see the Administrator Guide. 6. Click Apply to set the configuration parameters. 7. See the <LINK_DIR>/adapters/startup_script.xml file to verify adapter instance start-up configuration changes. See the <LINK_DIR>/adapters/config/<adapter instance name>.xml file to verify adapter instance run-time configuration changes 90 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Configuring and Running an Adapter Start the adapter, verify that it functions, then stop the adapter before attempting to configure message-oriented adapter operations. 6.1.3 Configuring an adapter operation 1. In the Administrator, under Adapter Instances, click a <Job Server>. 2. On the Adapter Instance Status page, click the Configuration tab. 3. Under Dependent Objects, next to the adapter instance for which you want to configure operations, click Operations. 4. Click Add to configure a new operation. Here, you can also click the link of an existing operation to edit the configuration of an existing operation. 5. After you click Add, select an operation from the Operation type list and click Apply. 6. Complete the configuration form for that operation and click Apply. 7. Repeat the previous steps for each operation you want to configure. Configuration forms may differ between operations. 8. Restart the adapter for adapter operation configurations to take affect. 9. See the <LINK_DIR>/adapters/config/<<adapter instance name>>.xml file to verify your operation run-time configuration changes. 6.2 Starting the Adapter SDK driver There are two ways to start the Adapter SDK driver: ● Use the adapter Start function in the Data Services Administrator. ● Start an adapter from a command prompt or under a debugging tool. 6.2.1 Starting an adapter using the command prompt For debugging purposes, you can start an adapter using the command prompt or from debugging tools. (This assumes the adapter instance is not running.) 1. Open the <LINK_DIR>/adapters/startup_script.xml file in your text editor, manually change the value of the “debugDeveloperMode” element to “true”, then save the file. 2. From the Data Services Administrator, start the adapter instance. The Job Server: ○ Prints to the Job Server log file the background command line that it will execute. ○ Waits indefinitely for the registration message from the adapter. 3. Use your text editor to open the Job Server log file, <LINK_DIR>/log/<JobServerName>/ server_eventlog.txt.Find the command line to start the adapter instance at the end of the file. User Guide for Adapter SDK Configuring and Running an Adapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 91 4. Copy the command line and paste in the command prompt or in your debugging tool for use in starting the adapter. The command line syntax for starting an adapter is: java -classpath <list_of_jar_files> com.acta.adapter.sdk.AdapterMain -a <adapter_class> -i <adapter_instance_name> -r LINK_DIR -h <job_server_host_name> -p <job_server_port> [-v] -c <adapter_manager_id> -51 -sh <access _server_host_name> -sp <access_server port> where: <<list_of_jar_files>> — all Java libraries necessary to run an adapter. The jar files required by the Adapter SDK are: Table 32: <LINK_DIR>/lib/acta_adapter_sdk.jar Adapter SDK <LINK_DIR>/lib/acta_broker_client.jar Broker Client <LINK_DIR>/lib/acta_tool.jar Helper classes <LINK_DIR>/ext/lib/xerces.jar XML parser <LINK_DIR>/lib/<adapter type name>.jar Adapter's jar file Note BrokerClient.jar is an implementation of the broker client API. com.acta.adapter.sdk.AdapterMain — The Adapter SDK driver class name. <<adapter_class>> — The fully qualified name of the adapter type class. <<adapter_instance_name>> — The name of the adapter instance (the same name used by the adapter instance's datastore in the Data Services Designer). <LINK_DIR> — The value for the LINK_DIR environmental variable. <job_server_<host_name>> — The host name of the computer where the Job Server runs. <job_server_<port>> — The Job Server port. [-v] — Turns off the "trace" mode. Refer to the Data Services Administrator Guide for more information. <<access_server_host_name>> — The host name of the computer where the Access Server runs. <<access_server_port>> — The Access Server port. <<adapter_manager_id>> — The unique ID used by the Job Server to communicate with the adapter. When starting an adapter from the command line, you must use this value. Find this value in the Job Server log file. 92 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Configuring and Running an Adapter 7 TestAdapter 7.1 Understanding TestAdapter TestAdapter, the sample adapter included with the Adapter SDK, uses your computer's file system as an information resource (IR) to demonstrate how the following features are implemented using the Adapter SDK : ● Metadata browsing and metadata import. Import both by browsing and by name. ● Message-oriented operations initiated by both Data Services and the information resource. ● Stream-oriented operations (shows each of the five basic batch interactions between Data Services and an information resource). ● Adapter datastore configuration. Implementing the Session interface exposes configuration properties in the adapter datastore. ● Adapter component customization. Provides user-friendly configuration from the Data Services Administrator and Designer. You can use TestAdapter as a working prototype for developing your own custom adapters. This section provides an overview of TestAdapter as well as step-by-step instructions for preparing and operating it. Use this section to: ● Identify TestAdapter and its associated files ● Configure TestAdapter instances and operations ● Create data flows that use TestAdapter operations ● Configure client interfaces that use TestAdapter operations ● Launch TestAdaper ● Start real-time services, jobs, and test applications to verify TestAdapter's functionality. 7.2 TestAdapter and associated files After installing the Adapter SDK , on Windows, find the TestAdapter jar file at <LINK_DIR>/lib/ acta_test_adapter.jar. After installing the Adapter SDK, on UNIX, find the TestAdapter jar file at <LINK_DIR> /lib/ acta_test_adapter.jar. All files necessary to operate TestAdapter are located at <LINK_DIR> /adapters/sdk/samples/ testadapter. The following table provides a quick description of the testadapter directory and some of its subdirectory structure. User Guide for Adapter SDK TestAdapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 93 Table 33: Item Description buildTestAdapter.bat Batch file to build the adapter. in_sales_details.txt Source file used in Job_Table_delim_target job. InvokeTest1.xml Source XML document used to invoke the real-time service defined for the RTJob_InvokeTest1 job. InvokeTest2.xml Source XML document used to invoke the real-time service defined for the RTJob_InvokeTest2 job. ListOfOrderEntrySample.dtd DTD file imported into Data Services . DTD used to create the Document Source for the RTDF_OutboundMessage real-time data flow in the RTJob_OutboundMessage job. (This DTD is already imported into the repository.) mtrl_avail.xml XML document used to run RTJob_OutboundMessage and RTJob_MessageFunc­ tion jobs in test mode. mtrl_avail_in.dtd DTD file imported into Data Services . DTD used to create the input XML Document for RTDF_MessageFunction real-time data flow from Job RTJob_MessageFunction job. (This DTD is already imported into the repository.) mtrl_avail_in_OK.xml XML document used to test real-time services created from JobsRTJob_Message­ Function and RTJob_OutboundMessage jobs. Used in StartOutboundTest.bat and StartFunctionCallTest.bat. mtrl_avail_out.dtd DTD file imported into Data Services . DTD used to create the output XML Docu­ ment for RTDF_MessageFunction real-time data flow from Job RTJob_Message­ Function job. (This DTD is already imported into the repository.) StartFunctionCallTest.bat Batch file to test ReceiveFromRtdf operation. StartOutboundTest.bat Batch file to test CallFromRtdf operation. TestAdapter.atl File that populates the Data Services repository. <DIR> data Directory of test results for the message-oriented operations. Data/Session1 Directory for session-related data, table , XML, and DTD files Data/FunctionCallTest.xml Response message file for CallFromRtdf <DIR> src Directory for test adapter source files 7.3 TestAdapter source code Your Adapter SDK installation includes a pre-built jar file for TestAdapter (acta_test_adapter.jar). The jar file contains classes for the TestAdapter components. Your installation also includes buildTestAdapter.bat, a batch file used to recreate the acta_test_adapter.jar file . This batch file also serves as an example of how to build (compile and package) your custom adapter. This batch file also recreates the run-time configuration file, <DS_COMMON_DIR>/ adapters/config/templates/TestAdapter.xml. The source code for TestAdapter includes the following files: 94 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK TestAdapter Table 34: File Contains a sample implementation of: Browse.java The MetadataBrowsing interface. CallFromRtdf.java The ListenerOperation interface. The CallFromRtdf operation type works like the ReceiveFromRtdf adapter operation type, only the real-time function call sending the message waits for a reply. CallFromRtdfBeanInfo.java The customizer for the CallFromRtdf.java class. ColumnNode.java The MetadataNode interface. FileNode.java The MetadataNode interface. FunctionCallTest.java The FunctionCall interface. Import.java The MetadataImport interface. InvokeService.java The PollOperation interface, which polls the information resource (our sample files), seeking certain events (in this case, a file written to a configured location). InvokeServiceBeanInfo.java The customizer for InvokeService.java class. ReadDocument.java The DocumentSource, Operation, and StreamOperation interfaces. ReadTable.java The Delimited, Operation, StreamOperation, Table, and TableSource interfaces. ReceiveFrom Rtdf.java The ListenerOperation interface, which processes messages received from real-time services. ReceiveFromRtdfBeanInfo.java The customizer for the ReceiveFrom Rtdf.java class. RootNode.java The MetadataNode interface. TestAdapter.java The Adapter interface. TestAdapterBeanInfo.java The customizer for the Adapter class. TestImportByName.java The ImportByName interface. TestImportByNameBeanInfo.java The customizer for the TestImportByName class. TestSession.java The Session interface. TestSessionBeanInfo.java The customizer for the TestSession class. WriteDocument.java The DocumentTarget, Operation, and StreamOperation interfaces. WriteTable.java The Delimited, Operation, StreamOperation, Table, and TableTarget interfaces. WriteTableBeanInfo.java 7.4 The customizer for the WriteTable class. Preparing and testing TestAdapter This section explains how to prepare, run, and test TestAdapter. Use this section to: User Guide for Adapter SDK TestAdapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 95 ● Populate the Data Services repository ● Configure real-time services ● Configure adapter (start-up and run-time) ● Configure adapter operation(s) ● Start the adapter ● Create the TestAdapter datastore ● Test browse and import metadata capabilities ● Test import by name ● Start real-time services ● Verify message-oriented adapter operations ● Verify stream-oriented adapter operations 7.4.1 Populate the Data Services repository To use TestAdapter with Data Services, you must first populate the Data Services repository. To do this, open the Data Services Designer and import the following file into the Data Services repository. <LINK_DIR>/adapters/sdk/samples/testadapter/TestAdapter.atl See the Designer Guide for specific instructions on how to import an ATL file. After you import this file, all objects necessary to support the test adapter are automatically added to the Data Services repository. In the Object Library, select the Datastores tab and open the TestAdapter datastore to view all available datastore type objects for this sample adapter. In the Projects tab, double-click to open TestAdapter_Project. This project contains seven batch jobs and four real-time jobs. The following illustration shows drill-down details (sources, query transforms, and targets) for three of these jobs. 96 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK TestAdapter Notice that the four real-time jobs contain simple real-time data flows. They are: Table 35: Job Description RTDF_InvokeTest1 Tests InvokeService adapter operation template. RTDF_InvokeTest2 Tests another instance of the InvokeService adapter operation template. RTDF_MessageFunction Tests the CallFromRtdf adapter operation template. RTDF_OutboundMessage Tests the ReceiveFromRtdf adapter operation template. 7.4.2 Configure real-time services After you import the ATL file into the Designer, use the Data Services Administrator to add services for the realtime jobs. Refer to the Administrator Guide for specific instructions on how to add the following job services: Table 36: Service Real-time job Data flow InvokeTest1 RTJob_InvokeTest1 RTDF_InvokeTest1 User Guide for Adapter SDK TestAdapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 97 Service Real-time job Data flow InvokeTest2 RTJob_InvokeTest2 RTDF_InvokeTest2 ReceiveFromAWAndReply RTJob_MessageFunction RTDF_MessageFunction ReceiveFromAW RTJob_OutboundMessage RTDF_OutboundMessage 7.4.3 Configure adapter (start-up and run-time) In the Data Services Administrator, you configure an adapter instance by first choosing a Job Server. Install the adapter on a Job Server computer, then, using the Server Manager, edit the Job Server configuration by selecting the Enable adapter and message broker communication check box. Next, open the Administrator and click the Adapter Instances node. You should see the Job Servers you enabled to support adapters listed under this node. 7.4.3.1 Configuring a new adapter instance 1. In the Administrator, under Adapter Instances, click a Job Server name. Job Servers are listed under this node after they are enabled for use with adapters in the Server Manager. 2. On the Adapter Instance Status page, click the Configuration tab. 3. Click Add. 4. Click the link of the adapter for which you want to create a new instance. Adapters are listed if they are installed on the Job Server's computer. 5. Complete the Adapter instance start-up and configuration form. Related Information Configuring a new TestAdapter instance [page 98] 7.4.3.2 Configuring a new TestAdapter instance 1. Follow the instructions for “Configuring a new adapter instance”. 2. Complete the Adapter instance start-up configuration form according to the following table. For the run-time configuration, the value of Root directory must refer to the directory where Data Services is installed. Specific entries are enclosed in quotation marks. Additional information is listed within parenthesis. 98 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK TestAdapter Table 37: Field Name Enter: Adapter instance name “TestAdapterInstance”" Access Server Host The name of the computer where your Access Server is running. Access Server Port “4000” Note This should be the port number associated with the client interfaces for the Access Server Host you specified above, unless you changed it. Adapter retry count (Leave unchanged.) Adapter retry interval (Leave unchanged.) Classpath (Automatically entered.) Autostart (Automatically entered.) Trace mode (Automatically entered.) Application java launch options (Leave unchanged.) Adapter type name (Automatically entered.) Adapter version (Automatically entered.) Adapter class (Automatically entered.) Root directory "LINK_DIR/Data Services/adapters/sdk/samples/testadapter/data" 3. Click Apply to set the configuration parameters. 4. View the status of the adapter instance on the Adapter Instance Status page. 7.4.3.3 About TestAdapter configuration files Adapter instance start-up and run-time configuration information is contained in XML files that Data Services users can edit using the Administrator. However, you can edit these files manually using a text editor. For the TestAdapter, the configuration file is located in the following directory: <LINK_DIR>/adapters/sdk/samples/testadapter/TestAdapterInstance.xml 7.4.4 Configuring operations for TestAdapterInstance in the Administrator 1. In the Administrator, under Adapter Instances, click a Job Server name. 2. On the Adapter Instance Status page, click the Configuration tab. 3. Next to TestAdapterInstance, click Operations under Dependent Objects. User Guide for Adapter SDK TestAdapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 99 4. Click Add to configure a new operation. Here, you can also click the link of an existing operation to edit the configuration of an existing operation. 5. After you click Add, select Invoke a RealTime service from the Operation type list and click Apply. 6. Complete the Invoke a RealTime service configuration form for InvokeTest1 operation and click Apply. 7. Repeat the previous steps, substituting InvokeTest2 for the operation in step #6. 8. Repeat steps 1 through 5, but choose Receive message from Data Services from the Operation type list and click Apply. 9. Complete the Receive message from Data Services service configuration form for the ReceiveFromAW operation and click Apply. Parameter Value Operation instance ReceiveFromAW Thread count 1 Display name Receive from AW Description Outbound Message for TestAdapter Enable true The root element name mtrl_avail_document Target file OutboundTarget.xml File name with DTD ..\adapters\sdk\samples\TestAdapter\mtrl_avail_in.dtd 10. Repeat steps 1 through 5, but choose Receive message from Data Services and send response from the Operation type list and click Apply. 11. Complete the Receive message from Data Services and send response service configuration form for the ReceiveFromAWAndReply operation and click Apply. Parameter Value Operation instance ReceiveFromAWAndReply Thread count 1 Display name Receive from AW And Reply Description Receive from AW And Reply Description Enable true XML response file FunctionCallTest.xml File name with input DTD ..\adapters\sdk\samples\TestAdapter\mtrl_avail_in.dtd Root element name for DTD mtrl_avail_document File name with output DTD ..\adapters\sdk\samples\TestAdapter\mtrl_avail_out.dtd Root element name for output DTD ord_create_document You will have added four new operations to TestAdapterInstance. These operations are closely associated with jobs you previously imported into the Data Services Designer. 100 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK TestAdapter 7.4.5 Starting the adapter instance 1. In the Administrator, select Adapter Instances Job Server . 2. Mark the Select box next to the TestAdapter instance you configured previously. 3. Click Start. When your adapter instance and its operations start, the message, “Started” appears in the Status column and the status for each Operation Instance is indicated by a status icon. 7.4.6 Creating the TestAdapter datastore Create a TestAdapter datastore in the Designer to use TestAdapter metadata in applications designed with Data Services . The procedures you will need to follow are described below. 1. In the Datastores tab of the Designer Object Library, right-click and select New. The Datastore Editor appears showing a Connection tab. 2. In the name text box, type TestAdapter. 3. Select Adapter for Application type. The Adapter Properties tab appears. 4. Select the Job Server associated with TestAdapter. 5. Choose TestAdapterInstance as Adapter instance name. 6. Click to select the Adapter Properties tab. 7. In the Value column, enter Session1, then click OK. In the Description column, you'll see the following text: “Enter the name of the subdirectory for the adapter directory defined for the directory adapter property in the adapter configuration.” For this adapter, the developer required one property. The Data Services user is required to enter the name of a metadata sub-directory. The value of this property affects how the metadata appears in the adapter browser window. After you create the TestAdapter datastore, you can browse and import sample data. 7.4.7 Testing browse and import metadata capabilites The TestAdapter provides access to sample metadata, organized by categories. Each category is a primary node in the Adapter Metadata Browser window. Files are listed in alphabetical order while message functions are categorized by operation type. 1. Double-click the TestAdapter datastore icon. The Adapter Metadata Browser window opens. 2. Click to open nodes and browse the available metadata. User Guide for Adapter SDK TestAdapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 101 3. Right-click any node to find out if that metadata can be imported into Data Services . If Import appears as the right-click menu option, you can import the metadata. For example: ○ Open the Q...Z category node. ○ Right-click the sales_details_delim(table) object, and click Import. 7.4.8 Importing TestAdapter metadata by name Scan the browser window to become familiar with metadata available from TestAdapter, then import some metadata objects by name. 1. Right-click the TestAdapter datastore icon and select Import By Name from the menu. 2. In the Import By Name window, select a metadata type from the Value list (choose table), then enter the metadata name (enter sales_details_delim_target). 3. Click OK to import that metadata object. 4. Look in the Object Library under TestAdapter table was imported to your repository. 7.4.9 Tables to verify that the “sales_details_delim_target” Other options From the Data Services Designer, you can delete imported metadata by right-clicking an imported object and selecting Delete from the menu. You can also create new resource metadata using existing metadata files in the .../Data/Session1 directory as a prototypes. You can open a prototype file using any text editor. Modify the information within existing structure constraints (see the FileNode class in the Adapter SDK API documentation for structure details), and save as a new metadata file. In the Designer, close and reopen the metadata browsing window to save and view the new metadata. You should be able to import the new metadata from the browsing window. 7.4.10 Starting real-time services for TestAdapter 1. In the Data Services Administrator, select Real-time Access Server Real-time services . 2. Click Select all. 3. Click Start. When all services are started, the message “<Service started>” appears in the Status column. 7.4.11 Verify message-oriented adapter operations This section describes methods to verify message-oriented adapter operations. 102 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK TestAdapter 7.4.11.1 InvokeTest1 and InvokeTest2 InvokeTest1 and InvokeTest2 are configured instances of the InvokeService adapter operation template. For more information on these operation types, refer to the comments inside InvokeService.java. To exercise and verify these two operation instances on the Job Server computer, copy the following two XML files: <LINK_DIR>/adapters/sdk/samples/testadapter/InvokeTest1.xml <LINK_DIR>/adapters/sdk/samples/testadapter/InvokeTest2.xml to the following directory: <LINK_DIR>/adapters/sdk/samples/testadapter/data If the test adapter successfully processes these two XML files, it deletes them and places two reply files in the same directory. The reply file names include the timestamp and have a form like: __reply__989622999190__InvokeTest1.xml __reply__989623001153__InvokeTest2.xml 7.4.11.2 TestAdapterOutboundMessage TestAdapterOutboundMessage is a configured instance of the ReceiveFromRtdf adapter operation template. For more information on this operation type, refer to the comments inside ReceiveFromRtdf.java. To verify this operation, go to the command prompt and change directories to the following directory: <LINK_DIR>/adapters/sdk/samples/testadapter Enter the following command: StartOutboundTest.bat <host_name> <message_broker_client_port> This batch file starts the ClientTest application that initiates the OutboundMessageTest service. The service processes the input XML message mtrl_avail_in_OK.xml and sends the reply XML message to TestAdapterOutboundMessage operation. The operation saves the reply XML message on the Job Server computer in the <LINK_DIR>/adapters/sdk/samples/testadapter/data directory. You will see something like: received__989976693948__OutboundTarget.xml if the operation completes successfully. You will also see the reply XML message from the service as an output of the ClientTest application. The presence of the element <CHECK_RULE>Ok</CHECK_RULE> in the message confirms that the ClientTest application received the correct reply message. 7.4.11.3 TestAdapterRequest TestAdapterRequest is a configured instance of the CallFromRtdf adapter operation template. For more information on this operation type, refer to the comments inside CallFromRtdf.java. User Guide for Adapter SDK TestAdapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 103 To verify this operation, go to the command prompt and change directories to the following directory. <LINK_DIR>/adapter/sdk/samples/testadapter Enter the following command. StartFCallTest.bat <host_name> <message_broker_client_port> This batch file starts the ClientTest application that initiates the FunctionCallTest service. This service processes the input XML message mtrl_avail_in_OK.xml and sends the request XML message from the Query transform to the TestAdapterRequest operation. The operation ignores this message and sends the configured XML message inside the Data/FunctionCallTest.xml file as the reply. The service continues processing and sends the reply XML message to the ClientTest application, which displays a message. An empty value for the <RETURNED_MESSAGE> element confirms that the ClientTest application received the correct reply message. If a problem occurs during real-time service message processing, the <RETURNED_MESSAGE> element contains an error message and the <RETURNED_ID> element contains an error code. 7.4.12 Verify stream-oriented adapter operations To verify TestAdapter's stream-oriented operations, run the following jobs from the Data Services Designer. These jobs are populated in the Data Services repository after you import the TestAdapter.atl file provided with your Adapter SDK installation. Table 38: Job Data flow demonstrates TestAdapter source code Job_Document_source Adapter document source. src/com/acta/adapter/testadapter/ ReadDocument.java Job_Table_delim_source Adapter table source. src/com/acta/adapter/testadapter/ ReadTable.java Delimited format data exchange. Job_Table_xml_source Adapter table source. src/com/acta/adapter/testadapter/ ReadTable.java XML format data exchange. Job_Document_target Adapter table source. src/com/acta/adapter/testadapter/ ReadTable.java Job_Table_delim_target Adapter table target. src/com/acta/adapter/testadapter/ WriteTable.java Delimited format data exchange. Job_Table_xml_target Adapter table target. src/com/acta/adapter/testadapter/ WriteTable.java XML format data exchange. Job_FunctionCall 104 Adapter function call in the query transform. PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. src/com/acta/adapter/testadapter/ FunctionCallTests.java User Guide for Adapter SDK TestAdapter 7.4.12.1 Job_Document_source Demonstrates how a stream-oriented adapter operation supports a document source in a Data Services data flow. Implements the com.acta.adapter.sdk.DocumentSource interface. Source code: src/com/acta/adapter/testadapter/ReadDocument.java Imported adapter metadata: Document: mtrl_avail_doc(TestAdapter) Other metadata involved: DTD file: mtrl_avail_document Input data: <LINK_DIR>/adapters/sdk/samples/testadapter/data/Session1/mtrl_avail_doc.dat Expected output: <LINK_DIR>/adapters/sdk/samples/testadapter/data/out_mtrl_avail.xml Should generate a new file with the same results as the source document. 7.4.12.2 Job_Table_delim_source Demonstrates how a stream-oriented adapter operation supports a table source in a Data Services data flow (delimited format data exchange). Implements com.acta.adapter.sdk.TableSource and com.acta.adapter.sdk.Delimited interfaces. Adapter operation: src/com/acta/adapter/testadapter/ReadTable.java Imported adapter metadata: sales_details_delim(TestAdapter) Other metadata involved: File Format: NoHeaderFF Input data: <LINK_DIR>/adapters/sdk/samples/testadapter/data/Session1/sales_details_delim.dat Expected output: <LINK_DIR>/adapters/sdk/samples/testadapter/data/out_sales_delim.txt Should generate a copy of the source file. User Guide for Adapter SDK TestAdapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 105 7.4.12.3 Job_Table_xml_source Demonstrates how a stream-oriented adapter operation supports a table source in a Data Services data flow (XML format data exchange). Implements the com.acta.adapter.sdk.TableSource interface. Adapter operation: src/com/acta/adapter/testadapter/ReadTable.java Imported adapter metadata: sales_details_xml(TestAdapter) Other metadata involved: File Format: NoHeaderFF Input data: <LINK_DIR>/adapters/sdk/samples/TestAdapter/Data/Session1/sales_details_delim.dat Expected output: <LINK_DIR>/adapters/sdk/samples/testadapter/data/out_sales_xml.txt Should generate a copy of the source file. 7.4.12.4 Job_Document_target Demonstrates how a stream-oriented adapter operation supports a table source in a Data Services data flow. Implements the com.acta.adapter.sdk.DocumentTarget interface. Adapter operation: src/com/acta/adapter/testadapter/WriteDocument.java Imported adapter metadata: sales_details_delim(TestAdapter) Other metadata involved: DTD file: material_avail_document Input data: <LINK_DIR>/adapters/sdk/samples/TestAdapter/mtrl_avail.xml Expected output: <LINK_DIR>/adapters/samples/testadapter/data/Session1/sales_details_delim.dat Should overwrite the existing file with the input document contents. 106 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK TestAdapter 7.4.12.5 Job_Table_delim_target Demonstrates how a stream-oriented adapter operation supports a table target in a Data Services data flow (delimited format data exchange). Implements the com.acta.adapter.sdk.TableTarget and com.acta.adapter.sdk.Delimited interfaces. Adapter operation: src/com/acta/adapter/testadapter/WriteTable.java Imported adapter metadata: sales_details_delim_target(TestAdapter) Other metadata involved: DTD material_avail_document Input data: <LINK_DIR>/adapters/sdk/samples/testadapter/in_sales_details.txt Expected output: <LINK_DIR>/adapters/sdk/samples/testadapter/data/Session1/ sales_details_delim_target.dat, the copy of the source file. The new data will be appended because the append option is true for the adapter target. 7.4.12.6 Job_Table_xml_target Demonstrates how a stream-oriented adapter operation supports a table target in a Data Services data flow (XML format data exchange). Implements the com.acta.adapter.sdk.TableTarget interface. Adapter operation: src/com/acta/adapter/testadapter/WriteTable.java Imported Adapter metadata: sales_details_xml_target(TestAdapter) Other metadata involved: File Format: sales_details Input data: <LINK_DIR>/adapters/sdk/samples/testadapter/in_sales_details.txt Expected output: Should generate a copy of the source file. The new data will be appended because the append option is true for the adapter target. <LINK_DIR>/adapters/sdk/samples/testadapter/data/Session1/sales_details_xml_target.dat. User Guide for Adapter SDK TestAdapter PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 107 7.4.12.7 Job_FunctionCall Demonstrates how a stream-oriented adapter operation supports a function call in a Data Services data flow query transform. Implements the com.acta.adapter.sdk.FunctionCall interface. Adapter operation: src/com/acta/adapter/testadapter/FunctionCallTest.java Imported Adapter metadata: func_call(TestAdapterInstance) Other metadata involved: DTD files: mtrl_avail_in and mtrl_avail_out Input data: <LINK_DIR>/adapters/sdk/samples/testadapter/mtrl_avail_in_OK.xml Expected output: <LINK_DIR>/adapters/sdk/samples/testadapter/data/out_mtrl_avail_func.xml 108 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK TestAdapter 8 Debugging in Eclipse 8.1 Debugging in Eclipse Before you debug in Eclipse, you need to do the following: ● Stop the Data Services service. ● Edit <DS_COMMON_DIR>\adapters\startup_script.xml. Set the element debugDeveloperMode to true ● Start the Data Services service ● In Management Console, your adapter instance should have a 'Starting' status. Other adapter instances should have a 'Started' status. ● Set a breakpoint in your adapter code. Perform the following to debug your adapter in Eclipse: 1. To open Debug Configurations, click the Debug icon and clicking Debug Configurations. 2. Create a new configuration by right-clicking Java Application and clicking New. 3. Under Main class, click Search, and choose com.acta.adapter.sdk.AdapterMain. 4. Click the Arguments tab, and enter the following: -a test.MyAdapter -i my_adapter -h PALD00494877A -p 4001 -ssl No -c com.acta.adapter.ServiceProvider.my_adapter -cs default -mcs default -51 -js win_j1 -r "<LINK_DIR>" -cr "<DS_COMMON_DIR>" Note In the text above, you must replace “my_adapter” with the name of your adapter instance. Also replace the paths. 5. Click Debug to start the debug process. ● MetadataNode interface: Even though the interface doesn't require, users should provide at minimal the methods below in order to identify the current node for further browsing and importing ○ public void setUniqueName(String v) ○ public void setDisplayName(String v) ● When 'Pushdown' is used, users should implement both 'SQLEnable' and 'QueryInXML' along with 'TableSource' at the reader level. User Guide for Adapter SDK Debugging in Eclipse PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 109 Important Disclaimers and Legal Information Coding Samples Any software coding and/or code lines / strings ("Code") included in this documentation are only examples and are not intended to be used in a productive system environment. The Code is only intended to better explain and visualize the syntax and phrasing rules of certain coding. SAP does not warrant the correctness and completeness of the Code given herein, and SAP shall not be liable for errors or damages caused by the usage of the Code, unless damages were caused by SAP intentionally or by SAP's gross negligence. Accessibility The information contained in the SAP documentation represents SAP's current view of accessibility criteria as of the date of publication; it is in no way intended to be a binding guideline on how to ensure accessibility of software products. SAP in particular disclaims any liability in relation to this document. This disclaimer, however, does not apply in cases of wilful misconduct or gross negligence of SAP. Furthermore, this document does not result in any direct or indirect contractual obligations of SAP. Gender-Neutral Language As far as possible, SAP documentation is gender neutral. Depending on the context, the reader is addressed directly with "you", or a gender-neutral noun (such as "sales person" or "working days") is used. If when referring to members of both sexes, however, the third-person singular cannot be avoided or a gender-neutral noun does not exist, SAP reserves the right to use the masculine form of the noun and pronoun. This is to ensure that the documentation remains comprehensible. Internet Hyperlinks The SAP documentation may contain hyperlinks to the Internet. These hyperlinks are intended to serve as a hint about where to find related information. SAP does not warrant the availability and correctness of this related information or the ability of this information to serve a particular purpose. SAP shall not be liable for any damages caused by the use of related information unless damages have been caused by SAP's gross negligence or willful misconduct. All links are categorized for transparency (see: http://help.sap.com/disclaimer). 110 PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. User Guide for Adapter SDK Important Disclaimers and Legal Information User Guide for Adapter SDK Important Disclaimers and Legal Information PUBLIC © 2015 SAP SE or an SAP affiliate company. All rights reserved. 111 www.sap.com/contactsap © 2015 SAP SE or an SAP affiliate company. All rights reserved. No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP SE or an SAP affiliate company. The information contained herein may be changed without prior notice. Some software products marketed by SAP SE and its distributors contain proprietary software components of other software vendors. National product specifications may vary. These materials are provided by SAP SE or an SAP affiliate company for informational purposes only, without representation or warranty of any kind, and SAP or its affiliated companies shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP or SAP affiliate company products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty. SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP SE (or an SAP affiliate company) in Germany and other countries. All other product and service names mentioned are the trademarks of their respective companies. Please see http://www.sap.com/corporate-en/legal/copyright/ index.epx for additional trademark information and notices.