Connector Framework Basics

Using the JDBC Connector

SAP AG

<Course Number>

Unit Title - 1

Course Objectives

After completing this session, you will be able to:

Use the Connector gateway to connect to a relational
database system to retrieve data using the JDBC
Connector
Identify ways to provide credentials to the connector
Retrieve data from a database using the JDBC Connector

SAP AG 2004, Connector Framework Basics Using the JDBC Connector / 2

SAP AG

<Course Number>

Unit Title - 2

SAP J2EE Server

PRT

SDK

General Architecture The Big Picture

Java API

SAP
Connector

R/3 App
Svr

Wizard

PeopleSoft
Connector

PeopleSoft
App Svr

Unification
Service

JDBC
Connector

RDBMS

Connector
Gateway

Java API
SDK

iView

SAP AG 2004, Connector Framework Basics Using the JDBC Connector / 3

SAP AG

<Course Number>

Unit Title - 3

Connector Framework (for JDBC Connector)

Connector Framework Client (for JDBC Connector):

Step1. Understand the table design structures.
Step2. Access the table data via Connector Framework API.

SAP AG 2004, Connector Framework Basics Using the JDBC Connector / 4

SAP AG

<Course Number>

Unit Title - 4

Using the Connector Framework (CF) API

There are several different approaches to using the JDBC
Connector. The approach you use depends on exactly how you
wish to interact with the Connection Framework.
Method 1:
Use the Interaction interface to execute stored procedures
Method 2:
Use the IQuery interface to execute SQL queries against the
database.
Note:This method is broken in NW04 from stack 04 09.
Method 3:
Use the INativeQuery interface to execute Native SQL queries
against the database.

SAP AG 2004, Connector Framework Basics Using the JDBC Connector / 5

The connector gateway is used as any other service in the portal is accessed.

SAP AG

<Course Number>

Unit Title - 5

Using the Connector Framework (CF) API - Interaction

Method 1: CF Basics for executing a JDBC Stored Procedure
1. Use the Connector Gateway Service to obtain connections to
backend systems
2. Use the ConnectionProperties object to facilitate SSO
3. Obtain a connection to the back-end system
4. Create an Executable Interaction interface to describe the
interaction with the backend system
5. Create an Interaction Spec (IInteractionSpec) to specify stored
procedure to call
6. Create an input record (MappedRecord) describing input parameters
7. Execute the Interaction Spec with the input record
8. Obtain the output (MappedRecord) usually returns a IRecordset
9. Iterate through recordset and deal with data
SAP AG 2004, Connector Framework Basics Using the JDBC Connector / 6

The connector gateway is used as any other service in the portal is accessed.

SAP AG

<Course Number>

Unit Title - 6

Using the Connector Framework (CF) API - Query

Method 2 & 3: CF Basics for a simple Query
1. Use the Connector Gateway Service to obtain connections to
backend systems
2. Use the ConnectionProperties object to facilitate SSO
3. Obtain a connection to the back-end system
4. Create a Query object (either IQuery or INativeQuery) to
describe the query you wish to execute on the back-end
system
5. Execute the Query and check return status
6. Obtain the output usually returns an IRecordset (or
ResultSet) object
7. Iterate through recordset and deal with data

SAP AG 2004, Connector Framework Basics Using the JDBC Connector / 7

The connector gateway is used as any other service in the portal is accessed.

SAP AG

<Course Number>

Unit Title - 7

Required imports and libraries

Using the CF Framework requires you to import several packages
and add certain libraries to your NWDS project
import com.sapportals.portal.ivs.cg.ConnectionProperties;
import com.sapportals.portal.ivs.cg.IConnectorGatewayService;
import com.sapportals.portal.ivs.cg.IConnectorService;
import com.sapportals.connector.connection.IConnection;
import com.sapportals.connector.execution.structures.*;

<PDK>/j2eeclient/activation.jar
<PDK>/j2eeclient/connector.jar
<PDK>/portalapps/com.sap.portal.ivs.connectorserviceapi.jar
<J2EE>/bin/ext/com.sap.genericconnector/GenericConnector.jar
<PDK>/j2eeclient/jta.jar

SAP AG 2004, Connector Framework Basics Using the JDBC Connector / 8

The required libraries can be found in the PDK Library convenience ZIP file.

SAP AG

<Course Number>

Unit Title - 8

CF API Getting a Connection

Use the Connector Gateway Service to obtain connections to back-end
systems

