Cornelia Davis’ Weblog

Getting the Apache CXF Jax-RS Basic sample running

I did it in January - just came back to it today and could not remember what I did. Where is my memory? So for my benefit, and perhaps the benefit of others, I’m writing it down. There are hints in the README that ships with the sample, but it was far from step by step.

Of course, there are a number of different ways you can get this running - this is just one way.

My environment:

• FUSE Services Framework (CXF) version 2.1.3.2
• Eclipse 3.3.2

And here’s what you do.

1. Start up Eclipse with a new or existing workspace and use the Java perspective.
2. Create a new project by selecting File->New->Other… and then Java->Java Project from Exiting Ant Buildfile. Enter the name of the project, something like “Basic Jax-RS Sample”. Browse to {FUSE Install dir}/samples/jax_rs/basic/build.xml. Check the box that reads “Link to the buildfile in the file system” and click Finish. Note that this checkbox does NOT make a copy of the sample directory, nor does it create a separate build.xml, rather uses the one that is in the sample directory. This build file references another build file that is relative to the build.xml file so in order to use the build file without changes it must be invoked from that directory.

This is all you need to do to set the project up. Now you can run it. We are going to do so all inside of eclipse. First we’ll run the server part of the sample and use a browser to invoke the services - just reads. Then we’ll run both the server and a simple client application from within eclipse. Read on.

Running the Server and GETting resources

1. Expand the Basic Jax-RS Sample project
2. Right click on the build.xml file and select “Run As->Ant Build…” - be sure to to select the “Ant Build…” with the dot-dot-dot so you can select what you want to build and run.
3. Now you can fetch some resources - note that a few are created for you when you run the server. Invoke a URL either http://localhost:9000/customerservice/customers/123 or http://localhost:9000/customerservice/orders/223/products/323. Notice in the code that customers, via the path “customers/{id}” and products, via the path “orders/{oid}/products/{pid}” are the only two resources that support GET.

Also notice that the server only stays up and running for 5 minutes by default - if you wish to lengthen this you can change the line of code in the Server.java file that reads:

Thread.sleep(5 * 60 * 1000);

And that’s it. You are running the application. If you want to test out some write operations…

Running the Server and a Client Application

Both the server and the client can be run from within eclipse.

1. If your server is not running follow the steps outlined in the section above - basically do a Run As->And Build… and select the server.
2. Now run the client by right-click on the build.xml, Run As->Ant Build… and this time select “client” (deselect “server”)
3. You can see the results of the execution in the console pane. Customer number 123 was updated and a new customer was created and assigned an id of 124 by the server. In fact you can now invoke the URL http://localhost:9000/customerservice/customers/124 to see that new customer resource.

That’s it, the basics of getting the application up and running.

Wow!

We did it!

EMC = Innovation?

Is that what springs to mind when you think of EMC? Isn’t it HP that = “invent”? Well, yeah, that HP marketing campaign was very successful but marketing or no, HP’s simply known for that innovative spirit. But EMC - what are they known for? Storage systems? Great sales force? Yes and yes. But innovation?

I admit, this isn’t likely to spring to mind but, at least for me and I suspect many of my colleagues, this is changing. I just got back from a week in Franklin, MA where EMC held its second annual innovation conference and I’d like to tell you a bit about it. First, it is an internal conference - last year it had attendance of approximately 300 - this year over 1000, more than half of which were via remote participation including video conferencing (so frankly, I think parts of it were attended by far more than 1000 people). There are several significant elements to this event.

First, is the Innovation Showcase. In the June timeframe a call for papers goes out (internally) where employees are encouraged to submit their ideas. From the submissions 30 finalists are selected and those are presented at the conference, both for “official” judging and for people’s choice. Of those 30, one people’s choice award is selected, and the top 4 are selected by that official panel of judges. Last year there approx 450 submissions were made, this year 984 from 19 countries. The cool thing is that ideas come from many different functions, in many cases individuals submit ideas that are not specifically related to their day jobs. By and large the ideas are mostly technical, though some of the finalists presented process oriented ideas as well - one of these won an honorable mention this year. The spirit of friendly competition is fantastic and the ideas are just superb. Very, very fun. (And I just saw a PR go out on the conference - you can see more of the details on the showcase and other things here)

