1Beware, this library contains a nasty vulnerability 2=================================================== 3 4As long as the vulnerability described in https://github.com/gturri/aXMLRPC/issues/143 is not fixed, you should probably not use aXMLRPC in your projects. :( 5 6What is aXMLRPC? 7================ 8 9aXMLRPC is a Java library with a leightweight XML-RPC client. XML-RPC is 10a specification for making remote procedure calls over the HTTP protocol 11in an XML format. The specificationc can be found under http://www.xmlrpc.com/spec. 12 13The library was developed for the use with Android. Since it has no dependencies to 14any Android library or any other 3rd-party library, it is fully functional in any 15common java virtual machine (not only on Android). 16 17You can control the client with some flags to extend its functionality. See the section 18about flags. 19 20How to include it? 21================== 22 23How to include the aXMLRPC client into your project? 24There are several ways to do that: 25 26### Include the source code 27 28You can just include all the source code from the `src` directory into the sourcecode 29of your project. If you use git yourself, you can use submodules to include the code 30as a module to yours. So you will always stay up to date with the library. 31 32### Compile it as library 33 34aXMLRPC uses maven, so you can build it using 35 36 mvn install 37 38### Use Maven 39 40To use it on your Maven project, add it as a dependency on your pom.xml file: 41 42```xml 43<dependency> 44 <groupId>fr.turri</groupId> 45 <artifactId>aXMLRPC</artifactId> 46 <version>X.Y.Z</version> 47</dependency> 48``` 49 50where X.Y.Z is the current aXMLRPC version 51 52 53How to use the library? 54======================= 55 56You can use the library by initiating an `XMLRPCClient` and make calls over it: 57 58```java 59try { 60 XMLRPCClient client = new XMLRPCClient(new URL("http://example.com/xmlrpc")); 61 62 Boolean b = (Boolean)client.call("isServerOk"); 63 Integer i = (Integer)client.call("add", 5, 10); 64} catch(XMLRPCServerException ex) { 65 // The server throw an error. 66} catch(XMLRPCException ex) { 67 // An error occured in the client. 68} catch(Exception ex) { 69 // Any other exception 70} 71``` 72 73Instead of passing the parameters as seperated values, you can also pack them in 74an array and pass the array to the method, like in the following example: 75 76```java 77// ... The try-catch has been ommited for clarity. 78XMLRPCClient client = new XMLRPCClient(url, "MyUserAgentString"); 79client.call("someMethod", new Object[]{ o1, o2, o3 }); 80// ... 81``` 82 83#### Asynchronous Calls 84 85The above method calls are synchronous. So the method `call` will return when the server responded 86or an error occured. There is also a possibility for asynchronous server calls. 87You need to implement an XMLRPCCallback that will get noticed about the respone (or error) from 88the server. The `callAsync` method can be used to make asynchronous calls. It returns an identifier 89that will also be send to the XMLRPCCallback instance with the response of the server, so your 90application can make multiple calls concurrently and use one listener for them, that distinguish 91between the different request by their ids. 92 93```java 94XMLRPCCallback listener = new XMLRPCCallback() { 95 public void onResponse(long id, Object result) { 96 // Handling the servers response 97 } 98 public void onError(long id, XMLRPCException error) { 99 // Handling any error in the library 100 } 101 public void onServerError(long id, XMLRPCServerException error) { 102 // Handling an error response from the server 103 } 104}; 105 106XMLRPCClient client = new XMLRPCClient(url); 107long id = client.callAsync(listener, "add", 5, 10); 108``` 109 110You will be also able to cancel an asynchonous call. Just use the `cancel` method on the `XMLRPCClient` instance, 111like in the following example. The listener will not be notified, if the call is canceled. 112 113```java 114XMLRPCClient client = new XMLRPCClient(url); 115long id = client.callAsync(listener, "method", params); 116// ... 117client.cancel(id); 118``` 119 120The data types 121-------------- 122 123The specification give some data tags for the server response. If you want to work on the 124type you must cast the returning `Object` from the `call` method to its specific type. 125Which type to cast which XML server response, tells the following list: 126 127`i4`,`int` => `Integer` 128 129`boolean` => `Boolean` 130 131`string` => `String` 132 133`double` => `Double` 134 135`dateTime.iso8601` => `Date` 136 137`base64` => `byte[]` (`Byte[]` won't work) 138 139`array` => `Object[]` 140 141`struct` => `Map<String,Object>` 142 143`i8` => `Long` (see Flags) 144 145 146Flags 147----- 148 149The client takes as second parameter (or third if an user agent is given) 150a combination of multiple flags. It could work like the following example: 151 152```java 153// ... 154XMLRPCClient client = new XMLRPCClient(url, 155 XMLRPCClient.FLAGS_STRICT | XMLRPCClient.FLAGS_8BYTE_INT); 156// ... 157``` 158 159The following flags are implemented: 160 161 162#### FLAGS_STRICT 163 164The client should parse responses strict to specification. 165It will check if the given content-type is right. 166The method name in a call must only contain of A-Z, a-z, 0-9, _, ., :, / 167Normally this is not needed. 168 169 170#### FLAGS_8BYTE_INT 171 172The client will be able to handle 8 byte integer values (longs). 173The xml type tag `<i8>` will be used. This is not in the specification 174but some libraries and servers support this behaviour. 175If this isn't enabled you cannot recieve 8 byte integers and if you try to 176send a long, the value must be within the 4 byte integer range. 177 178 179#### FLAGS_ENABLE_COOKIES 180 181With this flag, the client will be able to handle cookies, meaning saving cookies 182from the server and sending it with every other request again. This is needed 183for some XML-RPC interfaces that support login. 184 185 186#### FLAGS_NIL 187 188The client will be able to send `null` values. A `null` value will be send 189as `<nil/>`. This extension is described under: http://ontosys.com/xml-rpc/extensions.php 190 191 192#### FLAGS_IGNORE_STATUSCODE 193 194With this flag enabled, the XML-RPC client will ignore the HTTP status 195code of the response from the server. According to specification the 196status code must be 200. This flag is only needed for the use with 197not standard compliant servers. 198 199 200#### FLAGS_FORWARD 201 202With this flag enabled, the client will forward the request, if 203the 301 or 302 HTTP status code has been received. If this flag is not 204set, the client will throw an exception on these HTTP status codes. 205 206 207#### FLAGS_SSL_IGNORE_INVALID_HOST 208 209With this flag enabled, the client will ignore, if the URL doesn't match 210the SSL Certificate. This should be used with caution. Normally the URL 211should always match the URL in the SSL certificate, even with self signed 212certificates. 213 214 215#### FLAGS_SSL_INGORE_INVALID_CERT 216 217With this flag enabled, the client will ignore all unverified SSL/TLS 218certificates. This must be used, if you use self-signed certificates 219or certificated from unknown (or untrusted) authorities. 220 221 222#### FLAGS_DEFAULT_TYPE_STRING 223 224With this flag enabled, a value with a missing type tag, will be parsed 225as a string element. This is just for incoming messages. Outgoing messages 226will still be generated according to specification. 227 228 229#### FLAGS_IGNORE_NAMESPACES 230With this flag enabled, the client ignores all namespaces 231used within the response from the server. 232 233 234#### FLAGS_USE_SYSTEM_PROXY 235With this flag enabled, the XMLRPCClient will use the system http 236proxy to connect to the XML-RPC server. 237 238 239#### FLAGS_NO_STRING_ENCODE 240By default outgoing string values will be encoded according to specification. 241Meaning the & sign will be encoded to `&` and the "less then" sign to `<`. 242If you set this flag, the encoding won't be done for outgoing string values. 243See `FLAGS_NO_STRING_DECODE` for the counterpart. 244 245 246#### FLAGS_NO_STRING_DECODE 247This prevents the decoding of incoming strings, meaning `&` and `<` 248won't be decoded to the & sign and the "less then" sign. See 249`FLAGS_NO_STRING_ENCODE` for the counterpart. 250 251#### FLAGS_DEBUG 252Will display additional information on the console. 253Do not use it in production. 254 255#### FLAGS_ACCEPT_NULL_DATE 256By default a response with an empty date (eg: `<value><dateTime.iso8601/></value>`) 257is invalid and hence throws an exception. 258With this flag, this input is accepted, and returns a null date 259 260Meta Flags 261---------- 262 263This can be used exactly the same as normal flags. But each meta flag is just a 264collection of different other flags. There is no functional difference in using 265a meta flag or all the containing flags. For detailed documentation on the single 266flags read the above section. 267 268 269#### FLAGS_SSL_IGNORE_ERRORS 270 271This flag disables all SSL warnings. It is an alternative to use 272FLAGS_SSL_IGNORE_INVALID_CERT | FLAGS_SSL_IGNORE_INVALID_HOST. 273 274 275#### FLAGS_APACHE_WS 276 277This flag should be used if the server is an apache ws xmlrpc server. 278This will set some flags, so that the not standard conform behavior 279of the server will be ignored. 280This will enable the following flags: FLAGS_IGNORE_NAMESPACES, FLAGS_NIL, 281FLAGS_DEFAULT_TYPE_STRING 282 283Using an arbitrary transport 284============================ 285aXMLRPC uses http with the java.net API. If you want to use another protocol or API, you can do: 286 287```java 288 boolean debug = false; 289 // or you may build it with flags and/or a custom datetime format 290 SerializerHandler serializerHandler = new SerializerHandler(); 291 String payload = new Call(serializerHandler, "add", 5, 10).getXML(debug); 292 293 InputStream istream = sendPayloadWithMyTransport(payload); // use your implementation here 294 295 Integer i = (Integer) new ResponseParser.parse(serializerHandler, istream, debug); 296``` 297 298 299License 300======= 301 302The library is licensed under [MIT License] (http://www.opensource.org/licenses/mit-license.php). 303See the LICENSE file for the license text. 304 305For the uninformed reader: What does MIT mean? 306 307- You can copy this, modify it, distribute it, sell it, eat it. 308- You don't need to notice me about anything of the above. 309- If you make changes to it, it would be nice (but not obliged), if you would share it with me again. 310- Put the copyright notice and the LICENSE file in any copy you make. 311 312Bugs? 313===== 314 315If you find a bug or wish some enhancements for the library, please 316fill an issue here on github. 317 318Build status 319============ 320Status:  321
){kind=link}