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.hpp>

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)
const char *AXISCALL getTransportProperty (const char *key, bool response=true)
const char * getFirstTransportPropertyKey (bool response=true)
const char * getNextTransportPropertyKey (bool response=true)
const char * getCurrentTransportPropertyKey (bool response=true)
const char * getCurrentTransportPropertyValue (bool response=true)
void deleteCurrentTransportProperty (bool response=true)
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 (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 ()
void setProxyUsername (const char *pcProxyUsername)
void setProxyPassword (const char *pcProxyPassword)
const char * getProxyUsername ()
const char * getProxyPassword ()
Call * getCall ()
ISoapAttachment * createSoapAttachment ()
void AXISCALL SetSecure (char *,...)

Protected Methods

void applyUserPreferences ()
void includeSecure ()
void setSOAPHeaders ()
void setAuthorizationHeader ()
void setProxyAuthorizationHeader ()

Protected Attributes

Call * m_pCall
vector< IHeaderBlock * > m_vSOAPHeaderBlocks
vector< IHeaderBlock
* >::iterator 
m_viCurrentSOAPHeaderBlock
SOAPTransport * m_pTransport
char * m_pcUsername
char * m_pcPassword
char * m_proxyUsername
char * m_proxyPassword


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.

ISoapAttachment* Stub::createSoapAttachment  
 

Creates an ISoapAttachment which represents an attachment. The ISoapAttachment should be passed as an attachmment parameter to a web service. The storage associated with the ISoapAttachment will be automatically deleted by Axis C++ if it is passed as a parameter to a web service.

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 could 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 could 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 bool    response = true
 

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

Parameters:
response  true if it's the response property or false for the request

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 occurance 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.

NOTE: This method is used to delete individual cookies e.g. deleteTransportProperty("myCookie") will delete the cookie "myCookie" only. This method can also be used to delete all Cookies by doing deleteTransportProperty("Cookie").

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 bool    response = true
 

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.

Parameters:
response  whether the response or outgoing message is being used.
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 bool    response = true
 

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 pairs, 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. It must be called with the same "response" value as used here. 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.

Parameters:
response  whether the response or outgoing message should be used
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 bool    response = true
 

Iterator initiatior for transport property keys

This method must be called first to initiate access to the list of transport property keys. If you initialise e.g. response then ensure that you call this method for outgoing message too if you want the outgoing message in future calls.

Parameters:
response  whether the response or outgoing message is being used.
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 bool    response = true
 

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.

Parameters:
response  whether the response or outgoing message should be used
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

const char* Stub::getProxyPassword  
 

Gets the password used for Proxy authentication

const char* Stub::getProxyUsername  
 

Gets the username used for Proxy 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::includeSecure   [protected]
 

Apply SSL configuration properties.

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 Maintain session with service ot not.

Parameters:
bSession  - true if 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::setProxyAuthorizationHeader   [protected]
 

Set Authorization header for Proxy authentication

void Stub::setProxyPassword const char *    pcProxyPassword
 

Sets the password to be used for Proxy authentication

void Stub::setProxyUsername const char *    pcProxyUsername
 

Sets the username to be used for Proxy authentication

void AXISCALL Stub::SetSecure char *   ,
...   
 

Set SSL configuration properties.

void Stub::setSOAPHeaders   [protected]
 

Set SOAP Headers stored in m_vSOAPHeaderBlock 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 HTTP: "Cookie: sessiontoken=123345456;"
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. The exception to this is "Cookie" where multiple cookie values will only result in one "Cookie:" header being sent as is correct for HTTP.
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 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 Stub::setUsername const char *    pcUsername
 

Sets the username to be used for basic authentication


Member Data Documentation

Call* Stub::m_pCall [protected]
 

Call object

char* Stub::m_pcPassword [protected]
 

Password

char* Stub::m_pcUsername [protected]
 

Username

char* Stub::m_proxyPassword [protected]
 

proxy Password

char* Stub::m_proxyUsername [protected]
 

proxy Username

SOAPTransport* Stub::m_pTransport [protected]
 

Transport object

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

Transport keys iterator

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

Vector of Header Block pointers


The documentation for this class was generated from the following file:
Generated on Fri Mar 3 01:12:36 2006 for AxisC++ by doxygen1.2.18