JDBC Adapter

Author: Dennis Kropp

Objectives
After completing this session, you will be able to:

Understand the basics of J2EE JDBC adapter

Understand how to configure sender & receiver
JDBC adapter
Learn how to select data from database table
See how to insert content into a database table

Be familiar with technical aspects of the JDBC

adapter

SAP AG 2004, JDBC Adapter, Dennis Kropp, 2

JDBC Adapter

The JDBC adapter enables you to interchange data between

database systems and a XI Integration Server. The adapter
converts database content to XML messages and the other
way around.

SAP AG 2004, JDBC Adapter, Dennis Kropp, 3

JDBC Adapter
Type JDBC
Exactly one sender agreement
per Communication channel
(1:1)
At least interface name and
sender service must be
qualified in the sender
agreement

SAP AG 2004, JDBC Adapter, Dennis Kropp, 4

JDBC sender channel - prerequisites

this example provides information about creating a JDBC sender channel

sender means that a database provides information that are queried (via SELECT statement)
and send to XI integration server
Prerequisite for using the JDBC adapter is of course access to a database system like
SAP DB or MS SQL server or any database that provides a JDBC driver
An appropriate JDBC driver must be deployed on the system. See XI Configuration Guide
for more information
Be sure that in SQL Server authentication mode is set to mixed mode.
Right click your DBMS Server in Enterprise Manager Tool and select properties
->security-> choose SQL server and windows authentication
a sender agreement is needed for using a jdbc sender communication channel
To configure a complete roundtrip you could define a file receiver channel where
the message is delivered to
Routing rules and receiver has to be specified as for any other channel in the directory
object model

SAP AG 2004, JDBC Adapter, Dennis Kropp, 5

In the case of a JDBC sender, the database table is queried via a SELECT
statement.
The message is by definition asynchronous hence the QoS should be set as EO or
EOIO.

Example1 : Source DB table for sender channel

Data to be read:

The data should be converted into a xml structure and sent to XI

SAP AG 2004, JDBC Adapter, Dennis Kropp, 6

items stored in DB table

IB Directory sender channel configuration

SAP AG 2004, JDBC Adapter, Dennis Kropp, 7

Connection defines host,port and database where data is stored

User must have access to the database and rights to select/update tables within
this database
Configure user in SQL enterprise manager or similar tool for other databases
With this configuration JDBC adapter sends every 5 minutes a resultset depending
on the result of the query
In this case only db table entries with the value true in column new were
selected

IB Directory sender channel configuration

With this configuration JDBC adapter sends every 5 minutes a
resultset depending on the result of the query

SELECT * FROM orders WHERE new = 'true

in this case only db table entries with the value true in column new
were selected
UPDATE orders SET new='false' WHERE new='true
Use the UPDATE statement to update a column of the table
this way you can specify which entries were already read and should
not be selected next time
use <test> if you want only test the db query and do not want an
update
you may leave the other fields unchanged

SAP AG 2004, JDBC Adapter, Dennis Kropp, 8

XML resultset
<?xml version="1.0" encoding="utf-8"?>
<resultset>
<row>
<Index>1</Index>
<artNumber>3334</artNumber>
<description>Athlon XP 2300+</description>
<quantity>4</quantity>
<new>true</new>
</row>
<row>
<Index>2</Index>
<artNumber>1222</artNumber>
<description>INTEL P4 3200</description>
<quantity>2</quantity>
<new>true</new>
</row>
<row>
<Index>3</Index>
<artNumber>3222</artNumber>
<description>Athlon64 3200</description>
<quantity>10</quantity>
<new>true</new>
</row>
<row>
<Index>4</Index>
<artNumber>3223</artNumber>
<description>Athlon64 3400</description>
<quantity>5</quantity>
<new>true</new>
</row>
</resultset>
SAP AG 2004, JDBC Adapter, Dennis Kropp, 9

This is the resultset delivered by the jdbc sender

To finish the scenario you can use a file adapter receiver that store the file locally

JDBC receiver - prerequisites

this example provides information about creating a JDBC receiver channel

receiver means that data is written into a database via XI JDBC adapter
Prerequisite for using the JDBC adapter is of course access to a database system like
SAP DB or MS SQL server or any database that provides a JDBC driver
An appropriate JDBC driver must be deployed on the system. See XI Configuration Guide
for more information
Be sure that in SQL Server authentication mode is set to mixed mode.
Right click your DBMS Server in Enterprise Manager Tool and select properties
->security-> choose SQL server and windows authentication
To configure a complete roundtrip you could define a file sender channel where
the message is send from
Routing rules and sender has to be specified as for any other channel in the directory
object model

SAP AG 2004, JDBC Adapter, Dennis Kropp, 10

