For the first of these, dependency conflicts, we can use the enforcer plugin. Add the following to your POM:

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-enforcer-plugin</artifactId>
      <version>1.0.1</version>
      <executions>
        <execution>
          <id>validate-enforce</id>
          <configuration>
            <rules> 
               <DependencyConvergence />
            </rules>
          </configuration>
          <phase>validate</phase>
          <goals> 
            <goal>enforce</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
    ... other plugins ...
  </plugins>
</build>

This binds the enforcer:enforce goal to the validate phase, ie right at the beginning of the build of each project (or submodule, if an aggregator project). Any conflicts for that project/submodule, and the build will break.

For the other case, unused dependencies, we can use the dependency:analyze-only goal:

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-dependency-plugin</artifactId>
      <version>2.4</version>
      <configuration>
        <failOnWarning>true</failOnWarning>
      </configuration>
      <executions>
        <execution>
          <id>process-test-classes-dependency-analyze</id>
          <!-- needs all code to be compiled -->
          <phase>process-test-classes</phase>
          <goals>
            <goal>analyze-only</goal>
          </goals>
        </execution>
      </executions>
    </plugin>

    ... other plugins ...
  </plugins>
</build>

There is one tiny oddity here; we want to do the analysis as soon as we can, but the plugin does require that code and test code is compiled. The next phase on from test-compile is the process-test-classes, which runs directly before the test phase. The execution binding above ensures that we do the dependency analysis without having to wait for unit tests to run (ie we “fail as early as we can”).

If you use a corporate POM (one that every project’s POM would use as its parent), then you could consider moving both of these configurations up into it. That would then allow you to enforce these rules across all projects.

Recent changes have brought in:

• namespaced rel links
• the concept of addressable view models (a key part of supporting conneg)
• a slight change in the URL format so that the object’s domain type is no longer considered opaque
• deferral of some more advanced features such as paging and sorting and eager following of links (these will be added back in at a later date, for now they have moved to the ‘discussions’ chapters at the end)
• semantic versioning of the spec itself

There’s a reasonably complete change history in the doc itself.

The current state of implementations varies. Restful Objects for .NET has been tracking the spec closely, and is almost feature complete. On the Java platform, Restful Objects for Isis (as I’m now calling it) hasn’t moved on very much – it’s still back at v0.56 or thereabouts. Such time as I’ve had has been working on the spec itself, rather than the Isis implementation.

Anyway, any feedback welcome as ever.

function Sync-References([string]$PackageId) {
  get-project -all | %{
    Write-Host $proj.name; 
    $proj = $_ ;
    get-package -project $proj.name | ? { $_.id -match $PackageId } | % { 
      Write-Host $_.id; 
      uninstall-package -projectname $proj.name -id $_.id -version $_.version -RemoveDependencies -force ;
      install-package -projectname $proj.name -id $_.id -version $_.version
    }
  }
}

You can then use it to update selected packages, eg:

Sync-References FluentAssertions

One of the major changes in the next release to enable this is that we’re going to ditch the client/server “remoting” support. Although this was important feature when originally implemented (the big Irish government system that runs on Naked Objects is deployed in this configuration), it adds a heck of a lot of complexity and is increasingly less important in these days of Ajax, rich web apps, REST and mobile. So… the client/server support is being removed. As a by-the-by, that will mean that the original drag-n-drop viewer will be demoted
for use either in very simple single-user systems, or just as a prototyping and design tool.

Another, more technical, reason for that dropping the client/server remoting is important is that it allows the OIDs to become immutable. In Isis every domain object is wrapped in an “adapter”, which is the link into the Isis metamodel and which also keeps track of whether the object has been resolved from the object store. Each adapter is identified by an OID; in other words the OID is an object identifiers that act as keys to every object that is managed by Isis.

Now, with client/server, a lot of the complexity arose because it was necessary to track the persistence state of an object across the client and server. And this was done by having the OID as being mutable, keeping track of the previous OID (when the object was transient) and its current OID. With this requirement gone, OIDs can become immutable.

I’ve also taken the opportunity to simplify the OID hierarchy. In the original design of Isis, every object store implementation was responsible for defining its own OIDs. So the in-memory object store has a very simple OID, whereas the NoSQL and SQL object stores’ implementations are rather more complex. Fundamentally, though, all that an OID needs to do is to identify the class of an object, and its unique identity within that type.

