project
Class XmlRpcClient

java.lang.Object
  |
  +--project.XmlRpcClient

public class XmlRpcClient
extends java.lang.Object

This class facilitates development of XML messaging clients which use HTTP(S) POSTing to synchronously exchange XML documents. This may be used directly, or be subclassed to add application-specific behaviours such as specialized processing for some element vocabularies found in those documents.


Constructor Summary
XmlRpcClient()
          Constructs a client; its URL must be set later.
XmlRpcClient(java.net.URL url)
          Constructs a client, and sets its URL.
 
Method Summary
 com.sun.xml.tree.XmlDocument call(com.sun.xml.tree.XmlDocument request)
          This method sends the HTTP/HTTPS POST request to the object identified by the URL passed to the constructor.
protected  void customizeDocument(com.sun.xml.tree.SimpleElementFactory factory, boolean trustDocuments)
          The request document that's built from the request can be customized, so that the generic DOM functionality can be augmented with behaviour specific to each element type.
protected  void customizeResolver(org.xml.sax.EntityResolver r)
          Subclasses can provide a customized entity resolver to be used when resolving external entities such as DTDs.
protected  boolean getCheckTypes()
          Returns true if all documents must be validated (the default), or false if the servers are trusted to provide correct data
 java.net.URL getUrl()
          Returns the URL for which this client is a proxy.
protected  void setCheckTypes(boolean value)
          This method is used to indicate whether servers are controlled well enough that the data they provide doesn't need the XML analogue of static type checking: validation.
 void setUrl(java.net.URL url)
          Sets the URL for which this client is a proxy (stand-in); this is a write-once attribute;
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XmlRpcClient

public XmlRpcClient()
Constructs a client; its URL must be set later.

XmlRpcClient

public XmlRpcClient(java.net.URL url)
Constructs a client, and sets its URL.
Method Detail

setUrl

public void setUrl(java.net.URL url)
Sets the URL for which this client is a proxy (stand-in); this is a write-once attribute;
Parameters:
url - the URL to which requests will be sent.
Throws:
IllegalStateException - if the URL is already assigned
java.lang.IllegalArgumentException - if the URL scheme is not "http" or "https".

getUrl

public java.net.URL getUrl()
Returns the URL for which this client is a proxy.

call

public com.sun.xml.tree.XmlDocument call(com.sun.xml.tree.XmlDocument request)
                                  throws java.io.IOException
This method sends the HTTP/HTTPS POST request to the object identified by the URL passed to the constructor. Subclasses (or wrapper classes) may choose to provide convenience methods layered over this method, perhaps automatically constructing request documents or performing partial response processing.
Parameters:
request - the document sent to the object for processing
Throws:
IllegalStateException - if the URL is not assigned

setCheckTypes

protected void setCheckTypes(boolean value)
This method is used to indicate whether servers are controlled well enough that the data they provide doesn't need the XML analogue of static type checking: validation. This is not the default, since it's hard to establish such a high level of control in large open systems, and weak type checking is a major source of errors in all systems. Even if validation isn't needed, errors in the well formedness of the XML response document will always cause fatal errors in the RPC invocation.

getCheckTypes

protected boolean getCheckTypes()
Returns true if all documents must be validated (the default), or false if the servers are trusted to provide correct data

customizeDocument

protected void customizeDocument(com.sun.xml.tree.SimpleElementFactory factory,
                                 boolean trustDocuments)
The request document that's built from the request can be customized, so that the generic DOM functionality can be augmented with behaviour specific to each element type. This method lets you describe the basic customizations to be performed, and optionally enable documents themselves to specify further customizations.
Parameters:
factory - used to acquire customized element nodes
trustDocuments - if true, the document can add its own mappings from element names to Java element node classes

customizeResolver

protected void customizeResolver(org.xml.sax.EntityResolver r)
Subclasses can provide a customized entity resolver to be used when resolving external entities such as DTDs. Typically, DTDs will be cached locally (perhaps as Java resources or files). In some cases, this handler may know how to handle other sorts of URI; for example, URIs which indicate the XML-formatted results of a database query.