wso2wsf::ServiceClient Class Reference
[Service Client]

Class ServiceClient The service client Class serves as the primary client interface for consuming services. The Service Client is associated to a repository which includes an axis2.xml. Service client can be constructed by passing a configuration context as well. Optionally, you can pass options during the initialization. You also can explicitly set options. Advanced features such as engaging and disengaging modules, adding and removing headers are supported. Some methods in the client may throw exceptions identified as Axis Faults. There are several ways of invoking a service operation, which are based on the concept of a message exchange pattern (MEP). The two basic MEPs supported by service client are out-only and out-in. Each MEP can be used in either blocking or non-blocking mode.Out-only MEP means one way message which does not expect a response. Out-In MEP means a request response message exchange. The operation invocations using the service client API are based on the XML-in/XML-out principle: both the payload to be sent to the service and the result from the service are in XML, represented in AXIOM. More...

#include <ServiceClient.h>

List of all members.

Public Member Functions

WSF_EXTERN ServiceClient (std::string endpoint_address)
WSF_EXTERN ServiceClient (std::string repo_home, std::string endpoint_address)
WSF_EXTERN ServiceClient (const axis2_conf_ctx_t *conf_ctx, std::string endpoint_address)
virtual WSF_EXTERN ~ServiceClient ()
WSF_EXTERN bool isValidClient ()
WSF_EXTERN bool setOptions (Options *options)
WSF_EXTERN OMElementgetLastSOAPFault ()
WSF_EXTERN OptionsgetOptions ()
WSF_EXTERN bool engageModule (std::string module_name)
WSF_EXTERN bool disengageModule (std::string module_name)
WSF_EXTERN bool addHeader (OMElement *header)
WSF_EXTERN void removeAllHeaders ()
WSF_EXTERN bool setPolicy (NeethiPolicy *policy)
WSF_EXTERN bool send (OMElement *payload, std::string action) throw (WSFault)
WSF_EXTERN bool send (OMElement *payload, std::string operation, std::string action) throw (WSFault)
WSF_EXTERN bool send (OMElement *payload, bool robust, std::string operation, std::string action) throw (WSFault)
WSF_EXTERN bool send (OMElement *payload, bool robust, std::string action) throw (WSFault)
WSF_EXTERN OMElementrequest (OMElement *payload, std::string action) throw (WSFault)
WSF_EXTERN OMElementrequest (OMElement *payload, ICallback *callback, std::string operation, std::string action) throw (WSFault)
WSF_EXTERN OMElementrequest (OMElement *payload, ICallback *callback, std::string action) throw (WSFault)
WSF_EXTERN OMElementrequest (OMElement *payload, std::string operation, std::string action) throw (WSFault)
WSF_EXTERN OMElementgetLastResponseSoapEnvelope ()
WSF_EXTERN std::string getLastResponseSoapEnvelopeString ()
WSF_EXTERN axis2_svc_client_t * getAxis2SvcClient ()
WSF_EXTERN axis2_conf_ctx_t * getAxis2ConfCtx (std::string repositoryPath)
WSF_EXTERN bool setProxy (std::string proxyHost, std::string proxyPort)
WSF_EXTERN bool setProxyWithAuth (std::string proxyHost, std::string proxyPort, std::string username, std::string password)
WSF_EXTERN bool getHttpAuthRequired ()
WSF_EXTERN bool getProxyAuthRequired ()
WSF_EXTERN MessageContextgetInMessageContext ()
WSF_EXTERN MessageContextgetOutMessageContext ()
WSF_EXTERN bool close ()

Friends

class Stub


Detailed Description

