Main Page | Class Hierarchy | Class List | File List | Class Members | File Members | Related Pages | Examples

Stub Class Reference

This is the client Stub base class to be inherited by all stub classes genarated by WSDL2WS tool. This class acts as the interface between the users and the Axis C++ engine (client side). Programmer can use the API defined here to enrich the client application functionality. Setting transport properties, setting SOAP headers, setting connection timeout and specifying a proxy on the client stub is facilitated with this interface. More...

#include <Stub.hpp>

List of all members.

Public Member Functions

 Stub (const char *pcEndPointURI, AXIS_PROTOCOL_TYPE eProtocol)
virtual ~Stub ()
void AXISCALL setEndPoint (const char *pcEndPointURI)
void AXISCALL setTrasportProperty (const char *pcKey, const char *pcValue)
const char * getFirstTrasportPropertyKey ()
const char * getNextTrasportPropertyKey ()
const char * getCurrentTrasportPropertyKey ()
const char * getCurrentTrasportPropertyValue ()
void deleteCurrentTrasportProperty ()
void deleteTrasportProperty (char *pcKey, unsigned int uiOccurance=1)
void AXISCALL setTransportProperty (const char *pcKey, const char *pcValue)
const char *AXISCALL getTransportProperty (const char *key, bool response=true)
const char * getFirstTransportPropertyKey ()
const char * getNextTransportPropertyKey ()
const char * getCurrentTransportPropertyKey ()
const char * getCurrentTransportPropertyValue ()
void deleteCurrentTransportProperty ()
void deleteTransportProperty (char *pcKey, unsigned int uiOccurance=1)
void setHandlerProperty (AxisChar *name, void *value, int len)
IHeaderBlock *AXISCALL createSOAPHeaderBlock (AxisChar *pachLocalName, AxisChar *pachUri)
IHeaderBlock *AXISCALL createSOAPHeaderBlock (AxisChar *pachLocalName, AxisChar *pachUri, AxisChar *pachPrefix)
IHeaderBlockgetFirstSOAPHeaderBlock ()
IHeaderBlockgetNextSOAPHeaderBlock ()
IHeaderBlockgetCurrentSOAPHeaderBlock ()
void deleteCurrentSOAPHeaderBlock ()
void deleteSOAPHeaderBlock (IHeaderBlock *pHeaderBlock)
void setProxy (const char *pcProxyHost, unsigned int uiProxyPort)
void setTransportTimeout (const long lSeconds)
int getStatus ()
void setMaintainSession (bool bSession)
void setTransportProtocol (AXIS_PROTOCOL_TYPE eProtocol)
AXIS_PROTOCOL_TYPE getTransportProtocol ()
void setUsername (const char *pcUsername)
void setPassword (const char *pcPassword)
const char * getUsername ()
const char * getPassword ()
Call * getCall ()

Protected Member Functions

void applyUserPreferences ()
void setSOAPHeaders ()
void setSOAPMethodAttributes ()
void setAuthorizationHeader ()

Protected Attributes

Call * m_pCall
vector< IHeaderBlock * > m_vSOAPHeaderBlocks
vector< IHeaderBlock
* >::iterator 
m_viCurrentSOAPHeaderBlock
vector< IAttribute * > m_vSOAPMethodAttributes
vector< IAttribute * >::iterator m_viCurrentSOAPMethodAttribute
SOAPTransport * m_pTransport
char * m_pcUsername
char * m_pcPassword


Detailed Description

This is the client Stub base class to be inherited by all stub classes genarated by WSDL2WS tool. This class acts as the interface between the users and the Axis C++ engine (client side). Programmer can use the API defined here to enrich the client application functionality. Setting transport properties, setting SOAP headers, setting connection timeout and specifying a proxy on the client stub is facilitated with this interface.

Author:
Samisa Abeysinghe (sabeysinghe@virtusa.com)

Roshan Weerasuriya (roshan@opensource.lk, roshanw@jkcsworld.com)

Susantha Kumara (susantha@opensource.lk, skumara@virtusa.com)


Constructor & Destructor Documentation

Stub::Stub const char *  pcEndPointURI,
AXIS_PROTOCOL_TYPE  eProtocol
 

Constructor.

Parameters:
pcEndPointURI End point URI of the service to connect to. e.g. http://localhost:8080/axis/services/echo
eProtocol The protocol that this stub should use to communicate with the endpoint. See AXIS_PROTOCOL_TYPE in GDefine.h for possible values for eProtocol.