import com.sapportals.portal.ivs.cg.ConnectionProperties;
import com.sapportals.portal.ivs.cg.IConnectorGatewayService;
import com.sapportals.portal.ivs.cg.IConnectorService;
import com.sapportals.connector.connection.IConnection;
....
IConnectorGatewayService cgService =
(IConnectorGatewayService)
PortalRuntime.getRuntimeResources().
getService(IConnectorService.KEY);

SAP AG 2004, Connector Framework Basics Using the JDBC Connector / 9

The connector gateway is used as any other service in the portal is accessed.

SAP AG

<Course Number>

Unit Title - 9

CF API Getting a Connection (cont.)

Use the ConnectionProperties object to fill in the required
connection parameters for SSO
The Locale is required for language texts, etc., that may be
dependent on the user
The user is required to obtain user mapping info or logon ticket for
back-end system

import com.sapportals.portal.ivs.cg.ConnectionProperties;
...
ConnectionProperties cp = new
ConnectionProperties(request.getLocale(),
request.getUser());
...

SAP AG 2004, Connector Framework Basics Using the JDBC Connector / 10

SAP AG

<Course Number>

Unit Title - 10

CF API Getting a Connection (cont.)

Use the getConnection() method of the Gateway service to obtain
the actual connection to the back-end
There are several ways to obtain the connection. This version
requires the System Alias and a ConnectionProperties object
IMPORTANT: Make sure you close connection when you are done!
Failure to do so will cause you to run out of connections due to
connection pooling.
...
ConnectionProperties cp = new
ConnectionProperties(request.getLocale(),
request.getUser());
try {
connection = cgService.getConnection("Pubs",cp);
...
System Alias
// do some stuff
Connection Properties
} finally {
connection.close(); // IMPORTANT! MAKE SURE YOU CLOSE CONN.
}
SAP AG 2004, Connector Framework Basics Using the JDBC Connector / 11

SAP AG

<Course Number>

Unit Title - 11

CF API Stored Procedure Execution

A Stored Procedure can be executed using the Interaction interface in
a similar manner to the SAP Connector calling a BAPI or RFM
1. Create an Interaction using newInteractionEx() on the connection
object.
2. Obtain an InteractionSpec by calling getInteractionSpec() on the
Interaction object.
3. Set the name of the Stored Procedure on the InteractionSpec by using
setPropertyName("Name", "stored_procedure_name")
4. Create an input record to contain input parameters for the stored
procedure using the RecordFactory from the Interaction.
5. Add the required input parameters to the input record.
6. Execute the Interaction passing in the InteractionSpec and input
record. The execution of the query will result in a MappedRecord
object which will contain the results.
7. The result of the query is usually in a IRecordset type object. Iterate
through the recordset and process the data.

SAP AG 2004, Connector Framework Basics Using the JDBC Connector / 12

SAP AG

<Course Number>

Unit Title - 12

Interactions
An Interaction describes the data needed to call a specific
function or method in the backend system. It provides a generic
interface to talk to disparate systems and is created via a
Connection object.
You must build an InteractionSpec, fill in the required input
parameters, then execute the Interaction.
The result will be returned in an output type record

import com.sapportals.connector.execution.functions.IInteractionSpec;
import com.sapportals.connector.execution.functions.IInteraction;

...
IInteraction ix = connection.createInteractionEx();
...

SAP AG 2004, Connector Framework Basics Using the JDBC Connector / 13

SAP AG

<Course Number>

Unit Title - 13

Interaction Specs - 1
An InteractionSpec contains the data needed to call a specific
function or method in the backend system.
It is obtained from the Interaction object by calling
getInteractionSpec()

import com.sapportals.connector.execution.functions.IInteractionSpec;
import com.sapportals.connector.execution.functions.IInteraction;

...
IInteraction ix = connection.createInteractionEx();
// Get interaction spec
IInteractionSpec ixspec = ix.getInteractionSpec();
...

SAP AG 2004, Connector Framework Basics Using the JDBC Connector / 14

SAP AG

<Course Number>

Unit Title - 14

Interaction Specs - 2
After obtaining the InteractionSpec, you need indicate which
function/method you wish to call using setPropertyValue();
Next, build an input record via the RecordFactory that contains
the input parameters for the function/method you intend to call.
Use IndexedRecord for positional parameters, or MappedRecord
for named parameters.
...
// Specify name of function/procedure to call.
ixspec.setPropertyValue("Name", "CustOrderHist");
RecordFactory rf = ix.getRecordFactory();
//create input record for parameters to function
IndexedRecord input = rf.createIndexedRecord("input");
input.add(custNo); // Customer No is 1st param
...

