de.timroes.axmlrpc

Class XMLRPCClient

java.lang.Object

de.timroes.axmlrpc.XMLRPCClient

public class XMLRPCClient
extends java.lang.Object

An XMLRPCClient is a client used to make XML-RPC (Extensible Markup Language Remote Procedure Calls). The specification of XMLRPC can be found at http://www.xmlrpc.com/spec. You can use flags to extend the functionality of the client to some extras. Further information on the flags can be found in the documentation of these. For a documentation on how to use this class see also the README file delivered with the source of this library.

Field Summary

Fields

Modifier and Type	Field and Description
static int	FLAGS_8BYTE_INT The client will be able to handle 8 byte integer values (longs).
static int	FLAGS_APACHE_WS This flag should be used if the server is an apache ws xmlrpc server.
static int	FLAGS_DEFAULT_TYPE_STRING With this flag enabled, a value with a missing type tag, will be parsed as a string element.
static int	FLAGS_ENABLE_COOKIES With this flag, the client will be able to handle cookies, meaning saving cookies from the server and sending it with every other request again.
static int	FLAGS_FORWARD With this flag enabled, the client will forward the request, if the 301 or 302 HTTP status code has been received.
static int	FLAGS_IGNORE_NAMESPACES With this flag enabled, the XMLRPCClient ignores all namespaces used within the response from the server.
static int	FLAGS_IGNORE_STATUSCODE With this flag enabled, the XML-RPC client will ignore the HTTP status code of the response from the server.
static int	FLAGS_NIL The client will be able to send null values.
static int	FLAGS_NO_STRING_DECODE This prevents the decoding of incoming strings, meaning & and < won't be decoded to the & sign and the "less then" sign.
static int	FLAGS_NO_STRING_ENCODE By default outgoing string values will be encoded according to specification.
static int	FLAGS_NONE No flags should be set.
static int	FLAGS_SSL_IGNORE_ERRORS This flag disables all SSL warnings.
static int	FLAGS_SSL_IGNORE_INVALID_CERT With this flag enabled, the client will ignore all unverified SSL/TLS certificates.
static int	FLAGS_SSL_IGNORE_INVALID_HOST With this flag enabled, the client will ignore, if the URL doesn't match the SSL Certificate.
static int	FLAGS_STRICT The client should parse responses strict to specification.
static int	FLAGS_USE_SYSTEM_PROXY With this flag enabled, the XMLRPCClient will use the system http proxy to connect to the XML-RPC server.
static java.lang.String	VALUE

Constructor Summary

Constructors

Constructor and Description
XMLRPCClient(java.net.URL url) Create a new XMLRPC client for the given url.
XMLRPCClient(java.net.URL url, int flags) Create a new XMLRPC client for the given URL.
XMLRPCClient(java.net.URL url, java.lang.String userAgent) Create a new XMLRPC client for the given url.
XMLRPCClient(java.net.URL url, java.lang.String userAgent, int flags) Create a new XMLRPC client for the given URL.

Method Summary

Methods

Modifier and Type	Method and Description
java.lang.Object	call(java.lang.String method, java.lang.Object... params) Call a remote procedure on the server.
long	callAsync(XMLRPCCallback listener, java.lang.String methodName, java.lang.Object... params) Asynchronously call a remote procedure on the server.
void	cancel(long id) Cancel a specific asynchronous call.
void	clearCookies() Delete all cookies currently used by the client.
void	clearLoginData() Clear the username and password.
java.util.Map<java.lang.String,java.lang.String>	getCookies() Returns a Map of all cookies.
java.net.URL	getURL() Returns the URL this XMLRPCClient is connected to.
void	installCustomKeyManager(javax.net.ssl.KeyManager keyManager) Installs a custom KeyManager to handle SSL/TLS certificate verification.
void	installCustomKeyManagers(javax.net.ssl.KeyManager[] keyManagers) Installs custom KeyManagers to handle SSL/TLS certificate verification.
void	installCustomTrustManager(javax.net.ssl.TrustManager trustManager) Installs a custom TrustManager to handle SSL/TLS certificate verification.
void	installCustomTrustManagers(javax.net.ssl.TrustManager[] trustManagers) Installs custom TrustManagers to handle SSL/TLS certificate verification.
void	setCustomHttpHeader(java.lang.String headerName, java.lang.String headerValue) Set a HTTP header field to a custom value.
void	setLoginData(java.lang.String user, java.lang.String pass) Set the username and password that should be used to perform basic http authentication.
void	setProxy(java.net.Proxy proxy) Sets a proxy to use for this client.
void	setTimeout(int timeout) Sets the time in seconds after which a call should timeout.
void	setUserAgentString(java.lang.String userAgent) Sets the user agent string.