The Irish government system has an OID that can be converted to a string, and this has proven really useful for scenarios such as publish/subscribe. For example, CUS|1234567A identifies a customer with a unique id of 1234567A. The format of the identifier varies; for some types it is multiple components (usually corresponding to a composite primary key in a database table).

So, the simpler design that I’m working to is that a single Oid implementation has an object type (“CUS”) and a (string) identifier. The object store is responsible for creating and interpreting this identifier, but the OID implementation itself is fixed. So, basically, an Oid is just a value object of two strings: CUS|1234567A. Much simpler!

Of course, I lie. In fact, we need to distinguish between the Oid of a standalone entity (in DDD jargon, the root of an aggregate), and the Oid of an aggregated entity (one that is owned by the root). The canonical example is always Order/OrderLine, but equally one could have a Customer/Name or – perhaps – Customer/Address. So, in fact root entities have a RootOid (as described above), while aggregate entities have an AggregatedOid. An AggregatedOid consists of a reference to the parent Oid, along with an identifier that is (at least) unique within the aggregate.

In Isis there is another type of object that also gets its own OID, namely the List/Set instances that manage the “internal” collections. These have an adapter because we need to support lazy loading; rather than introducing a proxy collecioon object, the adapter keeps track of whether the collection have been retrieved from the object store or not.

So, the full set of OIDs are:
- Oid as a top-level interface
- RootOid, as an implementation for aggregate roots
- AggregatedOid, as an implementation for aggregated entities
- CollectionOid, as an implementaion for List/Set instances.

To illustrate all this, consider the following classes:

public class Customer {
  private Name name;
  public Name getName() { ... }
  public void setName(Name n) { ... }

  private Address billingAddress;
  @Aggregated
  public Address getBillingAddress() { ... }
  public void setBillingAddress(Address a) { ... }

  private Order mostRecentOrder;
  public Order getMostRecentOrder() { ... }
  public void setMostRecentOrder(Order o) { ... }

  private List<Name> previousNames = Lists.newArrayList();
  public List<Name> getPreviousNames() { ... }
  public void setPreviousNames(List<Name> n) { ... }

  public List<Address> shipToAddresses = Lists.newArrayList();
  @Aggregated
  public List<Address> getShipToAddresses() { ... }
  public void setShipToAddresses(List&lt;Address> a) { ... }

  private List<Order> orders = Lists.newArrayList();
  public List<Order> getOrders() { ... }
  public void setOrders(List<Order> o) { ... }
}

Here, the Name class is always intended to be aggregated (irrespective of context); it is thus annotated as @Aggregated:

@Aggregated
public class Name {
...
}

The Address class, meanwhile, may be aggregated in some contexts, but not in others. Therefore the class is not aggregated:

public class Address {
...
}

However, as you can see from the Customer’s billingAddress property and shipToAddresses collections, these references are annotated with @Aggregated. Therefore, for Customer at least, Address is part of its aggregate.

Finally, we have Order:

public class Order {
...
}

This is not annotated with @Aggregated, and its references from Customer also have no @Aggregate annoation. Each Order is therefore is its own aggregate root.

And the following object instance diagram shows what would be going on inside of Isis:

I’ve linked to them from the Restful Objects website.

The Apache Isis impl of Restful Objects currently lags behind the .NET impl, though not too far behind. Check out Isis’ online demo to see the current state.

The main theme in this release is to try to simplify things a little, so that would-be users can more easily grok what Isis is about:

• We’ve updated the website, hopefully explaining better what Isis is and what use cases it hits.
• we now have the online demo linked directly from the website.
• the archetype has also been reworked; rather than have a module for each of the viewers, we’ve reduced the number of viewers (just HTML viewer and JSON viewer) and put them into a single webapp module.

You can read full release notes here.

And, as for all Isis releases, the release can be found in the Maven central repo, you can use the Maven archetype to create a quickstart app, or you can download the release and build it from source.

By the way, work is well under way on the next release, where the plan is to re-introduce the Scimpi viewer to the archetype, and also to bring in NoSQL (MongoDB) support.

Recent significant changes include a full description of how to use view models to encapsulate the domain entities while preserving the RESTful HATEOAS principle, and support support for blobs/clobs, in other words media types such as application/pdf, image/jpeg etc.

Feedback always welcome.

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.