necessary-evil

necessary-evil is an implementation of XML-RPC built on top of the ring http library for Clojure. XML-RPC is a bit nasty, but it is the basis of a number of other standards such as certain blogging APIs and Ping Back.

necessary-evil will only work with Java 6+, and Clojure 1.2.1+

Usage

(require '[necessary-evil.core :as xml-rpc])

Making a client request is very simple:

(xml-rpc/call "http://example.com/rpc" :hello "World") 

This will either return a clojure data structure or, if there is a fault, a necessary-evil.methodresponse.Fault record. For the example above, you might expect something like "Hello, World!" to be returned. See xml-rpc mappings below for details of how xml-rpc data is converted to clojure data and vice versa.

Call accepts the arguments to the remote method as varags after the method name.

Here is a simple hello world request handler:

(use '[ring.adapter.jetty :only [run-jetty]]) 
    
(def handler (xml-rpc/end-point 
     {:hello (fn hello 
        ([] (hello "World"))
        ([name] (str "Hello, " name "!")))}))
    
(run-jetty handler {:port 3000 :join? false})

Methods are :keyword iFn pairs in the method map passed to end-point.

As XML-RPC requests are always HTTP POST requests, necessary-evil implements a very bare bones GET handler that returns a comma separated list of method names.

The handler generated by end-point should work properly with any other ring handler, and should play nice with middleware or any other ring library such as compojure or moustache.

Compojure example:

The following is a trivial example to attach an xml-rpc endpoint into a hello world compojure application:

(require '[necessary-evil.core :as xmlrpc])  
(use '[ring.adapter.jetty :only [run-jetty]])   
(use '[compojure.core :only [defroutes GET ANY]])
    
(def ep (xmlrpc/end-point 
          {:hello (fn [n] (str "Hello, " n "!"))}))

(defroutes handler 
  (GET "/hello" [] "Hello!")
  (ANY "/xml" [] ep))

(run-jetty #'handler {:port 3000 :join? false})

In this application / is a 404, /hello returns "Hello!", and /xml is the xmlrpc handler.

Moustache example:

This snippet implements the same server as the one above for Compojure:

(require '[necessary-evil.core :as xmlrpc])  
(use '[ring.adapter.jetty :only [run-jetty]])   
(use '[net.cgrand.moustache :only [app]])                                        
    
(def ep (xmlrpc/end-point 
          {:hello (fn [n] (str "Hello, " n "!"))}))
(def handler
  (app ["hello"] {:get "Hello!"} 
       ["xml"] ep))
    
(run-jetty #'handler {:port 3000 :join? false})

Just as in the compojure example above, / is a 404, /hello returns "Hello!", and /xml is the xmlrpc handler.

xml-rpc mappings

These tables describes the mapping of clojure datastructures and types to XML-RPC types. Note that as of version 2.0.0 these are no longer symmetric operations.

XML-RPC → Clojure
XML-RPC Element	Clojure or Java type
array	clojure.lang.IPersistentVector
base64	byte-array
boolean	java.lang.Boolean
dateTime.iso8601	org.joda.time.DateTime
double	java.lang.Double
i4	java.lang.Integer
int	java.lang.Integer
struct	clojure.lang.IPersistantMap — clojure.lang.Keyword keys
no element	java.lang.String

Clojure → XML-RPC
Clojure or Java type	XML-RPC Element
byte-array	base64
clojure.lang.IPersistantMap — clojure.lang.Keyword keys	struct
clojure.lang.Sequential	array
java.lang.Boolean	boolean
java.lang.Double	double
java.lang.Integer	int
java.lang.Long	int – Longs that are greater than Integer/MAX_VALUE will cause an exception to be thrown.
java.lang.String	string
java.util.Date	dateTime.iso8601
org.joda.time.DateTime	dateTime.iso8601

Note: nil is conspicuously absent from the list of types; this is because the spec for xml-rpc itself does not include any canonical representation.

Implementing additional mappings.

It is possible to extend the support to additional data types trivially. All the details of parsing and unparsing the various value types is handled in the necessary-evil.value namespace with the multimethod parse-value and the protocol ValueTypeElem. Simple implement the appropriate pair for each of these in your own code.

Keep in mind that if you specify a mapping from a new Clojure type to an existing xmlrpc type that the mapping will be asymmetric. If you add additional xmlrpc types keep in mind that the xmlrpc implementation at the other end will also need to know how to serialize and deserialize the type.

Primary API

The following the main API functions that you will use as a consumer of the library.

• necessary-evil.core/end-point — Defines a Ring handler that acts as an XML-RPC end-point. See above for examples.
• necessary-evil.core/call — Calls an XML-RPC function at a given end point.
• necessary-evil.core/call* — Calls an XML-RPC function at a given end point. Allows for more control than necessary-evil.core/call.
• necessary-evil.fault/fault — Creates a new fault, use this if you need to return an error condition to the caller.
• necessary-evil.fault/fault? — Predicate that tests a value for being a Fault record.
• necessary-evil.fault/attempt-all — A comprehension form to make it easier to work with potentially Fault returning functions. For more detail on this macro see my Error Monads and Error Monads Revisited blog posts.

Changes from 2.0.0 to 2.0.1

• Updated dependencies to newer versions

Changes from 1.2.2 to 2.0.0

Despite the big jump in version numbers relatively small changes have occured.

• Updated to work with Clojure 1.2.1, 1.3.0 and new contrib modules.
  • Class name munging of '-' characters in Record names caused problems using prior necessary-evil 1.x to have import errors on Clojure 1.2.1 and 1.3.
• Changed mappings in the ValueTypeElem protocol:
  • Instead of clojure.lang.PersistanceVector, any clojure.lang.Sequential implementor will be serialized to an array; this includes lists and lazy sequences.
  • Longs are now serialized as Integers (and must not exceed Integer.MAX_VALUE as the xmlrpc spec only allows for 4 byte signed ints).
  • java.util.Date objects are now serialized to time
• call* function added to necessary-evil.core to add more fine grained control to the http request. call now uses call* under the hood. The major difference is that call* takes the remote functions arguments as a sequence, and has keyword options for the configurable things.
• String values no longer normalize whitespace: You may now find you have to remove newlines or other whitespace yourself.
• Type hints to avoid reflection added across all namespaces.

Note that the serialization and deserialization processes are now asymmetric: For example in a round trip a list will return as vector, Java dates will return as Joda time dates and longs as ints.

Changes from 1.2.1 to 1.2.2

• Fixed issue #4 where empty string values that have no type elements would mysteriously disappear.

Changes from 1.2 to 1.2.1

• Addes UTF-8 character set to content type headers for both client and server. Thanks to Laurent Petit for this fix.

Changes from 1.1 to 1.2

• Fixes a bug with values containing XML special characters not being escaped
• Support for Null support extension with the necessary-evil.value/allow-nils form.
• Uses non-snapshot clj-time

Changes from 1.0 to 1.1

• fault handling code is now in its own namespace: necessary-evil.fault
• necessary-evil.fault now includes attempt-all macro to stream line writing code that may generate faults in multiple stages.

Notes

Laurent Petit has a recipe for making Make a SSL certificate visible to your app. This may be relevant if you wish to secure your api with HTTPS and are not running your application behind another web server.

Thanks

Thanks to the following people for their feedback and assistance:

• Raynes (also for letting me steal from his clj-xmlrpc code).
• Amalloy
• kumarshantanu
• semperos
• laurentpetit

License

Copyright (C) 2010, 2011 Andrew Brehaut

Distributed under the Eclipse Public License, the same as Clojure.