The agenda includes internal speakers, at least one strategic customer and a set of talks from our university partners. Of those sessions, this year there was one that was quite a highlight: on Thursday morning we had a “round the world tour”. This session had a moderator in the room in Franklin who kicked off by giving us all an overview of the Centers of Excellence within EMC. We have them in China, India, Isreal and Russia and in some locations the number of employees is significant. After this overview we switched from slides on the screen to video. The first stop was China and when the camera came up on a room full of probably two to three hundred people (mind you, it was between 10 and 11PM in China!!) with one representative standing at the front with a headset on, something very cool happened. All of our China colleagues waved. And we waved back. I know it seems simple and perhaps no big deal, but it was really, really cool. There were folks in the room with whom I have been working for months via online collaboration and frequent conference calls. Particularly since I telecomute and am used to working with people remotely, I already feel I know these folks pretty well, in spite of never having seen them. But to have a video connection was somehow powerful - we really connected!! That session was quite the buzz - my impressions seem to have been shared by the bulk of the audience. I’m looking forward to our next concall with my China colleagues to get their impression.

Innovating as a big company with many established products and customers is never easy. Not only is balancing investment in those existing products and customers with investments in the new stuff is a challenge, the cultural differences are also a challenge. EMC made the committment a few years ago to take a different approach to research, creating an Innovation Network instead of autonomous research centers. The Innovation Conference, along with other things such as a EMC Fellow and Distinguished Engineering Program and lecture series are making a big impact.

Yeah, EMC is a wicked cool place to work.

one.org

I try, every once in a while, to make my way over to ted.com to watch one of the always inspirational talks. I must admit that it is hard to not watch one after the other but so far I’ve been good at rationing - I always want to make sure there is one more talk I haven’t yet seen.

This evening I watched Bono speak. The recording was from 2005 and, of course, covered the cause emergency that he is now well known for - the plight in Africa. It’s somewhat ironic that I watched this now, in the fall of 2008, a time when the economy of (historically) one of the world’s major, superpowers is absolutely melting down. I couldn’t help but think about the blow that this movement will sustain because attentions are (necessarily) adverted elsewhere. That is not to say that this issue has to go on the back burner - no way - we just need to multitask!

In any case, the talk was great! Bono is a gifted speaker with boatloads to coolness added in. For those of you who may not be familiar with the statistics - Bono tells that 6500 people die in Africa from Aids EVERY DAY. Today there are 11 million Aids orphans on the continent - by the end of the decade there will be 20 million.

Woah.

And furthermore, millions more are dieing simply because they don’t have enough to eat.

Woah.

One thing I particularly liked about Bono’s talk was his assertion that helping Africa is more than just a human rights issue but that it also just makes good business sense. Befriending people today that might otherwise be our enemies tomorrow - that is a very good investment. Can’t argue with that can we?

But the coolest thing about his delivery is that the rock star spoke to the geeks in the room. He expressed his admiration for the work that they have done and the tremendous change it has brought to the world. And he then called on everyone to use that same ingenuity, and yes, even the technology, to change the world again.

Rather than giving away any more of the talk I’ll encourage you all to view it yourselves, and afterward go sign up at www.one.org. I did.

I’ll leave you with one final quote from Bono:

Where you live in the world should not determine whether you live in the world.

CMIS and Atom/AtomPub

As has been widely blogged on by Craig Randall, Chuck Hollis, Andrew Chapman, John Newton, Ethan Gur-esh, David Nuescheler and many analysts including IDC, Burton Group, CMS Watch, 451 Group and more, EMC, IBM and Microsoft today announced that they have worked together to create a draft specification for a web services based (and I use the term “web services” more generically than as SOAP-based services) standard for content management - Content Management Interoperability Services (CMIS). Other than to point out a couple of highlights, I won’t repeat what many others have already said - but those highlights that I must repeat are:

• This is a programming language agnostic interface. No matter what language you are using to implement your client, chances are there is adequate support for the things that are needed to invoke CMIS services (uh, HTTP - ubiquitous).
• The spec defines a domain model and services in the abstract (i.e. not mapped to any concreate binding - we agreed on the core semantics first) as well as both SOAP-based and REST-based bindings.
• Wow - EMC, IBM and Microsoft all agreed on the contents of this draft!! (and there are not lots and lots of optional features specified which would make assessing compliance against the standard a nightmare and the spec much less valuable)
• The spec was designed to be layered over existing repositories - that is, no reengineering of the repository implementations is required. This presents the real possibility that interoperability can be achieved over the repositories in existence today, not just the repositories of tomorrow.

