GOAT (Graphical OSGi Analysis Tools) is one of the Apache Aries samples. It's not released code but can be found in SVN and is easily built. Check building Aries to see how.

When you have built the project, navigate to the samples/goat/goat-assembly/target directory and run the sample by typing:

java -jar osgi-3.5.0.v20090520.jar -console

Have a look at the bundles (using 'ss'), you should see several 'goat' bundles active. Now, so that you can look at it later, install the Aries JDBC blog sample into the same framework. You should be able to do this just by copying the samples/blog/blog-jdbc-eba/target/*.eba into the goat-assembly/target/load directory.

Check that the blog sample is running by navigating to http://localhost:8080/org.apache.aries.samples.blog.web/, you should see this:

Click on 'Create Author' and create an author.

Now, in a different browser window, navigate to http://127.0.0.1:8080/org.apache.aries.samples.goat.web/web/. You should see this:

Not very exciting. Click on the drop-down beside 'DummyProvider' and select 'BundleContextModel', then click 'Use Provider'. Wait a few seconds while the screen builds itself, it should look like this:

On the left hand side you'll the same list of bundles as you saw with 'ss' from the command line, in the right hand area you can see each bundle drawn as an oblong shape. Since we are displaying all the bundles in the platform this is probably a bit too much information. Hit the 'Hide all' button at the top to get rid of them.

Use the slider to move down the list of bundles on the left until you get to the blog sample bundles. Click on 'show' for each blog sample bundle, grab the bundles and move them around to get to this:

Now you can see the four bundles that comprise the Blog sample and you can see a bit of information about how they are related to each other. Try clicking on the 'twisties' to expand information about packages and services.

This is really prototype code, we wrote it to get round the problem of using a mixture of the OSGi console and slides to explain how the blog sample works. GOAT works by having an OSGi bundle in the framework which spits out information to a web front end which we deal with in JavaScript - that's what allows you to move bundles around. Even though it's at the prototype stage at the moment I think it's worth mentioning in a post. I haven't found anything similar, Knopflerfish do have a graphical display but it's static - you can't grab things and move them around.

Running the Aries samples on Apache Geronimo

The Aries samples, which demonstrate the use of Enterprise OSGi components, also run on Apache Geronimo.

To run the samples, get the Geronimo V3-M1 release from here. Either the one based on Tomcat or Jetty will do.

Extract it and change directory to geronimo-jetty8-javaee6-3.0-M1 (or geronimo-tomcat7-javaee6-3.0-M1)

I found it useful to change the default http port from 8080 to something else (I have too many things that use 8080). To do this, edit the file ./var/config/config-substitutions.properties.


 Grab these pre-reqs (may not be needed in the next Geronimo release):

• tranql-connector-derby-embed-xa-1.6.rar
• aries-datasource.xml

 And the two versions of the Aries blog sample:

• org.apache.aries.samples.blog.jdbc.eba-0.2-incubating.eba
• org.apache.aries.samples.blog.jpa.eba-0.2-incubating.eba 

Start the Geronimo server,

./bin/geronimo run

to run in the foreground. In a different window, from the same directory, deploy the pre-reqs:

./bin/deploy -u system -p manager deploy tranql-connector-derby-embed-xa-1.6.rar aries-datasource.xml


Then deploy one or other version of the blog sample (but not both :-))

./bin/deploy -u system -p manager deploy org.apache.aries.samples.blog.jdbc.eba-0.2-incubating.eba

Navigate to http://localhost:XXXX/blog where XXXX is your HTTP port and check that the blog is running.

Navigate to http://localhost:XXXX/console and log in, uid 'system' , pwd 'manager'. Use the menu under Applications-> System Modules to start, stop, uninstall the blog sample.

More extensive documentation can be found here.

SVN Git shootout at the Apache Retreat

Apache Retreat, Hursley September 2010

Photo credit: Rainer Jung

Apache Aries JPA samples

There are two things that I almost always get caught by when developing samples for Apache Aries which use the JPA capabilities. The first is to do with datasources, the second is to do with enhancing persistence entities.

I get caught out because these two things would normally be provided by a JEE compliant container - something like the WebSphere App server - so,  as an application developer I would not normally have to think too much about them. However, all of the Aries samples need to be able to run in an OSGi platform built up using a set of readily available open source bundles so we need to find ways to do things that an app server would normally do for us.

Datasources

If you look at the source for the Apache Aries blog sample  you will find that the JPA persistence bundle depends on being able to use two other bundles. The relationships are like this:

On the left, shown in yellow, is the blog-jpa-persistence bundle. This is part of the blog sample application. Inside that bundle there are two important xml files, one with blueprint configuration, the other with persistence information. Configuration in these two files points to things supplied by the other two bundles.

The middle (green) and right hand side bundles (mauve) are both providing function that would normally be part of  an app server. The green one (transaction-wrappers) is available as part of Aries, it's a really simple implementation of function to enlist a data source. This is provided in Aries as a convenience for people writing samples. The 'datasource' bundle is something that needs to be  provided by the application developer but is not part of the application, there is no Java code to write - just a little blueprint which points to your database. For an example - look at the blueprint configuration in the blog sample data source. If you were using an app server you would normally configure data sources through an admin screen - providing the data source bundle is doing just the same thing.

When you assemble the OSGi platform that you will use to run your application you will need to make sure that both the transaction-wrappers bundle and your datasource bundle are running in the platform before you drop your OSGi application onto the load directory to be run. If you are in any doubt about how to assemble the kind of OSGi platforn you will need have a look at the blog-assembly project in Aries.

Enhancing persistence entities

The other part of JPA that I always get bitten by is the need to enhance  persistence entities. Enhancing means running a utility  that takes the byte code for persistence entities, processes it and spits out another, vastly more efficient and much larger, set of byte codes. This is again something that a fully compliant JEE container be expected to do for you - so you probably wouldn't be aware of it. There are various ways to enhance persistence  entities, in the Aries samples we use Maven, look at the pom.xml in samples/blog/blog-persistence-jpa/ to see how. Sadly, not everyone likes Maven as much as I do, so here is how to do it using Eclipse.

In this example I'm using the Eclipse JEE (Helios) development platform with the "IBM Rational Development Tools for OSGi Applications 0.6" installed. This is convenient because I can work on the code, build it and then export it as an OSGi application (.eba file). The .eba file can be dropped into the 'load' directory of my Aries platform to be run.

My Eclipse screen looks like this:

I'm using a sample Stocks application; the biz module has some persistence entities and the persistence xml is in it's default location in the META-INF directory.  To enhance the entities we need to run en external tool. Click on the external tools drop-down (the thing with a little red suitcase in the top bar) and then external tools configuration. From the next screen, select 'Program' and then 'new' (a white rectangle with a yellow cross in the corner). You should see something like this:

For 'Name', type in JPA_enhancer. Then, in the 'Location' field add the location of your Java executable. For me this is: /System/Library/Frameworks/JavaVM.framework/Versions/1.6.0/Home/bin/java.

Now the fun begins. Under 'Arguments' you will need to add the command to run the JPA enhancer, for me this looks something like:

-cp MYJARS/commons-collections-3.2.1.jar:MYJARS/geronimo-jta_1.1_spec-1.1.1.jar:MYJARS/geronimo-jpa_2.0_spec-1.0.jar:MYJARS/openjpa-2.0.0.jar:MYJARS/commons-lang-2.5.jar:MYJARS/org.apache.servicemix.bundles.serp-1.13.1_2.jar:MYWKSP/org.apache.stocks.biz/bin:MYWKSP/org.apache.stocks.api/bin:MYWKSP/org.apache.stocks.biz/src org.apache.openjpa.enhance.PCEnhancer

where MYJARS is the path to a directory where I have copies of all the jars I need. MYWKSP is the path to the sample code.

It's easiest to think about this in three parts. First,  all the jars that the enhancer need on the classpath, these are:

• commons-collections-3.2.1.jar
• geronimo-jta_1.1_spec-1.1.1.jar
• geronimo-jpa_2.0_spec-1.1.jar
• openjpa-2.0.0.jar
• commons-lang-2.5.jar
• org.apache.servicemix.bundles.serp-1.13.1_2.jar

Then you'll need the class files and the source for your persistence entities and the class files for any API they depend on, thus:

• org.apache.stocks.biz/bin
• org.apache.stocks.api/bin
• org.apache.stocks.biz/src

Finally the name of the program that you are going to run :

• org.apache.openjpa.enhance.PCEnhancer

Adding that command (with your own paths of course) and saving the configuration should get you to the point where you can run your JPA_enhancer. The easiest way to check that it has worked (apart from there being no obvious errors) is to look at the size of the class files  - they should be much larger than the unenhanced versions.

Before exporting the OSGi application you will  need to modify the MANIFEST.MF of your persistence bundle to make sure that the import-package contains:

org.apache.openjpa.enhance;version="[2.0,3)",org.apache.openjpa.util;version="[2.0,3)"

Don't worry if Eclipse complains about this. Finally - just export the project as an OSGi Application (EBA) and run it by adding it to the load directory of your OSGi platform.

Colliding worlds: Development and Marketing

During my career in the software industry I've worked in both marketing departments and in development labs. Now, as a technical advocate, I'm part of the development organisation but I work with marketing.

As a software developer my first reaction to any kind of marketing information, no matter who it comes from,  is that it is likely to be junk.  I wouldn't feel this way if I felt the material was aimed at me and was telling me about tools or products that would help me. But all too often it isn't. And yet, whose fault is that? We, as developers, can't expect marketing to 'just know' about cool stuff we are working on.

Really, development and marketing should talk to each other. And now we do - a little bit :-)

To illustrate the issues for both sides, this is the story of trying to create a marketing message that both organisations were happy with.  We were trying to find an illustration to go with the phrase "Turning developers into superheroes", this was the starting proposal from my marketing colleagues:

What's wrong with that? Seriously, just about everything. This might work if the caption was "Turning salesmen into superheroes".  No developer I know would come to work dressed like that - well, the cape maybe, but the shirt and tie? Forget it.

Development's counter proposal for the image was this:

Somewhat predictably, my colleagues in marketing issued an immediate veto. Underwear on display is apparently unacceptable even if it's worn over the top of other clothes and other underwear is being worn underneath. Actually I don't know that other underwear was being worn underneath, I'm not on that kind of terms with the model. Although I can safely assert that he is, in fact, a real developer.

Impasse.

I spent the weekend 'gimping up' the aforementioned unmentionables and came up with this:

However, I never got to  show it to marketing because they produced this:

which I  like a lot. The use of a QR code was a great idea and the guy doesn't look like a salesman. The image is a bit more "Incredible Hulk" than "Superman" but it works fine.  I'm really happy with this outcome, I think that we've got a much better result by working across an organisational boundary than either of us could have achieved on our own.

Next challenge - depict the benefits of Enterprise OSGi  in the style Marvel comics :-) I will be SpiderWoman.