Class ServiceClient The service client Class serves as the primary client interface for consuming services. The Service Client is associated to a repository which includes an axis2.xml. Service client can be constructed by passing a configuration context as well. Optionally, you can pass options during the initialization. You also can explicitly set options. Advanced features such as engaging and disengaging modules, adding and removing headers are supported. Some methods in the client may throw exceptions identified as Axis Faults. There are several ways of invoking a service operation, which are based on the concept of a message exchange pattern (MEP). The two basic MEPs supported by service client are out-only and out-in. Each MEP can be used in either blocking or non-blocking mode.Out-only MEP means one way message which does not expect a response. Out-In MEP means a request response message exchange. The operation invocations using the service client API are based on the XML-in/XML-out principle: both the payload to be sent to the service and the result from the service are in XML, represented in AXIOM.

Constructor & Destructor Documentation

WSF_EXTERN wso2wsf::ServiceClient::ServiceClient ( std::string  endpoint_address  ) 

Create a Service Client which is associated with the default repository. The service client assumes that WSFCPP_HOME environment variable is defined to point to the repo.

Parameters:
endpoint_address endpoint address which would be invoked using this service Client Object.

WSF_EXTERN wso2wsf::ServiceClient::ServiceClient ( std::string  repo_home,
std::string  endpoint_address 
)

Create a Service Client from the repository.

Parameters:
repo_home location of the repository.
endpoint_address endpoint address to be used.

WSF_EXTERN wso2wsf::ServiceClient::ServiceClient ( const axis2_conf_ctx_t *  conf_ctx,
std::string  endpoint_address 
)

Create a service client from a configuration context.

Parameters:
conf_ctx pointer to configuration context.
endpoint_address endpoint address to be used.

virtual WSF_EXTERN wso2wsf::ServiceClient::~ServiceClient (  )  [virtual]

Destructor frees resources.


Member Function Documentation

WSF_EXTERN bool wso2wsf::ServiceClient::addHeader ( OMElement header  ) 

Adds an XML element as a header to be sent to the server side. This allows users to go beyond the usual XML-in/XML-out pattern, and send custom SOAP headers. Once added, service client owns the header and will clean up when the service client is freed.

Parameters:
header om node representing the SOAP header in XML.
Returns:
true on success or false on failure.

WSF_EXTERN bool wso2wsf::ServiceClient::disengageModule ( std::string  module_name  ) 

Dis-engages the named module. Dis-engaging a module on a service client ensures that the axis2_engine would not invoke the named module when sending and receiving messages.

Parameters:
module_name name of the module to be dis-engaged.
Returns:
true on success or false on failure.

WSF_EXTERN bool wso2wsf::ServiceClient::engageModule ( std::string  module_name  ) 

Engages the named module. The engaged modules extend the message processing when consuming services. Modules help to apply QoS norms in messaging. Once a module is engaged to a service client, the axis2_engine makes sure to invoke the module for all the interactions between the client and the service.

Parameters:
module_name name of the module to be engaged.
Returns:
true on success or false on failure.

WSF_EXTERN axis2_conf_ctx_t* wso2wsf::ServiceClient::getAxis2ConfCtx ( std::string  repositoryPath  ) 

Returns the axis2_conf_ctx_t which can be used to create a configuration context once and pass it when creating multiple service clients.

WSF_EXTERN axis2_svc_client_t* wso2wsf::ServiceClient::getAxis2SvcClient (  ) 

Returns the axis2_svc_client used within ServiceClient.

WSF_EXTERN bool wso2wsf::ServiceClient::getHttpAuthRequired (  ) 

Gets the boolean value indicating whether HTTP Authentication is required.

Returns:
true if HTTP authentication is required, false otherwise.

WSF_EXTERN MessageContext* wso2wsf::ServiceClient::getInMessageContext (  ) 

Returns the MessageContext object used in the inflow of the Engine.

Returns:
MessageContext

WSF_EXTERN OMElement* wso2wsf::ServiceClient::getLastResponseSoapEnvelope (  ) 

Gets the last response SOAP envelope.

Returns:
pointer to SOAP envelope that was returned as a result when request was called last time.

WSF_EXTERN std::string wso2wsf::ServiceClient::getLastResponseSoapEnvelopeString (  ) 

