Package de.timroes.axmlrpc

Class 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, 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 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 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

      • 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_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.

      • 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_USE_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.