org.apache.axis2.client
Class ServiceClient

java.lang.Object
  org.apache.axis2.client.ServiceClient

Direct Known Subclasses:

MexClient

public class ServiceClient

extends java.lang.Object

Client access to a service. Each instance of this class is associated with a particular AxisService, and the methods support operations using that service. Options instances are used to configure various aspects of the service access.

Field Summary

static javax.xml.namespace.QName	ANON_OUT_IN_OP Operation name used for an anonymous in-out operation (meaning we sent a message and receive a response, equivalent to a WSDL In-Out operation).
static javax.xml.namespace.QName	ANON_OUT_ONLY_OP Operation name used for an anonymous out-only operation (meaning we send a message with no response allowed from the service, equivalent to a WSDL In-Only operation).
static javax.xml.namespace.QName	ANON_ROBUST_OUT_ONLY_OP Operation name used for an anonymous robust-out-only operation (meaning we send a message, with the only possible response a fault, equivalent to a WSDL Robust-In-Only operation).
static java.lang.String	ANON_SERVICE Base name used for a service created without an existing configuration.

Constructor Summary

ServiceClient()
Create a service client by assuming an anonymous service and any other necessary information.

ServiceClient(ConfigurationContext configContext, AxisService axisService)
Create a service client configured to work with a specific AxisService.

ServiceClient(ConfigurationContext configContext, javax.wsdl.Definition wsdl4jDefinition, javax.xml.namespace.QName wsdlServiceName, java.lang.String portName)
This is WSDL4J based constructor to configure the Service Client/ We are going to make this policy aware

ServiceClient(ConfigurationContext configContext, java.net.URL wsdlURL, javax.xml.namespace.QName wsdlServiceName, java.lang.String portName)
Create a service client for WSDL service identified by the QName of the wsdl:service element in a WSDL document.

Method Summary

void	addHeader(org.apache.axiom.om.OMElement header) Add an arbitrary XML element as a header to be sent with outgoing messages.
void	addHeader(org.apache.axiom.soap.SOAPHeaderBlock header) Add SOAP Header to be sent with outgoing messages.
void	addHeadersToEnvelope(org.apache.axiom.soap.SOAPEnvelope envelope) Add all configured headers to a SOAP envelope.
void	addStringHeader(javax.xml.namespace.QName headerName, java.lang.String headerText) Add a simple header consisting of some text (and a header name; duh) to be sent with interactions.
void	cleanup() Clean up configuration created with this client.
OperationClient	createClient(javax.xml.namespace.QName operationQName) Create an operation client with the appropriate message exchange pattern (MEP).
void	disengageModule(javax.xml.namespace.QName moduleName) Disengage a module for this service client
void	disengageModule(java.lang.String moduleName) Disengage a module for this service client
void	engageModule(javax.xml.namespace.QName moduleName) Engage a module for this service client.
void	engageModule(java.lang.String moduleName) Engage a module for this service client.
protected void	finalize()
void	fireAndForget(org.apache.axiom.om.OMElement elem) Directly invoke an anonymous operation with an In-Only MEP.
void	fireAndForget(javax.xml.namespace.QName operation, org.apache.axiom.om.OMElement elem) Directly invoke a named operation with an In-Only MEP.
AxisService	getAxisService() Return the AxisService this is a client for.
OperationContext	getLastOperationContext() Gets the last OperationContext
EndpointReference	getMyEPR(java.lang.String transport) Get the endpoint reference for this client using a particular transport.
Options	getOptions() Get the basic client configuration from this service interaction.
Options	getOverrideOptions() Get the client configuration used to override the normal options set by an operation client.
ServiceContext	getServiceContext() Get the service context.
EndpointReference	getTargetEPR() Get the endpoint reference for the service.
void	removeHeaders() Remove all headers for outgoing message.
org.apache.axiom.om.OMElement	sendReceive(org.apache.axiom.om.OMElement elem) Directly invoke an anonymous operation with an In-Out MEP.
org.apache.axiom.om.OMElement	sendReceive(javax.xml.namespace.QName operationQName, org.apache.axiom.om.OMElement xmlPayload) Directly invoke a named operationQName with an In-Out MEP.
void	sendReceiveNonBlocking(org.apache.axiom.om.OMElement elem, Callback callback) Directly invoke an anonymous operation with an In-Out MEP without waiting for a response.
void	sendReceiveNonBlocking(javax.xml.namespace.QName operation, org.apache.axiom.om.OMElement elem, Callback callback) Directly invoke a named operation with an In-Out MEP without waiting for a response.
void	sendRobust(org.apache.axiom.om.OMElement elem) Directly invoke an anonymous operation with a Robust In-Only MEP.
void	sendRobust(javax.xml.namespace.QName operation, org.apache.axiom.om.OMElement elem) Directly invoke a named operation with a Robust In-Only MEP.
void	setAxisService(AxisService axisService) Configure the ServiceClient to interact with the Web service described by the specified AxisService object.
void	setCachingOperationContext(boolean cachingOpContext) Sets whether or not to cache the last OperationContext
void	setOptions(Options options) Set the basic client configuration related to this service interaction.
void	setOverrideOptions(Options overrideOptions) Set a client configuration to override the normal options used by an operation client.
void	setTargetEPR(EndpointReference targetEpr) Set the endpoint reference for the service.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ANON_SERVICE