Gets the last response SOAP envelope.

Returns:
SOAP envelope that was returned as a result when request was called last time, as a String.

WSF_EXTERN OMElement* wso2wsf::ServiceClient::getLastSOAPFault (  ) 

Method to retrieve the last SOAP fault that resulted after invoking a send or a request operation.

Returns:
returns an OMElement containing the SOAP fault.

WSF_EXTERN Options* wso2wsf::ServiceClient::getOptions (  ) 

Gets options used by service client.

Returns:
a pointer to the options struct if options set, else NULL. Returns a reference, not a cloned copy.

WSF_EXTERN MessageContext* wso2wsf::ServiceClient::getOutMessageContext (  ) 

Returns the MessageContext object used in the outflow of the engine. This method is only valid when calling after a service invocation call using ServiceClient::request or ServiceClient::send methods.

Returns:
MessageContext. Freeing the returned MessageContext must be freed by the user. Before freeing the message context use

WSF_EXTERN bool wso2wsf::ServiceClient::getProxyAuthRequired (  ) 

Gets the boolean value indicating whether Proxy Authentication is required.

Returns:
true if proxy authentication is required and false otherwise.

WSF_EXTERN bool wso2wsf::ServiceClient::isValidClient (  ) 

Checks whether the ServiceClient got properly initialized or not. If the service client is properly initialized, it will return true and will return false otherwise.

Returns:
true on success, false otherwise.

WSF_EXTERN void wso2wsf::ServiceClient::removeAllHeaders (  ) 

Removes all the headers added to service client.

Exceptions:
AxisFault an exception is thrown if something goes wrong while removing headers.

WSF_EXTERN OMElement* wso2wsf::ServiceClient::request ( OMElement payload,
std::string  operation,
std::string  action 
) throw (WSFault)

Sends XML request and receives XML response. This method is used to interact with a service operation whose MEP is In-Out.

Parameters:
operation operation name. "" is equivalent to an operation name of "__OPERATION_OUT_IN__".
payload pointer to OM node representing the XML payload to be sent.
Returns:
pointer to OM node representing the XML response. The caller owns the returned node.
Parameters:
action soap/addressing action.
Exceptions:
AxisFault an exception is thrown if something goes wrong while creating a config context.

WSF_EXTERN OMElement* wso2wsf::ServiceClient::request ( OMElement payload,
ICallback callback,
std::string  action 
) throw (WSFault)

Sends XML request and receives XML response. This method is used to interact with a service operation whose MEP is In-Out.

Parameters:
payload pointer to OM node representing the XML payload to be sent.
callback pointer to callback object used to capture response, in a non-blocking operation, NULL represents a blocking operation.
Returns:
pointer to OM node representing the XML response. The caller owns the returned node.
Parameters:
action soap/addressing action.
Exceptions:
AxisFault an exception is thrown if something goes wrong while creating a config context.

WSF_EXTERN OMElement* wso2wsf::ServiceClient::request ( OMElement payload,
ICallback callback,
std::string  operation,
std::string  action 
) throw (WSFault)

Sends XML request and receives XML response. This method is used to interact with a service operation whose MEP is In-Out.

Parameters:
operation operation name. "" is equivalent to an operation name of "__OPERATION_OUT_IN__".
payload pointer to OM node representing the XML payload to be sent.
callback pointer to callback object used to capture response, in a non-blocking operation, NULL represents a blocking operation.
Returns:
pointer to OM node representing the XML response. The caller owns the returned node.
Parameters:
action soap/addressing action.
Exceptions:
AxisFault an exception is thrown if something goes wrong while creating a config context.

WSF_EXTERN OMElement* wso2wsf::ServiceClient::request ( OMElement payload,
std::string  action 
) throw (WSFault)

Sends XML request and receives XML response. This method is used to interact with a service operation whose MEP is In-Out.

