How Headers Work

HydraExpress Web Service Development Guide

15.2 How Headers Work

Header support is primarily provided by the class rwsf::CallInfo. In the client implementation, an rwsf::CallInfo object is used to define additional header elements to be added to the request message. When the client sends the request, the additional header data is extracted from the rwsf::CallInfo object and placed into SOAP and transport headers in the outgoing request message.

When the server parses the incoming SOAP message, it extracts any header data and places it into another rwsf::CallInfo object. If there is a response, the server obtains the response header data from the rwsf::CallInfo and places a properly formatted SOAP string into the SOAP response message.

HydraExpress parses and validates the format of the incoming SOAP header, returning a server error if the format is invalid. HydraExpress also guarantees correct formatting of the response SOAP header. No such validation occurs for transport headers. You must guarantee that the string representing header data is valid when adding it on the client or modifying it on the server.

The processing for transport header data is similar to that for SOAP headers: the incoming message is parsed for transport header data, which is placed in an rwsf::CallInfo object, and the process is reversed to create a transport header for the response message.

If you create your own transport and you want that transport to support custom header elements, the transport code must know how to add and later consume these additional header elements. For more information on creating a transport, see Chapter 11, "Custom Transports and Listeners." For more information on creating a message handler, see Chapter 14, "SOAP Message Handlers."

15.2.1 Defining and Using Headers through the rwsf::CallInfo Interface

Classrwsf::CallInfo includes a wide range of methods to add, clear, or otherwise manipulate transport and SOAP headers, in both client, server-side, and handler code.

This section uses transport headers for illustration, but SOAP headers work the same way. HydraExpress ships with a Headers example that illustrates working with SOAP and transport headers, Section 15.3. Also see Chapter 11 for information about transport handlers.

This section provides a few examples on using the some rwsf::CallInfo methods. For full information on rwsf::CallInfo, please see its entry in the reference guide.

This example shows how to retireve all the HTTP request headers:

#include <iostream>
#include <rwsf/core/Enumeration.h>

void ExampleImp::printHeaders(CallInfo& info , std::string payload)       //1
{
  rwsf::Enumeration<rwsf::CallInfo::TransportHeaderObject> httpHeaders =  //2
                           info.getRequestTransportHeaders();
  while( httpHeaders.hasMoreElements() ) {                                //3
    rwsf::CallInfo::TransportHeaderObject header = httpHeaders.nextElement();
    std::cout << header.name_ << ": " << header.value_ << std::endl; 
  }
}

`//1`	The `printHeaders()` method takes as parameters the `CallInfo` object and the payload.
`//2`	Gets all request transport headers and places them in an enumeration of *rwsf::CallInfo::TransportHeaderObject* objects containing key/value pairs representing the name/value in each header.
`//3`	Iterates through the transport headers adding each header to a new *TransportHeaderObject* `header` and printing it to standard out.

Note that you can also retrieve response headers in the same way by calling getResponseTransportHeaders() on the CallInfo object.

This code simply adds a request transport header:

rwsf::CallInfo info;
info.addRequestTransportHeader("myHeader", "MyValue");

On the server side, check to see if the request header was set and add a response transport header:

rwsf::CallInfo info;
std::string set = info.isRequestTransportHeaderSet("myHeader");
std::string value = info.getRequestTransportHeaderValue("myHeader");
info.addResponseTransportHeader("myHeaderResponse", "MyValueResponse");

Use a custom transport handler to remove a transport header and then add a different one:

class MyTransportHandler1 : public rwsf::MessageHandlerImp {

  public:

    virtual void invoke(rwsf::CallInfo& callInfo)
    {
      if (!callInfo.isRequest()) {
        callInfo.removeResponseTransportHeader("requestHeader");
        callInfo.addResponseTransportHeader("responseHeader", "Value1");
      }
    }

};

The Rogue Wave name and logo are registered trademarks of Rogue Wave Software, and HydraExpress is a trademark of Rogue Wave Software. All other trademarks are the property of their respective owners.
Provide feedback to Rogue Wave about its documentation.