---

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)
virtual	~Stub ()
void AXISCALL	setEndPoint (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 *pachPrefix, AxisChar *pachUri)
IHeaderBlock *	getFirstSOAPHeaderBlock ()
IHeaderBlock *	getNextSOAPHeaderBlock ()
IHeaderBlock *	getCurrentSOAPHeaderBlock ()
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)
Attribute *	getFirstSOAPMethodAttribute ()
Attribute *	getNextSOAPMethodAttribute ()
Attribute *	getCurrentSOAPMethodAttribute ()
void	deleteCurrentSOAPMethodAttribute ()
void	deleteSOAPMethodAttribute (Attribute *pAttribute)
void	setTransportTimeout (const long lSeconds)
int	getStatus ()
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)

---

Constructor & Destructor Documentation

Stub::Stub (  const char *    pcEndPointURI )

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

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 *    pachPrefix, 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.

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

• Stub.h

---