But the thing I want so say a bit more about is that the REST binding is specified as an extension to Atom and AtomPub. You may notice that more recent posts on my, as of late, slightly less neglected blog touch upon the Atom technologies - my interest in Atom is not just stemming from CMIS, I see Atom’s applicability to many other use cases beyond content management. I would say that the relative simplicity, core usefulness and significant uptake of Atom greatly influenced the choice to create the RESTful CMIS binding as an extension of Atom. There is enough in that CMIS binding to generate dozens of interesting dialogs, let me just touch upon a couple of things to start.

First, Atom applicability for content management is a natural. When we started to look at generating bindings for the abstract CMIS model, it was immediately apparent that it was very easy to create Atom Format representations for the core CMIS objects; also, many of the CMIS services deal with sets (I’m intentionally avoiding the term “collection” here because particularly in the context of Atom discussions that term is already heavily overloaded) of these objects. Yeah, we are talking about things that are easily represented as entries and feeds. And from a client perspective, the types of things that we want to do with our corresponding entry and feed representations are similar to what standard Atom clients already do - show the lists of objects and expose some of the attributes for each.

The CMIS domain model has a bit more complexity, for example, the notion of hierarchy. Folders (one of the core CMIS object types) can contain other folders as well as documents (another CMIS object type). There are lots of different ways that hierarchies can be represented of course, a flat list with pointers to ids/URIs/keys, etc. What the current CMIS draft does is include children of a folder (folder is represented as an Atom entry) as nested entries. The simple and powerful notion of foreign markup allows for this and there are a number of other ways that CMIS takes advantage of it. The Atom community has talked about nested collections before - CMIS offers an opportunity for a renewed dialog on that subject. Is it proof that entries needn’t be nested or is it a catalyst for inclusion? (In order to keep this initial post a bit on the less-long side I’ll address some of the other foreign markup that CMIS defines in future posts).

So on to AtomPub - this is where things get really interesting. You’ll notice that the REST binding starts off by defining the resource model for CMIS. It defines the folder, document, relationship and policy resources as well as many collections including children (of a particular folder), descendants (of a particular folder - this is where the hierarchy I talked about above comes in), checked out documents (ooh, now things are getting interesting), as so on. (Okay, so you’ll notice that I use the term “collections” here - I’ll admit that not all of what we call collections in CMIS follow the rules that I am being a stickler about here. It’s a draft - we’re still working on it.) Then, as good disciples of Richardson and Ruby we define which of the basic HTTP operations are supported against each. It’s pretty straight forward for many of the resources - GET on a document returns the metadata for that document (an ), GET on the document media URL gets the document contents, GET on a the folder children resource returns a containing an entry for each document or folder contained therein, … - you get the picture.

So what about the very core content management service of checkout? It’s tempting to think about the document that we want to check out as the resource that we want to manipulate - but then what operation do we apply? It surely ain’t GET or DELETE. PUT is kinda tempting - maybe I can PUT a representation that includes an attribute - true? If someone is really interested, I can dedicate a whole post to why this isn’t a good idea but the short of it is that it is generally not a good idea to model semantics such as these with a side effect to some state. So for now, believe me that this PUT approach is not good. What about POST? Well, POSTing is usually reserved for adding entries to collection resources and the document I want to check out isn’t a collection. So do we need a new verb - CHECKOUT? Hmmm, what was it that Richardson and Ruby warned us to do when we were tempted to create new verbs? And what was that we were just saying about POST and collections? AH HA - that’s it!! That is where the collection of checked out documents comes in. To check out a document using the CMIS REST, AtomPub-based binding you issue a POST of the document to the checked out documents collection!! Now that is cool. Ah, but I also have to acknowledge that by being posted to that new collection changes the state of the document. Gotta think on that a bit.