Methods inherited from class java.lang.Object

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

Field Detail

VALUE

public static final java.lang.String VALUE

See Also:

Constant Field Values

FLAGS_NONE

public static final int FLAGS_NONE

No flags should be set.

See Also:

Constant Field Values

FLAGS_STRICT

public static final int FLAGS_STRICT

The client should parse responses strict to specification. It will check if the given content-type is right. The method name in a call must only contain of A-Z, a-z, 0-9, _, ., :, / Normally this is not needed.

See Also:

Constant Field Values

FLAGS_8BYTE_INT

public static final int FLAGS_8BYTE_INT

The client will be able to handle 8 byte integer values (longs). The xml type tag <i8> will be used. This is not in the specification but some libraries and servers support this behaviour. If this isn't enabled you cannot recieve 8 byte integers and if you try to send a long the value must be within the 4byte integer range.

See Also:

Constant Field Values

FLAGS_ENABLE_COOKIES

public static final int FLAGS_ENABLE_COOKIES

With this flag, the client will be able to handle cookies, meaning saving cookies from the server and sending it with every other request again. This is needed for some XML-RPC interfaces that support login.

See Also:

Constant Field Values

FLAGS_NIL

public static final int FLAGS_NIL

The client will be able to send null values. A null value will be send as . This extension is described under: http://ontosys.com/xml-rpc/extensions.php

See Also:

Constant Field Values

FLAGS_IGNORE_STATUSCODE

public static final int FLAGS_IGNORE_STATUSCODE

With this flag enabled, the XML-RPC client will ignore the HTTP status code of the response from the server. According to specification the status code must be 200. This flag is only needed for the use with not standard compliant servers.

See Also:

Constant Field Values

FLAGS_FORWARD

public static final int FLAGS_FORWARD

With this flag enabled, the client will forward the request, if the 301 or 302 HTTP status code has been received. If this flag has not been set, the client will throw an exception on these HTTP status codes.

See Also:

Constant Field Values

FLAGS_SSL_IGNORE_INVALID_HOST

public static final int FLAGS_SSL_IGNORE_INVALID_HOST

With this flag enabled, the client will ignore, if the URL doesn't match the SSL Certificate. This should be used with caution. Normally the URL should always match the URL in the SSL certificate, even with self signed certificates.

See Also:

Constant Field Values

FLAGS_SSL_IGNORE_INVALID_CERT

public static final int FLAGS_SSL_IGNORE_INVALID_CERT

With this flag enabled, the client will ignore all unverified SSL/TLS certificates. This must be used, if you use self-signed certificates or certificated from unknown (or untrusted) authorities. If this flag is used, calls to installCustomTrustManager(javax.net.ssl.TrustManager) won't have any effect.

See Also:

Constant Field Values

FLAGS_DEFAULT_TYPE_STRING

public static final int FLAGS_DEFAULT_TYPE_STRING

With this flag enabled, a value with a missing type tag, will be parsed as a string element. This is just for incoming messages. Outgoing messages will still be generated according to specification.

See Also:

Constant Field Values

FLAGS_IGNORE_NAMESPACES

public static final int FLAGS_IGNORE_NAMESPACES

With this flag enabled, the XMLRPCClient ignores all namespaces used within the response from the server.

See Also:

Constant Field Values

FLAGS_USE_SYSTEM_PROXY

public static final int FLAGS_USE_SYSTEM_PROXY

With this flag enabled, the XMLRPCClient will use the system http proxy to connect to the XML-RPC server.

