ds 42 adapter sdk en

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.