public static final java.lang.String ANON_SERVICE

Base name used for a service created without an existing configuration.

See Also:

Constant Field Values

ANON_OUT_ONLY_OP

public static final javax.xml.namespace.QName ANON_OUT_ONLY_OP

Operation name used for an anonymous out-only operation (meaning we send a message with no response allowed from the service, equivalent to a WSDL In-Only operation).

ANON_ROBUST_OUT_ONLY_OP

public static final javax.xml.namespace.QName ANON_ROBUST_OUT_ONLY_OP

Operation name used for an anonymous robust-out-only operation (meaning we send a message, with the only possible response a fault, equivalent to a WSDL Robust-In-Only operation).

ANON_OUT_IN_OP

public static final javax.xml.namespace.QName ANON_OUT_IN_OP

Operation name used for an anonymous in-out operation (meaning we sent a message and receive a response, equivalent to a WSDL In-Out operation).

Constructor Detail

ServiceClient

public ServiceClient(ConfigurationContext configContext,
                     AxisService axisService)
              throws AxisFault

Create a service client configured to work with a specific AxisService. If this service is already in the world that's handed in (in the form of a ConfigurationContext) then I will happily work in it. If not I will create a small little virtual world and live there.

Parameters:

configContext - The configuration context under which this service lives (may be null, in which case a new local one will be created)

axisService - The service for which this is the client (may be null, in which case an anonymous service will be created)

Throws:

AxisFault - if something goes wrong while creating a config context (if needed)

ServiceClient

public ServiceClient(ConfigurationContext configContext,
                     javax.wsdl.Definition wsdl4jDefinition,
                     javax.xml.namespace.QName wsdlServiceName,
                     java.lang.String portName)
              throws AxisFault

This is WSDL4J based constructor to configure the Service Client/ We are going to make this policy aware

Parameters:

configContext -

wsdl4jDefinition -

wsdlServiceName -

portName -

Throws:

AxisFault

ServiceClient

public ServiceClient(ConfigurationContext configContext,
                     java.net.URL wsdlURL,
                     javax.xml.namespace.QName wsdlServiceName,
                     java.lang.String portName)
              throws AxisFault

Create a service client for WSDL service identified by the QName of the wsdl:service element in a WSDL document.

Parameters:

configContext - The configuration context under which this service lives (may be null, in which case a new local one will be created) *

wsdlURL - The URL of the WSDL document to read

wsdlServiceName - The QName of the WSDL service in the WSDL document to create a client for

portName - The name of the WSDL 1.1 port to create a client for. May be null (if WSDL 2.0 is used or if only one port is there). .

Throws:

AxisFault - if something goes wrong while creating a config context (if needed)

ServiceClient

public ServiceClient()
              throws AxisFault

Create a service client by assuming an anonymous service and any other necessary information.

Throws:

AxisFault

Method Detail

getAxisService

public AxisService getAxisService()

Return the AxisService this is a client for. This is primarily useful when the AxisService is created anonymously or from WSDL as otherwise the user had the AxisService to start with.

