Specifying a pluggable name handler

With default business object resolution, you can specify a pluggable name handler to determine the business object to be used in SOAP-message-to-business-object transformations. You do this by changing an MO_DataHandler_DefaultSOAPConfig attribute.

The MO_DataHandler_DefaultSOAPConfig has, among others, two attributes of type string that designate:

If the SOAPNameHandler attribute has a value, the SOAP data handler calls the specified name handler. If the value does not exist, or if the specified name handler fails to get a business object name, the SOAP data handler is called by default to perform default business object resolution.

The SOAP DataHandler uses the SOAPNameHandler property specified in the MO to instantiate the custom-name-handler class. It then calls the getBOName to resolve the business object name. The SOAP DataHanlder passes the SOAPProperty object it received from the connector to the custom-name-handler implementation class.

This SOAPProperty object contains a structured list of potential candidate BOs for resolution. Contained in the list are BodyName, BodyNamespace and BOName triplets. These triplets are based on the SOAP Config MO configuration information. The Default Name Handler uses this object to resolve the BO. A custom name handler developer may use this object at their discretion.

Using the SOAPProperty object

You use the SOAPPropertyUtils class to extract the business object name from the SOAPProperty. To do so, use the following method:

/**
 * Retrieve the business object name based on the body name and the body
* namespace
*.
* @param soapProp top level SOAPProperty object that is passed by the
* connector
* @param name body name from the SOAP message
* @param uri body namespace from the SOAP message
* @return business object name from the SOAPProperty object with the body
* name and body namespace.
*/
java.lang.String findBOName(SOAPProperty soapProp, String name, String uri);

Sample NameHandler

The following is a sample NameHandler:package

com.ibm.adapters.datahandlers.soap.namehandlers;
// DOM and Parsers
import javax.xml.parsers.DocumentBuilder;
import org.w3c.dom.Document;
import org.w3c.dom.Element;
import org.xml.sax.InputSource;
// Apache SOAP
import org.apache.soap.Envelope;
import org.apache.soap.Header;
import org.apache.soap.Body;
import org.apache.soap.Constants;
import org.apache.soap.util.xml.DOMUtils;
import org.apache.soap.util.xml.XMLParserUtils;
import org.apache.soap.util.xml.QName;
import org.apache.soap.encoding.soapenc.SoapEncUtils;
import org.apache.soap.encoding.soapenc.Base64;
// java
import java.util.Vector;
// SOAP data handler
import com.ibm.adapters.datahandlers.soap.*;
import com.ibm.adapters.datahandlers.soap.exceptions.*;
public class MyCustomNameHandler extends SOAPNameHandler {
  private static final String BOPREFIX = "MyCustomBOPrefix";
  private static final char UNDERSCORE = '_';
  private static final char EMPTY_STRING = "";

  public String getBOName(Envelope msgEnv, SOAPProperty prop)
    throws SOAPNameHandlerException
  {
    // Initialize a String Buffer
    StringBuffer boName = new StringBuffer();
    // Determine the "MyCustomBOPrefix" SOAP data handler 
    // MO property. If it exists, and is populated append 
    // this prefix to the front of the BOName.
    String pref = dh.getOption(BOPREFIX);
    if (pref != null) {
       boName.append(pref.equals(EMPTY_STRING)
       ? EMPTY_STRING : pref + UNDERSCORE);
  }
    // Begin parsing the SOAP msg envelope.
    Element bodyEl, requestEl;
    Body msgBody = msgEnv.getBody();
    Vector bodyEntries = msgBody.getBodyEntries();
    if((bodyEntries == null) || (bodyEntries.size() <= 0))
       throw new SOAPNameHandlerException("No Body Entries exist 
        for this SOAP message. Cannot determine BOName to use.");
    // Grab the first <SOAP-ENV:Body> Element
    bodyEl = (Element) bodyEntries.elementAt(0);
    // Grab the first Child Element of the <SOAP-ENV:Body> 
    // Element
    requestEl = (Element) DOMUtils.getFirstChildElement(bodyEl);
    // Read the name and namespace of this first child
    String name = bodyEl.getLocalName();
    String uri = bodyEl.getNamespaceURI();
    if (uri == null)
       uri = Constants.NS_URI_SOAP_ENV;
    // Use the SOAPPropertyUtils findBOName() method to search
    // the SOAPProperty object for this messages first element
    // name and namespace. If no match is found, a
    // SOAPDataHandlerException will be thrown. If a match is 
    // found, and it's not an empty string, append to the boname.
String returnedBOName = SOAPPropertyUtils.findBOName(prop, name, uri);
if (returnedBOName != null && 
       !returnedBOName.equals(EMPTY_STRING))
  boName.append(returnedBOName);
       return boName.toString()
   }
}

Copyright IBM Corporation 1997, 2004. All Rights Reserved.