Main Page   Class Hierarchy   Compound List   File List   Compound Members   File Members   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.h>

List of all members.

Public Methods

 Stub (const char *pcEndPointURI, AXIS_PROTOCOL_TYPE eProtocol)
virtual ~Stub ()
void AXISCALL setEndPoint (const char *pcEndPointURI)
void AXISCALL setTransportProperty (const char *pcKey, const char *pcValue)
char * getFirstTrasportPropertyKey ()
char * getNextTrasportPropertyKey ()
char * getCurrentTrasportPropertyKey ()
char * getCurrentTrasportPropertyValue ()
void deleteCurrentTrasportProperty ()
void deleteTrasportProperty (char *pcKey, unsigned int uiOccurance=1)
IHeaderBlock *AXISCALL createSOAPHeaderBlock (AxisChar *pachLocalName, AxisChar *pachUri)
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)
AttributegetFirstSOAPMethodAttribute ()
AttributegetNextSOAPMethodAttribute ()
AttributegetCurrentSOAPMethodAttribute ()
void deleteCurrentSOAPMethodAttribute ()
void deleteSOAPMethodAttribute (Attribute *pAttribute)
void setTransportTimeout (const long lSeconds)
int getStatus ()
const AxisChar *AXISCALL getNamespacePrefix (const AxisChar *pNamespace)

Protected Methods

void applyUserPreferences ()
void setTransportProperties ()
void setSOAPHeaders ()
void setSOAPMethodAttributes ()
void setTransportTimeout ()

Protected Attributes

Call * m_pCall
vector< char * > m_vKeys
vector< char * >::iterator m_viCurrentKey
vector< char * > m_vValues
vector< char * >::iterator m_viCurrentValue
vector< IHeaderBlock * > m_vSOAPHeaderBlocks
vector< IHeaderBlock
* >::iterator 
m_viCurrentSOAPHeaderBlock
vector< Attribute * > m_vSOAPMethodAttributes
vector< Attribute * >::iterator m_viCurrentSOAPMethodAttribute
long m_lTimeoutSeconds


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]
 

Default Constructor. /** 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
 

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", "th",
                                   "http://ws.apache.org/axisCppTest/");
  //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.

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::deleteCurrentTrasportProperty  
 

Deletes the trasport 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 Attribute   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::deleteTrasportProperty char *    pcKey,
unsigned int    uiOccurance = 1
 

Deletes the given occerance of the trasport 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 trasport properties after using this method, it is advisable to reinitialize the iterator using getFirstTrasportPropertyKey(); However you can use this method despite where the iterator is pointing currently.

Parameters:
pcKey  Key of the trasport 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.

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.

Attribute* 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.

char* Stub::getCurrentTrasportPropertyKey  
 

Accessor for trasport property keys.

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

getFirstTrasportPropertyKey() 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 getNextTrasportPropertyKey() is called in between.

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

char* Stub::getCurrentTrasportPropertyValue  
 

Accessor for trasport property values.

This method gives access to the value corresponding to the trasport key currently being pointed by trasport 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.

getFirstTrasportPropertyKey() 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 getNextTrasportPropertyKey() is called in between.

Returns:
Current transport property value. If there are no trasport 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.

Attribute* 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.

char* Stub::getFirstTrasportPropertyKey  
 

Iterator initiatior for trasport 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 trasport 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.

Attribute* 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.

char* Stub::getNextTrasportPropertyKey  
 

Iterator for trasport property keys

getFirstTrasportPropertyKey() 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 trasport 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

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::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 Stub::setTransportProperties   [protected]
 

Set transport properties stored in m_vKeys and m_vValues vectors. 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 trasport level. The Stub class does not validate the key value paires to see if the properties make sense to the undelying trasport.

Some example trasport 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 trasport header. e.g. If the method is called twise with (k,v1) and (k,v2) both k:v1 and k:v2 will appear in trasport header as seperate properties.
pcValue  Header value e.g. "da, en-gb;q=0.8, en;q=0.7"

void Stub::setTransportTimeout   [protected]
 

Set transport timeout stored in mm_lTimeoutSeconds Called by applyUserPreferences for each and every method invocation.

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.


Member Data Documentation

long Stub::m_lTimeoutSeconds [protected]
 

Timeout in seconds

Call* Stub::m_pCall [protected]
 

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

vector<char*>::iterator Stub::m_viCurrentKey [protected]
 

Trasport keys iterator

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

Trasport keys iterator

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

Trasport keys iterator

vector<char*>::iterator Stub::m_viCurrentValue [protected]
 

Trasport keys iterator

vector< char *> Stub::m_vKeys [protected]
 

Trasport property keys

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

Vector of Header Blok pointers

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

List of SOAPMethod Attributes

vector< char *> Stub::m_vValues [protected]
 

Trasport property values


The documentation for this class was generated from the following file:
Generated on Tue Jun 29 09:27:58 2004 for AxisC++ by doxygen1.2.18