org.apache.axis.client
Class ServiceClient

java.lang.Object
  |
  +--org.apache.axis.client.ServiceClient

public class ServiceClient
extends java.lang.Object

Allows an Axis service to be invoked from the client side. Contains message and session state which may be reused across multiple invocations on the same ServiceClient.

Author:
Rob Jellinghaus (robj@unrealities.com), Doug Davis (dug@us.ibm.com), Glen Daniels (gdaniels@macromedia.com)

Field Summary
static java.lang.String TRANSPORT_PROPERTY
          Static stuff
 
Constructor Summary
ServiceClient()
          Basic, no-argument constructor.
ServiceClient(AxisEngine engine)
          Construct a ServiceClient with just an AxisEngine.
ServiceClient(java.lang.String endpointURL)
          Construct a ServiceClient with a given endpoint URL
ServiceClient(java.lang.String endpointURL, AxisEngine engine)
          Construct a ServiceClient with a given endpoint URL & engine
ServiceClient(Transport transport)
          Construct a ServiceClient with the given Transport.
ServiceClient(Transport transport, AxisEngine engine)
          Construct a ServiceClient with the given Transport & engine.
 
Method Summary
 void addDeserializerFactory(QName qName, java.lang.Class _class, DeserializerFactory deserializerFactory)
          Map a type for deserialization.
 void addOption(java.lang.String name, java.lang.Object value)
          Set engine option.
 void addSerializer(java.lang.Class _class, QName qName, Serializer serializer)
          Map a type for serialization.
static void addTransportPackage(java.lang.String packageName)
          Add a package to the system protocol handler search path.
 java.lang.Object get(java.lang.String name)
          Get a property from our MessageContext.
 MessageContext getMessageContext()
          Obtain a reference to our MessageContext.
 java.util.Vector getOutputParams()
          Get the output parameters (if any) from the last invocation.
 Message getResponseMessage()
          Directly get the response message in our MessageContext.
 int getTimeout()
          Get timeout from our MessageContext.
 Transport getTransportForProtocol(java.lang.String protocol)
          Get the Transport registered for the given protocol.
static void initialize()
          Set up the default transport URL mappings.
 void invoke()
          Invoke this ServiceClient with its established MessageContext (perhaps because you called this.setRequestMessage())
 java.lang.Object invoke(RPCElement body)
          Invoke an RPC service with a pre-constructed RPCElement.
 SOAPEnvelope invoke(SOAPEnvelope env)
          Invoke the service with a custom SOAPEnvelope.
 java.lang.Object invoke(java.lang.String method, java.lang.Object[] args)
          Convenience method to invoke a method with a default (empty) namespace.
 java.lang.Object invoke(java.lang.String namespace, java.lang.String method, java.lang.Object[] args)
          Invoke an RPC service with a method name and arguments.
 void set(java.lang.String name, java.lang.Object value)
          Set property in our MessageContext.
 void setMaintainSession(boolean yesno)
          Determine whether we'd like to track sessions or not.
 void setRequestMessage(Message msg)
          Directly set the request message in our MessageContext.
 void setServiceDescription(ServiceDescription serviceDesc)
          Set the ServiceDescription associated with this ServiceClient.
 void setTimeout(int value)
          Set timeout in our MessageContext.
 void setTransport(Transport transport)
          Set the Transport for this ServiceClient.
static void setTransportForProtocol(java.lang.String protocol, java.lang.Class transportClass)
          Register a Transport that should be used for URLs of the specified protocol.
 void setTransportName(java.lang.String name)
          Set the name of the transport chain to use.
 void setURL(java.lang.String endpointURL)
          Set the URL (and the transport state).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

TRANSPORT_PROPERTY

public static final java.lang.String TRANSPORT_PROPERTY
Static stuff
Constructor Detail

ServiceClient

public ServiceClient()
Basic, no-argument constructor.

ServiceClient

public ServiceClient(AxisEngine engine)
Construct a ServiceClient with just an AxisEngine.

ServiceClient

public ServiceClient(java.lang.String endpointURL)
              throws AxisFault
Construct a ServiceClient with a given endpoint URL
Parameters:
endpointURL - a string containing the transport endpoint for this service.

ServiceClient

public ServiceClient(java.lang.String endpointURL,
                     AxisEngine engine)
              throws AxisFault
Construct a ServiceClient with a given endpoint URL & engine

ServiceClient

public ServiceClient(Transport transport)
Construct a ServiceClient with the given Transport.
Parameters:
transport - a pre-constructed Transport object which will be used to set up the MessageContext appropriately for each request

ServiceClient

public ServiceClient(Transport transport,
                     AxisEngine engine)
Construct a ServiceClient with the given Transport & engine.
Method Detail

setTransportForProtocol

public static void setTransportForProtocol(java.lang.String protocol,
                                           java.lang.Class transportClass)
Register a Transport that should be used for URLs of the specified protocol.
Parameters:
protocol - the URL protocol (i.e. "tcp" for "tcp://" urls)
transportClass - the class of a Transport type which will be used for matching URLs.

initialize

public static void initialize()
Set up the default transport URL mappings. This must be called BEFORE doing non-standard URL parsing (i.e. if you want the system to accept a "local:" URL). This is why the Options class calls it before parsing the command-line URL argument.

addTransportPackage