virtual Stub::~Stub  )  [virtual]
 

Destructor.


Member Function Documentation

void Stub::applyUserPreferences  )  [protected]
 

Apply user set preferences to each call made on the Stub object. This method is required because Axis engine holds only part of the state with refereance to subsequent calls on the same Stub object. Foxing this approach would make the engine much more efficient.

IHeaderBlock* AXISCALL Stub::createSOAPHeaderBlock AxisChar *  pachLocalName,
AxisChar *  pachUri,
AxisChar *  pachPrefix
 

Create and add a SOAP header block to the Stub.

This will create a header block that would look like the following when serialized:

   <th:TestHeader xmlns:th="http://ws.apache.org/axisCppTest/">
   </th:TestHeader>
 

User must use the IHeaderBlock pointer returned and fill in the header structure. e.g. To make the SOAP header look like

 <SOAP-ENV:Header>
   <th:TestHeader xmlns:th="http://ws.apache.org/axisCppTest/">
       <credentials>
            <username>Test User</username>
            <password>Test Password</password>
       </credentials>
   </th:TestHeader>
 </SOAP-ENV:Header>
 
the following code segment coule be used
  IHeaderBlock *phb = ws.createSOAPHeaderBlock("TestHeader", 
                                   "http://ws.apache.org/axisCppTest/",
                                   "th");
  //create parent node
  BasicNode *parentNode = phb->createChild(ELEMENT_NODE);
  parentNode->setLocalName("Credentials");
  //create child node
  BasicNode *childNode = phb->createChild(ELEMENT_NODE);
  childNode->setLocalName("username");
  //create char node for value
  BasicNode *valueNode = phb->createChild(CHARACTER_NODE);
  valueNode->setValue("Test User");
  //buld node tree
  childNode->addChild(valueNode);
  parentNode->addChild(childNode);

  //add another node set
  childNode = phb->createChild(ELEMENT_NODE);
  childNode->setLocalName("password");

  valueNode = phb->createChild(CHARACTER_NODE);
  valueNode->setValue("Test Password");

  childNode->addChild(valueNode);
  parentNode->addChild(childNode);

  phb->addChild(parentNode);
 

Parameters:
pachLocalName Local tag name of the SOAP header. e.g. TestHeader
pachPrefix Prefix to be used in XML represenation of SOAP header e.g. th
pachUri Namespace URI to be used in SOAP header. e.g http://ws.apache.org/axisCppTestHeader/
Returns:
Pointer to the creater SOAP header block.

IHeaderBlock* AXISCALL Stub::createSOAPHeaderBlock AxisChar *  pachLocalName,
AxisChar *  pachUri
 

Create and add a SOAP header block to the Stub.

This will create a header block that would look like the following when serialized:

   <th:TestHeader xmlns:th="http://ws.apache.org/axisCppTest/">
   </th:TestHeader>
 

User must use the IHeaderBlock pointer returned and fill in the header structure. e.g. To make the SOAP header look like

 <SOAP-ENV:Header>
   <th:TestHeader xmlns:th="http://ws.apache.org/axisCppTest/">
       <credentials>
            <username>Test User</username>
            <password>Test Password</password>
       </credentials>
   </th:TestHeader>
 </SOAP-ENV:Header>
 
the following code segment coule be used
  IHeaderBlock *phb = ws.createSOAPHeaderBlock("TestHeader",
                                   "http://ws.apache.org/axisCppTest/");
  //Note: The prefix will be added automaticaly.
  //create parent node
  BasicNode *parentNode = phb->createChild(ELEMENT_NODE);
  parentNode->setLocalName("Credentials");
  //create child node
  BasicNode *childNode = phb->createChild(ELEMENT_NODE);
  childNode->setLocalName("username");
  //create char node for value
  BasicNode *valueNode = phb->createChild(CHARACTER_NODE);
  valueNode->setValue("Test User");
  //buld node tree
  childNode->addChild(valueNode);
  parentNode->addChild(childNode);

  //add another node set
  childNode = phb->createChild(ELEMENT_NODE);
  childNode->setLocalName("password");

  valueNode = phb->createChild(CHARACTER_NODE);
  valueNode->setValue("Test Password");

  childNode->addChild(valueNode);
  parentNode->addChild(childNode);

  phb->addChild(parentNode);
 

