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!

 

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!

Clayton Tunnel

Tomorrow is the last of the 2010 Heritage Open Days and while searching through for something to do this weekend I spotted Clayton Tunnel North Portal on the list.

(c) Aaron Concannon. Some rights reserved.

By strange coincidence I finished my MSc 13 years ago tomorrow and my dissertation was based on the Clayton Tunnel accident. As Jo rightly points out, it’s not really that freaky a coincidence, but why let logic spoil a good story! My project was basically about modelling the accident, which is nicely explained by this more recent poster. After digging around some old files, I discovered a diagram of the tunnel:

…some screen shots of some exciting grey telegraph dials:

…and a bunch of other images; thirteen years on and .gifs are still going strong. The actual dissertation on the other hand was a little more tricky to look at. After several unsuccessful attempts with Microsoft Word Viewer, Lotus Symphony and Google Docs, OpenOffice finally did a passable job opening the ancient Word format:

Being able to step in and take on an agent’s role is one of the best ways to gain understanding about a system. In the Clayton Tunnel accident, and I suspect many other situations, there are interactions between agents that depend on the other agents having a different perspective on the model. Brown and Killick provide an excellent example of this. At one point in particular the difference between their views of the world results in the last mistake leading up to the accident. As far as Killick knows there are two trains in the tunnel whereas Brown is only expecting there to be one. Now when Killick sends, “is tunnel clear?”, to Brown as a train leaves the tunnel, Brown relies, “tunnel clear”. The modeler is omniscient about the model and hence can’t step in and act on behalf of agents with a limited view of the world without bringing with them knowledge the agent shouldn’t have: there’s a conflict of interests. This limits the modeler’s ability to accurately reproduce an agent’s behaviour.

I wonder if the Open Document Format will prove to be any more future proof. (I still have an original print out just in case!) I keep thinking it would be interesting to recreate the project in Second Life or Open Sim at some point. Maybe I’ll give it a go if I get a chance, although I would be surprised if either of those are around in the same form in 10 years time, unlike the tunnel.

Sadly the Clayton Tunnel tour was fully booked so we’ll have to find something else to do instead. Maybe it’ll be open again next year.

Master Information Hub: Customising a Maintenance UI

This is the third in a series of posts introducing Master Information Hub (MIH) development using the MIH Workbench. If you want to follow along with the example, you’ll need to take a look at the previous posts:

1. Master Information Hub: Getting Started
2. Master Information Hub: Social Bookmark Services

This post is just a few hints to get you started customising a maintenance UI generated for an MIH addition.

UML Diagrams

The user model generated in the previous post does not contain any diagrams. You can navigate and manipulate the model directly in the Project Explorer view but it is useful to have diagrams to show different aspects of the user model which you’re interested in, or when making modifications. There are a couple of quick ways to get UML diagrams depending on what you need them for.

If you’re just exploring the generated user model, Browse Diagrams can be handy. Right click on part of the model in the Project Explorer and choose, Visualize > Explore in Browse Diagram. For example, the diagram for Maintain Bookmark task looks like this:

Alternatively, when you want complete control over what to include in the diagram, or for editing the model, you can create a new Freeform Diagram. For the first modification to the user model I’m going to create a new freeform diagram called SocialBookmarkServices Domain. Right click on the model in Project Explorer and choose Add Diagram > Freeform Diagram. You can drag any model elements you’re interested in on to the new diagram from the project explorer, and you can add related elements automatically. For example, I added the following three user tasks:

…which leads neatly on to creating a domain for these user tasks.

SocialBookmarkServices Domain

The default user model does not include any domains, so when you initially log in you always have to switch to the goal view. One of Iain Duncan’s MDM Workbench blog posts explains how you can modify a generated user interface to only display the goal navigation method. To avoid making any code changes to the generated user interface, I’m going to create a new User Domain, so you can use both navigation methods instead. This approach would probably be more useful if your maintenance UI covers multiple modules.

Click on User Domain in the User Model section of the model palette, as shown below, and add it to the diagram.

Then use the Dynamic Connection to associate tasks to the new domain. You should have a diagram that looks something like this:

Use the Generate User Interface transformation configuration to regenerate the user interface; open the Generate User Interface.tc file and press the Run button on the Main tab. You can also use the context menu option to run the transformation, which is under Transform when you right click on the Generate User Interface.tc file.

Republish the web application and log in to see the new domain. You’ll notice that there are only two user tasks under the SocialBookmarkServices domain. This is because the addBookmark task appears in the user model as a non navigable supporting task for the Query Data goal. We’ll fix that in the next section.

Create Data Goal

To get the addBookmark task to appear in the domain navigation you could just set the isNavigable property to True on the supporting task stereotype. Instead, I’m going to go further and create a new User Goal for adding data.

Create a new Add Data Goal freeform diagram. Use the palette to create a new User Goal called Add Data Goal. Drag the Default Role user role and the addBookmark user task on to the diagram. Then simply associate both of these to the new goal using the Dynamic Connection, as shown here:

Regenerate and republish the web application and you should now see all three tasks in the domain navigation, plus a new goal in the goal navigation. Those task names don’t look all that friendly though but we change improve them very easily.

Task Names

The default task names are based on names from the module model, which may be obscure for someone using the maintenance UI. The task names aren’t actually too bad for the bookmark example but I would still prefer something a little less internal looking. The names on the UI are fully translatable using properties files in the UI’s help project, which makes it very easy to give them sensible names without needing to modify the generated user model.

Take a look in the generated ExampleHubUIHelp project. I needed to edit the orgModel_en_GB.properties file which was in the resources\i18n\ folder. Just edit the appropriate properties to modify what appears on the user interface, for example:

UserTask.AddBookmark.name=Add Bookmark

UserTask.GetBookmark.name=Get Bookmark

UserTask.UpdateBookmark.name=Update Bookmark

After republishing the web application, this what all the modifications look like:

These are just a few ideas to get you started. If you change anything in the generated user model, make sure you remove the generated stereotype, otherwise your change may be lost if you regenerate the user model.

The maintenance UI looks slightly better after the modifications above, but it would be a bit easier to use if the SocialBookmarkServices model had some transactions that worked without knowing the primary key of all the bookmarks. Changing that will require some custom code in the MIH module as well as user model modifications, which should be enough for another post!

Updated: Added link to Adding related elements to a UML diagram post on developerWorks. (25 June 2010)

Master Information Hub: Social Bookmark Services

This is the second in a series of posts introducing Master Information Hub (MIH) development using the MIH Workbench. This time you’ll see how quick and easy it is to extend MIH and create a maintenance UI for your new domain, with no coding required. If you want to try this exercise yourself, make sure you have set up the development environment first. The sample I’ll be building is based on social bookmarking, but you could build any data model you like.

Create a Social Bookmark Services module

To begin, create a new Hub Module Project to work on your data model. Open the File menu and choose New > Project…, then look for InfoSphere Master Information Hub > Hub Module Project.

Give the project a suitable name, and enter the Java package name and service namespace you want to use. If this is the first module project in the workspace, you will also need to give the application a name and enter the database schema name. For example:

You should now have a new project containing an empty module model, which will be opened in the module editor. Switch to the SocialBookmarkServices editor’s Model page; this is where you will enter the data model for the new module. To start with, add a new entity and add a few simple attributes as follows.

Right click on the SocialBookmarkServices folder and choose New > Entity. Call the entity Bookmark. Next, right click on the Bookmark entity and choose New > Attribute to add each of the following attributes, making sure that all of the attributes have the Persistent option checked and the Type set to String:

• Title
• URL
• Notes (check the Nullable option for this attribute to make it optional)

You should end up with something that looks like this:

Click on the Validate Model action to make sure there are no problems with the model, and fix any problems that are reported. Once the model validates successfully, click the Generate Code action to generate the MIH module implementation. Now for the fiddly bit…

Deploy the new hub application

When the code generation has finished, you need to follow a few additional manual steps to include the new module in the MIH application. Complete the tasks described in the following information center topic:

Modifying InfoSphere Master Information Hub using Workbench tools
> Developing InfoSphere Master Information Hub extensions and additions
> Deploying additions and extensions