So as I reflect on what I’ve written so far I realize that I have once again gone quickly down into the technical weeds - sorry, can’t help myself, I find the weeds rather fun. But in the interest of closing out this post while it is still announcement day in some timezones I’ll save some of those technical details for future posts. My aims today really were to first, celebrate the milestone that has been reached with CMIS and also to pique interest in the particularly the RESTful binding. I’m very interested in feedback from members of the REST and Atom communities - oh, forgot to mention that as said in the press release, the draft spec will go to OASIS for ratification - watch for announcements from OASIS on when the initial meeting will be. Until the OASIS forums are established I look forward to discussions on existing mailing lists and blogs. (Note, for lack of having an automated solution for keeping spam out of my comments I currently moderate all of them - so any comments posted here won’t show up until I approve them. I’m not on vacation so there shouldn’t be too much of a delay).

To paraphrase John Newton, congratulations to EMC, IBM and Microsoft for putting aside their differences for the benefit of customers and the industry as a whole!

Best take on Chrome

I’ve read or skimmed lots of articles about Google Chrome this week, most of which focus on features - the portability of tabs, the minimalist browser panes, the speed of loading pages, … or lack thereof - synch, linux support, etc. The best post I’ve seen is The cloud’s Chrome lining written on Nicholas Carr’s blog. Carr totally gets it and sums it up very well.

…winning a “browser war” is not its real goal. Its real goal, embedded in Chrome’s open-source code, is to upgrade the capabilities of all browsers so that they can better support (and eventually disappear behind) the applications.

Google is really interested in radically accelerating the transformation of browsers from a page renderer to an operating system for today’s cloud-based applications.

This is so amazingly cool.

XSD for Atom

Another question I’ve fielded several times over the last weeks: Is there any XSD for Atom?

My first response: “What are you using the schema for?” I won’t go into all of the details of that dialog, but remember that you should always carefully consider the use of a schema before building one.

So to the point…

The Atom format spec provides a Relax-NG schema, to provide a normative description of the atom syntax. It is, however, not enough to validate XML against this schema as Relax-NG is not expressive enough to capture some of the other validity requirements for atom feeds or entries - namely the requirements listed in sections 4.1.1 and 4.1.2, respectively. XML Schema is also not expressive enough, in fact, I don’t believe any schema language is and that is why we have the feed validator (also available here - it’s opensource). That being said, a schema can be used for more than validation, and quite a lot of tooling (e.g. web services tooling) leverages XSD. Hence the question.

I did a bit of digging and found what I think is the most recent (June) Atom xsd thread from the mailing lists. In particular this thread showed up in the Abdera user mailing list - Abdera is an opensource implementation of both RFC 4287 and RFC 5023 as well as several extensions, both approved and internet drafts. It is currently in incubation with Apache.

In this particular thread Danny Ayers suggested Trang for conversion from the Relax-NG schema to xsd. I gave it a shot and while I haven’t used the resulting xsd for anything I did find that another internal project here at EMC using Atom did the same and are using that xsd.

There doesn’t seem to be a defacto standard way of obtaining an xsd for the Atom format - this mechanism seems as good as any.

UPDATE: Unfortunately I have since found that the schema produced by trang is not valid. The primary problem seems to be that it is hard to produce an XSD that allows for extension that is still deterministic. More on that shortly.

Atompub collections and resource collections

There is a subtle but important difference in the use of the term “collection” in the context of resource oriented architectures and Atom standards. I’ve literally had this conversation 3 or 4 times with colleagues in the last week or two so thought it relevant to post.

At the crux of the matter is the fact that the term “collection” is used in both the Atom context and resource oriented context. The good news is that the thing each is referring to with the term “collection” is almost the same as what is referred to in the other - the bad news is that the things they are referring to are almost the same. It is the “almost” that I want to address here. Let me start out with the good news “almost.”

In resource oriented interfaces, i.e. REST interfaces, the term collection is colloquially used to refer to sets of resources. Examples of resource collections are all of my blog entries, all of my photos on Flickr, all of my snowboarding photos on Flickr or all of the blog entries from some source that are about Atom. Pretty simple concept. The Atom Syndication Format has a construct, a feed, that can be used to represent a resource collection. The Atom format doesn’t formally define a collection (it formally defines a feed), nor does any resource-oriented literature that I am aware of.

The term “collection” IS formally defined in Atompub.

