iWay Service Manager Component Reference Guide > Available Services > iWay Adapter (com.ibi.agents.XDAdapterAgent)

iWay Adapter (com.ibi.agents.XDAdapterAgent)

Topics:

Syntax:

com.ibi.agents.XDAdapterAgent

iIT Service Object:

defined by adapter

Description:

This service is used to call a preconfigured iWay adapter.

Note: This service should be used as adapters are defined. To use this service, an adapter must first be configured using iWay Explorer.

Parameters:

Parameter

Description

iBSP URL *

Select an available iBSP URL from the drop-down list or type a URL using the following format: 

http://host:port

where:

host

Is the name of the machine where iWay Service Manager is installed.

port

Is the port on which iBSP listens for SOAP requests. The default port is 9000.

The iBSP URL allows you to access targets defined in the iBSP repository.

Adapter *

The name of the configured adapter you are working with, for example, RDBMS.

Target *

The name of the user-defined target that is associated with the configured adapter, for example, Oracle11.

Class

The name of the Java class that implements the adapter associated with the service. This field is populated by iWay Service Manager when you create the Adapter service and should not be modified.

Descriptor

Key used by iWay Service Manager to locate the adapter target parameters to associate with the service. This field is populated by iWay Service Manager when you create the Adapter service and should not be modified.

Keys

Key used by iWay Service Manager to locate the adapter persistence keys associated with the service. This field is populated by iWay Service Manager when you create the Adapter service and should not be modified.

Persist Connection

If enabled, the adapter connection is reused between execution attempts. Select one of the following options from the drop-down list:

  • none (false). Each invocation of this service will create a new instance of the adapter. Thus, for simple processing, one instance of the adapter is used for each requested operation. When streaming, one adapter instance will be reused for all messages in the stream. In a transaction, each created adapter instance receives the commit or rollback.
  • persist (true). This refers to persistence at the process flow instance level. When an instance of the adapter is first encountered for a target, the service creates a new instance of the adapter that is specific to that target.

    This adapter instance is reused by subsequent invocations of the service, within an iterator loop and across invocations of the worker, including use within a streaming preparser situation.

    At the end of the process flow, the adapter instance is no longer available.

  • pool. An adapter with a specific set of parameters and a specific target will be cached at the worker (sub-channel) level. This means that multiple services within a process flow will share an adapter and that multiple invocations of the process flow or a different process flow requiring the same adapter or target will reuse that adapter. If you have a threading count of n, then there will be n instances of the cached adapter.

    Note: The term target refers to an evaluated target in which any iFL has been replaced with the value of that iFL. For example, a target with a port in a special register will be treated as the port value after the register value is obtained.

Promote OnFailure

If set to false, failure edges, such as fail_connect, are promoted to OnError. This is used for upward compatibility purposes.

Emit OnFailure

If the Promote OnFailure parameter is set to false, this parameter determines the type of document to emit on failures. Select one of the following options from the drop-down list:

  • status. A status document will become the output document. This option is selected by default.
  • input. The input document will become the output document.

Edges:

The edges returned are listed in the following table.

Edge

Description

success

Successful operation of the adapter.

fail_operation

The adapter failed and did not report the direct cause.

fail_security

The adapter has returned a security violation.

fail_partner

The adapter reports that it cannot reach the needed external system or that system has returned an error.

cancelled

The operation has been cancelled due to a timeout or other cause.

Example:

It is recommended to use an iWay Adapter as a Service object for connection with adapters rather than this service. For more information, see the Configuring the Adapter in iWay Designer chapter in the iWay adapter documentation that corresponds to the specific adapter you are trying to add or define (for example, iWay XML Adapter for RDBMS User's Guide).

Using iWay Functional Language With Adapters

A frequent requirement is to use iFL to adjust the target of an adapter, for example, to change the URL of a server to be reached. The example in this section discusses that issue.

Assume two MS SQL Server databases, smd1 and smd2, each of which contains a table named testtable. The two tables have the same structure, but contain different data. The application designer wants to create a flow using the RDBMS adapter that executes the SQL statement, select * from testable, against either the table in smd1 or the one in smd2, depending on the input document.

Using Application Explorer, create an RDBMS adapter target pointing at either of the two databases, as shown in the following image.

In the target, create the statement, which can be named stmt1.

Now, add the adapter to the iSM registry.

Edit the parameter values imported from the target to use iFL expressions.

Note that the expression combines the _property and _sreg functions. Since there are several connection parameters that are required to be set dynamically for each destination, you can store the values you need in a properties file using property names that follow a naming convention. Thus, if you can set the dest special register, then you can use the value of this register to get the values that are required to make a connection. For this example, the properties file has the following structure: 

smd1.host=localhost
smd1.port=1433
smd1.dbname=smd1
smd1.id=sa
smd1.password=harrison
smd1.url=jdbc:sqlserver://localhost:1433;databaseName=smd1
smd2.host=sdewitt4
smd2.port=1433
smd2.dbname=smd2
smd2.id=sa
smd2.password=harrison
smd2.url=jdbc:sqlserver://localhost:1433;databaseName=smd2

Save the adapter in the registry as DynamicRDBMS.

Other ways to store specific information includes the iWay Trading Profile Manager or another table reachable using the _jdbc() function call.

Now you need to create a flow that uses the DynamicRDBMS adapter. Since the adapter is defined in the registry, you must work in a registry based project. To keep things simple, the flow will contain two components. The XDSREGAgent service will set the dest special register to either smd1 or smd2, depending on the value of an attribute in the input document. To keep things simple, you will just add this attribute to the standard RDBMS adapter input message, so the value of dest can be: 

_xpath(/AdapterParams/@dest)

The next step is to add the DynamicRDBMS adapter.

Now, you can test the flow using the following input:

<AdapterParams location="RDBMS/Statements/stmt1" dest="smd2"/>

Since the dest attribute is set to smd2, you should use the correct properties to connect to the smd2 database.

Finally, you can retest the flow using the following input:

<AdapterParams location="RDBMS/Statements/stmt1" dest="smd1"/>

Now, the dest attribute is smd1, which means the adapter should connect to the smd1 database and retrieve different data.

Notice that all the bar values from the first result have changed to foo.