public static void addTransportPackage(java.lang.String packageName)
Add a package to the system protocol handler search path. This enables users to create their own URLStreamHandler classes, and thus allow custom protocols to be used in Axis (typically on the client command line). For instance, if you add "samples.transport" to the packages property, and have a class samples.transport.tcp.Handler, the system will be able to parse URLs of the form "tcp://host:port..."
Parameters:
packageName - the package in which to search for protocol names.

setTransport

public void setTransport(Transport transport)
Set the Transport for this ServiceClient.
Parameters:
transport - the Transport object we'll use to set up MessageContext properties.

setURL

public void setURL(java.lang.String endpointURL)
            throws AxisFault
Set the URL (and the transport state).

setTransportName

public void setTransportName(java.lang.String name)
Set the name of the transport chain to use.

getTransportForProtocol

public Transport getTransportForProtocol(java.lang.String protocol)
Get the Transport registered for the given protocol.
Parameters:
protocol - a protocol such as "http" or "local" which may have a Transport object associated with it.
Returns:
the Transport registered for this protocol, or null if none.

set

public void set(java.lang.String name,
                java.lang.Object value)
Set property in our MessageContext.
Parameters:
name - the property name to set.
value - the value of the property.

get

public java.lang.Object get(java.lang.String name)
Get a property from our MessageContext.
Parameters:
name - the property name to retrieve.
Returns:
the property's value.

setTimeout

public void setTimeout(int value)
Set timeout in our MessageContext.
Parameters:
value - the maximum amount of time, in milliseconds

getTimeout

public int getTimeout()
Get timeout from our MessageContext.
Returns:
value the maximum amount of time, in milliseconds

setRequestMessage

public void setRequestMessage(Message msg)
Directly set the request message in our MessageContext. This allows custom message creation.
Parameters:
msg - the new request message.

getResponseMessage

public Message getResponseMessage()
Directly get the response message in our MessageContext. Shortcut for having to go thru the msgContext
Returns:
the response Message object in the msgContext

setMaintainSession

public void setMaintainSession(boolean yesno)
Determine whether we'd like to track sessions or not. This just passes through the value into the MessageContext.
Parameters:
yesno - true if session state is desired, false if not.

getMessageContext

public MessageContext getMessageContext()
Obtain a reference to our MessageContext.
Returns:
the ServiceClient's MessageContext.

setServiceDescription

public void setServiceDescription(ServiceDescription serviceDesc)
Set the ServiceDescription associated with this ServiceClient.
Parameters:
serviceDesc - a ServiceDescription.

getOutputParams

public java.util.Vector getOutputParams()
Get the output parameters (if any) from the last invocation. NOTE that the params returned are all RPCParams, containing name and value - if you want the value, you'll need to call param.getValue().
Returns:
a Vector of RPCParams

addSerializer

public void addSerializer(java.lang.Class _class,
                          QName qName,
                          Serializer serializer)
Map a type for serialization.
Parameters:
_class - the Java class of the data type.
qName - the xsi:type QName of the associated XML type.
serializer - a Serializer which will be used to write the XML.

addDeserializerFactory

public void addDeserializerFactory(QName qName,
                                   java.lang.Class _class,
                                   DeserializerFactory deserializerFactory)
Map a type for deserialization.
Parameters:
qName - the xsi:type QName of an XML Schema type.
_class - the class of the associated Java data type.
deserializerFactory - a factory which can create deserializer instances for this type.

invoke

public SOAPEnvelope invoke(SOAPEnvelope env)
                    throws AxisFault
Invoke the service with a custom SOAPEnvelope.
Parameters:
env - a SOAPEnvelope to send.
Throws:
AxisFault -  

invoke

public java.lang.Object invoke(java.lang.String namespace,
                               java.lang.String method,
                               java.lang.Object[] args)
                        throws AxisFault
Invoke an RPC service with a method name and arguments. This will call the service, serializing all the arguments, and then deserialize the return value.
Parameters:
namespace - the desired namespace URI of the method element
method - the method name
args - an array of Objects representing the arguments to the invoked method. If any of these objects are RPCParams, Axis will use the embedded name of the RPCParam as the name of the parameter. Otherwise, we will serialize each argument as an XML element called "arg".
Returns:
a deserialized Java Object containing the return value
Throws:
AxisFault -  

invoke

public java.lang.Object invoke(java.lang.String method,
                               java.lang.Object[] args)
                        throws AxisFault
Convenience method to invoke a method with a default (empty) namespace. Calls invoke() above.
Parameters:
method - the method name
args - an array of Objects representing the arguments to the invoked method. If any of these objects are RPCParams, Axis will use the embedded name of the RPCParam as the name of the parameter. Otherwise, we will serialize each argument as an XML element called "arg".
Returns:
a deserialized Java Object containing the return value
Throws:
AxisFault -  

invoke

public java.lang.Object invoke(RPCElement body)
                        throws AxisFault
Invoke an RPC service with a pre-constructed RPCElement.
Parameters:
body - an RPCElement containing all the information about this call.
Returns:
a deserialized Java Object containing the return value
Throws:
AxisFault -  

addOption

public void addOption(java.lang.String name,
                      java.lang.Object value)
Set engine option.

invoke

public void invoke()
            throws AxisFault
Invoke this ServiceClient with its established MessageContext (perhaps because you called this.setRequestMessage())
Throws:
AxisFault -  


Copyright © 2001 Apache XML Project. All Rights Reserved.