You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by gd...@apache.org on 2001/07/06 17:52:20 UTC
cvs commit: xml-axis/java/src/org/apache/axis/client ServiceClient.java
gdaniels 01/07/06 08:52:20
Modified: java/src/org/apache/axis/client ServiceClient.java
Log:
Cleanup and flesh out JavaDocs.
Revision Changes Path
1.28 +168 -108 xml-axis/java/src/org/apache/axis/client/ServiceClient.java
Index: ServiceClient.java
===================================================================
RCS file: /home/cvs/xml-axis/java/src/org/apache/axis/client/ServiceClient.java,v
retrieving revision 1.27
retrieving revision 1.28
diff -u -r1.27 -r1.28
--- ServiceClient.java 2001/07/04 14:20:52 1.27
+++ ServiceClient.java 2001/07/06 15:52:20 1.28
@@ -2,7 +2,7 @@
* The Apache Software License, Version 1.1
*
*
- * Copyright (c) 1999 The Apache Software Foundation. All rights
+ * Copyright (c) 2001 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -91,16 +91,78 @@
// Only supports String
public class ServiceClient {
- // Client transports
+ private static final boolean DEBUG_LOG = false;
+
+ /***************************************************************
+ * Static stuff
+ */
+
+ public static final String TRANSPORT_PROPERTY =
+ "java.protocol.handler.pkgs";
+
private static Hashtable transports = new Hashtable();
+ private static boolean initialized = false;
+
- // keep prop hashtable small
- private Hashtable properties = new Hashtable(10);
+ /** Register a Transport that should be used for URLs of the specified
+ * protocol.
+ *
+ * @param protocol the URL protocol (i.e. "tcp" for "tcp://" urls)
+ * @param transport a Transport object which will be used for matching
+ * URLs.
+ */
+ public static void setTransportForProtocol(String protocol,
+ Transport transport)
+ {
+ transports.put(protocol, transport);
+ }
- // For testing
- private static Handler localServer = null ;
- public boolean doLocal = false ;
- private static final boolean DEBUG_LOG = false;
+ /**
+ * 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.
+ */
+ public static synchronized void initialize()
+ {
+ if (!initialized) {
+ addTransportPackage("org.apache.axis.transport");
+
+ setTransportForProtocol("local", new org.apache.axis.transport.local.LocalTransport());
+ setTransportForProtocol("http", new HTTPTransport());
+
+ initialized = true;
+ }
+ }
+
+ /** 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..."
+ *
+ * @param packageName the package in which to search for protocol names.
+ */
+ public static synchronized void addTransportPackage(String packageName)
+ {
+ String currentPackages = System.getProperty(TRANSPORT_PROPERTY);
+ if (currentPackages == null) {
+ currentPackages = "";
+ } else {
+ currentPackages += "|";
+ }
+ currentPackages += packageName;
+
+ System.setProperty(TRANSPORT_PROPERTY, currentPackages);
+ }
+
+ /*****************************************************************************
+ * END STATICS
+ */
// Our AxisClient
private AxisClient engine;
@@ -115,16 +177,20 @@
private Transport transport;
/**
- * Construct a ServiceClient with no properties.
- * Set it up yourself!
+ * Basic, no-argument constructor.
*/
public ServiceClient () {
engine = new AxisClient();
msgContext = new MessageContext(engine);
+ if (!initialized)
+ initialize();
}
/**
* Construct a ServiceClient with a given endpoint URL
+ *
+ * @param endpointURL a string containing the transport endpoint for this
+ * service.
*/
public ServiceClient(String endpointURL)
{
@@ -144,6 +210,10 @@
/**
* Construct a ServiceClient with the given Transport.
+ *
+ * @param transport a pre-constructed Transport object which will be used
+ * to set up the MessageContext appropriately for each
+ * request
*/
public ServiceClient (Transport transport) {
this();
@@ -151,131 +221,123 @@
}
/**
- * Force the transport to be set for this ServiceClient.
+ * Set the Transport for this ServiceClient.
*
- * @param transport the Transport object we'll use
+ * @param transport the Transport object we'll use to set up
+ * MessageContext properties.
*/
public void setTransport(Transport transport) {
this.transport = transport;
Debug.Print(1, "Transport is " + transport);
}
- /** Register a Transport that should be used for URLs of the specified
- * protocol.
+ /** Get the Transport registered for the given protocol.
*
- * @param protocol the URL protocol (i.e. "tcp" for "tcp://" urls)
- * @param transport a Transport object which will be used for matching
- * URLs.
+ * @param protocol a protocol such as "http" or "local" which may
+ * have a Transport object associated with it.
+ * @return the Transport registered for this protocol, or null if none.
*/
- public static void setTransportForProtocol(String protocol,
- Transport transport)
- {
- transports.put(protocol, transport);
- }
-
- public static final String TRANSPORT_PROPERTY =
- "java.protocol.handler.pkgs";
- private static boolean initialized = false;
-
- /**
- * This is a bit kludgey - call this at some point before parsing
- * URLs to set up default Axis transports....
- */
- public static synchronized void initialize()
- {
- if (!initialized) {
- addTransportPackage("org.apache.axis.transport");
-
- setTransportForProtocol("local", new org.apache.axis.transport.local.LocalTransport());
- setTransportForProtocol("http", new HTTPTransport());
-
- initialized = true;
- }
- }
-
- /** 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..."
- *
- * @param packageName the package in which to search for protocol names.
- */
- public static synchronized void addTransportPackage(String packageName)
- {
- String currentPackages = System.getProperty(TRANSPORT_PROPERTY);
- if (currentPackages == null) {
- currentPackages = "";
- } else {
- currentPackages += "|";
- }
- currentPackages += packageName;
-
- System.setProperty(TRANSPORT_PROPERTY, currentPackages);
- }
-
public Transport getTransportForProtocol(String protocol)
{
return (Transport)transports.get(protocol);
}
/**
- * Set property; pass through to MessageContext.
- * This works because the constants defined in Transport and its
- * subclasses are synonyms for MessageContext constants.
+ * Set property in our MessageContext.
+ *
+ * @param name the property name to set.
+ * @param value the value of the property.
*/
- public void set (String name, String value) {
- if (value == null) return;
-
+ public void set (String name, Object value) {
msgContext.setProperty(name, value);
}
/**
- * Get property; pass through to MessageContext.
- * This works because the constants defined in Transport and its
- * subclasses are synonyms for MessageContext constants.
+ * Get a property from our MessageContext.
+ *
+ * @param name the property name to retrieve.
+ * @return the property's value.
*/
- public String get (String name) {
- return (String)msgContext.getProperty(name);
+ public Object get (String name) {
+ return msgContext.getProperty(name);
}
+ /**
+ * Directly set the request message in our MessageContext.
+ *
+ * This allows custom message creation.
+ *
+ * @param msg the new request message.
+ */
public void setRequestMessage(Message msg) {
msgContext.setRequestMessage(msg);
}
/**
- * pass through whether we are maintaining session state
+ * Determine whether we'd like to track sessions or not.
+ *
+ * This just passes through the value into the MessageContext.
+ *
+ * @param yesno true if session state is desired, false if not.
*/
public void setMaintainSession (boolean yesno) {
msgContext.setMaintainSession(yesno);
}
/**
- * all-purpose accessor for fringe cases....
+ * Obtain a reference to our MessageContext.
+ *
+ * @return the ServiceClient's MessageContext.
*/
public MessageContext getMessageContext () {
return msgContext;
}
-
+
+ /**
+ * Set the ServiceDescription associated with this ServiceClient.
+ *
+ * @param serviceDesc a ServiceDescription.
+ */
public void setServiceDescription(ServiceDescription serviceDesc)
{
this.serviceDesc = serviceDesc;
}
+ /**
+ * Map a type for serialization.
+ *
+ * @param _class the Java class of the data type.
+ * @param qName the xsi:type QName of the associated XML type.
+ * @param serializer a Serializer which will be used to write the XML.
+ */
public void addSerializer(Class _class, QName qName, Serializer serializer) {
TypeMappingRegistry typeMap = msgContext.getTypeMappingRegistry();
typeMap.addSerializer(_class, qName, serializer);
}
+ /**
+ * Map a type for deserialization.
+ *
+ * @param qName the xsi:type QName of an XML Schema type.
+ * @param _class the class of the associated Java data type.
+ * @param deserializerFactory a factory which can create deserializer
+ * instances for this type.
+ */
public void addDeserializerFactory(QName qName, Class _class,
DeserializerFactory deserializerFactory) {
TypeMappingRegistry typeMap = msgContext.getTypeMappingRegistry();
typeMap.addDeserializerFactory(qName, _class, deserializerFactory);
}
+ /************************************************
+ * Invocation
+ */
+
+ /** Invoke the service with a custom SOAPEnvelope.
+ *
+ * @param env a SOAPEnvelope to send.
+ * @exception AxisFault
+ */
public SOAPEnvelope invoke(SOAPEnvelope env) throws AxisFault
{
msgContext.clearProperties();
@@ -284,6 +346,21 @@
return msgContext.getResponseMessage().getAsSOAPEnvelope();
}
+ /** 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.
+ *
+ * @param namespace the desired namespace URI of the method element
+ * @param method the method name
+ * @param 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<n>".
+ * @return a deserialized Java Object containing the return value
+ * @exception AxisFault
+ */
public Object invoke( String namespace, String method, Object[] args ) throws AxisFault {
Debug.Print( 1, "Enter: ServiceClient::invoke(ns, meth, args)" );
RPCElement body = new RPCElement(namespace, method, args, serviceDesc);
@@ -292,6 +369,13 @@
return ret;
}
+ /** Invoke an RPC service with a pre-constructed RPCElement.
+ *
+ * @param body an RPCElement containing all the information about
+ * this call.
+ * @return a deserialized Java Object containing the return value
+ * @exception AxisFault
+ */
public Object invoke( RPCElement body ) throws AxisFault {
Debug.Print( 1, "Enter: ServiceClient::invoke(RPCElement)" );
SOAPEnvelope reqEnv = new SOAPEnvelope();
@@ -370,8 +454,10 @@
}
/**
- * invoke this ServiceClient with its established MessageContext
+ * Invoke this ServiceClient with its established MessageContext
* (perhaps because you called this.setRequestMessage())
+ *
+ * @exception AxisFault
*/
public void invoke() throws AxisFault {
Debug.Print( 1, "Enter: Service::invoke()" );
@@ -382,32 +468,6 @@
if (transport != null) {
transport.setupMessageContext(msgContext, this, this.engine);
}
-
- /* ??? --Glen
-
- Message inMsg = msgContext.getRequestMessage();
-
- SOAPEnvelope reqEnv = null ;
-
- reqEnv = (SOAPEnvelope) inMsg.getAsSOAPEnvelope();
- if ( encodingStyleURI != null )
- reqEnv.setEncodingStyleURI( encodingStyleURI );
-
- Message reqMsg = new Message( reqEnv );
- */
-
- /*
- * I don't think we should be doing this. Debugging on the client
- * doesn't necessarily map to debugging on the server. Leaving
- * it commented for now. --Glen
- *
- if ( Debug.getDebugLevel() > 0 ) {
- DebugHeader header = new DebugHeader(Debug.getDebugLevel());
- header.setActor( Constants.URI_NEXT_ACTOR );
-
- reqEnv.addHeader( header );
- }
- */
try {
engine.invoke( msgContext );