Package 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.- Author:
- Tim Roes
-
-
Field Summary
Fields Modifier and Type Field 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_DEBUG
Activate debug mode.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, theXMLRPCClient
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, theXMLRPCClient
will use the system http proxy to connect to the XML-RPC server.static java.lang.String
VALUE
-
Constructor Summary
Constructors Constructor 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
All Methods Instance Methods Concrete Methods Modifier and Type Method 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 aMap
of all cookies.java.net.URL
getURL()
Returns the URL this XMLRPCClient is connected to.void
installCustomKeyManager(javax.net.ssl.KeyManager keyManager)
Installs a customKeyManager
to handle SSL/TLS certificate verification.void
installCustomKeyManagers(javax.net.ssl.KeyManager[] keyManagers)
Installs customKeyManagers
to handle SSL/TLS certificate verification.void
installCustomTrustManager(javax.net.ssl.TrustManager trustManager)
Installs a customTrustManager
to handle SSL/TLS certificate verification.void
installCustomTrustManagers(javax.net.ssl.TrustManager[] trustManagers)
Installs customTrustManagers
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.
-
-
-
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 toinstallCustomTrustManager(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, theXMLRPCClient
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, theXMLRPCClient
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. SeeFLAGS_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. SeeFLAGS_NO_STRING_ENCODE
for the counterpart.- See Also:
- Constant Field Values
-
FLAGS_DEBUG
public static final int FLAGS_DEBUG
Activate debug mode. Do NOT use if you don't need it.- 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. Iftimeout
will be zero or less the connection will never timeout. In case the connection times out anXMLRPCTimeoutException
will be thrown for calls made bycall(java.lang.String, java.lang.Object[])
. For calls made bycallAsync(de.timroes.axmlrpc.XMLRPCCallback, java.lang.String, java.lang.Object[])
theXMLRPCCallback.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, useFLAGS_USE_SYSTEM_PROXY
instead. If combined withFLAGS_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
- Usernamepass
- 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 aMap
of all cookies. It contains each cookie key as a map key and its value as a map value. Cookies will only be used ifFLAGS_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 customTrustManager
to handle SSL/TLS certificate verification. This will replace any previously installedTrustManager
s. IfFLAGS_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 customTrustManagers
to handle SSL/TLS certificate verification. This will replace any previously installedTrustManagers
s. IfFLAGS_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 customKeyManager
to handle SSL/TLS certificate verification. This will replace any previously installedKeyManager
s. IfFLAGS_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 customKeyManagers
to handle SSL/TLS certificate verification. This will replace any previously installedKeyManagers
s. IfFLAGS_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.
-
-