/README.md
Markdown | 314 lines | 214 code | 100 blank | 0 comment | 0 complexity | 40230848ea40ad2e1db3197d5ff2f21d MD5 | raw file
- What is aXMLRPC?
- ================
- aXMLRPC is a Java library with a leightweight XML-RPC client. XML-RPC is
- a specification for making remote procedure calls over the HTTP protocol
- in an XML format. The specificationc can be found under http://www.xmlrpc.com/spec.
- The library was developed for the use with Android. Since it has no dependencies to
- any Android library or any other 3rd-party library, it is fully functional in any
- common java virtual machine (not only on Android).
- You can control the client with some flags to extend its functionality. See the section
- about flags.
- How to include it?
- ==================
- How to include the aXMLRPC client into your project?
- There are several ways to do that:
- ### Include the source code
- You can just include all the source code from the `src` directory into the sourcecode
- of your project. If you use git yourself, you can use submodules to include the code
- as a module to yours. So you will always stay up to date with the library.
- ### Compile it as library
- aXMLRPC uses maven, so you can build it using
- mvn install
- ### Use Maven
- To use it on your Maven project, add it as a dependency on your pom.xml file:
- ```xml
- <dependency>
- <groupId>fr.turri</groupId>
- <artifactId>aXMLRPC</artifactId>
- <version>X.Y.Z</version>
- </dependency>
- ```
- where X.Y.Z is the current aXMLRPC version
- How to use the library?
- =======================
- You can use the library by initiating an `XMLRPCClient` and make calls over it:
- ```java
- try {
- XMLRPCClient client = new XMLRPCClient(new URL("http://example.com/xmlrpc"));
- Boolean b = (Boolean)client.call("isServerOk");
- Integer i = (Integer)client.call("add", 5, 10);
- } catch(XMLRPCServerException ex) {
- // The server throw an error.
- } catch(XMLRPCException ex) {
- // An error occured in the client.
- } catch(Exception ex) {
- // Any other exception
- }
- ```
- Instead of passing the parameters as seperated values, you can also pack them in
- an array and pass the array to the method, like in the following example:
- ```java
- // ... The try-catch has been ommited for clarity.
- XMLRPCClient client = new XMLRPCClient(url, "MyUserAgentString");
- client.call("someMethod", new Object[]{ o1, o2, o3 });
- // ...
- ```
- #### Asynchronous Calls
- The above method calls are synchronous. So the method `call` will return when the server responded
- or an error occured. There is also a possibility for asynchronous server calls.
- You need to implement an XMLRPCCallback that will get noticed about the respone (or error) from
- the server. The `callAsync` method can be used to make asynchronous calls. It returns an identifier
- that will also be send to the XMLRPCCallback instance with the response of the server, so your
- application can make multiple calls concurrently and use one listener for them, that distinguish
- between the different request by their ids.
- ```java
- XMLRPCCallback listener = new XMLRPCCallback() {
- public void onResponse(long id, Object result) {
- // Handling the servers response
- }
- public void onError(long id, XMLRPCException error) {
- // Handling any error in the library
- }
- public void onServerError(long id, XMLRPCServerException error) {
- // Handling an error response from the server
- }
- };
- XMLRPCClient client = new XMLRPCClient(url);
- long id = client.callAsync(listener, "add", 5, 10);
- ```
- You will be also able to cancel an asynchonous call. Just use the `cancel` method on the `XMLRPCClient` instance,
- like in the following example. The listener will not be notified, if the call is canceled.
- ```java
- XMLRPCClient client = new XMLRPCClient(url);
- long id = client.callAsync(listener, "method", params);
- // ...
- client.cancel(id);
- ```
- The data types
- --------------
- The specification give some data tags for the server response. If you want to work on the
- type you must cast the returning `Object` from the `call` method to its specific type.
- Which type to cast which XML server response, tells the following list:
- `i4`,`int` => `Integer`
- `boolean` => `Boolean`
- `string` => `String`
- `double` => `Double`
- `dateTime.iso8601` => `Date`
- `base64` => `byte[]` (`Byte[]` won't work)
- `array` => `Object[]`
- `struct` => `Map<String,Object>`
- `i8` => `Long` (see Flags)
- Flags
- -----
- The client takes as second parameter (or third if an user agent is given)
- a combination of multiple flags. It could work like the following example:
- ```java
- // ...
- XMLRPCClient client = new XMLRPCClient(url,
- XMLRPCClient.FLAGS_STRICT | XMLRPCClient.FLAGS_8BYTE_INT);
- // ...
- ```
- The following flags are implemented:
- #### 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.
- #### 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 4 byte integer range.
- #### 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.
- #### FLAGS_NIL
- The client will be able to send `null` values. A `null` value will be send
- as `<nil/>`. This extension is described under: http://ontosys.com/xml-rpc/extensions.php
- #### 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.
- #### 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 is not
- set, the client will throw an exception on these HTTP status codes.
- #### 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.
- #### FLAGS_SSL_INGORE_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.
- #### 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.
- #### FLAGS_IGNORE_NAMESPACES
- With this flag enabled, the client ignores all namespaces
- used within the response from the server.
- #### FLAGS_USE_SYSTEM_PROXY
- With this flag enabled, the XMLRPCClient will use the system http
- proxy to connect to the XML-RPC server.
- #### 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_DECODE` for the counterpart.
- #### 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.
- #### FLAGS_DEBUG
- Will display additional information on the console.
- Do not use it in production.
- #### FLAGS_ACCEPT_NULL_DATE
- By default a response with an empty date (eg: `<value><dateTime.iso8601/></value>`)
- is invalid and hence throws an exception.
- With this flag, this input is accepted, and returns a null date
- Meta Flags
- ----------
- This can be used exactly the same as normal flags. But each meta flag is just a
- collection of different other flags. There is no functional difference in using
- a meta flag or all the containing flags. For detailed documentation on the single
- flags read the above section.
- #### 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.
- #### 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
- Using an arbitrary transport
- ============================
- aXMLRPC uses http with the java.net API. If you want to use another protocol or API, you can do:
- ```java
- boolean debug = false;
- SerializerHandler serializerHandler = new SerializerHandler(); // or you may build it with flags
- String payload = new Call(serializerHandler, "add", 5, 10).getXML(debug);
- InputStream istream = sendPayloadWithMyTransport(payload); // use your implementation here
- Integer i = (Integer) new ResponseParser.parse(serializerHandler, istream, debug);
- ```
- License
- =======
- The library is licensed under [MIT License] (http://www.opensource.org/licenses/mit-license.php).
- See the LICENSE file for the license text.
- For the uninformed reader: What does MIT mean?
- - You can copy this, modify it, distribute it, sell it, eat it.
- - You don't need to notice me about anything of the above.
- - If you make changes to it, it would be nice (but not obliged), if you would share it with me again.
- - Put the copyright notice and the LICENSE file in any copy you make.
- Bugs?
- =====
- If you find a bug or wish some enhancements for the library, please
- fill an issue here on github.
- Build status
- ============
- Status: ![Status](https://travis-ci.org/gturri/aXMLRPC.svg?branch=master)