The Atom Protocol defines Collection Resources for managing and organizing both kinds of Member Resource. A Collection is represented by an Atom Feed Document. A Collection Feed’s Entries contain the IRIs of, and metadata about, the Collection’s Member Resources. A Collection Feed can contain any number of Entries, which might represent all the Members of the Collection, or an ordered subset of them.

Okay, so far, so good - seems not to have any conflict with the less formal notion of a collection in resource-oriented architectures. But later on in the spec is where the difference comes in. Atompub defines a new element, app:edited, which is the date that the entry was most recently changed, and it is the semantics around this that introduce a subtle difference between the resource collection and an Atompub collection.

The Entries in the returned Atom Feed SHOULD be ordered by their “app:edited” property, with the most recently edited Entries coming first in the document order.

“SHOULD” is defined in RFC2119 and should be read as “your compliant app really, really, really should abide by this but if it doesn’t, you better have a really, really, really good reason for any deviation.” What that means is that Atompub collections are to be ordered by the value of the app:edited value. I know, I know, there are plenty of instances where we want a feed that is ordered by something other than a last edited date - contacts or even documents alphabetically, calendar entries by the appointment date/time (not by when the appointment was created or updated), etc. Such sets of entries with such orderings can be safely represented as Atom feeds but they are NOT Atompub collections.

Why did Atompub add this constraint? Because Atompub is not only about the publishing or writing of content, it is equally about synchronization. Off line access. Take a feed reader for example. Many of them have off-line support so that I can catch up on the latest even when I am on an airplane. If the server producing the feed is Atompub compliant and you have subscribed to feeds that are in fact collections, whenever you do come on line the reader can request a refresh on a feed and be sure to get the latest changes without having to retrieve the entire feed.

Often when we have overloaded terms, like “collection”, the context of use makes it very clear which meaning is intended. In the case of resource collections and Atompub collections, however, the context doesn’t always help. One reason for that is that it is not at all uncommon for people to refer to feeds as “Atom collections”, even when they are not doing anything with Atompub. While this can lead to confusion it is technically still correct. But when someone starts talking about “Atom collections” when what they really mean are “Atompub collections”, but they are not properly ordering the entries in the collection feeds, that is when things can break.

Simply put, all Atompub collections are feeds, but not all feeds and not all resource collections can be said to be Atompub collections. I personally use the term “Atom feed” when I am referring to an Atom format representation of a resource collection and I use the term “Atompub collection” when I am referring to a true Atompub collection.

The new consumer of Atom/RSS feeds

Just this week I was talking with some colleagues about Atom and its applicability to representing content types other than blog entries and news articles and at the same time a query came over the atom syntax mailing list asking about feeds of non-blog content for use in mashups. Aside from mashups being one of the sexiest application development paradigms out there today, I’m happy to have them on the scene because they represent a class of use completely distinct from the first consumers of feeds. The original consumer of feeds was the human. Sure, there was a program that humans used to help parse the feed (the feed reader) but that parsing was generally the only automation that sat between the feed and the human. So, of course, the type of information in that feed was directly targeted at the human.

• GData: a feed including items found with the search term rest web service. (gdata API info)
• Flickr: an atom feed of publicly available photos - you would typically constrain the feed with a targeted query (flickr services info)

And moving a bit further into the realm of application consumers of feeds, OpenDS offers an Atom feed over the contents in the directory server.

Momentum is definitely building.

WOW - Photojournalism at its best

I got there via a rather convoluted path (that I’ll spare you), and I cannot believe that I hadn’t seen this before but Chris Jordan is truly a talent and one with a strong social conscience to boot. Wow. His current work, called Running the Numbers: an American Self-Portrait, (not yet complete) is to produce art, not from a single photograph (though he does that brilliantly as well - see his work on Katrina), but by building a collage. What is unique about his work is that the number of objects he is depicting in an image, sometimes in the millions, is tied to some statistic - i.e. the number of paper grocery bags used in the US every hour (1.14 million). Some of the pictures are fairly uniform, depicting sheer volume with little form, in others he creates form from arrangements of said objects, often with a degree of irony (i.e. paper bags depicting trees).

While the pictures really do tell a thousand words (or sometimes, as Mark Twain would espouse, far fewer), I found this review of his work, with a few extra words from him quite interesting - in particular, view the interactive feature.

Have a look - you won’t be disappointed!