xmlrpc

About

Fathom-XMLRPC integrates with Fathom-REST and Fathom-Security and allows you to register XML-RPC methods quickly and easily.

Installation

Add the Fathom-XMLRPC artifacts.

<dependency>
    <groupId>com.gitblit.fathom</groupId>
    <artifactId>fathom-xmlrpc</artifactId>
    <version>${fathom.version}</version>
</dependency>
<dependency>
    <groupId>com.gitblit.fathom</groupId>
    <artifactId>fathom-xmlrpc-test</artifactId>
    <version>${fathom.version}</version>
    <scope>test</scope>
</dependency>

Usage

There are three steps to setting up XML-RPC methods.

1. Register a POST handler for your XML-RPC methods.
2. Within the definition of your POST handler, register the method group classes.
3. Implement the method group classes.

!!! Note 1. Your XML-RPC method group classes may optionally be annotated with @XmlRpc. If you do not supply a name value to the @xmlRpc class attribute, the fully qualified class name will be used as the method group name. 2. Your XML-RPC methods must be public and must be annotated with @XmlRpc. If you do not supply a name value to the @XmlRpc method attribute, the actual method name will be used.

Example

public class Routes extends RoutesModule {

  @Override
  protected void setup() {
    POST("/RPC2", MyXmlRpcMethods.class);
  }

}

public class MyXmlRpcMethods extends XmlRpcRouteHandler {

    @Inject
    public MyXmlrpcMethods(XmlRpcMethodRegistrar methodRegistrar) {
      super(methodRegistrar);

      methodRegistrar.addMethodGroup(MyGroupXmlRpcMethods.class);
    }
}

@XmlRpc("myGroup")
public class MyGroupXmlRpcMethods {

    // myGroup.min
    @XmlRpc
    public int min(int a, int b) {
      return Math.min(a, b);
    }

    // myGroup.randomSecret
    @XmlRpc("randomSecret")
    @RequireAuthenticated
    public String secretPhrase() {
      return UUID.randomUUID().toString();
    }    

}

Security

The base Fathom-XMLRPC handler will automatically authenticate incoming requests using the Authorization header and delegates authentication of BASIC (username & password) and TOKEN to the Fathom-Security SecurityManager.

!!! Note Use of authentication and authorization is not required.

Testing

The fathom-xmlrpc-test dependency offers a simple integration test base class and adds the Apache XML-RPC client to your test classpath.

public class MyXmlRpcMethodsTest extends XmlRpcIntegrationTest {

    @Test
    public void testMinAsAnon() {
        int value = callAnon("myGroup.min", 1, 2);
        assertEquals("Unexpected minimum value!", 1, value);
    }

    @Test(expected = RuntimeExcepion.class)
    public void testRandomSecretAsAnon() {
        String secret = callAnon("myGroup.randomSecret");
        assertNotNull("Secret is null!", secret);
    }

    @Test
    public void testRandomSecretAsAdmin() {
        String secret = callAsAdmin("myGroup.randomSecret");
        assertNotNull("Secret is null!", secret);
    }

    protected <X> X callAsAdmin(String methodName, Object... args) {
       return call("admin", "admin", "/RPC2", methodName, args);
   }