SAP AG 2004, Connector Framework Basics Using the JDBC Connector / 15

SAP AG

<Course Number>

Unit Title - 15

CF API Retrieving the Data

The result of the Interaction is returned in an output record (type
MappedRecord).
This data structure can contain multiple recordsets.
You obtain a specific recordset by calling get() on the output record
You should check to see that the resulting returned type is the expected
datatype. For Stored Procedures, the resultset is available via the
PROCNAME.@RESULT in the output structure.
...
MappedRecord output = (MappedRecord)
ix.execute(ixspec, input);
IRecordset rs = null;
Object result = output.get("CustOrderHist.@RESULT");
if (result instanceof IRecordSet) {
rs = (IRecordSet) result;
}
SAP AG 2004, Connector Framework Basics Using the JDBC Connector / 16

SAP AG

<Course Number>

Unit Title - 16

CF API Interaction Example

// Execute Stored Proc "SalesByCategory" with params:
//
"Beverages","1996"
IConnection con = . . .;
// connection to Northwind DB
String PROCNAME = "SalesByCategory";
IRecordSet rs = null;
try {
// Create the Interaction interface for executing the command
IInteraction ix = con.createInteractionEx();
// Get interaction spec and set the name of the command to run
IInteractionSpec ixspec = ix.getInteractionSpec();
// Put Function Name into interaction Properties.
ixspec.setPropertyValue("Name", PROCNAME);
// create input MappedRecord from the RecordFactory
RecordFactory rf = ix.getRecordFactory();
IndexedRecord input = rf.createIndexedRecord("Input");
// put function input parameters for Category and Year
input.add("Beverages");
input.add("1996");
SAP AG 2004, Connector Framework Basics Using the JDBC Connector / 17

SAP AG

<Course Number>

Unit Title - 17

CF API Interaction Example (2)

// Execute the function (interaction) with the ixspec and
// input record. Result is an output recordset containing
// return structures from call
MappedRecord out = (MappedRecord) ix.execute(ixspec, input);
// retrieve the output recordset
Object result = out.get(PROCNAME+".@RESULT");
if (result instanceof IRecordSet) {
rs = (IRecordSet) result;
// do something with data . . .
}
} catch (ResourceException e) {
// handle exception
} finally {
try {
con.close();
} catch (ResourceException e1) {
// handle exception
}
}

SAP AG 2004, Connector Framework Basics Using the JDBC Connector / 18

SAP AG

<Course Number>

Unit Title - 18

CF API Using the Data

The IRecordSet is very similar to a JDBC type recordset, but is
generic and can actually contain tabular data from virtually any type
of EIS system
Some methods of the IRecordSet interface:
next()

Next record

previous()

Previous record

getInt(String field)

Get Integer value for field

getString(String field)

Get String value for field

getColumnName(int col)

Get Name of column

deleteRow()

Deletes the current row

setInt(String field, int val)

Sets Integer value of field name

setString(int field,String val)

Sets String value of column number

SAP AG 2004, Connector Framework Basics Using the JDBC Connector / 19

SAP AG

<Course Number>

Unit Title - 19

CF API Using the Data (cont.)

The recordset also contains metadata (IRecordMetaData) that can be
used to dynamically determine column names and other attributes at
runtime
IRecordMetaData rsMD = rs.retrieveMetaData();
response.write("<table><tr>");
int columnCount = rsMD.getColumnCount();
for (int index = 1; index <= columnCount; index++) {
response.write("<th>" +
rsMD.getColumnLabel(index) + "</th>");
}
Some Methods of IRecordMetaData
getColumnCount()

Get number of Columns

getColumnLabel(int column)

Get text description for the Column

getColumnName(int column)

Get the name of the Column

getColumnType(int column)

Get type of the Column

SAP AG 2004, Connector Framework Basics Using the JDBC Connector / 20

SAP AG

<Course Number>

Unit Title - 20

CF API Retrieving Query Results (cont.)

The IRecordSet object contains the rows resulting from the query
You can iterate through the recordset and retrieve data using the
next() method of the recordset of the query can be obtained if the
query was successful
You can use the getXXX() methods (getString(), getInteger(), etc.) to
retrieve values for each column of the row

...
// write data
response.write("</tr>");
while (rs.next()) {
response.write("<tr>");
for (int index = 1; index <= columnCount; index++) {
response.write("<td>" + rs.getString(index) + "</td>");
}
response.write("</tr>");
}
response.write("</table>");
...

