An XML-RPC client is a program that connects to a server, calls a method on a program on that server, and stores the result. Using Apache XML-RPC, the process is comparable to calling any other method in Java—you don’t have to create an XML request, parse an XML response, or connect to the server using one of Java’s networking classes. In the org.apache.xmlrpc package, the XmlRpcClient class represents a client. An XmlRpcClient object can be created in three ways, each of which requires the URL of the server:
· XmlRpcClient(String)—Create a client connecting to an address specified by the String, which must be a valid web address (such as http://www.example.com) or web address and port number (such ashttp://www.example.com:2274)
· XmlRpcClient(URL)—Create a client connecting to the specified URL object
· XmlRpcClient(String, int)—Create a client connecting to the specified hostname (String) and port number (int)
The two constructors that require a String argument throw java.net.MalformedURLException exceptions if the argument is not a valid web URL. The following statement creates a client to an XML-RPC client on the host cadenhead. org at the port 4413:
XmlRpcClient client = new XmlRpcClient(“http://cadenhead.org:4413”);
If you are calling a remote method with any arguments, they should be stored in a Vector object, a data structure that holds objects of different classes.
To work with vectors, call the Vector() constructor with no arguments and call its addElement(Object) method with each object that should be added to the vector. Objects can be of any class and must be added to the vector in the order that they are called in the remote method. The following data types can be arguments to a remote method:
· byte[] arrays for base64 data
· Boolean objects for boolean values
· Date objects for dateTime.iso8601 values
· Double objects for double values
· Integer objects for int values
· String objects for string values
· Hashtable objects for struct values
· Vector objects for arrays
The Date, Hashtable, and Vector classes are in the java.util package. For example, if an XML-RPC server has a method that takes String and double arguments, the following code creates a vector that holds each of the arguments:
· The name of the method
· The vector that holds the method’s arguments
The name of the method should be specified without any parentheses or arguments. An XML-RPC server usually documents the methods that it makes available to the public— for example, there really is a cadenhead.org XML-RPC server that operates on port 4413 (it’s my own test server). It offers dmoz.getRandomSite(), a method that returns an Object containing information about a random website. This method has no arguments.
The following statements create an XML-RPC client and call this method:
The execute() method returns an Object that contains the response. This object should be cast to one of the data types sent to a method as arguments: Boolean, byte[], Date, Double, Integer, String, Hashtable, or Vector. Like other networking methods in Java, execute() throws a java.net.IOException exception if an input/output error occurs during the connection between client and server.
There’s also an XmlRpcException exception that is thrown if the server reports an XMLRPC error. Objects returned by the execute() method have the following data types:
Boolean for boolean XML-RPC values, byte[] for base64 data, Date for dateTime.iso8601 data, Double for double values, Integer for int (or i4) values, String for strings, Hashtable for struct values, and Vector for arrays.
To see all this in a working program, enter the text of Listing 20.3 into your text editor and save the file as SiteClient.java.
The SiteClient application makes a connection to the XML-RPC server and calls the dmoz.getRandomSite() method on the server with no arguments. This method returns a Vector that contains four strings: “ok” (to show that the request was fulfilled) and the site’s URL, title, and description
The output for the SiteClient application should resemble the following:
