Interacting with the Pipeline
During run time, an adapter service has to perform the following:
Retrieve data from the pipeline at the beginning of its execution.
To retrieve data from the pipeline, the service must interrogate the WmRecord argument of the execute method. Limit the interrogation to fields identified in the service's signature because often there is other information in the pipeline that is not intended for the service.
Add data to the pipeline at the end of execution.
At the end of execution, the execute method must return a WmRecord instance containing the data that must be added to the pipeline. Organize the return data in a way that is consistent with the metadata signature so that other adapter services (or flow or Java services) can access it.
For discussion purposes, assume the following as a sample metadata signature for both input and output of an adapter service:
Field Name | Type |
customer.id | java.lang.Integer |
customer.name | java.lang.String |
customer.orders[].id | java.lang.Integer[] |
customer.orders[].date | java.util.Date[] |
customer.orders[].lineItems[].itemNumber | java.lang.Integer[][] |
customer.orders[].lineItems[].quantity | java.lang.Integer[][] |
customer.orders[].lineItems[].description | java.lang.String [][] |
The sample signature describes a hierarchal structure that can be expressed as a tree structure, where the actual field names form the leaves, and the elements preceding the field name are nodes. Thus, the names customer, orders, and lineItems are node names, and id, name, date, itemNumber, quantity, and description are leaves in the tree structure.
The WmRecord class, which is the primary carrier of data into and out of adapter services, is a JCA based wrapper for an IData object. It provides methods that access the IData content. However, when dealing with a hierarchal structure (as is the case with the sample), it is necessary to "drill down" into the IData structure. Therefore, ignore the WmRecord methods except for getIData, and putIData, which is used to access the underlying IData object.
Note:
The IData interface is part of the standard webMethods Integration Server Java API. Its structure is based on key/value pairs, where the key is a String and the value is a Java object. For more information, see the Javadoc entries for IData, IDataCursor, IDataFactory, and IDataUtil.
getIData Method
Returns an IData object that contains the entire pipeline at the time the service was invoked. The top-level branch or leaf name(s) in the metadata signature (in this case, customer) is the key used to access data intended for use by the service. The value associated with that key is either another IData object (if the key is a node name) or an object of the type specified by the corresponding type field of the signature. If the name of the branch or leaf includes a pair of square braces "[]", then the value contains an array of the designated object type.
Thus, the fields in the sample would be populated as follows:
Returns an
IData object with an entry, keyed with the name
customer.
The value associated with
customer is another
IData object, with three entries:
id,
name, and
orders.
The value corresponding with
id is an
Integer.
The value of
name is a
String.
The value of
orders would contain an array of
IData objects.
The
orders IData objects would each contain an
id of type
Integer, a
date of type
java.util.Date, and an array of
IData objects associated with the
lineItems key.
The
lineItems IData objects would contain entries for
itemNumber,
quantity, and
description, with the data types provided in the signature.
When constructing response data to place in the pipeline at the end of service execution, use the same rules that apply to interpreting the metadata signature. For each node level in the signature, there must be a corresponding layer of IData, keyed with the names from the signature. For each leaf, there must be an IData entry with the corresponding signature name and type.
Note:
Signatures are not enforced by Integration Server or the ADK framework. The validity of a request based on the presence or absence of a given field, or the value given to a field, is determined exclusively by the adapter implementation. Similarly, if the service fails to populate the response WmRecord with data organized according to the signature, subsequent services cannot access the data provided by the adapter service.