# 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 OMElement * | getLastSOAPFault ()
WSF_EXTERN Options * | getOptions ()
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 OMElement * | request (OMElement *payload, std::string action) throw (WSFault)
WSF_EXTERN OMElement * | request (OMElement *payload, ICallback *callback, std::string operation, std::string action) throw (WSFault)
WSF_EXTERN OMElement * | request (OMElement *payload, ICallback *callback, std::string action) throw (WSFault)
WSF_EXTERN OMElement * | request (OMElement *payload, std::string operation, std::string action) throw (WSFault)
WSF_EXTERN OMElement * | getLastResponseSoapEnvelope ()
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 MessageContext * | getInMessageContext ()
WSF_EXTERN MessageContext * | getOutMessageContext ()
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:

- ServiceClient.h