Modelling restful properties

I’ve recently been playing with Liberty and JAX-RS and in an effort to remember some of what I’ve discovered, I’m going to try and keep a few notes and post them here, probably along with a few questions. If anyone else finds them useful, or knows the answers, that’s a bonus!!

To start with Creating an efficient REST API with HTTP provides a nice overview of REST APIs and JAX-RS basics has a great simple sample application to get going with… and break!

Armed with the basics I thought it would be interesting to model the sample application to compare the working code with what Rational Software Architect (RSA) would generate for me. Obviously that’s not the most complex model in the world but it was good to have a few examples to follow:

• Design and implement RESTful web services with Rational Software Architect
• Getting started using RESTful services with IBM Rational Software Architect for WebSphere and IBM WebSphere Liberty Profile
• Modeling JAX-RS Subresouce locators and invoking CRUD methods from Dojo

(Those articles made much more sense when I’d tracked down all the likely looking JAXRS, REST and UML features in the RSA installer!)

Before generating any code, it was quite nice to get some basic API documentation out of the model. Not as fancy as using Swagger UI but certainly better than no documentation!

It’s only a start but that’s all for part 1. Hopefully there’ll be more posts at some point when I get further, probably along these lines:

• Creating an OSGi Web project and generating some code
• Using a REST client to check it works, including a puzzling Wink problem
• Adding some debug
• Expanding the sample with some awkward long running processing
• Deploying to Bluemix
• Anything else I encounter along the way!

If you know of any good articles/books/fancy new media that would help, please leave recommendations below. If there are better ways to design REST services (Swagger looks interesting but I haven’t had a chance to investigate), please share them. And any other tips, comments, or questions of your own are also very welcome!

 

Advertisement

Conference User Model

I hope to get round to blogging about the actual Code Generation conference at some point but this is about another Code Generation conference app. I’ve been playing with a user model based on an example at the conference and, since I mentioned the user interface generator to a few people, I thought it might be useful to share a few diagrams from the model here. If you were at the conference, and/or have looked at the Code Generation 2011 Android app, you’ll probably recognise these basic entities:

(At this point I had to stop myself going a bit mad with user objects for venues, rooms, capacities, etc. etc. etc.!)

Instead of focusing on the look and feel of a user interface, user modelling allows you to create a specification of a system from the user’s point of view. So, for example, a conference delegate might have a goal of attending a conference, which would consist of a number of tasks, like registering for the conference. The diagram below shows part of the model, with a simple task to view the available sessions:

By default, the <<select>> and <<view>> keywords on the associations between the View sessions task and Session object will generate the following activity diagram:

The user interface generator handles on screen presentation of the user objects for each of the <<ui_change>> actions in the activity diagram, while the <<command>> actions represent code that must be written to fetch data from some system. This could be code to call MDM Server transactions and, since the user interface generator is provided with MDM Server, this code can also be generated to create a basic sample data maintenance user interface. There’s no technical reason to prevent the commands getting data using any web services, or direct from a database, or anywhere really. To test drive a UI, there’s an option to generate all the code necessary for a simple file based data store for example.

Having generated enough of the user interface to view sessions, I wanted to add a way to favourite sessions like the Android app. The next diagram shows a customised activity diagram to do this:

You can see that after the UI change to view a selected session, there is now a decision with two options; there’s a Favourite flow in addition to the previous Done flow, which appears as another button in the UI. I could change the model again to make it possible to mark multiple sessions as favourites at the same time, which would require changing the cardinality of the task to user object relationship, as well as another decision node in the activity diagram. The last diagram from the model shows a more complex activity diagram that has a similar extra decision node, but for a task to manage conference tracks:

If you’re interested in finding out more about user modelling and the user interface generator, there’s an article on developerWorks. and some related blog posts. I’ve also blogged here about user modelling in the past.

Any questions or comments would be very welcome indeed.

Code Generation 2011

I’ve been having a closer look at the Code Generation event programme since my booking was confirmed. I can’t quite decide between a few of the sessions, but at the moment I think I’m most likely to choose these:

Day 1

• Can UML-Based Code Generation Be Efficient?
• Mixing Diagram, Tree, Text, Table and Form editors to build a Kick-Ass Modeling Workbench
• Model Driven Development beyond Code Generation
• Designing an Extensible High Integrity System Using Model Driven Development

Day 2

• Why program by hand in five days what you can spend five years of your life automating?
• WebRatio – how to get to 100% code generation and infinite virtuous cycles – an interactive session
• Cross-Platform Mobile Development with DSLs
• Generating Graphical DSLs
• Modelling the User Interface

That could change though, so I’d be interested to hear any recommendations. Unfortunately I won’t be there for the full conference, so don’t mention day 3!

Now I just need to organise somewhere to stay, and work out the chances of being able to park in Cambridge!

Sketching UML

Just discovered a very neat tool for playing around with small UML diagrams online. I was pondering extending the social bookmarking model earlier in the week, to make it possible to identify duplicate tags without confusing unrelated links. For example, a page tagged with ‘plant’ could be about machinery, or trees. yUML looks ideal for this kind of thing, drawing this diagram:

…from this simple markup:

# Social Bookmarking Diagram
[<<Entity>>;Tag]*-related to*[<<Entity>>;Tag]
[<<Entity>>;Tag]-[note: Tags could be ambiguous without knowing what other tags they are related to{bg:cornsilk}]
[<<Entity>>;Tag]*uses-used by*[<<Entity>>;Tagger]
[<<Entity>>;Tagger]*tagged by-bookmarked*[<<Entity>>;Link]
[<<Entity>>;Link]*applied to-tagged with*[<<Entity>>;Tag]

I can see this tool being really handy. If you want to give it a try, there are plenty of samples to get you started.

Social data modelling

I’ve been meaning to get round to extending a little social bookmarking example I started ages ago, and after a demo yesterday now seems like the perfect time. The rumours/news about Delicious are purely a coincidence; I’m definitely not planning to compete!!!

So I started out with a very basic model that only included bookmarks, which I’d now like to add tagging to, along with people. Here’s how I think that fits together:

The first question is, does that make sense as a basic tagging example? The next step is to create a physical data model, which I’m less sure about. My first attempt looks like this:

I hope I got the crows feat right, but is that a reasonable data model to achieve the kind of thing the first diagram shows? Are there any data modelling 101 guidelines that would help improve it? Any comments, tips and suggestions very welcome!

UML cats

I’ve been using UML a fair bit since I started working on the user interface generator but I still sometimes need reminding what the different associations are getting at. I’ve just been checking out the next user modeling demystified that will feature on the MDM Workbench developerWorks space and it has a nice example to help:

Mind you, that’s not the best description of the cats I’ve lived with: none of them have had collars, the word ‘owner’ is a bit suspect, and they all tended to play with mice before letting them escape under the cooker!

Update: I recently found an article describing UML class relationships in more detail, which looks quite useful. (8 February 2011)

Creating user interfaces another way

The paragraph about the user interface generator in my last post, or my other recent attempt to explain what it does, don’t really tell you very much. I hope this quick festive example provides a better idea about how user modeling and code generation can speed up user interface development.

First I needed to think of something Christmassy that might need a simple user interface. I apologise in advance, but I chose Christmas cracker jokes!! On the plus side, they’re really simple, and a basic create, read, update and delete interface makes perfect sense. So, I got started by creating a CRUD Joke UML diagram… and about five minutes later I stopped laughing to myself! Well, it’s funnier than most cracker jokes!

Anyway, the UML tools we provide for user modeling enable you to create a new user object with the default CRUD tasks in one go. Here’s what it looks like:

Next, because the user modeling is focused on the roles and goals of users, I added a few other bits just for the demo:

Perhaps a better role would have been, “Joke quality monitor”, with a goal of, “Maximise Christmas laughter”… or should that be minimise… well, you get the idea!

That’s pretty much it, I can then click the “Generate User Interface…” menu option, deploy the EAR it creates to an application server and fire up my web browser. It took longer to get this far through the blog post than it did to get a working user interface (admittedly I’m a very slow writer, but still, I think that’s pretty good).

(Thanks to a very old BBC article for that joke!)

The activity diagram behind the modify task above looks like this:

At some point you need to put real code in for the commands to interact with the back end system, whatever that might be, but to start with the tool will generate a default implementation so you can quickly prototype and test the UI.

So that’s all there is to creating cracking user interfaces.

Get your lovely fresh user interface generator here

IBM InfoSphere Master Data Management Server V8.5 has just been announced! I don’t usually get excited by IBM product announcements but the new version of MDM Server comes with the User Interface Generator, which is is what I actually work on in my day job. We get this description in the announcement letter:

A new sophisticated user interface generator for simplified user interface creation, customization, and use. This model-driven, role-based generator allows for the automatic generation and regeneration of comprehensive user interfaces and supports integration with nongenerated user interface screens.

If you’re as excited as I am, and who wouldn’t be, there’s a series of articles about the user modeling used to generate user interfaces from on developerWorks. Now it’s been shipped, I’ll probably be posting a bit more about what the user interface generator can do, plus I hope to have an update to the Setting up an MDM Server development environment post for version 8.5 soon.

Nobody deliberately builds a product that’s hard to use

There are undoubtedly some pretty hard to use products about. Computers seem particularly troublesome when it comes to making things easy to use, whether a desktop PC or in the guise of some consumer electronics like a PVR. There might actually be people deliberately designing products that are difficult to use (don’t ever hire me to write software to control lifts because impatient button pressing would definitely be taken in to account… mwahahaha!) but the reality is that it’s tough to make something easy to use. It’s even harder to modify or extend an existing product consistently.

Visual design can actually be a distraction when it comes to making a system easy to use. Pixel perfect placement of a button might make a big difference to the look of a product, but it’s how the button fits with your conceptual model of that product that will dictate how easy it is to use. (The Psychology of Everyday Things has a wonderful description of a set of doors that look great, but are difficult to use. You wouldn’t think it would be so hard to get doors right!) User modeling can help by focusing the design on the needs of users, rather than letting the design be dictated by the underlaying technology.

I’ve been having a go at creating a few simple user models since starting my new job and I’m starting to get the hang of it. Luckily help is at hand in the form of a user modeling series on developerWorks:

• Creating a system specification from the user’s point of view
• Building a user model
• Extend UML for user models

Is this the beginning of the end for products that are hard to use?