redstone.xmlrpc
Class XmlRpcClient

java.lang.Object
  org.xml.sax.helpers.DefaultHandler
      redstone.xmlrpc.XmlRpcParser
          redstone.xmlrpc.XmlRpcClient

All Implemented Interfaces:

org.xml.sax.ContentHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler, XmlRpcInvocationHandler

public class XmlRpcClient
extends XmlRpcParser
implements XmlRpcInvocationHandler

An XmlRpcClient represents a connection to an XML-RPC enabled server. It implements the XmlRpcInvocationHandler so that it may be used as a relay to other XML-RPC servers when installed in an XmlRpcServer.

Author:

Greger Olsson

Field Summary

Fields inherited from class redstone.xmlrpc.XmlRpcParser

ARRAY, BASE64, BOOLEAN, DATE, DOUBLE, I4, I8, INT, MEMBER, NAME, STRING, STRUCT, VALUE

Constructor Summary

XmlRpcClient(java.lang.String url, boolean streamMessages)
Creates a new client with the ability to send XML-RPC messages to the the server at the given URL.

XmlRpcClient(java.net.URL url, boolean streamMessages)

Method Summary

java.util.Map	getResponseHeaderFields() Returns the HTTP header fields from the latest server invocation.
java.lang.Object	invoke(java.lang.String method, java.util.List 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.
void	setRequestProperties(java.util.Map requestProperties) Sets the HTTP request properties that the client will use for the next invocation, and any invocations that follow until setRequestProperties() is invoked again.
void	setRequestProperty(java.lang.String name, java.lang.String value) Sets a single HTTP request property to be used in future invocations.
void	startElement(java.lang.String uri, java.lang.String name, java.lang.String qualifiedName, org.xml.sax.Attributes attributes) Override the startElement() method inherited from XmlRpcParser.

Methods inherited from class redstone.xmlrpc.XmlRpcParser

characters, endElement, parse

Methods inherited from class org.xml.sax.helpers.DefaultHandler

endDocument, endPrefixMapping, error, fatalError, ignorableWhitespace, notationDecl, processingInstruction, resolveEntity, setDocumentLocator, skippedEntity, startDocument, startPrefixMapping, unparsedEntityDecl, warning

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XmlRpcClient

public XmlRpcClient(java.lang.String url,
                    boolean streamMessages)
             throws java.net.MalformedURLException

Creates a new client with the ability to send XML-RPC messages to the the server at the given URL.

Parameters:

url - the URL at which the XML-RPC service is locaed

streamMessages - Indicates whether or not to stream messages directly or if the messages should be completed locally before being sent all at once. Streaming is not directly supported by XML-RPC, since the Content-Length header is not included in the HTTP post. If the other end is not relying on Content-Length, streaming the message directly is much more efficient.

Throws:

java.net.MalformedURLException

XmlRpcClient

public XmlRpcClient(java.net.URL url,
                    boolean streamMessages)

See Also:

XmlRpcClient(String,boolean)

Method Detail

setRequestProperties

public void setRequestProperties(java.util.Map requestProperties)

Sets the HTTP request properties that the client will use for the next invocation, and any invocations that follow until setRequestProperties() is invoked again. Null is accepted and means that no special HTTP request properties will be used in any future XML-RPC invocations using this XmlRpcClient instance.

Parameters:

requestProperties - The HTTP request properties to use for future invocations made using this XmlRpcClient instance. These will replace any previous properties set using this method or the setRequestProperty() method.

setRequestProperty

public void setRequestProperty(java.lang.String name,
                               java.lang.String value)

Sets a single HTTP request property to be used in future invocations.

Parameters:

name - Name of the property to set

value - The value of the property

See Also:

setRequestProperties(Map)

invoke

public java.lang.Object invoke(java.lang.String method,
                               java.util.List arguments)
                        throws XmlRpcException,
                               XmlRpcFault

Invokes a method on the terminating XML-RPC end point. The supplied method name and argument collection is used to encode the call into an XML-RPC compatible message.

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.

XmlRpcFault - Error occurred in the method call.

invoke

public java.lang.Object invoke(java.lang.String method,
                               java.lang.Object[] arguments)
                        throws XmlRpcException,
                               XmlRpcFault

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.

XmlRpcFault

getResponseHeaderFields

public java.util.Map getResponseHeaderFields()

Returns the HTTP header fields from the latest server invocation. These are the fields set by the HTTP server hosting the XML-RPC service.

Returns:

The HTTP header fields from the latest server invocation. Note that the XmlRpcClient instance retains ownership of this map and the map contents is replaced on the next request. If there is a need to keep the fields between requests the map returned should be cloned.

invokeAsynchronously

public 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. TODO Determine on proper strategy for instantiating Threads.

Parameters:

method - The name of the method at the server.

arguments - The arguments for the call. This may be either a java.util.List 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).

startElement

public void startElement(java.lang.String uri,
                         java.lang.String name,
                         java.lang.String qualifiedName,
                         org.xml.sax.Attributes 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.ContentHandler

Overrides:

startElement in class XmlRpcParser

Parameters:

uri -

name -

qualifiedName -

attributes -

Throws:

org.xml.sax.SAXException