A fairly common pattern is to use a filter that wraps the (Http)ServletRequest and (Http)ServletResponse in an app-specific wrapper; this can be used to hold user credentials and state etc. In essence it is:

@WebFilter("*")
public class AppRequestResponseFilter implements Filter {
  public void init(FilterConfig fConfig) throws ServletException { }
  public void destroy() {}
  public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
      throws IOException, ServletException {
    chain.doFilter(new AppRequest(request), new AppResponse(response));
  }
}

where

public class AppRequest extends HttpServletRequestWrapper {
  public AppRequest(ServletRequest request) {
    super((HttpServletRequest) request);
  }
}

and AppResponse similarly subclasses from HttpServletResponseWrapper.

But let’s now look at the following servlet that simply returns an error:

@WebServlet("/sendsAnError")
public class SendsAnErrorServlet extends HttpServlet {
  protected void doGet(HttpServletRequest request, HttpServletResponse response)
      throws ServletException, IOException {
    // safe to downcast here...
    // AppRequest appRequest = (AppRequest)request;
    response.sendError(401);
  }
}

As the comments note, this servlet could downcast HttpServletRequest to AppRequest if it so desired. Indeed, any filter or servlet could do perform this downcast. And you can see this in the stacktrace when I put a breakpoint in the servlet:

Or could it? Well, no, not always. Because in web.xml we have the following entry:

<error-page>
  <error-code>401</error-code>
  <location>/catchAnError</location>
</error-page>

This instructs the servlet container that if a servlet returns a 401, then to redirect to the resource at the /catchAnError mapping. In our case, this corresponds to the following servlet:

@WebServlet("/catchAnError")
public class CatchAnErrorServlet extends HttpServlet {
  protected void doGet(HttpServletRequest request, HttpServletResponse response)
      throws ServletException, IOException {
    // ... but not safe to downcast here
    // AppRequest appRequest = (AppRequest)request;
    response.getWriter().println("<p>an error occurred</p>");
  }
}

And so here’s the catch: when the servlet container invokes this servlet to handle the error, any filters are NOT called. And you can see this in the stacktrace when I break in this second servlet; the implementation that is provided is that of the servlet container, not of the filter:

What would happen, do you think, if you were to blindly downcast to AppRequest in this second servlet? Well, it’d be a ClassCastException, of course, which the servlet container will deal with by just rendering its default error page (for a 401, in this case). Meanwhile you’ll be stuck there wondering why your error handling servlet didn’t (seem to) fire.

I guess this is in the servlet spec somewhere, but it’s surprising behaviour. And it had us stumped for a little while.

As ever, comments welcome.

The app consists of a single html page, index.html, along with a number of supporting Javascript files. We start by bring in the Javascript libraries, most notably JQueryMobile and JQuery:

<link rel="stylesheet" href="../jquery.mobile/jquery.mobile-1.0.min.css" />
<script src="../jquery/jquery-1.6.4.min.js"></script>
<script src="../jquery.mobile/jquery.mobile-1.0.min.js"></script>
<script src="../jquery.tmpl/jquery.tmpl-vBeta1.0.0.min.js"></script>

You’ll note that I’ve also brought in the JQuery.tmpl library for templating. This has actually been discontinued by the JQuery team, but its replacement isn’t yet available. Since one templating solution is very much like another, I decided to carry on using it for this demo.

In addition to the third-party libraries, the app itself is broken up into a number of Javascript files:

<script type="text/javascript" src="namespace.js"></script>
<script type="text/javascript" src="util.js"></script>
<script type="text/javascript" src="generic.js"></script>
<script type="text/javascript" src="app.js"></script>

The namespace.js just defines a namespace() function in order that the other stuff can be namespaced properly:

namespace = function(namespaceString) {
  var parts = namespaceString.split('.'),
  parent = window,
  currentPart = '';

  for(var i = 0, length = parts.length; i < length; i++) {
    currentPart = parts[i];
    parent[currentPart] = parent[currentPart] || {};
    parent = parent[currentPart];
  }
  return parent;
}

Using this, the other script files define “util” and “generic” as aliases for a fully-qualified hierarchy:

var util = namespace('org.apache.isis.viewer.json.jqmobile.util');
var generic = namespace('org.apache.isis.viewer.json.jqmobile.generic');

We’ll dig into the Javascript some more in a moment, but the next thing we should look at is the index.html. JQueryMobile works by serving a single div’s at a time, and does all the animation between those div’s. In some apps those div’s could be pulled down from a server dynamically; in the case of this app, though, all the div’s we need are already within the index.html:

<body id="pageHolder">
  <div data-role="page" id="home"> ... </div>
  <div data-role="page" id="genericListView"> ... </div>
  <div data-role="page" id="genericDomainObjectView"> ... </div>
  <div data-role="page" id="genericObjectCollectionView"> ... </div>
</body>

When we load the index.html initially into the browser, JQuery automatically shows the first div. In our case this is the home div:

<div data-role="page" id="home">

  <div data-role="header">
    <h1>Home</h1>
  </div>

  <div data-role="content">
    <br/>
    <button>Todays Tasks</button>
    <ul data-role="listview" class="tasks"></ul>
  </div>

  <script class="tmpl" type="text/x-jquery-tmpl">
    <li>
      <a href="${href}">${title}</a>
    </li>
  </script>

  <script type="text/javascript">
    $("#home button").click(function(){
      $.mobile.changePage("../services/toDoItems/actions/toDosForToday/invoke", "pop")
    });
  </script>
</div>

This renders a single button on the page. The inline Javascript binds that to a JQueryMobile function to change page to the provided URL.

As you can probably guess, that URL actually corresponds to the “toDosForToday” action provided by the ToDoItems domain service. In the normal scheme of things, if that URL served up a div, then JQueryMobile would automatically bring that div into the browser’s DOM, and render it. For our app, though, things are a little more complex, because invoking that URL will retrieve JSON. What we need to do is to use that JSON to generate a div and then transition to it.

