12 Advanced Topics for Web Services

12.3.1 Client Side SOAP Request Header Support

Oracle Application Server Web Services generated client-side proxy code provides methods to use SOAP request headers. A SOAP request message, including the SOAP request headers is transmitted to a service endpoint when Web Services proxy code is invoked.

When Oracle Application Server Web Services generates a proxy, either from WSDL for a Web Services Document or RPC style service, the proxy code provides two SOAP request header support methods:

void _setSOAPRequestHeaders(org.apache.soap.Header headers)
org.apache.soap.Header _getSOAPRequestHeaders()

These methods provide access to an org.apache.soap.Header object. By default the org.apache.soap.Header object's value is set to null which signifies there are no headers in the SOAP request message. When a request header is needed, use the _setSOAPRequestHeaders() method to specify the Header object to be sent with the SOAP request message.

The SOAP request header information is shared for all proxy operations. After the headers are set using _setSOAPRequestHeaders(), all subsequent operation invocations using the proxy use the same header value. To set a new header value, call _setSOAPRequestHeaders() using a new Header object or with a null value.

To create and manipulate SOAP request headers you need to populate the header object. The org.apache.soap.Header object provides a method for specifying the contents of one or more SOAP header blocks. It is defined as:

public void setHeaderEntries(java.util.Vector headerEntries)

The vector is populated with org.w3c.dom.Element objects which specify individual SOAP header blocks.

When a header entry includes the mustUnderstand attribute set to the value 1, the recipient must process the header entry. If the recipient cannot process the header entry, then a SOAP fault is returned with the value FAULT_CODE_MUST_UNDERSTAND.

.
.
.
// Create an intance of the proxy
EmployeeProxy proxy = new EmployeeProxy();
// Create a Header objecy
Vector v = new Vector();
v.add (e);
Header hdr = new Header();
hdr.setHeaderEntries(v);

// Set the Header
proxy._setSOAPRequestHeaders(hdr);
// Invoke the request
System.out.println("Salary of MILLER is: " + proxy.getEmployeeSalary("MILLER"));

12.3.2 Server Side SOAP Request Header Support

To process a SOAP request header on the server side, a Web Service needs to implement the oracle.j2ee.ws.HeaderCallback interface that is part of the Oracle Application Server Web Services supplied wsserver.jar. This interface includes one method that takes a single org.apache.soap.Header argument.

The Oracle Application Server Web Services infrastructure calls the processHeaders() method before every associated service method.

When an incoming SOAP request header includes one or more header entries with the mustUnderstand attribute set to either 1, true, or TRUE values, then the Web Service implementation must implement the oracle.j2ee.ws.HeaderCallback interface. If this interface is not implemented, Oracle Application Server Web Services throws a SOAP fault with the fault code set to FAULT_CODE_MUST_UNDERSTAND.

If a Web Service implementation implements the HeaderCallback interface, the implementation can throw a SOAP exception with the fault code set to FAULT_CODE_MUST_UNDERSTAND if the service does not know how to process a header entry with the mustUnderstand attribute set to 1, true, or TRUE. Oracle Application Server Web Services then translates the exception and Oracle Application Server Web Services throws a SOAP fault with the fault code set to FAULT_CODE_MUST_UNDERSTAND.

This section shows server-side Web Services code that provides the implementation for the Employee service. The complete sample containing this Web Service is available in the directory $ORACLE_HOME/web_services/demo/basic/header_demo/client (after unzipping $ORACLE_HOME/webservices/demo/demo.zip).

Example 12-5 shows an interface that extends HeaderCallback.

Example 12-6 shows a section of the service implementation for the sample getEmployeeSalery interface, including the processHeaders() method that can handle incoming SOAP request headers of the form:

<SOAP-ENV:Header>  <credentials>    <username>scott</username>    <password>tiger</password>   <datasource>jdbc/OracleCoreDS</datasource>  </credentials></SOAP-ENV:Header>

import oracle.j2ee.ws.HeaderCallback;
/**
 *  Employee java class being exposed as Web Services
 *  This service also extends HeaderCallback so as to
 *  access Headers.
 */
public interface Employee
  extends  HeaderCallback
{
  // Get the salary for a given Employee
  int getEmployeeSalary(String  ename);
}

  public void processHeaders(Header header)
     throws java.io.IOException,
            oracle.xml.parser.v2.XSLException
  {
    // Get all the Elements
    Vector entries = header.getHeaderEntries();
    Element e = (Element) entries.firstElement();
    System.out.println("Element received is: " );
    ((XMLElement)e).print(System.out);

    // Get independent nodes and retrieve node values.
    Node userNode;
    userNode = ((XMLNode)e).selectSingleNode("username");
    userName = ((XMLElement)userNode).getText();

    Node passwordNode;
    passwordNode = ((XMLNode)e).selectSingleNode("password");
    password = ((XMLElement)passwordNode).getText();

    Node dsNode;
    dsNode = ((XMLNode)e).selectSingleNode("datasource");
    datasourceName = ((XMLElement)dsNode).getText();

    System.out.println("User name is: " + userName);
    System.out.println("Password is: " + password);
    System.out.println("Datasource is: " + datasourceName);
  }

12.3.3 Limitations for SOAP Header Support

The following list contains limitations related to SOAP header support:

1. Oracle Application Server Web Services does not provide support for processing or translating header information that is specified in a WSDL definition.

2. Oracle Application Server Web Services does not provide validation, XML or otherwise, for SOAP request header information provided in the org.apache.soap.Header object. The user is responsible for populating this object with well-formed XML.

3. Oracle Application Server Web Services does not provide support for SOAP response headers.

4. When proxies are generated for JMS Document Style Web Services, the SOAP request header _setSOAPRequestHeaders() and _getSOAPRequestHeaders() methods are not supplied. Using JMS Web Services there are no server-side facilities for processing SOAP request headers.

5. When proxies are generated for Stored Procedure Web Services, the SOAP request header _setSOAPRequestHeaders() and _getSOAPRequestHeaders() methods are not supplied. Using Stored Procedure Web Services there are no server-side facilities for processing SOAP request headers.