See Also:

Constant Field Values

FLAGS_NO_STRING_DECODE

public static final int FLAGS_NO_STRING_DECODE

This prevents the decoding of incoming strings, meaning & and < won't be decoded to the & sign and the "less then" sign. See FLAGS_NO_STRING_ENCODE for the counterpart.

See Also:

Constant Field Values

FLAGS_NO_STRING_ENCODE

public static final int FLAGS_NO_STRING_ENCODE

By default outgoing string values will be encoded according to specification. Meaning the & sign will be encoded to & and the "less then" sign to <. If you set this flag, the encoding won't be done for outgoing string values. See FLAGS_NO_STRING_ENCODE for the counterpart.

See Also:

Constant Field Values

FLAGS_SSL_IGNORE_ERRORS

public static final int FLAGS_SSL_IGNORE_ERRORS

This flag disables all SSL warnings. It is an alternative to use FLAGS_SSL_IGNORE_INVALID_CERT | FLAGS_SSL_IGNORE_INVALID_HOST. There is no functional difference.

See Also:

Constant Field Values

FLAGS_APACHE_WS

public static final int FLAGS_APACHE_WS

This flag should be used if the server is an apache ws xmlrpc server. This will set some flags, so that the not standard conform behavior of the server will be ignored. This will enable the following flags: FLAGS_IGNORE_NAMESPACES, FLAGS_NIL, FLAGS_DEFAULT_TYPE_STRING

See Also:

Constant Field Values

Constructor Detail

XMLRPCClient

public XMLRPCClient(java.net.URL url,
            java.lang.String userAgent,
            int flags)

Create a new XMLRPC client for the given URL.

Parameters:

url - The URL to send the requests to.

userAgent - A user agent string to use in the HTTP requests.

flags - A combination of flags to be set.

XMLRPCClient

public XMLRPCClient(java.net.URL url,
            int flags)

Create a new XMLRPC client for the given URL. The default user agent string will be used.

Parameters:

url - The URL to send the requests to.

flags - A combination of flags to be set.

XMLRPCClient

public XMLRPCClient(java.net.URL url,
            java.lang.String userAgent)

Create a new XMLRPC client for the given url. No flags will be set.

Parameters:

url - The url to send the requests to.

userAgent - A user agent string to use in the http request.

XMLRPCClient

public XMLRPCClient(java.net.URL url)

Create a new XMLRPC client for the given url. No flags will be used. The default user agent string will be used.

Parameters:

url - The url to send the requests to.

Method Detail

getURL

public java.net.URL getURL()

Returns the URL this XMLRPCClient is connected to. If that URL permanently forwards to another URL, this method will return the forwarded URL, as soon as the first call has been made.

Returns:

Returns the URL for this XMLRPCClient.

setTimeout

public void setTimeout(int timeout)

Sets the time in seconds after which a call should timeout. If timeout will be zero or less the connection will never timeout. In case the connection times out and XMLRPCTimeoutException will be thrown for calls made by call(java.lang.String, java.lang.Object[]). For calls made by callAsync(de.timroes.axmlrpc.XMLRPCCallback, java.lang.String, java.lang.Object[]) the XMLRPCCallback.onError(long, de.timroes.axmlrpc.XMLRPCException) method of the callback will be called. By default connections won't timeout.

Parameters:

timeout - The timeout for connections in seconds.

setUserAgentString

public void setUserAgentString(java.lang.String userAgent)

Sets the user agent string. If this method is never called the default user agent 'aXMLRPC' will be used.

Parameters:

userAgent - The new user agent string.

setProxy

public void setProxy(java.net.Proxy proxy)

Sets a proxy to use for this client. If you want to use the system proxy, use #FLAGS_adbUSE_SYSTEM_PROXY instead. If combined with FLAGS_USE_SYSTEM_PROXY, this proxy will be used instead of the system proxy.

Parameters:

proxy - A proxy to use for the connection.

setCustomHttpHeader

public void setCustomHttpHeader(java.lang.String headerName,
                       java.lang.String headerValue)

Set a HTTP header field to a custom value. You cannot modify the Host or Content-Type field that way. If the field already exists, the old value is overwritten.

