Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.axis2.client
Class ServiceClient

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

Direct Known Subclasses:
  MexClient

    public class ServiceClient

extends 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. Note that these instances are not intended to be thread-safe. `Options` instances are used to configure various aspects of the service access.

Field Summary
`static 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 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 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 String` | `ANON_SERVICE` Base name used for a service created without an existing configuration.
`static String` | `AUTO_OPERATION_CLEANUP` Option property name for automatically cleaning up old OperationContexts
`protected static org.apache.commons.logging.Log` | `log`

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, QName wsdlServiceName, String portName)` This is WSDL4J based constructor to configure the Service Client/ TODO: make this policy aware
`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.

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(QName headerName, String headerText)` Add a simple header containing some text to be sent with interactions.
`void` | `cleanup()` Clean up configuration created with this client.
`void` | `cleanupTransport()` Release resources allocated by the transport during the last service invocation.
`OperationClient` | `createClient(QName operationQName)` Create an operation client with the appropriate message exchange pattern (MEP).
`void` | `disengageModule(QName moduleName)` Deprecated. Please use String version instead
`void` | `disengageModule(String moduleName)` Disengage a module for this service client
`void` | `engageModule(QName moduleName)` Deprecated. Please use String version instead
`void` | `engageModule(String moduleName)` Engage a module for this service client.
`boolean` | `equals(Object obj)`
`protected void` | `finalize()`
`void` | `fireAndForget(org.apache.axiom.om.OMElement elem)` Directly invoke an anonymous operation with an In-Only MEP.
`void` | `fireAndForget(QName operation, org.apache.axiom.om.OMElement elem)` Directly invoke a named operation with an In-Only MEP.
`AxisConfiguration` | `getAxisConfiguration()` Get the AxisConfiguration
`AxisService` | `getAxisService()` Return the AxisService this is a client for.
`OperationContext` | `getLastOperationContext()` Gets the last OperationContext
`EndpointReference` | `getMyEPR(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.
`int` | `hashCode()`
`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(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, AxisCallback callback)` Directly invoke an anonymous operation with an In-Out MEP without waiting for a response.
`void` | `sendReceiveNonBlocking(org.apache.axiom.om.OMElement elem, Callback callback)` Deprecated. Please use the AxisCallback interface rather than Callback, which has been deprecated
`void` | `sendReceiveNonBlocking(QName operation, org.apache.axiom.om.OMElement elem, AxisCallback callback)` Directly invoke a named operation with an In-Out MEP without waiting for a response.
`void` | `sendReceiveNonBlocking(QName operation, org.apache.axiom.om.OMElement elem, Callback callback)` Deprecated. Please use the AxisCallback interface rather than Callback, which has been deprecated
`void` | `sendRobust(org.apache.axiom.om.OMElement elem)` Directly invoke an anonymous operation with a Robust In-Only MEP.
`void` | `sendRobust(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)` Deprecated.
`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, getClass, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### log

    protected static final org.apache.commons.logging.Log log

### ANON_SERVICE

    public static final String ANON_SERVICE

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

  See Also:
    Constant Field Values

### AUTO_OPERATION_CLEANUP

    public static final String AUTO_OPERATION_CLEANUP

  Option property name for automatically cleaning up old OperationContexts

  See Also:
    Constant Field Values

### ANON_OUT_ONLY_OP

    public static final 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 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 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,
                         QName wsdlServiceName,
                         String portName)
                  throws AxisFault

  This is WSDL4J based constructor to configure the Service Client/ TODO: make this policy aware

  Parameters:
    `configContext` - active ConfigurationContext
    `wsdl4jDefinition` - the WSDL we're going to be using to configure ourselves
    `wsdlServiceName` - QName of the WSDL service we'd like to access
    `portName` - name of the WSDL port we'd like to access
  Throws:
    `AxisFault` - in case of error

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

  Throws:
    `AxisFault` - in case of error

Method Detail

### getAxisConfiguration

    public AxisConfiguration getAxisConfiguration()

  Get the AxisConfiguration

  Returns:
    the AxisConfiguration associated with the client.

### 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` - the Options to use

### 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(QName moduleName)
                      throws AxisFault

  Deprecated. Please use String version instead

  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(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(QName moduleName)

  Deprecated. Please use String version instead

  Disengage a module for this service client

  Parameters:
    `moduleName` - name of Module to disengage

### disengageModule

    public void disengageModule(String moduleName)

  Disengage a module for this service client

  Parameters:
    `moduleName` - name of Module to disengage

### 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(QName headerName,
                                String headerText)
                         throws AxisFault

  Add a simple header containing some text to be sent with interactions.

  Parameters:
    `headerName` - name of header to add
    `headerText` - text content for header
  Throws:
    `AxisFault` - in case of error

### 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(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(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.

  Unless the `callTransportCleanup` property on the `Options` object has been set to `true`, the caller must invoke `cleanupTransport()` after processing the response.

  Parameters:
    `elem` - the data to send (becomes the content of SOAP body)
  Returns:
    response
  Throws:
    `AxisFault` - in case of error
  See Also:
    `createClient(QName)`, `cleanupTransport()`

### sendReceive

    public org.apache.axiom.om.OMElement sendReceive(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.

  Unless the `callTransportCleanup` property on the `Options` object has been set to `true`, the caller must invoke `cleanupTransport()` after processing the response.

  Parameters:
    `operationQName` - name of operationQName to be invoked (non-`null`)
    `xmlPayload` - the data to send (becomes the content of SOAP body)
  Returns:
    response OMElement
  Throws:
    `AxisFault` - in case of error
  See Also:
    `cleanupTransport()`

### sendReceiveNonBlocking

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

  Deprecated. Please use the AxisCallback interface rather than Callback, which has been deprecated

  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` - the data to send (becomes the content of SOAP body)
    `callback` - a Callback which will be notified upon completion
  Throws:
    `AxisFault` - in case of error
  See Also:
    `createClient(QName)`

### sendReceiveNonBlocking

    public void sendReceiveNonBlocking(org.apache.axiom.om.OMElement elem,
                                       AxisCallback 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` - the data to send (becomes the content of SOAP body)
    `callback` - a Callback which will be notified upon completion
  Throws:
    `AxisFault` - in case of error
  See Also:
    `createClient(QName)`

### sendReceiveNonBlocking

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

  Deprecated. Please use the AxisCallback interface rather than Callback, which has been deprecated

  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` - the data to send (becomes the content of SOAP body)
    `callback` - a Callback which will be notified upon completion
  Throws:
    `AxisFault` - in case of error
  See Also:
    `createClient(QName)`

### sendReceiveNonBlocking

    public void sendReceiveNonBlocking(QName operation,
                                       org.apache.axiom.om.OMElement elem,
                                       AxisCallback 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` - the data to send (becomes the content of SOAP body)
    `callback` - a Callback which will be notified upon completion
  Throws:
    `AxisFault` - in case of error
  See Also:
    `createClient(QName)`

### createClient

    public OperationClient createClient(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` - the SOAPEnvelope in which to write the headers

### getMyEPR

    public EndpointReference getMyEPR(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` - in case of error

### 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` - the EPR this ServiceClient should target

### getLastOperationContext

    public OperationContext getLastOperationContext()

  Gets the last OperationContext

  Returns:
    the last OperationContext that was invoked by this ServiceClient

### setCachingOperationContext

    public void setCachingOperationContext(boolean cachingOpContext)

  Deprecated.

  Sets whether or not to cache the last OperationContext

  Parameters:
    `cachingOpContext` - true if we should hold onto the last active OperationContext

### getServiceContext

    public ServiceContext getServiceContext()

  Get the service context.

  Returns:
    context

### finalize

    protected void finalize()
                     throws Throwable

  Overrides:
    `finalize` in class `Object`
  Throws:
    `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` - in case of error

### cleanupTransport

    public void cleanupTransport()
                          throws AxisFault

  Release resources allocated by the transport during the last service invocation. This method will call `TransportSender.cleanup(MessageContext)` on the transport sender used during that invocation.

  If the `callTransportCleanup` property on the `Options` object is set to `false` (which is the default), then this method must be called after each invocation of an operation with an in-out MEP, but not before the response from that operation has been completely processed (or `OMSerializable.build()` has been called on the response element).

  If the `callTransportCleanup` property is set to `true`, then this method is called automatically. Note that in this case, `OMSerializable.build()` will be called on the response element before is returned. This effectively disables deferred parsing of the response and prevents the code from starting to process the response before it has been completely received. Therefore this approach is not recommended whenever performance is important.

  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.

### hashCode

    public int hashCode()

  Overrides:
    `hashCode` in class `Object`
  See Also:
    `Object.hashCode()`

### equals

    public boolean equals(Object obj)

  Overrides:
    `equals` in class `Object`
  See Also:
    `Object.equals(java.lang.Object)`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2004-2011 The Apache Software Foundation. All Rights Reserved.