work in progress, any feedback and contributions welcome!

REST module sample#

This document describes a sample Open Wonderland module that displays a cell. On right-click a 'register' option can be selected that will register the user against an external webservice that follows a REST interface.

Please note that you will have to provide that webservice!

The code for this tutorial can be found here, and a screencast showing what to expect from the module can be found here

Classpaths and expected structure for Netbeans#

Please refer to the README file in the project.

The external webservice#

For the example (and screencast), a simple Ruby on Rails web application was used, running on an external server connected to the Internet. The service can be written in whatever platform you choose, as long as it complies with REST.

The URL at which the webservice is running has to be configured in the Bundle file found in the client package. This is not ideal, but it is enough for a simple tutorial like this one.

To run the module please specify the URL and context of the call in the bundle file and code.

The internal webservice Client#

This module was conceived to try and demonstrate the facilities that Open Wonderland provides to connect to external resources. The REST realted client code is the simplest solution I could find so it does not interfere with the understanding (and simplicity) of the module.

In the following blog post, this code is categorised as a Raw Data Communication client.

A lot more can be done with the code, and as the post suggests, JAXB2 could be a great alternative in this case because it is already used in Wonderland. Feel free to expand the example as you think fits.

The code#

The only part of the code that we will see here is the client.rest package. The other code in the module comes straight from the Cell tutorials and it is explained in there at length.

The only difference is the call to the REST gateway in the ContextMenuActionListener, within the RESTSampleCell.java file:

    class MenuItemListener implements ContextMenuActionListener {
        public void actionPerformed(ContextMenuItemEvent event) {
            //NOTE this instead of changing shape, we could launch some kind of
            //'Registering' animation to use as feedback or change the texture
            shapeType = (shapeType.equals("BOX") == true) ? "SPHERE" : "BOX";
            renderer.updateShape();
            
            RESTURLGateway gateway = new RESTURLGateway();
            String URLToPostTO = gateway.createURLToPostTo("users.xml");
            String userString = gateway.createMessageToPost();
            try {
                gateway.restPOSTConnection(URLToPostTO, userString.toString());
                //NOTE for this sample, we can do a GET call and print out to console.
                System.out.println(gateway.restGETConnection(URLToPostTO));
            } catch (Exception ex) {
                //NOTE if an exception happens, you have to let the user know! (out of scope for this sample)
                Logger.getLogger(RESTSampleCell.class.getName()).log(Level.SEVERE, null, ex);
            }
            
        }
    }

Note that the method createURLToPostTo("users.xml") needs a parameter that indicates the REST resource that will appended to the URL at which the webservice is running.

The RESTGateway interface provides the following calls to interact with the external web service:

    /**
     * A GET REST request is sent to the external service. An xml reply is expected.
     * @param remoteRestURL the URL and data to be accessed.
     * @return String wrapping the xml information read from the remote server.
     */
    String restGETConnection(String remoteRestURL) throws MalformedURLException, IOException;

    /**
     * A POST REST request is sent to the remote server, to insert data in the database.
     * @param remoteRestURL
     * @param xmlMessage xml snippet to be inserted in the remote database
     * @return String wrapping the xml of the new inserted item
     * @throws Exception see TODO
     */
    String restPOSTConnection(String remoteRestURL, String xmlMessage) throws MalformedURLException, IOException;

An implementation of this interface is given in RESTURLGateway.java, using an URLConnection (provided by the Java sdk) as the basis for the calls. Alternative implementations can be extended from this model, like the ones described in the internal webservice client section above.

Design decisions and testing#

I wanted to separate completely the REST code from the Cell code. This was mainly for testability reasons. It can be quite a challenge to instantiate any of the Cell related classes in a test harness such as JUnit. For this, the REST code is self-contained, and the calls are made from Cell (event handlers) code.

I am experimenting with the creation of isolated tests by using the mock framework mockito but this is a work in progress. It should not affect the reading/use of the tutorial in any case.

Trying the module#

To test the module, the webservice should be running and accessible. The module can be compiled and deployed as any other Open Wonderland Module.

Add new attachment

Only authorized users are allowed to upload new attachments.
« This page (revision-8) was last changed on 21-May-2011 00:12 by Maggie Leber