The hook for doing this lives within app.js:

  $(document).bind("pagebeforechange", generic.submitRenderAndNavigate);

This will cause the page transition ($.mobile.changePage) that we requested in the Javascript earlier to actually call the generic.submitRenderAndNavigate() function. You can find this function in generic.js:

generic.submitRenderAndNavigate = function(e, pageChangeData) {
  if (typeof pageChangeData.toPage !== "string") {
    return;
  }

  var url = $.mobile.path.parseUrl(pageChangeData.toPage)
  var urlHref = generic.extract(url.href)
  if(!urlHref) {
    return;
  }

  generic.submitAndRender(urlHref, pageChangeData);
  e.preventDefault();
}

The function can be called by JQueryMobile in two different ways: either the pageChangeData.toPage is a string, or it is an in-memory page object. We intercept the former case (checking that the URL is parseable), and then delegate off to generic.submitAndRender() to do the ajax etc. The call to e.preventDefault() suppresses JQueryMobile’s usual page handling.

We’re going to look at generic.submitAndRender() in a second, but for now it’s worth understanding that the end result of that processing is a page object. This is given back to JQueryMobile, which then calls back into this function. The second time around the function just returns; because in this flow the e.preventDefault() is not called, JQueryMobile does its usual page transitions.

But, let’s look to see how generic.submitAndRender() function ends up generating the page. For a start, this is the method where the ajax call gets made:

generic.submitAndRender = function(urlHref, pageChangeData) {
  $.ajax({
    url : urlHref,
    dataType : 'json',
    success : function(json, str, xhr) {
      var contentType = xhr.getResponseHeader("Content-Type");
      var handler = generic.handlers[contentType];
      if(!handler) {
        alert("unable to handle response")
        return;
      }
      var pageAndOptions = handler(urlHref, pageChangeData, json, xhr)
     $.mobile.changePage(pageAndOptions.page, pageAndOptions.options);
   }
 })
}

The example given here is only a demo, so there’s no sad-case failure handling. But assuming that the ajax call completes, the success callback looks up a
handler function based on the returned “Content-Type”. Here’s the lookup table:

generic.handlers = {
  "application/json;profile=\"urn:org.restfulobjects/domainobject\"": generic.handleDomainObjectRepresentation,
  "application/json;profile=\"urn:org.restfulobjects/list\"": generic.handleListRepresentation,
  "application/json;profile=\"urn:org.restfulobjects/objectcollection\"": generic.handleObjectCollectionRepresentation,
  "application/json;profile=\"urn:org.restfulobjects/actionresult\"": generic.handleActionResultRepresentation
}

This looking up of the relevant handler is the heart of the app; using it we can handle representations of domain objects, a list, or a domain object collection, or an action result.

Since the demo app initially starts by invoking an action, let’s look at the generic.handleActionResultRepresentation():

generic.handleActionResultRepresentation = function(urlHref, pageChangeData, json, xhr) {
  var resultType = json.resulttype
  var handler = generic.actionResultHandlers[resultType];
  if(!handler) {
    alert("unable to handle result type")
    return;
  } 
  return handler(urlHref, pageChangeData, json.result, xhr)
}

As you can see, this also looks up a handler, this time based on the json.resultType of the returned json.result:

generic.actionResultHandlers = {
  "object": generic.handleDomainObjectRepresentation,
  "list": generic.handleListRepresentation
}

Perhaps no surprise, the handler functions that the action result handler delegates to one-and-the-same as those we noted earlier. So let’s look at generic.handleListRepresentation in more detail (starting there simply because that’s what the demo app does when you invoke the “todaysTasks” service action):

generic.handleListRepresentation = function(urlHref, pageChangeData, json, xhr) {

  var page = $("#genericListView");
  var header = page.children(":jqmData(role=header)");
  var content = page.children(":jqmData(role=content)");

  var items = generic.itemLinks(json.value)

  header.find("h1").html("Objects");

  var div = page.find("ul");
  var templateDiv = page.find(".tmpl");

  util.applyTemplateDiv(items, div, templateDiv);

  page.page();
  content.find( ":jqmData(role=listview)" ).listview("refresh");
  page.trigger("create");

  return generic.pageAndOptions(page, "genericListView", urlHref)
}

