com.sap.aii.mapping.lookup

Class LookupService

java.lang.Object
  com.sap.aii.mapping.lookup.LookupService

public final class LookupService
extends Object

Lookup service for communicating with remote systems via adapters. The service contains methods for getting accessors which provide access to remote systems. The accessors support synchronous calls to the remote systems.

The Lookup API supports access via the JDBC, RFC, and SOAP adapter. If you want to execute a mapping lookup with a third party adapter, then the adapter must fulfil the following conditions:

• The adapter must support synchronous calls.
• The adapter must not use a Receiver Agreement.

You can get a generic system accessor (SystemAccessor).

You can get two specific system accessors using specific adapters, a system accessor which allows executing queries on a data base via the JDBC adapter ( DataBaseAccessor), and a system accessor for calling remote function modules of a SAP system (RFC) via the RFC adapter. (RfcAccessor). These specific accessors have specific interfaces appropriate to their adapters.

The methods to get a system accessor have a communication channel parameter. The communication channel is configured in the Integration Directory and specifies the remote system and the adapter type. You can get a channel parameter value by using the method getChannel(String, String, String)or by using the parameters of your mappign program InputParameters.getChannel(String). Be aware that you can only use channels which are of type receiver channel and which use adapters which allow synchronous calls and do not use a receiver agreement.

The generic system accessor uses as request message an object of type Payload. You can create such a payload object with the methods getXmlPayload(InputStream), getTextPayload(InputStream, String), or getBinaryPayload(InputStream). You should choose the correct payload type which the choosen adapter can work with.

The RFC system accessor uses as request message an object of type XmlPayload. You can create such a payload object with the method getXmlPayload(InputStream).

The accessors do not support transactional behaviour. Therefore, they should not be used to change the state in the accessed system; writing data to the accessed system can lead to inconsistencies. The accessors should only be used to read data from the accessed system.

Since:

SAP NetWeaver '04 SPS 13

See Also:

Channel, SystemAccessor, DataBaseAccessor, Payload

Nested Class Summary

static class

LookupService.Internal Internal Service.

Method Summary

static BinaryPayload	getBinaryPayload(InputStream stream) Returns a binary payload which can be used in SystemAccessor.call(Payload).
static Channel	getChannel(String service, String channelName) Returns a channel object without party for a given communication component and channel name which can be used in the method getSystemAccessor(Channel), getDataBaseAccessor(Channel), and getRfcAccessor(Channel).
static Channel	getChannel(String party, String service, String channelName) Returns a channel object for a given party, communication component, and channel name which can be used in the methods getSystemAccessor(Channel), getDataBaseAccessor(Channel), and getRfcAccessor(Channel).
static DataBaseAccessor	getDataBaseAccessor(Channel channel) Returns a database accessor for a given communication channel.
static RfcAccessor	getRfcAccessor(Channel channel) Returns a RFC accessor for a given communication channel.
static SystemAccessor	getSystemAccessor(Channel channel) Returns a generic system accessor instance for a given communication channel.
static TextPayload	getTextPayload(InputStream stream, String encoding) Returns a text payload which can be used in SystemAccessor.call(Payload).
static XmlPayload	getXmlPayload(InputStream stream) Returns a xml payload which can be used in SystemAccessor.call(Payload)or RfcAccessor.call(XmlPayload)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getSystemAccessor

public static SystemAccessor getSystemAccessor(Channel channel)
                                        throws LookupException

Returns a generic system accessor instance for a given communication channel. If you call this method a second time, you will get a different accessor instance, even if you use the same channel. The method invocation establishes the connection to the adapter engine.

The following code fragment shows how to use a generic system accessor.

//1. Determine a channel.
Channel channel = LooupService.getChannel("party","myService","myChannel");
// or use parametrization (TransformationInput.getInputParameters()).
// InputParameters parameters = transformationInput.getInputParameters();
// Channel channel = (Channel)parameters.getChannel("paramName");
// 2. Get a system accessor for the channel.
SystemAccessor accessor = LookupService.getSystemAccessor(channel);
try{

// 3. Create a payload according to the data type which the adapter exspects.
// Use service.getBinaryPayload() for binary payload,
// and service.getTextPayload() for text payloads.
Payload payload = LookupService.getXmlPayload(inputStream);
// 4. Execute lookup.
Payload result = accessor.call(payload);
...
// Steps 3. and 4. can be executed several times.
...

}finally{

// 5. Close the accessor in order to free resources.
if (accessor!=null) accessor.close();

}

Parameters:

channel - communication channel, must be a receiver channel of a adapter supporting synchronous calls

Returns:

generic system accessor.

Throws:

LookupException, - if an error occurs during getting the accessor, connecting to the adapter engine, or connecting to the remote system.

NullPointerException - if channel is null.

LookupException

getDataBaseAccessor

public static DataBaseAccessor getDataBaseAccessor(Channel channel)
                                            throws LookupException

Returns a database accessor for a given communication channel. If you call this method a second time, you will get a different accessor instance, even if you use the same channel. The method invocation establishes the connection to the adapter engine.