Parameters:

headerName - The name of the header field.

headerValue - The new value of the header field.

setLoginData

public void setLoginData(java.lang.String user,
                java.lang.String pass)

Set the username and password that should be used to perform basic http authentication.

Parameters:

user - Username

pass - Password

clearLoginData

public void clearLoginData()

Clear the username and password. No basic HTTP authentication will be used in the next calls.

getCookies

public java.util.Map<java.lang.String,java.lang.String> getCookies()

Returns a Map of all cookies. It contains each cookie key as a map key and its value as a map value. Cookies will only be used if FLAGS_ENABLE_COOKIES has been set for the client. This map will also be available (and empty) when this flag hasn't been said, but has no effect on the HTTP connection.

Returns:

A Map of all cookies.

clearCookies

public void clearCookies()

Delete all cookies currently used by the client. This method has only an effect, as long as the FLAGS_ENABLE_COOKIES has been set on this client.

installCustomTrustManager

public void installCustomTrustManager(javax.net.ssl.TrustManager trustManager)

Installs a custom TrustManager to handle SSL/TLS certificate verification. This will replace any previously installed TrustManagers. If FLAGS_SSL_IGNORE_INVALID_CERT is set, this won't do anything.

Parameters:

trustManager - TrustManager to install.

See Also:

installCustomTrustManagers(javax.net.ssl.TrustManager[])

installCustomTrustManagers

public void installCustomTrustManagers(javax.net.ssl.TrustManager[] trustManagers)

Installs custom TrustManagers to handle SSL/TLS certificate verification. This will replace any previously installed TrustManagerss. If FLAGS_SSL_IGNORE_INVALID_CERT is set, this won't do anything.

Parameters:

trustManagers - TrustManagers to install.

See Also:

installCustomTrustManager(javax.net.ssl.TrustManager)

installCustomKeyManager

public void installCustomKeyManager(javax.net.ssl.KeyManager keyManager)

Installs a custom KeyManager to handle SSL/TLS certificate verification. This will replace any previously installed KeyManagers. If FLAGS_SSL_IGNORE_INVALID_CERT is set, this won't do anything.

Parameters:

keyManager - KeyManager to install.

See Also:

installCustomKeyManagers(javax.net.ssl.KeyManager[])

installCustomKeyManagers

public void installCustomKeyManagers(javax.net.ssl.KeyManager[] keyManagers)

Installs custom KeyManagers to handle SSL/TLS certificate verification. This will replace any previously installed KeyManagerss. If FLAGS_SSL_IGNORE_INVALID_CERT is set, this won't do anything.

Parameters:

keyManagers - KeyManagers to install.

See Also:

installCustomKeyManager(javax.net.ssl.KeyManager)

call

public java.lang.Object call(java.lang.String method,
                    java.lang.Object... params)
                      throws XMLRPCException

Call a remote procedure on the server. The method must be described by a method name. If the method requires parameters, this must be set. The type of the return object depends on the server. You should consult the server documentation and then cast the return value according to that. This method will block until the server returned a result (or an error occurred). Read the README file delivered with the source code of this library for more information.

Parameters:

method - A method name to call.

params - An array of parameters for the method.

Returns:

The result of the server.

Throws:

XMLRPCException - Will be thrown if an error occurred during the call.

callAsync

public long callAsync(XMLRPCCallback listener,
             java.lang.String methodName,
             java.lang.Object... params)

Asynchronously call a remote procedure on the server. The method must be described by a method name. If the method requires parameters, this must be set. When the server returns a response the onResponse method is called on the listener. If the server returns an error the onServerError method is called on the listener. The onError method is called whenever something fails. This method returns immediately and returns an identifier for the request. All listener methods get this id as a parameter to distinguish between multiple requests.

Parameters:

listener - A listener, which will be notified about the server response or errors.

methodName - A method name to call on the server.

params - An array of parameters for the method.

Returns:

The id of the current request.

cancel

public void cancel(long id)

Cancel a specific asynchronous call.

Parameters:

id - The id of the call as returned by the callAsync method.