Returns:

the axisService

setOptions

public void setOptions(Options options)

Set the basic client configuration related to this service interaction.

Parameters:

options - (non-null)

getOptions

public Options getOptions()

Get the basic client configuration from this service interaction.

Returns:

options

setOverrideOptions

public void setOverrideOptions(Options overrideOptions)

Set a client configuration to override the normal options used by an operation client. Any values set in this configuration will be used for each client, with the standard values for the client still used for any values not set in the override configuration.

Parameters:

overrideOptions -

getOverrideOptions

public Options getOverrideOptions()

Get the client configuration used to override the normal options set by an operation client.

Returns:

override options

engageModule

public void engageModule(javax.xml.namespace.QName moduleName)
                  throws AxisFault

Engage a module for this service client.

Parameters:

moduleName - name of the module to engage

Throws:

AxisFault - if something goes wrong

engageModule

public void engageModule(java.lang.String moduleName)
                  throws AxisFault

Engage a module for this service client.

Parameters:

moduleName - name of the module to engage

Throws:

AxisFault - if something goes wrong

disengageModule

public void disengageModule(javax.xml.namespace.QName moduleName)

Disengage a module for this service client

Parameters:

moduleName -

disengageModule

public void disengageModule(java.lang.String moduleName)

Disengage a module for this service client

Parameters:

moduleName -

addHeader

public void addHeader(org.apache.axiom.om.OMElement header)

Add an arbitrary XML element as a header to be sent with outgoing messages.

Parameters:

header - header to be sent (non-null)

addHeader

public void addHeader(org.apache.axiom.soap.SOAPHeaderBlock header)

Add SOAP Header to be sent with outgoing messages.

Parameters:

header - header to be sent (non-null)

removeHeaders

public void removeHeaders()

Remove all headers for outgoing message.

addStringHeader

public void addStringHeader(javax.xml.namespace.QName headerName,
                            java.lang.String headerText)
                     throws AxisFault

Add a simple header consisting of some text (and a header name; duh) to be sent with interactions.

Parameters:

headerName -

headerText -

Throws:

AxisFault

sendRobust

public void sendRobust(org.apache.axiom.om.OMElement elem)
                throws AxisFault

Directly invoke an anonymous operation with a Robust In-Only MEP. This method just sends your supplied XML and possibly receives a fault. For more control, you can instead create a client for the operation and use that client to execute the send.

Parameters:

elem - XML to send

Throws:

AxisFault - if something goes wrong while sending, or if a fault is received in response (per the Robust In-Only MEP).

See Also:

createClient(QName)

sendRobust

public void sendRobust(javax.xml.namespace.QName operation,
                       org.apache.axiom.om.OMElement elem)
                throws AxisFault

Directly invoke a named operation with a Robust In-Only MEP. This method just sends your supplied XML and possibly receives a fault. For more control, you can instead create a client for the operation and use that client to execute the send.

Parameters:

operation - name of operation to be invoked (non-null)

elem - XML to send

Throws:

AxisFault - if something goes wrong while sending it or if a fault is received in response (per the Robust In-Only MEP).

See Also:

createClient(QName)

fireAndForget

public void fireAndForget(org.apache.axiom.om.OMElement elem)
                   throws AxisFault

Directly invoke an anonymous operation with an In-Only MEP. This method just sends your supplied XML without the possibility of any response from the service (even an error - though you can still get client-side errors such as "Host not found"). For more control, you can instead create a client for the operation and use that client to execute the send.

Parameters:

elem - XML to send

Throws:

AxisFault - ff something goes wrong trying to send the XML

See Also:

createClient(QName)

fireAndForget

public void fireAndForget(javax.xml.namespace.QName operation,
                          org.apache.axiom.om.OMElement elem)
                   throws AxisFault

Directly invoke a named operation with an In-Only MEP. This method just sends your supplied XML without the possibility of any response from the service (even an error - though you can still get client-side errors such as "Host not found"). For more control, you can instead create a client for the operation and use that client to execute the send.

Parameters:

operation - name of operation to be invoked (non-null)

elem - XML to send

Throws:

AxisFault - if something goes wrong trying to send the XML

See Also:

createClient(QName)

sendReceive

public org.apache.axiom.om.OMElement sendReceive(org.apache.axiom.om.OMElement elem)
                                          throws AxisFault

Directly invoke an anonymous operation with an In-Out MEP. This method sends your supplied XML and receives a response. For more control, you can instead create a client for the operation and use that client to execute the exchange.

Parameters:

elem -

Returns:

response

Throws:

AxisFault

See Also:

createClient(QName)

sendReceive

public org.apache.axiom.om.OMElement sendReceive(javax.xml.namespace.QName operationQName,
                                                 org.apache.axiom.om.OMElement xmlPayload)
                                          throws AxisFault

Directly invoke a named operationQName with an In-Out MEP. This method sends your supplied XML and receives a response. For more control, you can instead create a client for the operationQName and use that client to execute the exchange.

Parameters:

operationQName - name of operationQName to be invoked (non-null)

xmlPayload -

Returns:

response

Throws:

AxisFault

sendReceiveNonBlocking

public void sendReceiveNonBlocking(org.apache.axiom.om.OMElement elem,
                                   Callback callback)
                            throws AxisFault

Directly invoke an anonymous operation with an In-Out MEP without waiting for a response. This method sends your supplied XML with response notification to your callback handler. For more control, you can instead create a client for the operation and use that client to execute the exchange.

Parameters:

elem -

callback -

Throws:

AxisFault

See Also:

createClient(QName)

sendReceiveNonBlocking

public void sendReceiveNonBlocking(javax.xml.namespace.QName operation,
                                   org.apache.axiom.om.OMElement elem,
                                   Callback callback)
                            throws AxisFault

Directly invoke a named operation with an In-Out MEP without waiting for a response. This method sends your supplied XML with response notification to your callback handler. For more control, you can instead create a client for the operation and use that client to execute the exchange.

Parameters:

operation - name of operation to be invoked (non-null)

elem -

callback -

Throws:

AxisFault

See Also:

createClient(QName)

createClient

public OperationClient createClient(javax.xml.namespace.QName operationQName)
                             throws AxisFault

Create an operation client with the appropriate message exchange pattern (MEP). This method creates a full-function MEP client which can be used to exchange messages for a specific operation. It configures the constructed operation client to use the current normal and override options. This method is used internally, and also by generated client stub code.

Parameters:

operationQName - qualified name of operation (local name is operation name, namespace URI is just the empty string)

Returns:

client configured to talk to the given operation

Throws:

AxisFault - if the operation is not found

addHeadersToEnvelope

public void addHeadersToEnvelope(org.apache.axiom.soap.SOAPEnvelope envelope)

Add all configured headers to a SOAP envelope.

Parameters:

envelope -

getMyEPR

public EndpointReference getMyEPR(java.lang.String transport)
                           throws AxisFault

Get the endpoint reference for this client using a particular transport.

Parameters:

transport - transport name (non-null)

Returns:

local endpoint

Throws:

AxisFault

getTargetEPR

public EndpointReference getTargetEPR()

Get the endpoint reference for the service.

Returns:

service endpoint

setTargetEPR

public void setTargetEPR(EndpointReference targetEpr)

Set the endpoint reference for the service.

Parameters:

targetEpr -

getLastOperationContext

public OperationContext getLastOperationContext()

Gets the last OperationContext

setCachingOperationContext

public void setCachingOperationContext(boolean cachingOpContext)

Sets whether or not to cache the last OperationContext

getServiceContext

public ServiceContext getServiceContext()

Get the service context.

Returns:

context

finalize

protected void finalize()
                 throws java.lang.Throwable

Throws:

java.lang.Throwable

cleanup

public void cleanup()
             throws AxisFault

Clean up configuration created with this client. Call this method when you're done using the client, in order to discard any associated resources.

Throws:

AxisFault

setAxisService

public void setAxisService(AxisService axisService)
                    throws AxisFault

Configure the ServiceClient to interact with the Web service described by the specified AxisService object.

Parameters:

axisService - the AxisService that represents the new Web service.

Throws:

AxisFault - if an error occurs while configuring the ServiceClient.