RFC: Sorting embedded representations - some API changes in HalBuilder

[Mark Derricutt]

Hey all,

At $work our front-end guys have been asked for our HAL representations to be pre-sorted in a specific manner, which as I've mentioned on here earlier seems to be grey area in the HAL spec without any specific way to identify an ordering.

At the same time, users of HalBuilder have been asking for per-rep control over whether a single rel should be rendered as an array or only as an object.

After thinking on this for awhile, and finally having a bit of breathing room from $work I've come up with an API that seems to work, but was thinking of garnering some feedback/thoughts.

Without much fanfare, lets take a peak at the simlest case, the singleton rel:

new DefaultRepresentationFactory()
  .withRel(Rel.singleton("bar"))
  .newRepresentation("/foo")
  .withLink("bar", "/bar")
  .withLink("bar", "/bar");

Here we start with a new RepresentationFactory and declare a singleton rel type Rel.singleton("bar"):

• A singleton rel is always rendered as an object
• It is also prevented from being added twice.
• This also works with withRepresentation ( independent from link checking tho )
• withRel can also be called on the individual Representation as well as the factory.

And the second part - sorted rels ( which really only make sense for embedded representations and not links - currently ):

ReadableRepresentation party = newBaseResource(href)
  .withRel(Rel.sorted("ns:user", "id", new Comparator<ReadableRepresentation>() {
    public int compare(ReadableRepresentation r1, ReadableRepresentation r2) {
      return r2.getValue("id", 0).compareTo(r1.getValue("id", 0));
    }
  })).....

Which renders out as...

"_embedded" : {
  "ns:user sorted:id" : [ {
    "_links" : {
      "self" : {
        "href" : "https://example.com/user/11"
      }
    },
    "age" : 32,
    ...

The potentially contentious issue here is added a space separate sorted:id rel here, where the id portion comes from the declared withRel(Rel.sorted("ns:user", "id", new Comparator....

Again, the rel spec is semi unclear about the contents of the rel attribute, pointing at the Link spec and mentioning just that non-IANA rels should be URIs ( the link spec specifically allows whitespace separate rels ).

This serves as a convenient means to identify that this collection of embedded representations is also sorted.

I've not yet committed any of this to github yet but will probably push it in the morning to either a feature branch of just to develop.

Any thoughts - how are other people handling sorting ( and potentially per-representation sorting based on requests ).

Mark

--
Mark Derricutt
http://www.theoryinpractice.net
http://www.chaliceofblood.net
http://plus.google.com/+MarkDerricutt
http://twitter.com/talios
http://facebook.com/mderricutt