We will only be using web services for this example, not XML over RMI, so you only need to complete these tasks:

• Modifying the InfoSphere Master Information Hub database
• Assembling the required property files
• Preparing for deployment

Note: when running in the test environment, the server will have the contents of the CustomerResources project on its classpath, but to deploy an application on a production server, the properties.jar and DWLSchema.jar files in the MIH EAR need to be manually updated with the contents of the CustomerResources project.

Now the extended MIH application is ready to publish and use. If you followed the instructions in step 4 of the getting started post, you can right click on your server in the Servers view and choose Publish.

Create a hub client

That’s the awkward bit over. Now that the MIH application is deployed and running, you are likely to want to connect to it and run transactions. One way to simplify this is by creating a hub web service client. This is the way the automatically generated maintenance UI will connect to the MIH application, so create one now. Open the File menu and choose New > Project…, then look for InfoSphere Master Information Hub > Hub Web Service Client Project. I’ve based the client project name on the hub base name, since you probably won’t want a different client for every module. Fill in the rest of the fields and click next. These are the settings I used:

On the next page, make sure you select the OperationalCodeTypeService as well as the web services for the module you just created, as shown:

Click finish and wait for code generation to complete. Now for the fun bit!

Create a hub maintenance UI

One of the new features in the latest workbench is the ability to automatically generate a basic maintenance user interface. This uses information from module models in the client project to create a UML user model for the User Interface Generator. Even the command beans are taken care of automatically when the user interface is generated, connecting to your MIH application using the web service client. As before, open the File menu and choose New > Project…. This time you need InfoSphere Master Information Hub > Hub User Interface Project. Again, I’ve based the project name on the hub base name. Enter a Java package name for the generated code, and pick the target runtime you’re using. Click finish and wait for code generation to complete.

That’s all there is to it; deploy the generated web application to the same server as the MIH application using RSA. If you followed the same example, and your test server is using the default ports, you can open the maintenance UI using the following address.

http://localhost:9080/ExampleHubUI/

Note: if your server is using a different port, you will need to update the service URLs used by the web service client. These are defined by the ejbModule/client.properties file in the web service client project.

The generated user interface should provide a simple starting point for maintaining data in a custom MIH application, and it’s a great tool for development and demo purposes. In future posts I hope to show some simple ways you might want to alter the generated user model to customise this maintenance UI.

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)

Simple Second Life building exercise

I’ve been working on a simple building exercise again recently. The basic idea is to give a taster of all the elements involved when building in Second Life, from prims to simple scripts, in the form of a trail with instructions on how to build a futuristic chair. Hopefully after completing the exercise people will be able to get more out of other much more detailed resources available, like the Ivory Tower of Prims, and (if all went well) a working chair! I have only just had the chance to work on a few of the suggestions I received after trying the trail out on a few guinea pigs at a recent hackday and I hope to get a bit more done at the weekend. If you pass through the IBM Sandbox and find the trail out there while I attempt to get it finished off, I would be very interested to know if you have any comments or suggestions.

The global shed

Second Life is full of surprises, sometimes when you least expect them. I’ve just been in the IBM 6 sandbox experimenting with a little display to show scores when PatriciaAnne Daviau stopped by to say hello. It turns out she’s been working on building a whole town far above the ground, and she took me up for a tour. Here’s part of the town- a very nice garage:

The twist is that I couldn’t even see it when I arrived- the whole town is tiny. Really tiny! Here it is with avatars to give a bit of an idea of scale:

Even that doesn’t really convey quite how small this is. From the normal view in Second Life the whole build looks more like a flat object with a picture on it. She should give out magnifying glasses to visitors! It has to be one of the most amazing things I’ve seen in Second Life.

So, to explain the title, this is what I really like about Second Life. It’s like bashing bits of wood together in a shed to build some hair-brained project when someone from halfway round the globe stops by for a chat, and to show you what they’re up to in a shed thousands of miles away. That’s some shed. And there aren’t any spiders… unless you build some!

Update: there’s now a tiny JCB to help out with the building!

Update: just found a great video of some more of the insanely small builds via the eightbar blog; still my favourite thing in Second Life. (8 Jan 2009)