Trading Partner Agreement

A Trading Partner Agreement (TPA) driver enables information from an external data store to be accessed during message handling. Such data stores often hold information relating to the processing of a message based on characteristics of the message; most commonly, the trading partner. For this reason, iWay considers these data stores to house trading partner information, although they can hold any information organized in an arbitrary fashion.

Information from the data store is accessed using the _tpa() function, which provides information from the data store at any point in the flow in which the _tpa() function is referenced in the configuration. This is similar to the xpath() and sreg() functions. But, because the format of the data store housing this trading partner information can be expected to vary, Service Manager routes trading partner information requests through drivers, referred to as TPA drivers. Each driver is charged with handling some aspect of a TPA request, and any single request must be resolved by a single driver.

Access Components

Each request provides the following information:

A TPA Class ID. This is an arbitrary token that distinguishes drivers. There is no restriction that drivers support unique class IDs, only that they recognize the ID. An example of a class ID might be "XML" for a driver that works with XML files, or "AUTO" for a driver that works with automotive requests.

Attribute wanted. This is the name of a single attribute to be located in the data store.

Default. The default value is returned, if the attribute wanted is not located.

Search context. One or more tokens used to direct the search within the driver. For example, if the driver works with a Java properties object, with keys such as

Toyota.wheels=4

the context would be "Toyota" and the configured request might be:

_tpa("CARS","wheels","4",xpath(/sales/car/model))

Similarly, if the TPA takes the form of a relational data base, the context variables might resolve to values used in select statements to locate the desired data.

Driver Resolution

When a _tpa() request is made, Service Manager evaluates the class ID and context to determine whether it knows which of the configured drivers is to receive the request. If it does not already "recognize" the class/context, it inquires of each driver in configuration order whether it can service the request for attributes based on that class ID and context. The first driver to respond that can service the request will receive this request and all subsequent requests for the combination of class ID and context.

Driver Internals

Drivers, like all other iSM exits, extend XDExitBase, which provides the driver with parameter resolution services, tracing, and so on. The driver itself extends XDTPADriver, which provides driver-specific exit services. If the driver exists in an extension, the XDTPADriver class is responsible for loading the driver, as is customary for exits. The driver should (by convention) be in the com.ibi.exits package.

Each driver must expose, in addition to the standard init() and term() methods, two "business" methods:

public int handles(String tpaid, String[] context) throws Exception;

and

public String access(String tpaid, String[] context,
String attribute, String deflt) throws Exception;

The handles() method returns whether the driver can service requests for the combination of tpaid(class) and the context variable values. It can select to handle all requests for the specified tpaid or only requests for the tpaid in combination with the context access pattern values. The handles() method returns:

Mnemonic	Value	Description
HANDLES_NO	0	Cannot handle this tpaid/context pattern.
HANDLES_YES	1	Can handle this tpaid/context pattern.
HANDLES_ALL	2	Can handle any call for this tpaid, regardless of the context values.

The access() method is called by iSM to obtain the attribute value based on the context values, which the driver has already reported that it can support.

For example, consider a driver that obtains TPA values from an XML file. The file looks like this:

<tpa>
  <group1>
    <attr1>value1</attr1>
    <attr2>value2</attr2>
  </group1>
  <group2>
    <attr1>value1</attr1>
    <attr2>value2</attr2>
  </group2>
</tpa>

The init() routine accepts two parameters: the class ID that this driver represents (it might have been the root element name as well) and the path to the XML file. The init() routine creates a list of the class IDs it supports and then parses the file and loads a second list with the names of the first level children (group1, group2). This example assumes that the object context map is constructed containing class IDs that this driver represents.

public int handles(String tpaid, String[] context) throws Exception
{
  if (tpaidList != null && !tpaidList.contains(tpaid)) 
  {
      return HANDLES_NO;
  }
  if (contextMap == null)
  {
      return HANDLES_ALL;   // supports all contexts
  }
  if (contextMap.containsKey(context[0]))  // this specific context
  {
      return HANDLES_YES;
  }
  return HANDLES_NO; // context required and not in my context
}

After the driver has reported that it handles the specific request, it will be called upon to service the request. It might do this by taking the context and finding that subtree, and within that subtree locating the desired attribute:

public String access(String tpaid, String[] context, String attribute,
 String deflt) throws Exception
{
  XDNode contextRoot = root.findChild(context[0]);
  XDNode attrNode = contextRoot.findChild(attribute);
  if (attrNode == null)
  {
    return deflt;
  }
  else
  {
    return attrNode.getValue();
  }
}

As above, no error handling is provided in this example.

Assuming that the driver handles "XML" as the class ID, then the call in the configurator might have been:

_tpa("XML",attr2,"default",sreg("toparty"))

If the toparty special register holds the name of the to party in the TPA, which in our case is either "group1" or "group2", the external call to the TPA function will look like:

_tpa("tpa","attr1","def1",sreg("tpa.toparty"))