The function uses a helper function generic.itemLinks to build a list of link objects. Then, we identify the template script $(“#genericListView .tmpl”), and pass both to the util.applyTemplateDiv helper function. This in turn calls the jQuery.tmpl library to do the heavy lifting.

Here’s the HTML div that it works against:

<div data-role="page" id="genericListView">

  <div data-role="header">
    <a data-icon="back" data-rel="back">Back</a>
    <h1>List</h1>
  </div>

  <div data-role="content">
    <br/>
    <ul data-filter="true" data-role="listview"></ul>
  </div>

  <script class="tmpl" type="text/x-jquery-tmpl">
    <li>
      <a href="${href}">${title}</a>
    </li>
  </script>
</div>

The href’s of the link objects are formulated such that, when followed, they will again trigger the generic.submitRenderAndNavigate() function. In this way, we are able to walk between (the representations of) connected domain objects.

Once the content has been generated, we call a bunch of JQueryMobile functions (page.page() and so on) to tell the framework to “enhance” the generated page. And once that has been done, we call the generic.pageAndOptions() function to create the in-memory page. We’ll drill into that helper shortly.

Let’s now have a look at the biggest of the handlers, the generic.handleDomainObjectRepresentation:

generic.handleDomainObjectRepresentation = function(urlHref, pageChangeData, json, xhr) {

  var page = $("#genericDomainObjectView");
  var header = page.children(":jqmData(role=header)");
  var content = page.children(":jqmData(role=content)");

  header.find("h1").html(json.title);

  // value properties
  var valueProperties = json.members.filter(function(item) {
    return item.memberType === "property" && !item.value.href;
  });

  valueProperties = $.map( valueProperties, function(value, i) {
    var dataType = generic.dataTypeFor(value)
    return {
      "id": value.id,
      "value": value.value,
      "dataTypeIsString": dataType === "string",
      "dataTypeIsBoolean": dataType === "boolean"
    }
  });

  var valuePropertiesDiv = page.children(":jqmData(role=content)").find(".valueProperties");
  var valuePropertiesTemplateDiv = page.children(".valueProperties-tmpl");
  util.applyTemplateDiv(valueProperties, valuePropertiesDiv, valuePropertiesTemplateDiv);

  // reference properties
  var referenceProperties = json.members.filter(function(item) {
    return item.memberType === "property" && item.value.href;
  });

  var referencePropertiesList = page.children(":jqmData(role=content)").find(".referenceProperties");
  var referencePropertiesTemplateDiv = page.children(".referenceProperties-tmpl");
  util.applyTemplateDiv(referenceProperties, referencePropertiesList, referencePropertiesTemplateDiv);

  var collections = json.members.filter(function(item) {
    return item.memberType === "collection";
  }).map(function(value, i) {
    var href = util.grepLink(value.links, "details").href
    return {
      "hrefUrlEncoded" : util.urlencode(value.links[0].href),
      "id" : value.id,
      "href" : value.links[0].href
    }
  });

  // collections
  var collectionsList = page.children(":jqmData(role=content)").find(".collections");
  var collectionsTemplateDiv = page.children(".collections-tmpl");
  util.applyTemplateDiv(collections, collectionsList, collectionsTemplateDiv);

  page.page();
  content.find( ":jqmData(role=listview)" ).listview("refresh");
  page.trigger("create");

  return generic.pageAndOptions(page, "genericDomainObjectView", urlHref)
}

Although this handler is longer, it’s doing much the same thing as the list handler. Specifically, it processes the JSON into three lists, one for value properties, one for references properties, and one for collections. For each, it uses the util.applyTemplateDiv function again in order to render against the corresponding templates, $(“#genericDomainObjectView .valueProperties-tmpl”) and so forth.

The corresponding div in the HTML is:

<div data-role="page" id="genericDomainObjectView">

  <div data-role="header">
    <a data-icon="back" data-rel="back">Back</a>
    <h1>Object</h1>
  </div>

  <div data-role="content">
    <div class="valueProperties"></div>
    <br/>
    <p>References</p>
    <ul data-role="listview" data-inset="true" class="referenceProperties"></ul>
    <br/>
    <p>Collections</p>
    <ul data-role="listview" data-inset="true" class="collections"></ul>
  </div>

  <script class="valueProperties-tmpl" type="text/x-jquery-tmpl">
  {{if dataTypeIsString}}
    <label for="${id}">${id}:</label>
    <input type="text" name="${id}" id="${id}" value="${value}" placeholder="${id}" class="required"/>
  {{/if}}
  {{if dataTypeIsBoolean}}
    <div data-role="fieldcontain">
      <fieldset data-role="controlgroup">
        <legend>${id}?</legend>
        <input type="checkbox" name="${id}" id="${id}" value="${value}" class="required"/>
        <label for="${id}">${id}</label>
      </fieldset>
    </div>
  {{/if}}
  </script>

  <script class="referenceProperties-tmpl" type="text/x-jquery-tmpl">
    <li>
      <a data-transition="slide" href="${value.href}">
        <p>${id}</p>
        <p><b>${value.title}</b></p>
      </a>
    </li>
  </script>

  <script class="collections-tmpl" type="text/x-jquery-tmpl">
    <li>
      <a data-transition="slideup" href="${href}">${id}</a>
    </li>
  </script>
</div>

The template for value properties is, admittedly, a little ugly: it uses the {{if}} template in order to bring in either a checkbox or a textbox widget dependent on the value’s type. A more fully-featured application would probably generalize this to use subtemplates (and might even be extensible) to allow richer value types such as images or maps to be rendered accordingly.

The last of our handlers, generic.handleObjectCollectionRepresentation, is very similar to the generic.handleListRepresentation:

generic.handleObjectCollectionRepresentation = function(urlHref, pageChangeData, json, xhr) {
  var page = $("#genericObjectCollectionView");
  var header = page.children(":jqmData(role=header)");
  var content = page.children(":jqmData(role=content)");

  var items = generic.itemLinks(json.value)

  var parentTitle = util.grepLink(json.links, "up").title

  var collectionId = json.id;
  header.find("h1").html(collectionId + " for " + parentTitle);

  var div = page.find("ul");
  var templateDiv = page.find(".tmpl");
  util.applyTemplateDiv(items, div, templateDiv);

  page.page();
  content.find( ":jqmData(role=listview)" ).listview("refresh");
  page.trigger("create");

  return generic.pageAndOptions(page, "genericObjectCollectionView", urlHref, "slideup")
}

It’s corresponding div in the HTML is:

<div data-role="page" id="genericObjectCollectionView">

  <div data-role="header">
    <a data-icon="back" data-rel="back">Back</a>
    <h1>Collection</h1>
  </div>

  <div data-role="content">
    <br/>
    <ul data-filter="true" data-role="listview"></ul>
  </div>

  <script class="tmpl" type="text/x-jquery-tmpl">
    <li>
      <a href="${href}">${title}</a>
    </li>
  </script>
</div>

There’s just a couple more functions I want to go through. The first is generic.pageAndOptions(); this is the function, if you recall, that creates and hands back the in-memory page option:

generic.pageAndOptions = function(page, view, dataUrl, transition) {
  var pageAndOptions = {
    "page": page,
    "options": {
      "dataUrl": "#" + view + "?dataUrl=" + util.urlencode(dataUrl),
      "allowSamePageTransition": true,
      "transition": transition
    }
  }
  return pageAndOptions
}

This little function returns a tuple consisting of the newly created page, along with an options object that has a dataUrl. This options.dataUrl property that is important, because it is what appears in the browser’s address bar.

As you can see, I’ve designed it to include both the view name (as an anchor), along with a ?dataUrl query param. Why so? Well, it allows the page to be bookmarked, so that the user can come back to any domain object rather than starting from home. The little bit of processing to do this is in app.js:

// if user manually refreshes page for domain object, then re-retrieve
var locationHref = location.href;
if(locationHref.indexOf("genericDomainObjectView") != -1) {
  var urlHref = generic.extract(locationHref);
  generic.submitAndRender(urlHref, "pop");
} else {
  $.mobile.changePage($("#home"))
}

Here we try to extract the dataUrl from the locationHref, in other words the dataUrl query param. If successful, we call generic.submitAndRender(), as described above. Or, if the dataUrl cannot be interpreted, then we just revert back to the home page.

I hope the above run-thru has been useful. Bear in mind that this is far from production quality, and there could be bugs in it (in fact, I’m pretty sure that there are…). And there are, of course, plenty of things that this demo doesn’t yet support – invoking actions, for one.

In the future we expect that there’ll be a fully fledged generic REST client. In the meantime, though, hopefully this is a good demonstrator for the potential of the Rest API that ships with Isis.

PS: If you’re interested in the source code, you can either just save the files from the online demo (index.html, app.js, generic.js, util.js, namespace.js), or you can browse to the Isis subversion repository.

However, JSON representations do not a user interface make; instead the idea is that the developer will write either custom or generic UIs to consume those representations.  As an example of such an app (and by way of learning a little more Javascript) I’ve put together a very simple mobile app using the recently-released JQueryMobile framework.

For now, this mobile app is part of the Apache Isis online demo, which you can download as a WAR or as a self-hosted WAR (run using java -jar …).  By the time you read this it may well also be available online here.

To try out the demo, the first thing you’ll need to do is to register a user through the HTML viewer, and then reset the demo fixtures to create some initial data for your newly-created user.  The demo has full documentation on how to do this, so I won’t repeat it here.

Once you’ve done that, you’ll be able to browse to the home page for the mobile app (under mobile/index.html); you should see a home page showing just a single button:

When you press that button, you’ll find that your prompted for a username/password; this is the Basic Authentication that is used to secure the demo app.  Enter the username/password that you just entered.

With the username/password successfully entered, you should see a list of todo-items; these are the result of a domain service action ( ToDoItems#todaysTasks(), to be exact):

Thereafter everything in the app is generic; in other words it is able to display any domain object that is in the model.  For example, click on a link and you’ll find yourself viewing one of the ToDoItems:

Similarly, you can look at the contents of the ‘similarItems’collection:

And, from there, you can navigate to other domain objects, and so on.

This little webapp consists of ~200 lines of HTML (mobile/index.html), about ~300 lines of custom Javascript (mobile/app.js, mobile/generic.js, mobile/util.js and mobile/namespace.js).  The rest of the Javascript magic is JQuery, JQueryMobile and JQuery-tmpl.

In the next post I’ll go through the source code and dissect it a little; in the meantime though you’re welcome to reverse-engineer it yourself.

As ever, comments welcome.

The usual flow is to right-click on References, and choose “Manage NuGet Packages”.  The NuGet dialog then pops up, showing available packages.  Once you’ve selected a package, NuGet will:

• download the package to your repository (if required)
• update the VS project file (.csproj or .vbproj etc)
• update its own packages.config file.

What if things get out-of-sync, though, eg you’ve moved your repository so that all the reference hints in the .csproj file are wrong?  It’d be nice to be able to use the info in the packages.config to automatically resync the .csproj file.

Here’s one brute-force way to do this (from within the Package Manager console in VS):

get-project -all | %{
  $proj = $_ ;
  get-package -project $proj.name | %{
    uninstall-package -projectname $proj.name -id $_.id -version $_.version -RemoveDependencies -force ;
   install-package -projectname $proj.name -id $_.id -version $_.version
  }
}

Actually, I have a suspicion there’s a flag for one of the NuGet commands to do this much more simply; but my google-fu failed me on this occasion.  If you know of a better way, please comment below.

The following test shows what I ended up with:

package com.danhaywood.tdd.dbunit.test;

import static org.hamcrest.Matchers.equalTo;
import static org.hamcrest.Matchers.is;
import static org.junit.Assert.assertThat;

import java.sql.ResultSet;
import java.sql.Statement;

import org.dbunit.Assertion;
import org.dbunit.dataset.ITable;
import org.hsqldb.jdbcDriver;
import org.junit.Rule;
import org.junit.Test;

import com.danhaywood.tdd.dbunit.DbUnitRule;
import com.danhaywood.tdd.dbunit.DbUnitRule.Ddl;
import com.danhaywood.tdd.dbunit.DbUnitRule.JsonData;

public class DbUnitRuleExample {

    @Rule
    public DbUnitRule dbUnit = new DbUnitRule(
            DbUnitRuleExample.class, jdbcDriver.class,
            "jdbc:hsqldb:file:src/test/resources/testdb", "SA", "");

@Ddl("customer.ddl")
    @JsonData("customer.json")
    @Test
    public void update_lastName() throws Exception {

        // when
        Statement statement = dbUnit.getConnection().createStatement();
        statement.executeUpdate("update customer set last_name='Bloggs' where id=2");

        // then (verify directly)
        ResultSet rs2 = dbUnit.executeQuery("select last_name from customer where id = 2");
        assertThat(rs2.next(), is(true));
        assertThat(rs2.getString("last_name"), equalTo("Bloggs"));

        // then (verify using datasets)
        ITable actualTable = dbUnit.createQueryTable("customer", "select * from customer order by id");
        ITable expectedTable = dbUnit.jsonDataSet("customer-updated.json").getTable("customer");

        Assertion.assertEquals(expectedTable, actualTable);
    }
}

where customer.ddl is:

drop table customer if exists;
create table customer (
	id         int         not null primary key
   ,first_name varchar(30) not null
   ,initial    varchar(1)  null
   ,last_name  varchar(30) not null
)

and customer.json (the initial data set) is:

{
  "customer":
	  [
	    {
	      "id": 1,
	      "first_name": "John",
	      "initial": "K",
	      "last_name": "Smith"
	    },
	    {
	      "id": 2,
	      "first_name": "Mary",
	      "last_name": "Jones"
	    }
	  ]
}

and customer-updated.json (the final data set) is:

{
  "customer":
	  [
	    {
	      "id": 1,
	      "first_name": "John",
	      "initial": "K",
	      "last_name": "Smith"
	    },
	    {
	      "id": 2,
	      "first_name": "Mary",
	      "last_name": "Bloggs"
	    }
	  ]
}

As you’ve probably figured out, the @Ddl annotation optionally specifies DDL script(s) to run against the database, while the @JsonData defines a JSON-formatted dataset.

The actual implementation of the DbUnitRule class is:

package com.danhaywood.tdd.dbunit;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.nio.charset.Charset;
import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.SQLException;

import org.dbunit.IDatabaseTester;
import org.dbunit.JdbcDatabaseTester;
import org.dbunit.database.IDatabaseConnection;
import org.dbunit.dataset.DataSetException;
import org.dbunit.dataset.IDataSet;
import org.dbunit.dataset.ITable;
import org.junit.rules.MethodRule;
import org.junit.runners.model.FrameworkMethod;
import org.junit.runners.model.Statement;

import com.google.common.io.Resources;

public class DbUnitRule implements MethodRule {

    @Retention(RetentionPolicy.RUNTIME)
    @Target({ ElementType.METHOD })
    public static @interface Ddl {
        String[] value();
    }

    @Retention(RetentionPolicy.RUNTIME)
    @Target({ ElementType.METHOD })
    public static @interface JsonData {
        String value();
    }

    private final Class<?> resourceBase;

    private IDatabaseTester databaseTester;
    private IDatabaseConnection dbUnitConnection;

    private Connection connection;
    private java.sql.Statement statement;

    public DbUnitRule(Class<?> resourceBase, Class<?> driver, String url, String user, String password) {
        this.resourceBase = resourceBase;
        try {
            databaseTester = new JdbcDatabaseTester(driver.getName(), url, user, password);
            dbUnitConnection = databaseTester.getConnection();
            connection = dbUnitConnection.getConnection();
            statement = connection.createStatement();
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }

    @Override
    public Statement apply(final Statement base, final FrameworkMethod method, final Object target) {

        return new Statement() {

            @Override
            public void evaluate() throws Throwable {

                try {
                    Ddl ddl = method.getAnnotation(Ddl.class);
                    if (ddl != null) {
                        String[] values = ddl.value();
                        for (String value : values) {
                            executeUpdate(Resources.toString(
                                resourceBase.getResource(value), Charset.defaultCharset()));
                        }
                    }

                    JsonData data = method.getAnnotation(JsonData.class);
                    if (data != null) {
                        IDataSet ds = new JSONDataSet(resourceBase.getResourceAsStream(data.value()));
                        databaseTester.setDataSet(ds);
                    }

                    databaseTester.onSetup();

                    base.evaluate();
                } finally {
                    databaseTester.onTearDown();
                }
            }
        };
    }

    public java.sql.Connection getConnection() {
        return connection;
    }

    public void executeUpdate(String sql) throws SQLException {
        statement.executeUpdate(sql);
    }

    public ResultSet executeQuery(String sql) throws SQLException {
        return statement.executeQuery(sql);
    }

    public IDataSet jsonDataSet(String datasetResource) {
        return new JSONDataSet(resourceBase.getResourceAsStream(datasetResource));
    }

    public ITable createQueryTable(String string, String string2) throws DataSetException, SQLException {
        return dbUnitConnection.createQueryTable(string, string2);
    }
}

This uses Lieven Doclo’s JSONDataSet (copied here for your convenience):

import org.codehaus.jackson.map.ObjectMapper;
import org.dbunit.dataset.*;
import org.dbunit.dataset.datatype.DataType;

import java.io.File;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.util.*;

/**
 * DBUnit DataSet format for JSON based datasets. It is similar to the flat XML layout,
 * but has some improvements (columns are calculated by parsing the entire dataset, not just
 * the first row). It uses Jackson, a fast JSON processor.
 * <br/><br/>
 * The format looks like this:
 * <br/>
 * <pre>
 * {
 *    "&lt;table_name&gt;": [
 *        {
 *             "&lt;column&gt;":&lt;value&gt;,
 *             ...
 *        },
 *        ...
 *    ],
 *    ...
 * }
 * </pre>
 * <br/>
 * I.e.:
 * <br/>
 * <pre>
 * {
 *    "test_table": [
 *        {
 *             "id":1,
 *             "code":"JSON dataset",
 *        },
 *        {
 *             "id":2,
 *             "code":"Another row",
 *        }
 *    ],
 *    "another_table": [
 *        {
 *             "id":1,
 *             "description":"Foo",
 *        },
 *        {
 *             "id":2,
 *             "description":"Bar",
 *        }
 *    ],
 *    ...
 * }
 * </pre>
 *
 * @author Lieven DOCLO
 */
public class JSONDataSet extends AbstractDataSet {
    // The parser for the dataset JSON file
    private JSONITableParser tableParser = new JSONITableParser();

    // The tables after parsing
    private List<ITable> tables;

    /**
     * Creates a JSON dataset based on a file
     * @param file A JSON dataset file
     */
    public JSONDataSet(File file) {
        tables = tableParser.getTables(file);
    }

    /**
     * Creates a JSON dataset based on an inputstream
     * @param is An inputstream pointing to a JSON dataset
     */
    public JSONDataSet(InputStream is) {
        tables = tableParser.getTables(is);
    }

    @Override
    protected ITableIterator createIterator(boolean reverse) throws DataSetException {
        return new DefaultTableIterator(tables.toArray(new ITable[tables.size()]));
    }

    private class JSONITableParser {

        private ObjectMapper mapper = new ObjectMapper();

        /**
         * Parses a JSON dataset file and returns the list of DBUnit tables contained in
         * that file
         * @param jsonFile A JSON dataset file
         * @return A list of DBUnit tables
         */
        public List<ITable> getTables(File jsonFile) {
            try {
                return getTables(new FileInputStream(jsonFile));
            } catch (IOException e) {
                throw new RuntimeException(e.getMessage(), e);
            }
        }

        /**
         * Parses a JSON dataset input stream and returns the list of DBUnit tables contained in
         * that input stream
         * @param jsonStream A JSON dataset input stream
         * @return A list of DBUnit tables
         */
        @SuppressWarnings("unchecked")
        public List<ITable> getTables(InputStream jsonStream) {
            List<ITable> tables = new ArrayList<ITable>();
            try {
                // get the base object tree from the JSON stream
                Map<String, Object> dataset = mapper.readValue(jsonStream, Map.class);
                // iterate over the tables in the object tree
                for (Map.Entry<String, Object> entry : dataset.entrySet()) {
                    // get the rows for the table
                    List<Map<String, Object>> rows = (List<Map<String, Object>>) entry.getValue();
                    ITableMetaData meta = getMetaData(entry.getKey(), rows);
                    // create a table based on the metadata
                    DefaultTable table = new DefaultTable(meta);
                    int rowIndex = 0;
                    // iterate through the rows and fill the table
                    for (Map<String, Object> row : rows) {
                        fillRow(table, row, rowIndex++);
                    }
                    // add the table to the list of DBUnit tables
                    tables.add(table);
                }

            } catch (IOException e) {
                throw new RuntimeException(e.getMessage(), e);
            }
            return tables;
        }

        /**
         * Gets the table meta data based on the rows for a table
         * @param tableName The name of the table
         * @param rows The rows of the table
         * @return The table metadata for the table
         */
        private ITableMetaData getMetaData(String tableName, List<Map<String, Object>> rows) {
            Set<String> columns = new LinkedHashSet<String>();
            // iterate through the dataset and add the column names to a set
            for (Map<String, Object> row : rows) {
                for (Map.Entry<String, Object> column : row.entrySet()) {
                    columns.add(column.getKey());
                }
            }
            List<Column> list = new ArrayList<Column>(columns.size());
            // create a list of DBUnit columns based on the column name set
            for (String s : columns) {
                list.add(new Column(s, DataType.UNKNOWN));
            }
            return new DefaultTableMetaData(tableName, list.toArray(new Column[list.size()]));
        }

        /**
         * Fill a table row
         * @param table The table to be filled
         * @param row A map containing the column values
         * @param rowIndex The index of the row to te filled
         */
        private void fillRow(DefaultTable table, Map<String, Object> row, int rowIndex) {
            try {
                table.addRow();
                // set the column values for the current row
                for (Map.Entry<String, Object> column : row.entrySet()) {
                    table.setValue(rowIndex, column.getKey(), column.getValue());

                }
            } catch (Exception e) {
                throw new RuntimeException(e.getMessage(), e);
            }
        }
    }
}

The libraries I used for this (ie are dependencies) are:

• hsqldb 2.2.6
• dbunit 2.4.8
• jackson 1.9.3
• slf4j-api-1.6.4, slf4j-nop-1.6.4
• google-guava 10.0.1
• junit 4.8

As ever, comments welcome.

I was about to go implement something to support Mockito’s @Mock annotation, but thought I’d browse the jmock.org website first.  It looks like Steve and Nat are ahead of me, and that JMock 2.6 will have the sort of support I need.

As I write this, they haven’t released that version yet, but the actual code that’s needed isn’t much.   So I thought I’d copy-n-paste for your delectation:

package org.jmock.integration.junit4;

import org.jmock.auto.internal.Mockomatic;
import org.jmock.internal.AllDeclaredFields;
import org.junit.rules.MethodRule;
import org.junit.runners.model.FrameworkMethod;
import org.junit.runners.model.Statement;

import java.lang.reflect.Field;
import java.util.List;

import static org.junit.Assert.fail;

public class JUnitRuleMockery extends JUnit4Mockery implements MethodRule {
    private final Mockomatic mockomatic = new Mockomatic(this);

    @Override
    public Statement apply(final Statement base, FrameworkMethod method, final Object target) {
        return new Statement() {
            @Override
            public void evaluate() throws Throwable {
                prepare(target);
                base.evaluate();
                assertIsSatisfied();
            }

            private void prepare(final Object target) {
                List<Field> allFields = AllDeclaredFields.in(target.getClass());
                assertOnlyOneJMockContextIn(allFields);
                fillInAutoMocks(target, allFields);
            }

            private void assertOnlyOneJMockContextIn(List<Field> allFields) {
                Field contextField = null;
                for (Field field : allFields) {
                    if (JUnitRuleMockery.class.isAssignableFrom(field.getType())) {
                        if (null != contextField) {
                            fail("Test class should only have one JUnitRuleMockery field, found "
                                  + contextField.getName() + " and " + field.getName());
                        }
                        contextField = field;
                    }
                }
            }

            private void fillInAutoMocks(final Object target, List<Field> allFields) {
                mockomatic.fillIn(target, allFields);
            }
        };
    }
}

A typical class to use this would use this as follows:

public class ATestWithSatisfiedExpectations {
    @Rule
    public final JUnitRuleMockery context = new JUnitRuleMockery();
    @Mock
    private Runnable runnable;
    @Test
    public void doesSatisfyExpectations() {
        context.checking(new Expectations() {{
            oneOf (runnable).run();
        }});
        runnable.run();
    }
}

As you can see, this supports @Mock very much the same way as Mockito.  The @Mock annotation itself is simply:

package org.jmock.auto;

import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

import java.lang.annotation.Retention;
import java.lang.annotation.Target;

@Retention(RUNTIME)
@Target(FIELD)
public @interface Mock {
}

There is also an @Auto annotation which can be used to automatically instantiate States and Sequences:

package org.jmock.auto;

import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

import java.lang.annotation.Retention;
import java.lang.annotation.Target;

@Retention(RUNTIME)
@Target(FIELD)
public @interface Auto {
}

Meanwhile, there are two internal class to do some of the reflection stuff. First, Mockomatic:

package org.jmock.auto.internal;

import java.lang.reflect.Field;
import java.util.List;

import org.jmock.Mockery;
import org.jmock.Sequence;
import org.jmock.States;
import org.jmock.auto.Auto;
import org.jmock.auto.Mock;
import org.jmock.internal.AllDeclaredFields;

public class Mockomatic {
    private final Mockery mockery;

    public Mockomatic(Mockery mockery) {
        this.mockery = mockery;
    }

    public void fillIn(Object object) {
        fillIn(object, AllDeclaredFields.in(object.getClass()));
    }

    public void fillIn(Object object, final List<Field> knownFields) {
        for (Field field : knownFields) {
            if (field.isAnnotationPresent(Mock.class)) {
                autoMock(object, field);
            }
            else if (field.isAnnotationPresent(Auto.class)) {
                autoInstantiate(object, field);
            }
        }
    }

    private void autoMock(Object object, Field field) {
        setAutoField(field, object,
                     mockery.mock(field.getType(), field.getName()),
                     "auto-mock field " + field.getName());
    }

    private void autoInstantiate(Object object, Field field) {
        final Class<?> type = field.getType();
        if (type == States.class) {
            autoInstantiateStates(field, object);
        }
        else if (type == Sequence.class) {
            autoInstantiateSequence(field, object);
        }
        else {
            throw new IllegalStateException("cannot auto-instantiate field of type " + type.getName());
        }
    }

    private void autoInstantiateStates(Field field, Object object) {
        setAutoField(field, object,
                     mockery.states(field.getName()),
                     "auto-instantiate States field " + field.getName());
    }

    private void autoInstantiateSequence(Field field, Object object) {
        setAutoField(field, object,
                     mockery.sequence(field.getName()),
                     "auto-instantiate Sequence field " + field.getName());
    }

    private void setAutoField(Field field, Object object, Object value, String description) {
        try {
            field.setAccessible(true);
            field.set(object, value);
        }
        catch (IllegalAccessException e) {
            throw new IllegalStateException("cannot " + description, e);
        }
    }
}

and second, AllDeclaredFields:

</pre>
package org.jmock.auto.internal;

import java.lang.reflect.Field;
import java.util.ArrayList;
import java.util.List;

import static java.util.Arrays.asList;

public class AllDeclaredFields {
    public static List<Field> in(Class<?> clazz) {
        final ArrayList<Field> fields = new ArrayList<Field>();
        for (Class<?> c = clazz; c != Object.class; c = c.getSuperclass()) {
            fields.addAll(asList(c.getDeclaredFields()));
        }
        return fields;
    }
}

The above is a great improvement; my own small extension is to add some convenience methods, and to introduce a factory method to replace the rather obscure way that JMock has for mocking classes:

package org.apache.isis.core.testsupport.jmock;

import org.jmock.Expectations;
import org.jmock.lib.legacy.ClassImposteriser;
import org.junit.runners.model.FrameworkMethod;
import org.junit.runners.model.Statement;

public class JUnitRuleMockery2 extends JUnitRuleMockery {

    public static enum Mode {
        INTERFACES_ONLY,
        INTERFACES_AND_CLASSES;
    }

    public static JUnitRuleMockery2 createFor(Mode mode) {
        JUnitRuleMockery2 jUnitRuleMockery2 = new JUnitRuleMockery2();
        if(mode == Mode.INTERFACES_AND_CLASSES) {
            jUnitRuleMockery2.setImposteriser(ClassImposteriser.INSTANCE);
        }
        return jUnitRuleMockery2;
    }

    public <T> T ignoring(final T mock) {
        checking(new Expectations() { { ignoring(mock); } });
        return mock;
    }

    public <T> T allowing(final T mock) {
        checking(new Expectations() { { allowing(mock); } });
        return mock;
    }

    public <T> T never(final T mock) {
        checking(new Expectations() { { never(mock); } });
        return mock;
    }

    public <T> T mockAndIgnoring(final Class<T> typeToMock) {
        return ignoring(mock(typeToMock));
    }

    public <T> T mockAndIgnoring(final Class<T> typeToMock, final String name) {
        return ignoring(mock(typeToMock, name));
    }

    public <T> T mockAndAllowing(final Class<T> typeToMock) {
        return allowing(mock(typeToMock));
    }

    public <T> T mockAndAllowing(final Class<T> typeToMock, final String name) {
        return allowing(mock(typeToMock, name));
    }

    public <T> T mockAndNever(final Class<T> typeToMock) {
        return never(mock(typeToMock));
    }

    public <T> T mockAndNever(final Class<T> typeToMock, final String name) {
        return never(mock(typeToMock, name));
    }
}

This can be used as follows:

public class MyTest {

  @Rule
  public final Junit4Mockery2 context = Junit4Mockery2.createFor(Mode.INTERFACES);
  ...
}

Comments always welcome.

I’ve just updated the deck in line with the forthcoming v0.2.0 release; the most significant new content includes an overview of the main use cases for Apache Isis.  The online demo for Isis also gets a link.

As ever, feedback welcome!

If you’re still with me, you’ll find that the online demo shows how Isis can dynamically generate a (human-usable) webapp and a (machine-usable) RESTful API from the same domain object model. The REST API is that
defined by the Restful Objects spec.

The online demo bundles its own documentation, which shows the full source code for the domain model (all 3 classes) along with guidance on how to use Chrome (or similar) extensions to play with the REST API directly from your browser.

Feedback very welcome on the isis-dev mailing list.

The domain object model you need to understand for this example is really simple; just a finder on a repository:

@Named("Customers")
public interface Customers {

    @QueryOnly
    public Customer findByEmail(
        @Named("Email")
        String email);
    ...
}

And as you can probably imagine, one of the properties of Customer is an email address:

public class Customer extends AbstractDomainObject {
    ...
    // {{ Email (property)
    private String email;

    @MemberOrder(sequence = "4.0")
    public String getEmail() {
        return email;
    }

    public void setEmail(final String email) {
        this.email = email;
    }
    // }}
    ...
}

Next, I downloaded the jQTouch and unzipped into src/main/webapp of my viewer-json module (as generated by the Isis archetype).

Hopping into src/main/webapp/demo, I copied “skel” to a new directory, “webshop”.

The top of src/main/webapp/demo/webshop/index.html is all boilerplate:

<!doctype html>
<html>
    <head>
        <meta charset="UTF-8" />

        <title>Webshop on Isis</title>
        <style type="text/css" media="screen">@import "../../jqtouch/jqtouch.css";</style>
        <style type="text/css" media="screen">@import "../../themes/jqt/theme.css";</style>
        <script src="../../jqtouch/jquery-1.4.2.min.js" type="text/javascript" charset="utf-8"></script>
        <script src="../../jqtouch/jqtouch.js" type="application/x-javascript" charset="utf-8"></script>
        <script type="text/javascript" charset="utf-8">
            var jQT = new $.jQTouch({
                icon: 'jqtouch.png',
                addGlossToIcon: false,
                startupScreen: 'jqt_startup.png',
                statusBar: 'black'
            });

            $(function(){
                // Custom Javascript (onReady)
            });
        </script>
        <style type="text/css" media="screen">
        </style>

        <script src="webshop.js" type="application/x-javascript" charset="utf-8"></script>
    </head>
    <body>
        <div id="jqt">
        </div>
    </body>
</html>

This is pretty much what the same as skel/index.html; the only addition is that script include of webshop.js.

The skeleton for the webshop.js script itself is:

(function($){

$(function(){
    ... this is where our functions go ...
});

})(jQuery);

I broke the app itself down into two pages. The first shows the finders for Customer:

        <div id="jqt">
            <div id="customers" class="current">
                <div class="toolbar">
                    <h1>Customers</h1>
                    <a href="#" class="back">Back</a>
                </div>
                <h2>Find by Email</h2>
                <div class="findByEmail">
                    <form>
                        <ul class="edit rounded">
                            <li class="email">
                                <input type="email" name="email" placeholder="email@address.com"></input>
                                <span style="display: inline; font-size: 75%; color:rgb(255,127,0)"/>
                            </li>
                        </ul>
                        <a style="margin:0 10px;color:rgba(0,0,0,.9)" href="#" class="submit whiteButton">Submit</a>
                        <a style="display:none" href="#customer" class="onsuccess">dummy text</a>
                    </form>
                </div>
            </div>
            ...
        </div>

In webshop.js I then have a binding onto this form:

     $("#customers .findByEmail form").submit(function() {
         var email = $("#customers .findByEmail .email input").val()
         if (!email) {
             $("#customers .findByEmail .email span").text("Enter email address").show().fadeOut(1000);
             return false;
         }

         $.get("/services/customers/actions/findByEmail/invoke?email=" + email,
            function(data) {
                $("#customer").data("object", data.result)
                $("#customers .findByEmail .onsuccess").click();
            }
        );

         return false;
    });
    ...

When the user submits the form, we validate the email address and then call the REST API to get the customer. This is the bound to the target #customer div as a data element “object”.

The #customer div, which will show the customer, looks like this:

        <div id="jqt">
            ...
            <div id="customer">
                <div class="toolbar">
                    <h1>No Customer</h1>
                    <a href="#" class="back">Back</a>
                </div>
                <ul class="rounded members">

                </ul>
            </div>
        </div>

And the javascript to render the customer is:

    ...
    $('#customer').bind('pageAnimationStart', function (e, info) {
      var cust = $("#customer").data("object")
      $("h1").text(cust.title)
      var email = $.each(cust.members, function(index, member) {
        if(member.memberType == 'property') {
            $(".members").append('<li><span>' + member.id + ': </span><span>' + member.value + '</span></li>')
        }
       } );
      $(".email").text(email)

    });

There’s plenty more that could be done to tidy this up, but that’s hopefully gives you an idea…

Restful Objects defines a set of RESTful resources, and corresponding representations, for accessing and manipulating a domain object model.  The most up-to-date version of this specification may be downloaded from  http://restfulobjects.org; as of now I’m up to v0.51.

Noteworthy changes since my last post include:

• moved content from introductory chapter into new “Patterns and Practices” section at end, and expanded its discussion
• added diagrams to show links from every representation out to the resources
• Introduced a new action-result representation, with object, list and scalar representations inlined.  This allows implementations to append additional information in the “extensions” and “lists” nodes.  In particular, Apache Isis provides changed/dirty object lists in the “extensions” node.
• renamed the “domain type member” resources to “domain member description”
• introduced a new domain type action equivalent to java.lang.Class#isAssignableFrom().  This allows clients to query the type hierarchy of domain types
• 204 “no content” is hardly returned anywhere anymore.  In particular, object put, property put, property delete, collection put, collection post, collection delete all now return representations.  Actions returning void return the action-result representation.

The spec is currently being implemented by two different open source frameworks: Apache Isis (Java) and Naked Objects MVC (.NET).    The changes in this version have come about either from those implementations, or from feedback of a Javascript client implementation that is underway.

Other comments always welcome.