Stubby - Adding SOAP Header Information to a Request

This page discusses how you can add SOAP Header information to web services called by Stubby, a Lotus Notes database that helps you create Apache Axis "stub" files that can be used to call web services from a Lotus Notes 7.x environment. If you need more information, please see the main page.

A typical SOAP envelope looks something like this:

<SOAP-ENV:Envelope  
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"  
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
    <ns1:GetStockInfo xmlns:ns1="urn:thisNamespace">
      <ns1:symbol>FOO</ns1:symbol>
    </ns1:GetStockInfo>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

If you use Stubby to generate the Axis client code for you to use in Lotus Notes, this SOAP envelope will be generated by code similar to the following:

import StockInfoNamespace.*;

StockInfoServiceLocator locator = new StockInfoServiceLocator();
StockInfoService service = locator.getDomino();
service.GetStockInfo("FOO"); 

Sometimes a web service will also require you to include SOAP Header information, usually for login purposes. In the case of explicit headers (that are defined in the WSDL), the SOAP Header information is supposed to be writable directly from the Axis client code. However, if the headers are implicit (not defined in the WSDL), you will have to generate them manually.

There are two kinds of header elements you may have to generate. The first are elements that are simply child nodes of the <Header> element, like so:

<SOAP-ENV:Envelope  
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"  
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
	
  <SOAP-ENV:Header>
    <ns1:UserName xmlns:ns1="urn:thisNamespace">John Doe</ns1:UserName>
  </SOAP-ENV:Header>
  
  <SOAP-ENV:Body>
    <ns2:GetStockInfo xmlns:ns2="urn:thisNamespace">
      <ns2:symbol>FOO</ns2:symbol>
    </ns2:GetStockInfo>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

This type of envelope can be created with Stubby code similar to this:

import StockInfoNamespace.*;
import lotus.domino.axis.client.Stub;

StockInfoServiceLocator locator = new StockInfoServiceLocator();
StockInfoService service = locator.getDomino();

// add a <UserName> node to the SOAP Header
((Stub) service).setHeader("urn:thisNamespace", "UserName", "John Doe");

service.GetStockInfo("FOO"); 

You can also end up with header elements that are nested, such that there are nodes with subnodes within the <Header> element, like so:

<SOAP-ENV:Envelope  
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"  
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
	
  <SOAP-ENV:Header>
    <ns1:AuthenticationInfo xmlns:ns1="urn:thisNamespace">
      <ns1:UserName>John Doe</ns1:UserName>
    </ns1:AuthenticationInfo>
  </SOAP-ENV:Header>
  
  <SOAP-ENV:Body>
    <ns2:GetStockInfo xmlns:ns2="urn:thisNamespace">
      <ns2:symbol>FOO</ns2:symbol>
    </ns2:GetStockInfo>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

In this case, the <UserName> node is within an <AuthenticationInfo> node within the SOAP Header. This type of envelope can be created with Stubby code similar to this:

import StockInfoNamespace.*;
import lotus.domino.axis.client.Stub;
import lotus.domino.axis.message.SOAPHeaderElement;
import javax.xml.soap.SOAPElement;

StockInfoServiceLocator locator = new StockInfoServiceLocator();
StockInfoService service = locator.getDomino();

// add an <AuthenticationInfo> node with a <UserName> subnode 
// to the SOAP Header
SOAPHeaderElement header = new SOAPHeaderElement(
    "urn:thisNamespace", "AuthenticationInfo");
SOAPElement node = header.addChildElement("UserName");
node.addTextNode("John Doe");
((Stub) service).setHeader(header);

service.GetStockInfo("FOO"); 

Note that we're talking about SOAP Envelope Headers here, not HTTP headers.

---

last edited March 8, 2007