Parameters:
pachLocalName Local tag name of the SOAP header. e.g. TestHeader
pachUri Namespace URI to be used in SOAP header. e.g http://ws.apache.org/axisCppTestHeader/
Returns:
Pointer to the creater SOAP header block.

void Stub::deleteCurrentSOAPHeaderBlock  ) 
 

Deletes the SOAP header block currently pointed to by the iterator.

void Stub::deleteCurrentTransportProperty  ) 
 

Deletes the transport property key:value pair currently pointed to by the iterator.

void Stub::deleteCurrentTrasportProperty  )  [inline]
 

Deprecated:
To fix spelling mistake.
Deletes the transport property key:value pair currently pointed to by the iterator.

void Stub::deleteSOAPHeaderBlock IHeaderBlock pHeaderBlock  ) 
 

Deletes the given SOAP header block pointer from the current list of SOAP header blocks.

This method does a pointer comparison. It does not compare the contents within objects. Hence it is expected that either the pointer returned by the create method or by one of the iterator methods would be used with this method.

This method does not advance the iterator in line with the deletes done. In case you want to access the SOAP header blocks after using this method, it is advisable to reinitialize the iterator using getFirstSOAPHeaderBlock(); However you can use this method despite where the iterator is pointing currently.

Parameters:
pHeaderBlock Pointer of the header block to be deleted.

void Stub::deleteTransportProperty char *  pcKey,
unsigned int  uiOccurance = 1
 

Deletes the given occerance of the transport property key:value pair corresponding to the given key.

This method does not advance the iterator in line with the deletes done. In case you want to access the transport properties after using this method, it is advisable to reinitialize the iterator using getFirstTransportPropertyKey(); However you can use this method despite where the iterator is pointing currently.

Parameters:
pcKey Key of the transport property key:value pair to be deleted If the given key is not set currently, nothing will happen.
uiOccurance Which occerance of the key to be deleted, because there can be multiple values for the same key. Default is to delete the first occurance. Count starts from 1.

void Stub::deleteTrasportProperty char *  pcKey,
unsigned int  uiOccurance = 1
[inline]
 

Deprecated:
To fix spelling mistake.
Deletes the given occerance of the transport property key:value pair corresponding to the given key.

This method does not advance the iterator in line with the deletes done. In case you want to access the transport properties after using this method, it is advisable to reinitialize the iterator using getFirstTransportPropertyKey(); However you can use this method despite where the iterator is pointing currently.

Parameters:
pcKey Key of the transport property key:value pair to be deleted If the given key is not set currently, nothing will happen.
uiOccurance Which occerance of the key to be deleted, because there can be multiple values for the same key. Default is to delete the first occurance. Count starts from 1.

Call* Stub::getCall  )  [inline]
 

Call object of the Stub. This is the point of access to the internals of the Axis engine.

IHeaderBlock* Stub::getCurrentSOAPHeaderBlock  ) 
 

Accessor for SOAP header blocks

This method gives access to the SOAP header block pointer corresponding to the SOAP header block currently being pointed by SOAP header blocks iterator.

getFirstSOAPHeaderBlock() method must have been called at least once before this method is called. If not behaviour is undefined.

This method does not advance the iterator. Repeated calls always retuen the same key unless getNextSOAPHeaderBlock() is called in between.

Returns:
Current SOAP header block pointer. If there are no SOAP header block set or if iterator is at the end of the list, returns NULL.

const char* Stub::getCurrentTransportPropertyKey  ) 
 

Accessor for transport property keys.

This method gives access to the key corresponding to the transport key currently being pointed by transport property key iterator.

getFirstTransportPropertyKey() method must have been called at least once before this method is called. If not behaviour is undefined.

This method does not advance the iterator. Repeated calls always retuen the same key unless getNextTransportPropertyKey() is called in between.

Returns:
Current transport property key. If there are no transport properties set or if iterator is at the end of the list, returns NULL.

const char* Stub::getCurrentTransportPropertyValue  ) 
 

Accessor for transport property values.

This method gives access to the value corresponding to the transport key currently being pointed by transport property key iterator. As keys and values are treated as paires, access to the value field is based on the access to the key field.

getFirstTransportPropertyKey() method must have been called at least once before this method is called. If not behaviour is undefined.

