marquee.xmlrpc
Class XmlRpcClient

java.lang.Object
  marquee.xmlrpc.XmlRpcParser
      marquee.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