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 * 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 setSOAPMethodAttribute (const AxisChar *pLocalname, const AxisChar *pPrefix, const AxisChar *pValue)
void setSOAPMethodAttribute (const AxisChar *pLocalname, const AxisChar *pPrefix, const AxisChar *pUri, const AxisChar *pValue)
IAttributegetFirstSOAPMethodAttribute ()
IAttributegetNextSOAPMethodAttribute ()
IAttributegetCurrentSOAPMethodAttribute ()
void deleteCurrentSOAPMethodAttribute ()
void deleteSOAPMethodAttribute (IAttribute *pAttribute)
void setTransportTimeout (const long lSeconds)
int getStatus ()
const AxisChar *AXISCALL getNamespacePrefix (const AxisChar *pNamespace)
void setMaintainSession (bool bSession)
void setTransportProtocol (AXIS_PROTOCOL_TYPE eProtocol)
AXIS_PROTOCOL_TYPE getTransportProtocol ()

Protected Member Functions

void applyUserPreferences ()
void setSOAPHeaders ()
void setSOAPMethodAttributes ()
Call * getCall ()

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


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::deleteCurrentSOAPMethodAttribute  ) 
 

Deletes the SOAP method attribute 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::deleteSOAPMethodAttribute IAttribute pAttribute  ) 
 

Deletes the given occerance of the SOAP method attribute from the current list of SOAP method attributes

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 method attributes after using this method, it is advisable to reinitialize the iterator using getFirstSOAPMethodAttribute(); However you can use this method despite where the iterator is pointing currently.

Parameters:
pAttribute Pointer of Attribute 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, protected]
 

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.

IAttribute* Stub::getCurrentSOAPMethodAttribute  ) 
 

Accessor for SOAP method attributes

This method gives access to the SOAP method attribute pointer corresponding to the SOAP method attribute currently being pointed by SOAP method attributes iterator.

getFirstSOAPMethodAttribute() 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 getNextSOAPMethodAttribute() is called in between.

Returns:
Current SOAP method attribute pointer. If there are no SOAP method attribute 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.

IAttribute* Stub::getFirstSOAPMethodAttribute  ) 
 

Iterator initiatior for SOAP method attributes

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

Returns:
First SOAP method attribute pointer. If there are no SOAP method attributes 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.

const AxisChar* AXISCALL Stub::getNamespacePrefix const AxisChar *  pNamespace  ) 
 

Get a namespace prefix for a given namespace URI

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.

IAttribute* Stub::getNextSOAPMethodAttribute  ) 
 

Iterator for SOAP method attributes

getFirstSOAPMethodAttribute() 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 method attribute pointer. If there are no SOAP method attributes 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.

int Stub::getStatus  ) 
 

Get the status of the stub to see any error situation

AXIS_PROTOCOL_TYPE Stub::getTransportProtocol  ) 
 

Get transport protocol being used by the transport.

Returns:
Protocol used by transport

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::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::setSOAPMethodAttribute const AxisChar *  pLocalname,
const AxisChar *  pPrefix,
const AxisChar *  pUri,
const AxisChar *  pValue
 

Sets a Attribute to the SOAPMethod, using the given Attribute data.

Parameters:
pLocalname The local name of the Attribute.
pPrefix The prefix of the Attribute.
pUri The namespace uri of the Attribute.
pValue The value of the Attribute.

void Stub::setSOAPMethodAttribute const AxisChar *  pLocalname,
const AxisChar *  pPrefix,
const AxisChar *  pValue
 

Sets a Attribute to the SOAPMethod, using the given Attribute data.

Parameters:
pLocalname The local name of the Attribute.
pPrefix The prefix of the Attribute.
pValue The value of the Attribute.

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"


Member Data Documentation

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 Tue Feb 8 14:34:20 2005 for AxisC++ by doxygen 1.3.8