Thursday, 4 October 2007

Gaikokugo - high level design

I decided to try and document my approach with Gaikokugo. My first problem is describing OSGi services in UML. Peter Krien's touched on this in his blog [here], and looks like he gave up. I like Peter's simple notation and the more complicated diagram further down the post is likely to get very complicated in a UML environment. However, I'm determined to use UML (as there are so many tools to hand and is pretty much an industry standard), so here is what I came up with to describe the core components of the Gaikokugo Language Platform as it currently stands using a simple component diagram.

The components represent OSGi bundles or Eclipse plugins, as appropriate.
  • gaikokugo.common contains common classes used throughout and exposes no services. Right now it contains a single class; GaikokugoException, which is an unchecked exception that can be used to wrap checked exceptions or thrown when it is unreasonable for the application to cope with the current situation or checked exception.
  • gaikokugo.rcp is the UI part of the application, an Eclipse specific plugin. All of the UI code is in here at the moment. This may change and I'm already considering adding an extension point to allow a re-usable Exception handler to be plugged in to handle the unhandled exceptions and report them back to me via email, or directly in to buzilla, etc. This is likely to be a seperate project and an extension point is probably not even required, now that I think about it.
  • gaikokugo.db is a standard OSGi bundle that exposes the persistence interfaces for the application. One of my goals for this application was to avoid having to have the user "save" their work as they went along, so my design forces the implementation of the db to be persistent throughout. I do talk in terms of database, but the GaikokugoDBService's only method is to open a file on the filesystem. How this file is read and written is up to the persistence implementation.
  • gaikokugo.db.db40 is a persitence implementation based on db40 and registers itself as an implementation of the GaikokugoDBService interface exposed in the db bundle. I was using the db40 OSGi bundle, but I just couldn't work out what benefits it gave me over included the libraries in the bundle itself and I had problems getting Eclipse to detect it as a plugin. Anyway, all of the implementation code for the db is specific to db4o in this bundle, so no problems with classloaders or anything like this.
  • gaikokugo.db.db40.test doesn't yet exist, but will contain unit tests for the db40 implementation. This will most likely be executed using ProSyst's Test Platform... but even though it is excellent it isn't a free piece of software, so I may build my own OSGi based unit testing framework.
  • likewise gaikokugo.rcp.test also does not exist, but envisaged having UI unit tests in this bundle, as well as an implementation of the db bundle specific to the UI tests. Not sure how I am going to do this yet, but I believe it is possible to hook in to the UI programmatically in order to simulate user activities.
There is still lots to be done, but at least I have done some design... I have started listing the features of the project as "Mylyn Tasks" within my Eclipse IDE. I probably need a better way to do this as I frequently switch from my laptop to my desktop PC and I don't think the tasks come along for the right. I should probably setup bugzilla or something similar.


Peter said...

well, I have not given up. We are actually talking about the technique because some of us are working on an OSGi book.

I buy the argument that there are many tools out there that support UML. However, the interface symbol is not a service, and absolutely not a dynamic service like OSGi. It is also too hard to see in your picture who registers and who does not. Because you modify the semantics of the symbols, you use the UML tool as a drawing tool ... I think.

I found using the triangles as services extremely helpful to interpret large systems because they nicely show the flow because the arrows of the triangle point in the call direction. However, given good arguments I am willing to change to come up with a standard. However, out of the box is missing the right symbols. (Ab)using the existing symbols is bound to be confusing. Can't these symbols not be added to the tools?

To show the difference, I also made an interpretation here:

Peter Kriens

Chris Brind said...

Hi Peter,

Thanks for your comments.

I think you've misinterpreted my component diagram (which compounds the fact that it probably isn't clear). Your diagram suggests that the db bundle requires the test bundle, but that's not the case.

The dependancy is as follows:

db.db4o.tests requires db.db4o
db.db4o requires db
db requires common

The only bundle which registers the service is the db.db4o bundle.

(The RCP side looks correct)

Also, how would I know which bundle exposes the service interface?

Finally, which tool did you use to create your diagram? One of the problems with there being some many UML tools is that the free ones are usually incomplete in some way and the really good ones cost a lot of money. Even a free generic diagram tool would be more useful sometimes.

My belief is that UML is extensible (through profiles? I need to find out more about this). However, the UML standard doesn't dictate that a tool must allow the symbols to be changed (though I believe that this is valid according to UML) and so you get out of the box notation with most tools and yes, they're not right for every situation. (I used to Star UML for the diagram in the main post).


German Viscuso said...

I've created this space for you.
This project looks interesting (specially if you'll be providing modules for testing db4o)

Best regards and thanks!

German Viscuso
db4o community manager

Chris Brind said...

Thanks German! I'll be sure to update it. Have been on holiday for a week so only just seen this. =)