marquee.xmlrpc
Class XmlRpcClient

java.lang.Object
  extended bymarquee.xmlrpc.XmlRpcParser
      extended bymarquee.xmlrpc.XmlRpcClient
All Implemented Interfaces:
org.xml.sax.DocumentHandler, XmlRpcInvocationHandler

public class XmlRpcClient
extends XmlRpcParser
implements XmlRpcInvocationHandler

An XmlRpcClient represents a connection to an XML-RPC enabled server.

Since:
JDK 1.1
Version:
$Revision: 1.13 $
Author:
Greger Ohlson (greger.ohlson@marquee.se), Toby Allsopp (tobya@peace.com)

Field Summary
 
Fields inherited from class marquee.xmlrpc.XmlRpcParser
ARRAY, BASE64, BOOLEAN, DATE, DOUBLE, I4, INT, MEMBER, NAME, STRING, STRUCT, VALUE
 
Constructor Summary
XmlRpcClient(java.lang.String host, int port, java.lang.String path)
          Creates a new client with the ability to send XML-RPC messages to the given host, on the given port and path.
XmlRpcClient(java.net.URL url)
          Creates a new client with the ability to send XML-RPC messages the the server at the given URL.
 
Method Summary
 java.lang.Object invoke(java.lang.String method, java.util.Collection arguments)
          Invokes a method on the terminating XML-RPC end point.
 java.lang.Object invoke(java.lang.String method, java.lang.Object[] arguments)
          Invokes a method on the terminating XML-RPC end point.
 void invokeAsynchronously(java.lang.String method, java.lang.Object arguments, XmlRpcCallback callback)
          A asynchronous version of invoke performing the call in a separate thread and reporting responses, faults, and exceptions through the supplied XmlRpcCallback.
 boolean isFaultResponse()
          Determines if the most previously XML-RPC response contained a fault struct, in which case the return value of the most previous invoke() call contains a hash table with this fault struct.
 void setKeepAlive(boolean keepAlive)
          Determines if the client object should try to keep the socket connection to the server alive or not.
 void setZipStream(boolean zipStream)
          Determines if the XML payload sent to the server should be zipped or not.
 void startElement(java.lang.String name, org.xml.sax.AttributeList attributes)
          Override the startElement() method inherited from XmlRpcParser.
 
Methods inherited from class marquee.xmlrpc.XmlRpcParser
characters, endDocument, endElement, ignorableWhitespace, parse, processingInstruction, setDocumentLocator, setDriver, setDriver, startDocument
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XmlRpcClient

public XmlRpcClient(java.lang.String host,
                    int port,
                    java.lang.String path)
Creates a new client with the ability to send XML-RPC messages to the given host, on the given port and path.

Parameters:
host - The XML-RPC host (IP address or host name).
port - The port the host is accepting connections on.
path - The path to the service (e.g. "/RPC2").

XmlRpcClient

public XmlRpcClient(java.net.URL url)
Creates a new client with the ability to send XML-RPC messages the the server at the given URL.

Parameters:
url - the URL at which the target server can be contacted
Method Detail

isFaultResponse

public final boolean isFaultResponse()
Determines if the most previously XML-RPC response contained a fault struct, in which case the return value of the most previous invoke() call contains a hash table with this fault struct.

Returns:
true or false -- the most previous call contained a fault struct or not.

invoke

public final java.lang.Object invoke(java.lang.String method,
                                     java.util.Collection arguments)
                              throws XmlRpcException
Invokes a method on the terminating XML-RPC end point. The supplied method name and argument vector is used to encode the call into XML-RPC.

Specified by:
invoke in interface XmlRpcInvocationHandler
Parameters:
method - The name of the method to call.
arguments - The arguments to encode in the call.
Returns:
The object returned from the terminating XML-RPC end point.
Throws:
XmlRpcException - One or more of the supplied arguments are unserializable. That is, the built-in serializer connot parse it or find a custom serializer that can. There may also be problems with the socket communication.

invoke

public final java.lang.Object invoke(java.lang.String method,
                                     java.lang.Object[] arguments)
                              throws XmlRpcException
Invokes a method on the terminating XML-RPC end point. The supplied method name and argument vector is used to encode the call into XML-RPC.

Parameters:
method - The name of the method to call.
arguments - The arguments to encode in the call.
Returns:
The object returned from the terminating XML-RPC end point.
Throws:
XmlRpcException - One or more of the supplied arguments are unserializable. That is, the built-in serializer connot parse it or find a custom serializer that can. There may also be problems with the socket communication.

invokeAsynchronously

public final void invokeAsynchronously(java.lang.String method,
                                       java.lang.Object arguments,
                                       XmlRpcCallback callback)
A asynchronous version of invoke performing the call in a separate thread and reporting responses, faults, and exceptions through the supplied XmlRpcCallback.

Parameters:
method - The name of the method at the server.
arguments - The arguments for the call. This may be either a java.util.Collection descendant, or a java.lang.Object[] array.
callback - An object implementing the XmlRpcCallback interface. If callback is null, the call will be performed but any results, faults, or exceptions will be ignored (fire and forget).

setKeepAlive

public void setKeepAlive(boolean keepAlive)
Determines if the client object should try to keep the socket connection to the server alive or not. Keeping it alive during several calls through the client may increase performance, but may consume unnecessary resources at the server if the client is called very rarely.

Parameters:
keepAlive - -- true or false.

setZipStream

public void setZipStream(boolean zipStream)
Determines if the XML payload sent to the server should be zipped or not. Zipping the payload requires a server that handles the "accept-encoding: gzip" HTTP header.

Parameters:
zipStream - -- true or false.

startElement

public void startElement(java.lang.String name,
                         org.xml.sax.AttributeList attributes)
                  throws org.xml.sax.SAXException
Override the startElement() method inherited from XmlRpcParser. This way, we may set the error flag if we run into a fault-tag.

Specified by:
startElement in interface org.xml.sax.DocumentHandler
Overrides:
startElement in class XmlRpcParser
Throws:
org.xml.sax.SAXException
See Also:
documentation