org.apache.axis2.client
Class ServiceClient

java.lang.Object
  extended byorg.apache.axis2.client.ServiceClient
Direct Known Subclasses:
RESTCall, RPCServiceClient

public class ServiceClient
extends Object

A ServiceClient class is used to create a client for a service. More details need to be explained here.


Field Summary
static QName ANON_OUT_IN_OP
           
static QName ANON_OUT_ONLY_OP
           
static QName ANON_ROBUST_OUT_ONLY_OP
           
static String ANON_SERVICE
           
 
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, URL wsdlURL, QName wsdlServiceName, String portName)
          Create a service client for WSDL service identified by the QName of the wsdl:service element in a WSDL document.
ServiceClient(ConfigurationContext configContext, org.apache.wsdl.WSDLDescription wsdldesc, QName wsdlServiceName, String portName)
          This is WOM based constructor to configure the Service Client/ We are going to make this policy aware
 
Method Summary
 void addHeader(org.apache.ws.commons.om.OMElement header)
          Add an XML element as a header to be sent with interactions.
 void addStringHeader(QName headerName, String headerText)
          Add a simple header consisting of some text (and a header name; duh) to be sent with interactions.
 OperationClient createClient(QName operation)
          Create a MEP client for a specific operation.
 void disEngageModule(QName moduleName)
           
 void engageModule(QName moduleName)
          Engage a module for this service client.
 void finalizeInvoke()
          This will close the out put stream or , and remove entry from waiting queue of the transport Listener queue
 void fireAndForget(org.apache.ws.commons.om.OMElement elem)
          Send a bit of XML and forget about it.
 void fireAndForget(QName operation, org.apache.ws.commons.om.OMElement elem)
          Send a bit of XML and forget about it under the guise of a specific operation.
 AxisService getAxisService()
          Return the AxisService this is a client for.
 EndpointReference getMyEPR(String transport)
          To get the EPR that the service is running transport : can be null , if it is null then epr will be craetd using any available transports
 Options getOptions()
          Get the client configuration from this service interaction.
 Options getOverrideOptions()
          Get the client configuration from this service interaction which have been used to overide operation client options as well.
 EndpointReference getTargetEPR()
          To get the Targert EPR if any in service conetext and reference paramters in TEPR can send back , in the same time this epr can use to manage session across mutiple ServiceClient
 void removeHeaders()
          To remove all the headers in ServiceClient
 org.apache.ws.commons.om.OMElement sendReceive(org.apache.ws.commons.om.OMElement elem)
           
 org.apache.ws.commons.om.OMElement sendReceive(QName operation, org.apache.ws.commons.om.OMElement elem)
           
 void sendReceiveNonBlocking(org.apache.ws.commons.om.OMElement elem, Callback callback)
           
 void sendReceiveNonBlocking(QName operation, org.apache.ws.commons.om.OMElement elem, Callback callback)
           
 void sendRobust(org.apache.ws.commons.om.OMElement elem)
          This is a simple client API to invoke a service operation who's MEP is Robust In-Only.
 void sendRobust(QName operation, org.apache.ws.commons.om.OMElement elem)
          This is a simple client API to invoke a service operation who's MEP is Robust In-Only.
 void setOptions(Options options)
          Set the client configuration related to this service interaction.
 void setOverrideOptions(Options overrideOptions)
          Set the client configuration related to this service interaction to override any options that the underlying operation client may have.
 void setTargetEPR(EndpointReference targetEpr)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ANON_SERVICE

public static final String ANON_SERVICE
See Also:
Constant Field Values

ANON_OUT_ONLY_OP

public static final QName ANON_OUT_ONLY_OP

ANON_ROBUST_OUT_ONLY_OP

public static final QName ANON_ROBUST_OUT_ONLY_OP

ANON_OUT_IN_OP

public static final QName ANON_OUT_IN_OP
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.
Throws:
AxisFault - if something goes wrong while creating a config context (if needed)

ServiceClient

public ServiceClient(ConfigurationContext configContext,
                     org.apache.wsdl.WSDLDescription wsdldesc,
                     QName wsdlServiceName,
                     String portName)
              throws AxisFault
This is WOM based constructor to configure the Service Client/ We are going to make this policy aware

Parameters:
configContext -
wsdldesc -
wsdlServiceName -
portName -
Throws:
AxisFault

ServiceClient

public ServiceClient(ConfigurationContext configContext,
                     URL wsdlURL,
                     QName wsdlServiceName,
                     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.

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 client configuration related to this service interaction.


getOptions

public Options getOptions()
Get the client configuration from this service interaction.

Returns:
set of options set earlier.

setOverrideOptions

public void setOverrideOptions(Options overrideOptions)
Set the client configuration related to this service interaction to override any options that the underlying operation client may have.


getOverrideOptions

public Options getOverrideOptions()
Get the client configuration from this service interaction which have been used to overide operation client options as well.

Returns:
set of options set earlier.

engageModule

public void engageModule(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

disEngageModule

public void disEngageModule(QName moduleName)

addHeader

public void addHeader(org.apache.ws.commons.om.OMElement header)
Add an XML element as a header to be sent with interactions. This allows users to go a bit beyond the dirt simple XML in/out pattern using this simplified API. A header

Parameters:
header - The header to be added for interactions. Must not be null.

removeHeaders

public void removeHeaders()
To remove all the headers in ServiceClient


addStringHeader

public void addStringHeader(QName headerName,
                            String headerText)
Add a simple header consisting of some text (and a header name; duh) to be sent with interactions.

Parameters:
headerName -
headerText -

sendRobust

public void sendRobust(org.apache.ws.commons.om.OMElement elem)
                throws AxisFault
This is a simple client API to invoke a service operation who's MEP is Robust In-Only. This API can be used to simply send a bit of XML and possibly receive a fault. If you need more control over this interaction then you need to create a client (@see createClient()) for the operation and use that instead.

Parameters:
elem - The 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).

sendRobust

public void sendRobust(QName operation,
                       org.apache.ws.commons.om.OMElement elem)
                throws AxisFault
This is a simple client API to invoke a service operation who's MEP is Robust In-Only. This API can be used to simply send a bit of XML and possibly receive a fault under the guise of a specific operation. If you need more control over this interaction then you need to create a client (@see createClient()) for the operation and use that instead.

Parameters:
operation - The name of the operation to use. Must NOT be null.
elem - The 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).

fireAndForget

public void fireAndForget(org.apache.ws.commons.om.OMElement elem)
                   throws AxisFault
Send a bit of XML and forget about it. This API is used to interact with a service operation who's MEP is In-Only. That is, there is no opportunity to get an error from the service via this API; one may still get client-side errors, such as host unknown etc.

Parameters:
elem - The XML element to send to the service
Throws:
AxisFault - If something goes wrong trying to send the XML

fireAndForget

public void fireAndForget(QName operation,
                          org.apache.ws.commons.om.OMElement elem)
                   throws AxisFault
Send a bit of XML and forget about it under the guise of a specific operation. This API is used to interact with a service operation who's MEP is In-Only. That is, there is no opportunity to get an error from the service via this API; one may still get client-side errors, such as host unknown etc.

Parameters:
operation - The operation to send fire the message under
elem - The XML element to send to the service
Throws:
AxisFault - If something goes wrong trying to send the XML

sendReceive

public org.apache.ws.commons.om.OMElement sendReceive(org.apache.ws.commons.om.OMElement elem)
                                               throws AxisFault
Throws:
AxisFault

sendReceive

public org.apache.ws.commons.om.OMElement sendReceive(QName operation,
                                                      org.apache.ws.commons.om.OMElement elem)
                                               throws AxisFault
Throws:
AxisFault

sendReceiveNonBlocking

public void sendReceiveNonBlocking(org.apache.ws.commons.om.OMElement elem,
                                   Callback callback)
                            throws AxisFault
Throws:
AxisFault

sendReceiveNonBlocking

public void sendReceiveNonBlocking(QName operation,
                                   org.apache.ws.commons.om.OMElement elem,
                                   Callback callback)
                            throws AxisFault
Throws:
AxisFault

createClient

public OperationClient createClient(QName operation)
                             throws AxisFault
Create a MEP client for a specific operation. This is the way one can create a full function MEP client which can be used to exchange messages for this specific operation. If you're using this then you must know what you're doing and need the full capabilities of Axis2's client architecture. This is meant for people with deep skin and not the light user.

Parameters:
operation - The QName of the operation to create a client for.
Returns:
a MEP client configured to talk to the given operation or null if the operation name is not found.
Throws:
AxisFault - if the operation is not found or something else goes wrong

finalizeInvoke

public void finalizeInvoke()
                    throws AxisFault
This will close the out put stream or , and remove entry from waiting queue of the transport Listener queue

Throws:
AxisFault

getMyEPR

public EndpointReference getMyEPR(String transport)
                           throws AxisFault
To get the EPR that the service is running transport : can be null , if it is null then epr will be craetd using any available transports

Throws:
AxisFault

getTargetEPR

public EndpointReference getTargetEPR()
To get the Targert EPR if any in service conetext and reference paramters in TEPR can send back , in the same time this epr can use to manage session across mutiple ServiceClient

Returns:
EndpointReference

setTargetEPR

public void setTargetEPR(EndpointReference targetEpr)