For the JDBC receiver, the message can be sent synchronously or asynchronously.
In the case of a SELECT statement, only a synchronous request makes sense, of
course (Best effort), since the result set will be returned.
In the case of other statements (UPDATE, INSERT, DELETE), if the message
was sent synchronously, then the response will contain the number of rows
affected.

10

Example : definition in repository (source)

Data type definition in IB repository for source structure

SAP AG 2004, JDBC Adapter, Dennis Kropp, 11

11

Example : Source structure instance

This structure is provided by a sender, e.g. file adapter

<?xml version="1.0" encoding="UTF-8"?>

<ns:MT_Products xmlns:ns="http://sap.com/xi/jdbc">
<Products cat=HARD">
<Product>
<ID>3324</ID>
<name>AMD Athlon64 3400</name>
<number>5</number>
</Product>
<Product>
<ID>4424</ID>
<name>INTEL XEON 1600</name>
<number>3</number>
</Product>
</Products>
</ns:MT_Products>

SAP AG 2004, JDBC Adapter, Dennis Kropp, 12

12

Example : expected structure (target)

expected structure by JDBC adapter:
<StatementName>
<dbTableName action=INSERT>
<table>realDbTableName</table>
<access>
<col1>val1</col1>
<col2>val2</col2>
</access>
<access>
<col1>val11</col1>
</access>
</dbTableName>
</StatementName>

SAP AG 2004, JDBC Adapter, Dennis Kropp, 13

This represents the canonical XML format used to represent SQL statements to be processed by
the JDBC receiver adapter.
This canonical format can be used to represent the SQL statements of type
SELECT,INSERT,UPDATE,DELETE as well as calls to SQL procedures.
The metadata depends on the structure of the target table(s). It should be defined at design-time as
an Interface Object in the Integration Repository (the Interface objects for this XML canonical
format are not predefined in the Integration Repository by SAP).
The advantage of this canonical format is that it presents a message-oriented view of the SQL
statement (easier for mappings). It is independent of the JDBC driver and the database vendor.
If you use the optional <table> element, the value specified here is used as a database table name.
This enables you, for example, to define table names, which contain non-XML-compatible
characters or characters that stop them from being used in interface definitions in the Integration
Builder.
<StatementName> can have a arbitrary name
<dbTableName action=INSERT> replace dbTableName by the name of your table if you do not
use <table> element
action=INSERT
Statements with this action cause existing table values to be inserted. Therefore, the statement
corresponds to an SQL INSERT statement.
The block <access> contains the new column values.
A statement with the action INSERT must have at least one <access> element. It cannot have a
<key> element.
The corresponding SQL statement for StatementName in the example above is as follows:
INSERT INTO dbTableName

(col1, col2) VALUES(val1, val2)

INSERT INTO dbTableName

(col1) VALUES(val11)

13

Example : definition in repository (target)

Data type definition in IB repository for target structure

SAP AG 2004, JDBC Adapter, Dennis Kropp, 14

Structure in repository following the rules of previous page

Orders is the name of db table
<Access> defines the columns where data should be inserted

14

Example : Mapping of structures in IB

you need a mapping to convert source into target structure

SAP AG 2004, JDBC Adapter, Dennis Kropp, 15

The tag <Product is mapped to <access> so for each <Product> tag in source a
<access> tag is created in target structure
The attribute action is mapped with a constant value INSERT
The tag <new> is mapped with a constant value true
Each <access> tag means one INSERT statement in jdbc adapter

15

Example : structure after mapping

<?xml version="1.0" encoding="UTF-8"?>
<ns:MT_OrderJDBC xmlns:ns="http://sap.com/xi/jdbc">
<Statement>
<orders action="INSERT">
<access>
<artNumber>3324</artNumber>
<description>AMD Athlon64 3400</description>
<quantity>5</quantity>
<new>true</new>
</access>
<access>
<artNumber>4424</artNumber>
<description>INTEL XEON 1600</description>
<quantity>3</quantity>
<new>true</new>
</access>
</orders>
</Statement>
</ns:MT_OrderJDBC>
SAP AG 2004, JDBC Adapter, Dennis Kropp, 16

Structure after mapping

16

IB Directory receiver channel configuration

SAP AG 2004, JDBC Adapter, Dennis Kropp, 17

Connection defines host,port and database where data should be stored

User must have access to the database and rights to select/update tables within
this database
Configure user in SQL enterprise manager or similar tool for other databases
With this configuration JDBC adapter can receive data in XML-SQL format and
convert into a SQL statement

17

Result: data in DB

SAP AG 2004, JDBC Adapter, Dennis Kropp, 18

New entries are marked with true in column <new>

18

Summary

Now you should be able to:

Understand the basics of J2EE JDBC adapter

Understand how to configure sender & receiver
JDBC adapter
select data from database table
insert content into a database table
Be familiar with technical aspects of the JDBC
adapter

SAP AG 2004, JDBC Adapter, Dennis Kropp, 19

19