This method does not advance the iterator. Repeated calls always retuen the same value unless getNextTransportPropertyKey() is called in between.

Returns:
Current transport property value. If there are no transport properties set or if iterator is at the end of the list, returns NULL.

const char* Stub::getCurrentTrasportPropertyKey  )  [inline]
 

Deprecated:
To fix spelling mistake.
Accessor for transport property keys.

This method gives access to the key corresponding to the transport key currently being pointed by transport property key iterator.

getFirstTransportPropertyKey() method must have been called at least once before this method is called. If not behaviour is undefined.

This method does not advance the iterator. Repeated calls always retuen the same key unless getNextTransportPropertyKey() is called in between.

Returns:
Current transport property key. If there are no transport properties set or if iterator is at the end of the list, returns NULL.

const char* Stub::getCurrentTrasportPropertyValue  )  [inline]
 

Deprecated:
To fix spelling mistake.
Accessor for transport property values.

This method gives access to the value corresponding to the transport key currently being pointed by transport property key iterator. As keys and values are treated as paires, access to the value field is based on the access to the key field.

getFirstTransportPropertyKey() method must have been called at least once before this method is called. If not behaviour is undefined.

This method does not advance the iterator. Repeated calls always retuen the same value unless getNextTransportPropertyKey() is called in between.

Returns:
Current transport property value. If there are no transport properties set or if iterator is at the end of the list, returns NULL.

IHeaderBlock* Stub::getFirstSOAPHeaderBlock  ) 
 

Iterator initiatior for SOAP header blocks

This method must be called first to initiate access to the list of SOAP header blocks.

Returns:
First SOAP header block pointer. If there are no SOAP header blocks set, returns NULL.

const char* Stub::getFirstTransportPropertyKey  ) 
 

Iterator initiatior for transport property keys

This method must be called first to initiate access to the list of transport property keys.

Returns:
First transport property key. If there are no transport properties set, returns NULL.

const char* Stub::getFirstTrasportPropertyKey  )  [inline]
 

Deprecated:
To fix spelling mistake.
Iterator initiatior for transport property keys

This method must be called first to initiate access to the list of transport property keys.

Returns:
First transport property key. If there are no transport properties set, returns NULL.

IHeaderBlock* Stub::getNextSOAPHeaderBlock  ) 
 

Iterator for SOAP header blocks

getFirstSOAPHeaderBlock() method must have been called at least once before this method is called. If not behaviour is undefined.

This method advances the iterator by one position. Repeated calls always retuen the next value.

Returns:
Next SOAP header block pointer. If there are no SOAP header blocks set or if iterator is at the end of the list, returns NULL.

const char* Stub::getNextTransportPropertyKey  ) 
 

Iterator for transport property keys

getFirstTransportPropertyKey() method must have been called at least once before this method is called. If not behaviour is undefined.

This method advances the iterator by one position. Repeated calls always retuen the next value.

Returns:
Next transport property key. If there are no transport properties set or if iterator is at the end of the list, returns NULL.

const char* Stub::getNextTrasportPropertyKey  )  [inline]
 

Deprecated:
To fix spelling mistake.
Iterator for transport property keys

getFirstTransportPropertyKey() method must have been called at least once before this method is called. If not behaviour is undefined.

This method advances the iterator by one position. Repeated calls always retuen the next value.

Returns:
Next transport property key. If there are no transport properties set or if iterator is at the end of the list, returns NULL.

const char* Stub::getPassword  ) 
 

Gets the password used for basic authentication

int Stub::getStatus  ) 
 

Get the status of the stub to see any error situation

const char* AXISCALL Stub::getTransportProperty const char *  key,
bool  response = true
 

Get a transport property.

Returns the value of a transport property based on a key.

Parameters:
key the property's name to search for
response set to true searches the response message for the property set to false searches the send message for the property
Returns:
the value of the property or NULL if it was not found.

AXIS_PROTOCOL_TYPE Stub::getTransportProtocol  ) 
 

Get transport protocol being used by the transport.

Returns:
Protocol used by transport

const char* Stub::getUsername  ) 
 

Gets the username used for basic authentication

void Stub::setAuthorizationHeader  )  [protected]
 

Set Authorization header for basic authentication

void AXISCALL Stub::setEndPoint const char *  pcEndPointURI  ) 
 

Set end point of service to connect to.