SAP AG 2004, Connector Framework Basics Using the JDBC Connector / 21

SAP AG

<Course Number>

Unit Title - 21

CF API Queries
A Query can be used for simple interactions with back-end systems
A query is usually the easiest way to interact with a RDBMS
Some resource adapters may not provide a query interface and will
throw an exception if queries are not supported.

You build a query using either the IQuery or INativeQuery object

Obtained from the Connection object

IQuery Interface:
For the IQuery interface, the execution of the query will result in
boolean success/failure flag
The result of the query (IRecordset) can be obtained if successful
IQuery does not work until NW04 Stack 10 See SAP Note 782106

INativeQuery Interface:
For the INativeQuery interface on a JDBC system, the execution of a
SELECT query will result in a native JDBC java.sql.ResultSet
For other types of systems, the result of the query execution will be
the native result type for particular system type.
SAP AG 2004, Connector Framework Basics Using the JDBC Connector / 22

SAP AG

<Course Number>

Unit Title - 22

CF API IQuery Example

import com.sapportals.connector.execution.objects.IQuery;

...
IQuery query = connnection.newQuery();
String qstr = "SELECT title_id,title,price FROM titles " +
"WHERE title_id LIKE 'P%'");
boolean success = query.execute(qstr);

...

SAP AG 2004, Connector Framework Basics Using the JDBC Connector / 23

SAP AG

<Course Number>

Unit Title - 23

CF API Retrieving Query Results

An IRecordset object containing all the rows resulting from the
query can be retrieved from the query object using the
retrieveRecordset() method of the query object
Metadata can also be obtained from the recordset using
retrieveMetaData(). Metadata is often useful for determining what
columns were returned by the query
import com.sapportals.connector.execution.structures.IRecordMetaData;
import com.sapportals.connector.execution.structures.IRecordSet;

...
IRecordSet rs = query.retrieveRecordSet();
IRecordMetaData rsMD = rs.retrieveMetaData();
response.write("<table><tr>");
int columnCount = rsMD.getColumnCount();
for (int index = 1; index <= columnCount; index++) {
response.write("<th>" + rsMD.getColumnLabel(index) + "</th>");
}

SAP AG 2004, Connector Framework Basics Using the JDBC Connector / 24

SAP AG

<Course Number>

Unit Title - 24

CF API INativeQuery Example

The INativeQuery interface can be used to pass a query to the backend
system without any translation by the connector framework. This feature
requires you to know the exact syntax for the query interface (for JDBC
standard SQL).
The result is in the native backend data structures (e.g.
java.sql.ResultSet for JDBC, or com.sap.mw.jco.JCO.Table for JCO
connections).
For JDBC systems, use the ResultSet just like any normal JDBC interface.
import java.sql.ResultSet;
import com.sapportals.connector.execution.objects.INativeQuery;
...
INativeQuery query = connnection.newNativeQuery();
String qstr = "SELECT title_id,title,price FROM titles " +
"WHERE title_id LIKE 'P%'");
Object o = query.execute(qstr);
ResultSet rs = null;
if (o instanceof java.sql.ResultSet) {
rs = (ResultSet) o;
...
}
SAP AG 2004, Connector Framework Basics Using the JDBC Connector / 25

SAP AG

<Course Number>

Unit Title - 25

Java Documentation
Available in the PDK documentation
Java Development > Javadocs > Connector Framework / Connector Gateway
Service

SAP AG 2004, Connector Framework Basics Using the JDBC Connector / 26

SAP AG

<Course Number>

Unit Title - 26

More Information
SDN Articles:
SAP Connector Framework Examples

PDK Documenation:
Java Development -> Portal Development -> Connector Framework

Books:
J2EE Connector Architecture and Enterprise Application Integration

Sun Information:
http://java.sun.com/j2ee/connector/

J2EE Connector Architecture Industry Support

http://java.sun.com/j2ee/connector/download.html

J2EE Connector Architecture Brings Business Systems to the Web

SAP AG 2004, Connector Framework Basics Using the JDBC Connector / 27

SAP AG

<Course Number>

Unit Title - 27

Unit Summary

You should now be able to:

Use the Connector gateway to connect to a relational
database system to retrieve data using the JDBC Connector
Identify ways to provide credentials to the connector
Retrieve data from a database using the JDBC Connector

SAP AG 2004, Connector Framework Basics Using the JDBC Connector / 28

SAP AG

<Course Number>

Unit Title - 28