Parameters:
payload pointer to OM node representing the XML payload to be sent
Returns:
pointer to OM node representing the XML response. The caller owns the returned node.
Parameters:
action soap/addressing action.
Exceptions:
AxisFault an exception is thrown if something goes wrong while creating a config context.

WSF_EXTERN bool wso2wsf::ServiceClient::send ( OMElement payload,
bool  robust,
std::string  action 
) throw (WSFault)

This method is used to interact with a service operation whose MEP is Out-Only, or Robust Out-Only. That is, there is an opportunity to get an error from the service via this method; one may still get client-side errors, such as host unknown etc.

Parameters:
payload pointer to OM node representing the XML payload to be sent.
robust true represents a robust operation, and false represents an ordinary send operation.
action soap/addressing action.
Returns:
true if no soap fault was received, and false if received.
Exceptions:
AxisFault an exception is thrown if something goes wrong while creating a config context.

WSF_EXTERN bool wso2wsf::ServiceClient::send ( OMElement payload,
bool  robust,
std::string  operation,
std::string  action 
) throw (WSFault)

This method is used to interact with a service operation whose MEP is Out-Only, or Robust Out-Only. That is, there is an opportunity to get an error from the service via this method; one may still get client-side errors, such as host unknown etc.

Parameters:
operation operation name. "" is equivalent to an operation name of "__OPERATION_OUT_ONLY__".
payload pointer to OM node representing the XML payload to be sent.
robust true represents a robust operation, and false represents an ordinary send operation.
action soap/addressing action.
Returns:
true if no soap fault was received, and false if received.
Exceptions:
AxisFault an exception is thrown if something goes wrong while creating a config context.

WSF_EXTERN bool wso2wsf::ServiceClient::send ( OMElement payload,
std::string  operation,
std::string  action 
) throw (WSFault)

This method is used to interact with a service operation whose MEP is Robust Out-Only. That is, there is an opportunity to get an error from the service via this method; one may still get client-side errors, such as host unknown etc.

Parameters:
payload pointer to OM node representing the XML payload to be sent.
operation operation name. "" is equivalent to an operation name of "__OPERATION_OUT_ONLY__".
action soap/addressing action.
Returns:
true if no soap fault was received, and false if received.
Exceptions:
AxisFault an exception is thrown if something goes wrong while creating a config context.

WSF_EXTERN bool wso2wsf::ServiceClient::send ( OMElement payload,
std::string  action 
) throw (WSFault)

This method is used to interact with a service operation whose MEP is Robust Out-Only. That is, there is an opportunity to get an error from the service via this method; one may still get client-side errors, such as host unknown etc.

Parameters:
payload pointer to OM node representing the XML payload to be sent.
action soap/addressing action.
Returns:
true if no soap fault was received, and false if received.
Exceptions:
AxisFault an exception is thrown if something goes wrong while creating a config context.

WSF_EXTERN bool wso2wsf::ServiceClient::setOptions ( Options options  ) 

Sets the options to be used by service client.

Parameters:
options pointer to options struct to be set.
Returns:
true on success or false on failure.

WSF_EXTERN bool wso2wsf::ServiceClient::setPolicy ( NeethiPolicy policy  ) 

Set the given policy object to the description hierarchy.

Parameters:
policy pointer to a policy struct.
Returns:
true on success or false on failure.

WSF_EXTERN bool wso2wsf::ServiceClient::setProxy ( std::string  proxyHost,
std::string  proxyPort 
)

Configure Service client with a proxy.

Parameters:
proxyHost proxy host
proxyPort proxy port

WSF_EXTERN bool wso2wsf::ServiceClient::setProxyWithAuth ( std::string  proxyHost,
std::string  proxyPort,
std::string  username,
std::string  password 
)

Set proxy with authentication

Parameters:
proxyHost Proxy host
proxyPort proxy port
username username required for proxy authentication
password password required for proxy authentication


The documentation for this class was generated from the following file:

Generated on Wed Oct 14 00:43:26 2009 for WSF/CPP by  doxygen 1.5.7.1