Parameters:
pcEndPointURI End point URI of the service to connect to. e.g. http://localhost:8080/axis/services/echo

void Stub::setHandlerProperty AxisChar *  name,
void *  value,
int  len
 

Sets a property that can be accessed from a handler.

Parameters:
name The name of the property
value The value of the property
len The length of the value

void Stub::setMaintainSession bool  bSession  ) 
 

Set whether to Maitain session with service ot not.

Parameters:
bSession - true is session should be maintained. False otherwise.

void Stub::setPassword const char *  pcPassword  ) 
 

Sets the password to be used for basic authentication

void Stub::setProxy const char *  pcProxyHost,
unsigned int  uiProxyPort
 

Set proxy server and port for transport.

Parameters:
pcProxyHost Host name of proxy server
uiProxyPort Port of proxy server

void Stub::setSOAPHeaders  )  [protected]
 

Set SOAP Headers stored in m_vSOAPHeaderBlock vector. Called by applyUserPreferences for each and every method invocation.

void Stub::setSOAPMethodAttributes  )  [protected]
 

Set SOAP method attributes stored in m_vSOAPMethodAttributes vector. Called by applyUserPreferences for each and every method invocation.

void AXISCALL Stub::setTransportProperty const char *  pcKey,
const char *  pcValue
 

Set transport property.

Handling the semantics of the headers is up to the user. The user has to make sure that the key:value paires passed to this method would make sense at transport level. The Stub class does not validate the key value paires to see if the properties make sense to the undelying transport.

Some example transport properties:
For HTTP: "Accept-Language: da, en-gb;q=0.8, en;q=0.7"
For SMTP: "Reply-To: user@apache.org"

Parameters:
pcKey Header name e.g. "Accept-Language". Note that the key is not tested for uniqueness. One can set several values to the same key and they all will appear in the outgoing transport header. e.g. If the method is called twise with (k,v1) and (k,v2) both k:v1 and k:v2 will appear in transport header as seperate properties.
pcValue Header value e.g. "da, en-gb;q=0.8, en;q=0.7"

void Stub::setTransportProtocol AXIS_PROTOCOL_TYPE  eProtocol  ) 
 

Set transport protocol to be used by the transport.

Parameters:
eProtocol - protocol to use

void Stub::setTransportTimeout const long  lSeconds  ) 
 

Set transport timeout.

Parameters:
lSeconds Timeout in seconds. If lSeconds is 0, then the transport will assume no timeout. Hence you want to reset a timeout already set use 0.

void AXISCALL Stub::setTrasportProperty const char *  pcKey,
const char *  pcValue
[inline]
 

Deprecated:
To fix spelling mistake.
Set transport property.

Handling the semantics of the headers is up to the user. The user has to make sure that the key:value paires passed to this method would make sense at transport level. The Stub class does not validate the key value paires to see if the properties make sense to the undelying transport.

Some example transport properties:
For HTTP: "Accept-Language: da, en-gb;q=0.8, en;q=0.7"
For SMTP: "Reply-To: user@apache.org"

Parameters:
pcKey Header name e.g. "Accept-Language". Note that the key is not tested for uniqueness. One can set several values to the same key and they all will appear in the outgoing transport header. e.g. If the method is called twise with (k,v1) and (k,v2) both k:v1 and k:v2 will appear in transport header as seperate properties.
pcValue Header value e.g. "da, en-gb;q=0.8, en;q=0.7"

void Stub::setUsername const char *  pcUsername  ) 
 

Sets the username to be used for basic authentication


Member Data Documentation

char* Stub::m_pcPassword [protected]
 

Password

char* Stub::m_pcUsername [protected]
 

Username

SOAPTransport* Stub::m_pTransport [protected]
 

Transport object

vector<IHeaderBlock *>::iterator Stub::m_viCurrentSOAPHeaderBlock [protected]
 

Transport keys iterator

vector<IAttribute*>::iterator Stub::m_viCurrentSOAPMethodAttribute [protected]
 

Transport keys iterator

vector< IHeaderBlock * > Stub::m_vSOAPHeaderBlocks [protected]
 

Vector of Header Blok pointers

vector<IAttribute*> Stub::m_vSOAPMethodAttributes [protected]
 

List of SOAPMethod Attributes


The documentation for this class was generated from the following file:
Generated on Sat Apr 9 15:11:58 2005 for AxisC++ by doxygen 1.3.8