The following code fragment shows an example for the usage of the database accessor.

// 1. Determine a channel.
Channel channel = LookupService.getChannel("myService","myJdbcChannel");
// or use parametrization (TransformationInput.getInputParameters()).
// InputParameters parameters = tranaformationInput.getInputParameters();
// Channel channel = (Channel)parameters.getChannel("paramName");
// 2. Get a database accessor for the channel.
DataBaseAccessor accessor = LookupService.getDataBaseAccessor(channel);
try{

// 3. Prepare a SQL statement "sqlStatement".
String sqlStatement = "SELECT a, b, c FROM TABLE2";
// 4. Execute lookup.
DataBaseResult result = accessor.execute(sqlStatement);
// 5. Iterate over the result rows.
for( Iterator rows = result.getRows(); rows.hasNext(); ){

Map columnMap = (Map)rows.next();
Object valueA = columnMap.get("a");
Object valueB = columnMap.get("b");
....

}
// Steps 4. and 5. can be executed several times.

}finally{

// 6. Close the accessor in order to free resources.
if (accessor!=null) accessor.close();

}

Parameters:

channel - communication channel, must be a receiver channel for the JDBC adapter.

Returns:

database accessor.

Throws:

LookupException, - if an error occurs during getting the accessor.

NullPointerException - if channel is null.

LookupException

getRfcAccessor

public static RfcAccessor getRfcAccessor(Channel channel)
                                  throws LookupException

Returns a RFC accessor for a given communication channel. If you call this method a second time, you will get a different accessor instance, even if you use the same channel. The method invocation establishes the connection to the adapter engine.

See Channelfor getting a communication channel.

The following code fragment shows an example for the usage of the RFC accessor.

// 1. Determine a channel.
Channel channel = LookupService.getChannel("myService","myRfcChannel");
// or use parametrization (TransformationInput.getInputParameters()).
// InputParameters parameters = tranaformationInput.getInputParameters();
// Channel channel (Channel)parameters.getChannel("paramName");
// 2. Get a RFC accessor for a channel.
RfcAccessor accessor = LookupService.getRfcAccessor(channel);
try{

// 3. Create a xml input stream representing the function module request message.
InputStream inputStream;
...
// 4. Create xml payload
Payload payload = LookupService.getXmlPayload(inputStream);
// 5. Execute lookup.
Payload result = accessor.call(payload);
...
// steps 3. to 5. can be executed several times.
...

}finally{

// 7. close the accessor in order to free resources.
if (accessor!=null) accessor.close();

}

Parameters:

channel - communication channel, must be a receiver channel for the RFC adapter.

Returns:

RFC accessor.

Throws:

LookupException, - if an error occurs during getting the accessor.

NullPointerException - if channel is null.

LookupException

getChannel

public static Channel getChannel(String party,
                                 String service,
                                 String channelName)
                          throws LookupException

Returns a channel object for a given party, communication component, and channel name which can be used in the methods getSystemAccessor(Channel), getDataBaseAccessor(Channel), and getRfcAccessor(Channel). The channel must be configured in the Integration Directory. It must be a receiver channel for an adapter which supports synchronous calls and which does not use the receiver agreement. Otherwise the accessor will throw an exception during runtime.

Parameters:

party - name of the party

service - name of the communication component

channelName - name of the channel

Returns:

channel

Throws:

NullPointerException - if party,service, or channelName is null.

LookupException

getChannel

public static Channel getChannel(String service,
                                 String channelName)
                          throws LookupException

Returns a channel object without party for a given communication component and channel name which can be used in the method getSystemAccessor(Channel), getDataBaseAccessor(Channel), and getRfcAccessor(Channel). The channel must be configured in the Integration Directory. It must be a receiver channel for an adapter supporting synchronous calls. Otherwise the accessor will throw an exception during runtime.

Parameters:

service - name of the communication component

channelName - name of the channel

Returns:

channel

Throws:

NullPointerException - if service, or channelName is null.

LookupException

getXmlPayload

public static XmlPayload getXmlPayload(InputStream stream)

Returns a xml payload which can be used in SystemAccessor.call(Payload)or RfcAccessor.call(XmlPayload)

Parameters:

stream - payload data as input stream

Returns:

xml payload.

Throws:

NullPointerException - if stream is null.

getTextPayload

public static TextPayload getTextPayload(InputStream stream,
                                         String encoding)

Returns a text payload which can be used in SystemAccessor.call(Payload).

Parameters:

stream - payload data as input stream

encoding - encoding character set name

Returns:

text payload.

Throws:

NullPointerException - if stream is null.

getBinaryPayload

public static BinaryPayload getBinaryPayload(InputStream stream)

Returns a binary payload which can be used in SystemAccessor.call(Payload).

Parameters:

stream - payload data as input stream

Returns:

binary paylaod.

Throws:

NullPointerException - if stream is null.

Access Rights

This class can be accessed from:

SC	DC	Public Part	ACH
[sap.com] SAP_XIAF	[sap.com] com.sap.aii.mapping.lib.facade	api	BC-XI