De presentatie van Jaap Vriend ging over LWUIT, een UI library voor J2ME. Deze library biedt een op Swing lijkend programmeermodel en maakt het veel makkelijker om een J2ME applicatie er op alle telefoons hetzelfde uit te laten zien.

Richard van der Laan presenteerde samen met Tony Sloos van ArchitecIT een pragmatische benadering van MDA. Aan de hand van een concreet voorbeeld lieten ze zien hoe je bottom-up MDA kunt invoeren, waarbij je er vanaf het begin voordeel van hebt.

Onze OSGi guru, Marcel Offermans, had een leuke demo samengesteld op basis van de leukste bug. Nu is een live demo natuurlijk altijd riskant, maar Marcel is typisch iemand die dat wel aan kan. Helaas voor hem (en voor het publiek) waren de goden hem dit keer niet zo goed gezind en lukte het niet de demo dat te laten doen wat hij had moeten doen. Dus die houden we van hem tegoed! Bij de J-Fall op de luminis stand?

De presentaties kun je als pdf downloaden:

• LWUIT, proberen of negeren?
• MDA: Slimmer ontwikkelen van Java EE applicaties
• De leukste Bug!

This blog assumes that the felix 1.4.0 environment is used. All source code used and all relevant bundles can be found in this zip.

Some of the reasons EJB3 can be of interest when moving beyond what JPA has to offer:

• container managed transactions;
• dependency injection.

For more detailed information on the advantages of EJB3, refer to this article on javaworld


Using EZB within an OSGi context may be of interest to you if you’re working with an:

• EJB3 environment and you’re thinking about migrating towards OSGi;
• OSGi environment, but you don’t have a satisfactory solution for handling persistency issues.

In this blog we will use a simple example that uses some basic EJB3 functionality; we’ll use a command line client that connects to a stateless session bean. The session bean is able to interact with an entity bean called Wombat and is able to create, update and delete (Wombat) entities. We’ll walk through the specifics of each step below.

In order to execute a command, the client first has to connect to (i.e. obtain a reference to) the stateless session bean (EzbCommand.java):

    private static final String STATELESS_REMOTE = "net.luminis.ezb.example1.stateless.StatelessRemote";

    public void execute(String commandLine, PrintStream out, PrintStream err) {
        ServiceReference ref = m_bundleContext.getServiceReference(STATELESS_REMOTE);
        m_stateless = (StatelessRemote)m_bundleContext.getService(ref);

EZB registers each stateless session bean as an OSGi service when the bundle that contains the service (and using the org.ow2.easybeans.osgi.ejbjar.Activator) is started. Because of this, it is possible to use the service without EJB3/EZB specific code in the client or the service interface, even though you can still use JNDI to lookup the service. When trying this, be warned that there’s a class loader issue. When dealing with stateful beans, this mechanism does not work and a JNDI lookup must always be used.

Following that, the session bean receives a command from the client, e.g. a ‘create’ command. StatelessImpl.java then picks up the command and creates a new Wombat object with the supplied values. Once that is done, it uses the EntityManager injected into the implementation by EZB (because of the @PersistenceContext annotation – default EJB3 behaviour) to persist the newly created Wombat entity:

    @PersistenceContext
    private EntityManager m_entityManager = null;

    public void createWombat(int id, String name) {
        Wombat entity = new Wombat();
        entity.setId(id);
        entity.setName(name);
        m_entityManager.persist(entity);
        System.out.println("Created entity bean: " + findWombat(id));

The entity bean used (defined in Wombat.java) contains three EJB3 annotations, denoting it as an entity bean (’@Entity’), indicating which table to create/use for the entity (’@Table’) and indicating which of the bean’s attributes can be used as its primary key (’@Id’):

@Entity

@Table(name = "WOMBATS")
public class Wombat implements Serializable {

    // [cut some code]

    @Id
    public int getId() {
        return m_id;
    }

Update the Felix configuration

Once again, please note that a felix 1.4.x environment should be used. For more information on previous releases, refer to the README in the zip file. In order to start the EZB bundles, a few changes need to be made in the configuration.

A pre-configured conf/config.properties file can be downloaded from here.
Of course, you can also apply the required changes yourself; an overview of the changes that need to be applied to the conf/config.properties file will follow.

Note that you’ll need the file config.properties of a previous release to copy two specific configuration entries: ‘org.osgi.framework.system.packages’ and ‘jre-1.x’ (depending on the JRE used, this is a list of packages that are exported by default).
Now, edit the config.properties of your newly installed Felix configuration and:

• Uncomment the ‘org.osgi.framework.system.packages’ entry and set the value to the one copied from a previous release.
• Add the complete ‘jre-1.x’ entry to (the bottom of) the file.

The ‘org.osgi.framework.system.packages’ entry should now look something like:

org.osgi.framework.system.packages=org.osgi.framework; version=1.4.0, \
 org.osgi.service.packageadmin; version=1.2.0, \
 org.osgi.service.startlevel; version=1.1.0, \
 org.osgi.service.url; version=1.0.0, \
 org.osgi.util.tracker; version=1.3.3 \
 ${jre-${java.specification.version}}

Note that the last line (with the ${jre-${java.specification.version}} construct) includes all items that are set in the copied ‘jre-1.x’ configuration and that this means that you must have at least 1 section in your config file that starts like:

jre-1.5=, \
 javax.accessibility; \

Also, add the sun.rmi packages to the config.properties file, which can now be done more cleanly through:

org.osgi.framework.system.packages.extra= \
 sun.rmi.server; \
 sun.rmi.transport; \
 sun.rmi.registry;

Finally, make sure Felix only logs a warning if it encounters unsupported fragment behavior through uncommenting the line with the felix.fragment.validation option:

felix.fragment.validation=warning

Download the EZB bundles

The required easybean jars can be downloaded from here. This blog is based on usage of the ‘1.1.0-M1′ release, select that release (or possibly a newer release) and then download the package available under “OSGi bundles of EasyBeans”. Unzip the file and note the location of the ‘bundles’ folder.

Install the EZB bundles

Note that this this step should be performed using a felix-1.0.x configuration or a felix-1.4.x configuration only!
In order to install the bundles, start Felix (make sure you’re using the updated configuration!) and execute the following commands in Felix:

-> cd file:/<absolute_path_to_bundle_folder>/
-> start org.apache.felix.configadmin-1.0.4.jar
-> start org.apache.felix.dependencymanager-1.1.0-2008.07.10.jar
-> start org.apache.felix.log-0.9.0-incubator-2007.12.14.jar
-> start org.apache.felix.scr-1.0.6.jar
-> start ow2-bundles-externals-commons-logging-1.0.8.jar
-> start ow2-bundles-externals-commons-modeler-1.0.8.jar
-> start ow2-util-event-api-1.0.8.jar
-> install ow2-util-event-impl-1.0.8.jar
-> start ow2-util-jmx-api-1.0.8.jar
-> install ow2-util-jmx-impl-1.0.8.jar
-> start slf4j-api-1.5.2.jar
-> start slf4j-jcl-1.5.2.jar
-> install easybeans-core-1.1.0-M1.jar
-> install easybeans-component-carol-1.1.0-M1.jar
-> install easybeans-component-jdbcpool-1.1.0-M1.jar
-> install easybeans-component-joram-1.1.0-M1.jar
-> install easybeans-component-jotm-1.1.0-M1.jar
-> install easybeans-component-quartz-1.1.0-M1.jar
-> install easybeans-component-hsqldb-1.1.0-M1.jar
-> install easybeans-agent-1.1.0-M1.jar

Once all these bundles are Active or Installed, start the easybeans-agent bundle. Once that bundle is Active, all bundles should be. Now you can start the ezb-command.jar and the statelessbean.jar bundles (same command structure as above). If you want to build the bundles yourself, copy the file easybeans-core-1.1.0-M1.jar from the ezb bundles dir and use ant to create the bundles:

cd <example1-location>
cp <ezb-bundledir-location>/easybeans-core-1.1.0-M1.jar lib
ant clean bundle.all

Once that is done, you can use the jars that can be found in the output dir.

An interesting point to note for this section is the use of the ‘easybeans-agent’ bundle. This bundle is used to stop and start the ‘ow2-util-event-impl’, the ‘ow2-util-jmx-impl’, the ‘easybeans-core’ and all ‘easybeans-component’ bundles in the right order (also refer to ‘issues encountered’ section below).

Issues encountered

• When a bundle defines an entity bean in an exported package, it must import the package ‘javassist.util.proxy’ with ‘optional’ resolution;
• The fact that EZB uses the easybeans-agent instead of using dependencies was often a source of confusion, if not errors: it felt like the startup order could not always be reproduced and only by stopping the agent, shutting down the framework and restarting both, could problems be resolved;
• Running a client from the outside (not deployed in osgi / running in another JVM) that attempts to lookup (JNDI) a session bean was a real bother (and is therefore not included in this blog);
• Injecting a session bean service that is not defined in the same bundle is not (yet) possible;
• When using entity beans defined in a separate bundle, it is required to include the entity class name to be used both in the entity bundle itself and the bundle using it;

Maybe a follow-up of this blog will elaborate on the last two issues when moving on from using a single bundle to using multiple bundles.

Conclusion

All in all, the ability to use EJB3 related features from within OSGi is definitely a good thing, even though there’s a couple of usability issues to take into account still. Keeping in mind that the product is still in development and that the support is very good (when posting a question in the ow2 mailing, a response will usually follow within a day, if not within the hour), the EZB container is definitely one to keep an eye on!

There are two disadvantages with respect to the single bundle approach (apart from
that it’s just ugly). Suppose you would develop deploy several bundles that provide
persistence services, and that these would all contain the OpenJPA jar (2.8 M) and all
of its supporting libraries (another megabyte). Having copies of these jars in each
bundle whould be a waste of space (disk space and memory!) and if you would
like to update one library, you’d have to update all bundles. Of course, it would be
much better if each “component” (whatever that me be) is in its own bundle.

Another issue is that the domain objects (in the code sample the Person
class) are bundled together with the persistence service. This is not ideal, as you can
image that domain objects can be used without persistence. Bundling them together would
require each application that uses domain objects, to have the persistence service
bundle to be installed as well. Having the domain objects in a separate,
independant bundle, results in a more modular configuration.

A domain bundle

We’ll start with the last issue, as this is the simplest one to fix. Starting point is
the sample code we developed last time (download the zip for all sample code).
The test client, a bundle that extends the
Felix command shell with a simple command to call our persistence service, is exactly
the same as last time. However, if you compare the first build file
(build1.xml) of the jpa-sample bundle with the ones from the previous blog
entry, you’ll notice differences with respect to imports of the sample bundle. This is
the result of upgrading to OpenJPA 1.1.0. With this new OpenJPA version, a number of
(obscure) dependencies (oracle, apache.avalon, weblogic) seem to be vanished, and also
commons-logging doesn’t seem to be required anymore, so we could clean up the
<bundle&gt task a bit.

Separating the domain classes is easy: create a bundle that only contains the
net.luminis.sample.jpainosgi.domain package. At the same time, we’ll
remove this package from the existing jpasample bundle (that is now
renamed to jpa-sample-service). This is not
required (OSGi can handle several bundles providing the same package), but we want to
ensure that our new setup works when the domain classes are in the domain bundle only.
However, as the domain classes use the javax.persistence package, this is
not enough: someone must export this package in order to make the domain bundle
resolvable. As this package is in the jpa-sample-service bundle, we’ll add an extra
export there (build2.xml).

If you’d deploy these two bundles in Felix and test it, you’d notice this works. But
it’s not yet perfect: due to the javax.persistence package that is
provided by the jpa-sample-service bundle, our newly created domain bundle still needs
the service bundle. That’s not we wanted, the domain bundle should be completely
independent from the service bundle! Hence, we must move out the
javax.persistence from the service bundle and make it a separate bundle.

Supporting libraries

The OpenJPA distribution comes with an implementation of the
javax.persistence package
(geronimo-jta_1.1_spec-1.1.jar). Turning this library into an OSGi bundle
is not difficult, and can be easily achieved with the Bnd tool (*).
But creating these bundles by hand is not necessary anymore, because the
javax.persistence and javax.transaction libraries that are
shipped with Apache Geronimo since version 2.1, are already OSGi bundles.
If you download the 2.1.2 Geronimo release, you’ll find the libraries in the
geronimo-jetty6-javaee5-2.1.2/repository/org/apache/geronimo/specs
subdirectory.

There are more common libraries that are used by OpenJPA and that can be easily
stripped from the bundle: the most used Apache Commons libraries are nowadays released as OSGi
bundles too. Unfortunately, the ones shipped with OpenJPA are not OSGi ready, but the
newest releases of Commons Collections, Commons Lang and Commons Pool are (see
overview). So you can simply
download these new versions and install them right away in your OSGi framework.

The Postgres JDBC driver is not yet available as OSGi bundle, so i fixed this by hand
(with a little help from Bnd). You can download this bundle, as well as the Bnd
configuration file used to create this bundle, from the
luminis open source server.
This results in a much smaller jpa-sample-service
bundle (build4.xml).

OpenJPA OSGi bundle

The final step, removing the openjar itself from our bundle, is a little bit more
tricky. We start by creating a bundle from the OpenJPA jar file. This time the Bnd
configuration file is less trivial; not only we must provide the (do-not)import
specifications that were previously in the build file (!org.apache.tools.ant;
!org.apache.tools.ant.types;, etc), but also we need to explicitely export the
packages that will be needed by other bundles. This leads to an OSGi enabled version of
the OpenJPA jar (download it here).
Next we remove the openjpa stuff from our jpa-sample-service bundle. Trying to run this
version results in an “Creating EntityManagerFactory failed!” error. What’s going on here?

To understand what’s going on, we must understand how the generic
javax.persistence.Persistence class, finds a specific
EntityManagerFactory (since that class is part of the JPA implementation
you use, in constract to the Persistence class that bootstraps it). The find out which
JPA implementation you’d like the use, the Persistence class searches the classpath for
a provider configuration file in the META-INF/services resource
directory, see href="http://java.sun.com/j2se/1.5.0/docs/guide/jar/jar.html#Service%20Provider">Jar
file specification (actually, it asks the thread-context-classloader to list all
these files). In our old scenario, with the openjpa jar inside the bundle, this worked
well because the openjpa.jar was on the bundle-classpath (and hence, could be loaded by
the bundle classloader, that was set as context-classloader). But now, these service
definitions are in another bundle and it is not possible to load these resources from
outside (it is possible to load resources from another bundle, but not in this way).

We can solve this problem by explicitly telling the Persistence class which persistence
provider we want. This is possible by passing a property:

props.put("javax.persistence.provider", "org.apache.openjpa.persistence.PersistenceProviderImpl");

Hard-coding this is of course bad style, as we would tie our persistence service to one
specific JPA implementation. In production ready software, one would make this configurable.

Now, the Persistence class knows which persistence provider (class) to create. We must
only ensure that this class is visible for the jpa-sample-service bundle: it must
import org.apache.openjpa.persistence and org.apache.openjpa.jdbc.kernel. With this
setup (build5.xml) the bundle can start and create an EntityManagerFactory.

Unfortunately, this does not mean that calling the persistence service succeeds. When
you try, you’ll get a ClassNotFoundException for the Person class. This is caused by
the fact that OpenJPA tries to load the Person class from the same classloader that has loaded
the OpenJPA classes. In this case, that is the bundle classloader of the openjpa.jar
bundle, which of course, cannot find the Person class (it does not import it). In the
previous setup, both the openjpa.jar and the Person class were in the same bundle and
thus loaded via the same (bundle) classloader.

We can solve this by setting the thread context classloader, as OpenJPA tries that
classloader too. The disadvantage of this approach is that we have to add
setContextClassLoader() calls to each and every method in our service
implementation that uses JPA, e.g.

public void list() {
    ClassLoader oldCL = Thread.currentThread().getContextClassLoader();
    Thread.currentThread().setContextClassLoader(this.getClass().getClassLoader());

    EntityManager entityManager = entityManagerFactory.createEntityManager();

    EntityTransaction transaction = entityManager.getTransaction();
    try {
        transaction.begin();
        List resultList = entityManager.createQuery("select p from Person p").getResultList();
        System.out.println("List of all persons in db: ");
        for (Object p: resultList)
            System.out.println(p);
    }
    finally {
        transaction.commit();
        entityManager.close();
    }
    Thread.currentThread().setContextClassLoader(oldCL);
}

Of course, this is not what we want. We want to be able to use a “normal” piece of
(JPA) persistence code, without change, in a service implementation. The classloader
fiddling is an infrastructure aspect, that should be separated from our business
code. A simple solution is to use a proxy object that takes care of the context
classloader, see the sample source code for details.

Setting the context classloader solves the class not found issue, but reveals another
one: OpenJPA now complains that the Person class is not enhanced. This is strange,
because OpenJPA enhance persistent classes on the fly – after all, that is how it
worked in all the previous samples. I tried to track down this issue; it has to do with
a difference between the classloader that is used to enhance the classes and the one
that is used for accessing these classes. I’m not sure yet whether this is an OpenJPA
or an OSGi (or Felix) issue. Anyway, it’s easy to solve by enhancing the classes
beforehand. If you run the enhance task in build6.xml before the
bundle task, it creates a domain bundle with pre-enhanced domain
classes. Deploy this bundle in Felix, and see how it all works fine now!

We finally arrived at the situation with two very small sample bundles, that contain no
infrastructural libraries anymore. All libraries used are now bundles on their own, and
deploying these in an OSGi framework is all what it takes to make it work.

Conclusion

We showed that using OpenJPA in an OSGi context is very easy. An OSGi service
implementation that uses OpenJPA, can be implemented in the same way you would do when
used outside OSGi. Although there is one small difference, the need for setting the thread context
classloader upon each service invocation, this can be easily hidden by using a
proxy. If you want to maximize ease of development, and have no worries about the
overhead caused by using dynamic proxies, you could use a dynamic proxy that
automatically delegates all methods in the interface.

The bottom line is that using OpenJPA within an OSGi context is painless. That makes
OpenJPA a perfect solution for introducing persistency in an OSGi based application.

For our experiments, we take a simple JPA example, consisting of one entity class Person and a Persister class that will either list all the person items in the database, or add a new one. For example, its create method looks like this:

public void create(Person person) {
    EntityManager entityManager = entityManagerFactory.createEntityManager();
    EntityTransaction transaction = entityManager.getTransaction();
    try {
        transaction.begin();
        entityManager.persist(person);
        transaction.commit();
    }
    finally {
        if (transaction.isActive())
            transaction.rollback();
        entityManager.close();
    }
}

Both operations (create & list) are contained in an interface that is published as an OSGi service, which enables code external to our jpa bundle to use this functions.

The first step in our little experiment is of course to create a bundle for these classes. We’ll use the Bnd tool for this, wrapped in the ant task that is available on http://opensource.luminis.net. We’ll start with the naive approach: we create a bundle that only contains our sample classes, add an activator and see what happens. The activator calls the Persister.initJPA() method in its start method, that tries to create the EntityManagerFactory:

private void initJPA() {
    Properties props = new Properties();
    entityManagerFactory = Persistence.createEntityManagerFactory("openjpa", props);
    if (entityManagerFactory == null)
        throw new RuntimeException("Creating EntityManagerFactory failed");
    else
        System.out.println("Init JPA ok.");
}

Of course JPA can not function without its persistence.xml file, which we add in the META-INF directory of our bundle (see build-attempt1.xml).

Installing this bundle in Felix results in one unresolved package: javax.persistence. This is easy to understand: our Person class uses JPA annotations (@Entity, @Id). We'll take the geronimo-jpa_3.0_spec-1.0.jar that comes with openJPA and add this to our bundle (eventually, we would like to make this separate bundles, but let's focus on getting it to work first). To do so, we adapt the build file to include the jar as a resource and set it on the bundle classpath explicitely (see build-attempt2.xml).

Loading this next version of the bundle in Felix, results in an exception: because the EntityManagerFactory is null. Note that there is no openJPA exception that gives us a clue about what is going wrong, but it's likely that is has something to do with the fact that we did not yet deploy any openJPA jars. So we add the openjpa-1.0.2.jar to the bundle and try again. If we try to load this bundle in Felix, it complains about an unresolved org.apache.tools.ant.types package. If we study the Import-Packages header generated by Bnd, we see a long list of missing dependencies, containing the usual suspects like org.apache.commons.lang, but also containing items like

• com.ibm.websphere.jtaextensions
• oracle.sql
• org.apache.tools.ant.taskdefs
• sun.misc
• weblogic.transaction

which will a bit harder to track down. We take the pragmatic approach of adding the packages that (we think) openJPA really needs and ignore the others. In the end, we won't get away with this approach, but for now, it suffices. See the build file build-attempt5.xml for the exact list of ignored packages and the openJPA libaries that are added on the bundle classpath.

Note that the geronimo-jta_1.1_spec-1.1.jar that provides javax.transaction is needed, even though this package is delivered with the JDK and Felix makes it available on the system classpath. The funny thing is, is that the JDK version of this packages includes only a few classes of this package (and its javax.transaction.xa subpackage). This leads to the strange behaviour that the bundle does not load with a ClassNotFoundException, even though the package javax.transaction can be resolved!

Unfortunately, adding all these jars did not resolve the issue of having no EntityManagerFactory. This turns out to be a classloader issue: the openJPA classes are on the bundle classpath, but the JPA bootstrap code (the Persistence class) doesn't know about the bundle classloader. This can be solved by passing the bundle classloader as context classloader:

private void initJPA() {

    ClassLoader oldCL = Thread.currentThread().getContextClassLoader();
    Thread.currentThread().setContextClassLoader(this.getClass().getClassLoader());
    Properties props = new Properties();
    entityManagerFactory = Persistence.createEntityManagerFactory("openjpa", props);
    ...
    Thread.currentThread().setContextClassLoader(oldCL);
}

Note the last line of this method: its considered good practice to switch back to the original context classloader before returning.

Now the initJPA method seems to succeed, it's time for a real test. If you downloaded the source code of this samples, you'll find a seperate bundle (perscmd.jar) that adds an interactive command to the Felix shell, that will talk to our PersonPersistence service. This command bundle works only with Felix (i.e. with the Felix command shell), but you can easily create a similar bundle for other frameworks, e.g. Equinox or Knopflerfish.
Running this command shows that we're not done yet: the jdbc driver class can't be loaded. Adding the jdbc driver jar to the bundle classpath (postgres in our case) solves this last classloader problem and after creating a database and a "person" table, we can finally create persistent Person classes, as the following trace of the Felix interactive shell shows:

-> persistence list
List of all persons in db:
-> persistence create 1 john
-> persistence create 2 mike
-> persistence list
List of all persons in db:
john (1); registered on Mon Mar 24 21:19:53 CET 2008
mike (2); registered on Mon Mar 24 21:20:00 CET 2008
->

The conclusion is that it is fairly simple to use openJPA in an OSGi bundle. Actually, i was quite surprised how easy it turned out to be, given my previous experience with other persistency frameworks. I guess the fact that a library is so easily deployed in a context it was not designed for, tells us something about the quality of the library. And by the way, i got the same impression about quality when browsing through the code, trying to pinpoint the few problems i had to solve.

Conclusion

There are a few things to improve. First, bundling everything in the same jar is a bit of a brute force approach; ideally, we should create one or more separate bundles for the openJPA stuff. I did some work on this already, maybe i'll come back to that later.
Second, we created a sort of a work around for the unresolved imports, which should be solved differently.
However, i think both issues are doable in reasonable time, so for me openJPA is considered a good candidate for adding persistence to OSGi applications.

What’s most frustrating about the whole situation, is that Apple doesn’t communicate at all about its plans with Java. In an attempt to make Apple stop ignoring the Java developer community, this blog started an action to make our voice heard. Of course, we support the 13949712720901ForOSX effort too. All we ask is that Apple is more open about a timeline for Java 6 support, or a statement that this will not happen at all (which would probably fuel initiatives to create a port of Java 6 by some other means).

For demonstrating the use of an external OSGi services, we’ll use a very simple bundle
exposing an AuditService service that looks like this:

public interface AuditService
{
    public void audit(String action);
}

The bundle provides an implementation of this interface that simply prints a message to
system out. You can download this bundle here; of course the
complete bundle source is available in the source
zip. It’s a plain (non-Spring) bundle
that use a standard OSGi activator; don’t bother if you don’t grasp all the details of this bundle
implementation: we’ll just use it as an external service. If you install and start this
bundle in Felix, you’ll see the new service appear when issue the services command.

Binding service to Spring bean

The next thing to do, is of course to adapt our reversestringbean bundle,
to use this service. We change the reverse method to audit-log all
invocations of the reverse method:

private AuditService m_auditService;

public String reverse(String arg) {
    if (m_auditService != null) {
        m_auditService.audit("reverse(String) called with argument '" + arg + "'");
    }
    ...
}

If you have Felix running with the previous version of
the reversestringbean bundle and made the change outlined above, you can
replace the old bundle with the new version (issue
an update command with the id of the old bundle and the file url of the
new version), and see that the reverse command is still working, even
though it has switched to the new version.
(If you get an error like “Unresolved package in bundle 19: package;
(package=nl.luminis.demo.audit)”, you forgot to install the audit bundle; install it
and try to start the reversestring bundle again.)

The new reversestringbean implementation is not using the audit service yet, because the service
reference is not set. When can make Spring do this, by specifying the service in
the spring.xml file:

<osgi:reference id="externalAuditService"
                interface="nl.luminis.demo.audit.AuditService"/>

and use this reference as property value for the bean that was already defined in the
same spring.xml file:

<bean name="reverseBean" class="nl.luminis.demo.reversestring.ReverseStringBean">
    <property name="auditService" ref="externalAuditService"/>
</bean>

When you build the bundle with the updated spring.xml file and reload it,
Spring will notice that
the reversestringbean bundle requires an AuditService, and
pass the bean a reference to that service. When you issue the reverse
command again, you’ll see the audit message printed to the console:

-> reverse hello there!
AuditService: reverse(String) called with argument ' hello there!'
!ereht olleh
->

Service not available

Now it’s time for a little experiment, to see how things behave when the audit service
is not (yet) available. After all, we’re now working in a service oriented environment
and service orientation is all about dynamics.

We’ll restart the Felix framework, with a non-active audit service. To do so, issue the
stop command on the audit service bundle and restart Felix. The framework will remember
each bundle’s last state, so after the restart, the state of the audit service bundle
will be “Resolved” (check this with the ps command). Note that we can’t
uninstall the audit service bundle, as it is the only bundle providing
the AuditService interface, and this interface (its class file)
is needed by the reversestringbean bundle. A better alternative would be
to split the audit service bundle and have the interface and implementation in two
separate bundles: in that case you could now uninstall the implementation bundle and
leave the interface bundle – this is left as an exercise for the reader .

Issue a reverse again: you’ll get a message (from the command bundle)
telling you that there
is no string service. If you’d study the output of the services command,
you’ll notice that although the reversestringbean bundle is started and
active, it is not publishing any service: not even Spring’s
org.springframework.context.ApplicationContext service we saw earlier.
The explanation for this behaviour is that Spring will not activate the bundle before
all its required dependencies are satisfied. You can verify this by starting the audit
service and trying again: now it works as before.

To continue our little experiment, stop the audit service again, study the output of
the services command and issue the reverse command
again. This time, the reverse string service is still there, even though the bundle’s
required services are not satisfied anymore. So, Spring refuses to start our bean when
the required service(s) (i.e. the audit service) are not there, but it doesn’t bother
to stop the bean when the required service(s) disappear. Personally I dislike this
non-symmetric behaviour and I think it shows that Spring was never designed for dynamic
systems: somehow they can’t really stop an ApplicationContext (and
restart it later) once it is created, I guess.

Optional service dependency

To return to our sample bundle that won’t start when there is not audit service:
this is not what we want. The reversestringbean bundle
should always perform the reverse operation; whether or not the audit service is there
(in a banking example this might not be the case, but for this example, assume
auditting is not crucial).
The solution is in the word “required”: if
we define the audit service to be optional, Spring will start the bundle, even when the
audit service is not there yet.

Let’s try this: add cardinality “0 to 1″ to the service reference definition:

<osgi:reference id="externalAuditService"
                interface="nl.luminis.demo.audit.AuditService"
                cardinality="0..1" />

and additionally, add the lazy-init="true" to the bean definition. Now
build and reload the bundle and issue another reverse command. To your
surprise (I guess…, at least to mine!), it still won’t work; you’ll get
a ServiceUnavailableException now.
Check the output of the services command: the reverse string
service is published. What’s going on here?

The point is that, in constrast to ‘plain’ OSGi behaviour, Spring provides the bean
with a proxy to the service, instead of a plain Java reference to the service
implementation (as the OSGi framework itself does). Moreover, this proxy is set,
irrespective of whether the service is available. The
ServiceUnavailableException is intentional: you should always be prepared
to get an exception when calling an external service.

I can agree with this last rule: in a dynamic environment, you can never be sure
whether a service is there; even when it was there a few minutes ago, it might be gone
at the very moment you’re using the service. However, in a case like this, I wouldn’t
expect the service proxy to be passed to the bean in the first place, until the service it
represents actually exists. We’ll come back to this in a minute.

Let’s add a try-catch block to the code around calling the service and try again.
This time it works as expected, although it might take a little longer than you expect:
that’s because Spring has a default wait time when it tries to find a service. You can
skip this by adding a attribute timeout="0" to
the <osgi:reference> element in the spring.xml file.
Now, the service behaves as expected: it does its job whether or not the audit service
is available, and it does it without any additional delay.

Dynamic services

There is an alternative to the setter injection, that better suits dynamic
behaviour: callback methods on the bean. As you’d expect from the Spring framework,
your bean doesn’t have to implement an interface in order to be listener; just add two
methods and specify their names in the spring.xml:

<osgi:reference id="externalAuditService"
                interface="nl.luminis.demo.audit.AuditService"
                cardinality="0..1">
  <osgi:listener ref="reverseBean"
                 bind-method="serviceAdded"
                 unbind-method="serviceRemoved"/>
</osgi:reference>

Note that the signature of the methods is fixed to this (at least in Spring-OSGi
1.0-m2; it was different in earlier versions, so it might as well differ in newer
versions):

public void serviceAdded(AuditService service, Dictionary d) {
    m_auditService = service;
}

public void serviceRemoved(AuditService service, Dictionary d) {
    m_auditService = null;
}

Don’t forget to remove the (setter injection) property from the bean definition. If you
add println's to these listener methods, you’ll see that these are indeed
called exactly at the moment the service appears or disappears.

You might wonder what happens when the cardinality is set to something else, e.g. 1 to
many 0 to many. In both cases, the setter that receives the service(s) is supposed to
receive a collection instead of a single service reference. The collection is managed
by Spring behind the scenes: each time you iterate over this collection, it’s contents
may be different, as it reflects the current state of the OSGi framework. Handling of
the case that there is no service is easy, as an iterator over the collection will
return nothing. However, one has still to cover for the
dreadfull ServiceUnavailableException, as a service may disappear between
the moment you get its reference from the collection and call a method on it.

Conclusion

We’ve seen how a normal Spring bean can interact with external OSGi services, and that
by using setter injection, the implementation of the bean doesn’t have to different
from a bean that is used within Spring exclusively. On the other hand, we’ve also seen
that a ServiceUnavailableException is always to be expected and that the
setter injection solution doesn’t combine very well with the dynamic behaviour of a
service oriented framework.

If you want to get it right, you can’t get away with a normal Spring bean
implementation that does not handle ServiceUnavailableException's and is
not prepared to handle missing dependencies. It’s an illusion that you can take an
existing Spring bean implementation and use it unmodified in an OSGi context. It’s
similar to having to deal with remote calls: you can’t hide remoteness from your
application, as remote calls might fail, and your code has to be aware of it – provided
you aim at robust code, of course. The same holds for a dynamic service oriented
environment: you have to deal with disappearing services, you can’t simply ignore
that. That is what makes OSGi different from old fashioned Spring usage that always
assumes that all beans are there, once the system is started.

The good news though, is that with Spring-OSGi, handling dynamic service is possible
and that it can’t be done without implementing specific interfaces. In that sense,
Spring-OSGi is non-intrusive, just like plain Spring is. You can’t ignore the fact that
you’ve to deal with disappearing services, but you can do it in a way that does not
limit reuse of your beans in other (non-OSGi) environments.

Finally a tip for those who want to experiment with the Spring-OSGi framework: enable
Spring (log4j) logging. It’s hard to get it all right the first time, especially with
all the xml-configuration stuff, and sometimes errors are swallowed by the framework,
leaving you in total dispair. Logging can enabled by passing a system property on the
java command line:

-Dlog4j.configuration=file:///your/path/to/spring-log4j.properties

You’ll find a sample log4j.properties file in the source zip. Happy coding!

With the introduction of Spring OSGi,
it becomes relatively easy to split up a Spring application in separate OSGi bundles,
and have a much more modular application architecture, without all the classloading
hassle you may encounter when deploying components in J2EE application servers.

The purpose of this series of blog posts is to get you started with Spring-OSGi. We’ll
develop some simple examples that will get you up and running.
Theoretically, it is possible to use Eclipse for developing OSGi bundles using Spring,
but, at least in my experience, this is a bumpy road with lots of obstacles, and in the
end it does not lead to better understanding of the concepts. Therefore, the samples
presented here will be provided with simple ant build files and do not require special
tools to build or deploy. The complete source code of the samples can be found in this
zip file.

OSGi is (a standard defining) a service oriented framework as well as a number of
standard services that can be deployed on these frameworks. Key concepts are “bundles”
and “services”. A bundle is essentially a normal Java jar file and is the unit of
deployment, i.e. you can install, update and de-install them in a running
framework. Each bundle can publish one or more services, that can be used by other
bundles. Bundles can locate services by querying the OSGi service registry. One of the
most important aspects of OSGi, is that even bundles that use each others services,
have nothing more in common than the service interface.
A complete introduction on OSGi is beyond the scope of this blog post, but there is
enough information online, see for example
OSGi.nl,
www.aqute.biz/OSGi/Tutorial,
www.osgi.org,
felix.apache.org.

Hello…, OSGi

We’ll start with a simple “hello world” like sample, that exposes a trivial Spring bean
as an OSGi service. The next step will be to create a bundle that actually uses this
service, so we can run the demo in an OSGi framework and experiment with this. Also,
these samples will help us to setup the compile time and run time environment
correctly.

As said, we start with a simple, not to say trivial (Spring) bean. Here is its source:

package nl.luminis.demo.reversestring;

public class ReverseStringBean
{
    public String reverse(String arg) {
        String result = "";
        for (int i = arg.length() - 1; i >= 0; i--)
            result += arg.charAt(i);
        return result;
    }
}

To make it Spring bean, we have to add a configuration file that defines the bean. In
plain Spring this would be something like:

<beans xmlns="http://www.springframework.org/schema/beans">
  <bean name="reverseBean"
        class="nl.luminis.demo.reversestring.impl.ReverseStringImpl"/>
</beans>

(omitting xml namespace stuff for brevity, see the zip for complete source).

Exposing beans as OSGi services is fairly simple in Spring-OSGi. Basically, the only
thing you’ll have to do is to add an <osgi:service> element to the
spring xml configuration file like this:

<?xml version="1.0" encoding="UTF-8"?>
<beans> <!-- (again, namespace declarations omitted) -->

  <bean name="reverseBean"
        class="nl.luminis.demo.reversestring.ReverseStringImpl"/>
  <osgi:service ref="reverseBean"
                interface="nl.luminis.demo.string.ReverseString"/>

</beans>

Of course, we need an interface that defines the service we’re exposing, so we define
the ReverseString
interface and add the reverseString() method to it.

To make it a bundle, the last thing to do is add a manifest file with the (OSGi)
required entries:

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: ReverseStringBean
Bundle-SymbolicName: ReverseStringBean
Bundle-Version: 1.0.0

Strictly speaking, not all of these entries are required, but it is common practice to
have at least these entries in the manifest file.

This completes our first bundle. If you’re familair with OSGi you might wonder if our
bundle doesnt’ need a BundleActivator, that provides start()
and stop() lifecyle methods that the OSGi framework can call to start or
stop our bundle. The answer is that it doesn’t need it, because Spring-OSGi works
similar to the OSGi declarative service specification: the framework will inspect the
service declaration and instantiate the service on our bundle’s behalf; instead of
publishing the service ourselves (from within the BundleActivators start method), the
framework “pulls” the service out of our bundle, so to speak.

Setting up the runtime environment

Now it’s time to set up our run time environment. For the demo we will
use Apache Felix 1.0, but you can deploy the
bundle in any OSGi framework, e.g. (Eclipse) Equinox, or Knopflerfish. Download felix
and start it by executing the jar file in its bin directory and enter a profile
name. If you enter ps on the prompt you’ll see that there are only three
bundles active: the system bundle (i.e. the framework ifself) and two bundles that
constitute the shell service that executes the commands your typing at the
prompt. Install our demo bundle by using the install command, passing it a
file url that points to the bundle:

-> install file:///Users/peter/.../reverestringbean.jar

You can start the bundle now, but it won’t register any services yet, as no
one is paying attention to our service declaration in the spring.xml
file. Execute the services command to confirm this.

As the final step in setting up the run time environment, we’ll install the Spring-OSGi
framework. For this demo, we used the milestone 2 release of Spring-OSGi 1.0; newer versions should work also, but of course, small (presumably subtle) differences may occur.
Make sure you download the “-with-dependencies” zip file.

Install these Spring-OSGi bundles from the dist directory:

• spring-osgi-core-1.0-m2.jar
• spring-osgi-extender-1.0-m2.jar
• spring-osgi-io-1.0-m2.jar

These bundles depend on (but do not include) the plain Spring code, so you have to install
a number of bundles (all of which can be found in the lib
directory) that contain the plain spring framework modules:

• spring-core-2.0.5-osgi-m2.jar (from spring-core/2.0.5-osgi-m2/)
• spring-aop-2.0.5-osgi-m2.jar (from spring-aop/2.0.5-osgi-m2/)
• spring-beans-2.0.5-osgi-m2.jar (from spring-beans/2.0.5-osgi-m2/)
• spring-context-2.0.5-osgi-m2.jar (from spring-context/2.0.5-osgi-m2/)
• aopalliance.osgi-1.0-SNAPSHOT.jar (from aopalliance.osgi/1.0-SNAPSHOT/)
• backport-util-concurrent-3.0-SNAPSHOT.jar (from backport-util-concurrent/3.0-SNAPSHOT/)

Additionally, some SLF4J libraries
have to be installed. SLF4J is a logging facade for several logging implementations,
similar to Apache Commons Logging. An important difference with Apache Commons Logging
is that in order to determine what implementation to use, it does not rely on
classloading tricks that can cause a lot of trouble, especially when
used in dynamic environments like an OSGi framework.

From SLF4J you need the following libraries:

• slf4j-api-1.4.3.jar (contains only the SLF4J API)
• slf4j-log4j12-1.4.3.jar (implementation of SFL4J, hard-wired to log4j)
• jcl104-over-slf4j-1.4.3.jar (100% compatible drop-in replacement for Commons Logging)

Just install them as normal bundles, these libraries are OSGi ready. The
jcl104-over-slf4j library contains modified versions
of org.apache.commons.logging.Log.java etc, that redirect to SLF4J. This
will take care of libraries using the Commons Logging API.

As we’ll be using log4j as the logging implementation that does the real work, we’ll
have to install that too. An OSGi compatible version of log4j can be found in the
Spring OSGi package

• log4j.osgi-1.2.13-SNAPSHOT.jar (from src/spring-modules/spring-required-libraries/log4j/target)

but, you’ll have to build it first (with maven). Alternatively, you can download the
file here.

After you’ve installed these bundles, you can start them all. Note that if you try to
start some bundles before you installed them all, you’re likely to get errors about
unresolved packages; to avoid that you would have to install them in the right order.
You’ll probably see some warnings about resources files and namespace handlers that
can’t be found, which you can just ignore.

Now the Spring-OSGi extender is running, it should have discovered and published our
service. Due to a bug in the M2 release (fixed in later releases), it doesn’t yet work this way and you have to
restart our bundle. If you do so, you’ll get some warnings about BeanInfo classes not
being found; ignore these too.

Using the service

If you issue the services command once again, you’ll notice that our simple demo
bundle provides to services: nl.luminis.demo.string.ReverseString
and org.springframework.context.ApplicationContext. The latter is the
well known Spring application context, that is merely provided as OSGi service for
debugging purposes (you shouldn’t use it to access a bean from outside its bundle).

Essentially, we’re ready now, as our first spring enabled bundle is up and running and
publishes its service. However, we can’t be satisfied until we’ve actually seen it do
something “usefull”. To make that happen, we’ll write an extension for the felix
command interpreter, that will call our service. This extension will be a bundle on its
own. As it hooks in into the Felix command shell, this of course is a Felix specific
solution, but similar constructs exist for Equinox and Klopflerfish.

The heart of this command bundle is the execute() method, that tries to
locate the service and calls it:

public void execute(String line, PrintStream out, PrintStream err)
{
    // (...)
    ServiceReference ref = m_context.getServiceReference("nl.luminis.demo.string.ReverseString");
    Object service = (ref != null)? m_context.getService(ref): null;
    if (service != null)
        try {
            out.println(((ReverseString) service).reverse(arg));
        }
        catch (Exception e) {
            err.println("calling reverse string service failed: " + e);
        }
    else {
        err.println("no reverse string service, ref=" + ref);
    }
}

See the source.zip for the complete source code.

After installing and starting the command bundle, you’ll notice the new “reverse” command in the
help text:

-> help
...
install <URL> [<URL> ...]           - install bundle(s).
ps [-l | -s | -u]                   - list installed bundles.
resolve [<id> ...]                  - attempt to resolve the specified bundles.
reverse <arg>                       - reverses a string, using a ReverseString service
services [-u] [-a] [<id> ...]       - list registered or used services.
...

and issuing this command will finally show that our service works correctly:

-> reverse  OSGi is cool!
!looc si iGSO
->

This concludes our first working Spring-OSGi sample. It’s not yet a full-blown J2EE
application, but it clearly shows what is needed to make a basic Spring-OSGi bundle
work and have it publish a bean as an OSGi service. In future installments, we’ll have a
look at using external OSGi services in our beans, and experiment with some less
trivial bundles, including a simple web application and database access.

When I was looking for such a monitoring application, I came accross the 2.0 version of MC4J that
provides a "Thread Info" panel that
displays threads together with CPU usage; exactly what I
needed. Unfortunately, there is only an alpha release of this MC4J
version, that is not yet perfectly stable. Moreover, the thread info
panel doesn’t handle applications with large amounts of threads very
well. As the source code of this version of MC4J is not (yet)
publically available, this option turned out to be a dead end.

To my surprise, other applications with such functionality are hard to
find. There are probably enough profiling applications that can do the
job, but I wanted something simple, something JMX-based, that can used
also to monitor applications running in production.

There is however something called JTop, which is a plugin for
JConsole. It’s actually a demo for the new (since Java 6) JConsole
plugin API, that does show CPU usage per thread. It’s fairly basic and
only shows total CPU usage, which is not very usefull. You would
expect that (after a year), somebody would have extended the demo to
something more useful, but as I couldn’t find anything like that, I
thought I should give it a try myself.

The result is a JConsole plugin that displays the top threads, sorted
by cpu usage in the last sampling period. It also displays cpu usage
history, and an average over the last 10 sampling periods.

To avoid ending up with an unresponsive user interface when monitoring
applications with large number of threads, I took a few
precautions. First of all, the plugin has it’s own refresh rate. It’s
independent from the JConsole poll interval, which is 4 seconds by
default. For applications with large amounts of threads, this is way
too short: only retrieving all thread information can already take 4
or 5 seconds! Although you can change the JConsole poll interval with
a command line option, I thought it would be more convenient to be
able to change it from the monitoring panel. It’s default set to 10
seconds, which I think is reasonable in most cases. If you notice that
cpu usage measurement takes too much of the application under test,
just increase the sample period and see the RMI Connection thread that
processes these request, sink in the list.

Another precaution was not to list all threads in the
table. Displaying thousands of rows in a table is quite useless in any
case, and I was afraid it would seriously harm
performance. Eventually, diplaying that many rows turned out to be not
much of a problem; I guess I still suffer from an prejudice with
respect to Swing performance…

Using MX4J also showed me that in a continuously refreshing table,
it’s hard to select a thread in order to see it’s
stacktrace. Therefore, in this plugin, tracing a thread is "sticky":
when you click a row in the table, the stacktrace of that thread is
shown immediately and is refreshed with each new sample, until you
deselect it or select another thread.

Even though having threads sorted by cpu usage is the logical thing to
do, it’s not always convenient when you’re studying the results, as
rows keeping moving with each refresh. To lock the rows to there
current position, click the "fix order" button. The topmost rows
(actually all rows with a non-zero cpu usage), will stay where they
are. Rows that had a cpu usage of zero, but have a non-zero value
in the next sampling periods, will appear just below these rows, to
avoid that you oversee any thread that suddenly takes a large amount
of cpu time.

You can run the plugin by downloading the jar file and passing it to JConsole with the plugin option:
jconsole -pluginpath topthreads.jar. When JConsole connects, it should have a seventh tab named "top threads".

Wat mij betreft is de redenering heel helder: weliswaar definieert de javadoc van
Object dat het resultaat een "concise but informative representation" van het object
moet zijn (en voor mensen goed leesbaar), maar dat laat nogal wat ruimte voor
variatie. Als programmeur kun je er dus niet op vertrouwen dat hetgeen je terugkrijgt
van toString bruikbaar is om er iets mee te doen of enige beslissing hierop te baseren.

Dit wordt nog wel eens afgedaan als een theoretische redenering. Immers, als je zelf de
toString implementeert weet je precies wat hij teruggeeft, en waarom zou je die kennis
niet kunnen gebruiken? Als je het heel netjes doet specificeer je in de javadoc heel
precies wat de return waarde is, en niemand kan je wat maken.

Waar dit aan voorbij gaat, is dat "derden" die specifieke semantiek niet verwachten. Er komt een dag dat
iemand anders de code aanpast of met een afgeleide class uitbreidt, en die gaat niet de
javadoc van toString() bestuderen – die kent hij al. Zonder zich er van bewust te zijn
breekt hij het (gewijzigde!) contract en is Leiden in last. En laten we wel wezen: op
de keper beschouwd was het preciezer definieren van het toString resultaat al een
wijziging in het contract. Hiermee wordt een belangrijk principe van "good coding
style" overtreden: goede code bevat geen verrassingen.

Aanroeper onbekend
Een andere reden om op te passen met de implementatie van de toString method, is dat
het onderdeel is van het Object contract en je nooit weet wie of wat je wanneer
aanroept. Hoe vreselijk dit uit de hand kan lopen, merkte ik een tijdje geleden toen ik
probeerde een performance probleem op te lossen.

Het ging om een applicatie die draaide op JBoss. De testers hadden het gevoel dat de
applicatie onder zware belasting steeds langzamer werd – meer dan ze op grond van de
belasting zouden verwachten. Met een profiler had ik van alles onderzocht, en ook wat
kleinere issues opgelost, maar de klacht bleef.

Nadat ik op een gegeven moment wat had zitten monitoren met JConsole en eigenlijk
gedachtenloos wat zat te klikken in de thread view, viel mijn oog op een stacktrace
waarin een toString method werd aangeroepen van een van andere Queue class. Dat was
verdacht, vooral omdat in die applicatie bij zware belasting nogal lange queues konden
ontstaan. Het zou toch niet zo zijn dat…

Het was wel zo. De queue bevatte enkele duizenden of tienduizenden elementen en de
toString leverde een string op van enkele megabytes groot (niet echt "concise"). De aanroep kwam uit een
toString van een worker-thread class; waarschijnlijk had iemand daarin ooit de toString van
de queue toegevoegd om beter te kunnen debuggen. En de verrassing was dat deze methode
niet vanuit applicatie code werd aangeroepen, maar vanuit JBoss.

Ergens diep in de transactie en lock management van JBoss, wordt van een thread die in
een wachtrij geplaatst wordt, de toString() aangeroepen; ook hier weer voor
debugging en/of monitoring. Hoe drukker de applicatie, hoe meer locks, hoe vaker de
toString werd aangeroepen en hoe drukker JBoss was met het uitrekenen van Strings die
eigenlijk nooit gebruikt werden, in plaats van met het uitvoeren van applicatie code.

Het was zo’n vondst waarop je altijd hoopt als je performance problemen onderzoekt. De
aanpassing was letterlijk in twee tellen gebeurd en de performance verbetering was echt
aanzienlijk.

De moraal van het verhaal is duidelijk: geen gekke dingen doen in de toString, want je
weet nooit wie het aanroept. En dat geldt niet alleen voor (afgeleide classes van)
infrastructurele elementen zoals Thread, maar juist omdat toString onderdeel uitmaakt
van het Object contract, voor alle classes.

Thanks to the fact the ThreadPoolExecutors provides an abstract method afterExecute()
that is called after execution of the task, I didn’t have to pollute my task
implementation with retry logic, but could clearly separate these concerns. In the
afterExecute() method of the (subclassed) ScheduledThreadPoolExecutor, I could ask the
task whether it had succeeded, and if not I could simply reschedule it. And all this
just in a few lines of code:

void afterExecute(Runnable task, Throwable exception) {
     if ((RemoteCallerTask) task).failed()) {
         super.schedule(task, 10, TimeUnit.SECONDS);
     }
}

When I first tested it, I got a ClassCastExeception. My first guess was that it might
have something to do with different class loaders, but when I ran it in a debugger it
turned out to be something that realy surprised me: the Runnable task that was passed
to this method was not my do-a-remote-call task that I had passed to the executor, but
something of a completely different type
(ScheduledThreadPoolExecutor$ScheduledFutureTask).

Maybe I misinterpreted the documentation? I went back to the ThreadPoolExecutor
javadoc. It talked about “methods that are called before and after execution of each
task”, and the parameter description claimed the Runnable parameter to be “the runnable
that has completed”. This seemed to match my expectations: you execute a Runnable task
and that is what is passed to afterExecute. That would be the only sensible definition
of a after-execution hook, wouldn’t it? As the source code is the best documentation, I
checked the ThreadPoolExecutor source, which confirmed what I was expecting: the task
that is run is passed to the beforeExecute() and afterExecute() hooks.

A little bit of studying on the ScheduledThreadPoolExecutor source revealed why I got a
ClassCastExeception: it wraps the (user supplied) task in a ScheduledFutureTask object
before passing it to the base class (that puts it in the task queue). One of the
reasons why this wrapper is needed, is because the ScheduledThreadPoolExecutor uses a
DelayQueue to store the tasks and elements of this queue must implemented Delayed
(i.e. have a method that returns the delay). This type of queue sorts tasks based on
the delay: shorter delay comes first. When taking an element from the queue, it blocks
until the delay of the first task has passed. Using this type of queue makes the
implementation of the ScheduledThreadPoolExecutor quite simple: it wraps the task in a
wrapper that implements getDelay() and puts these wrappers in the queue.

Although I can appreciate the beauty of using a DelayQueue in combination with a normal
ThreadPoolExecutor, I don’t think it is the right solution. The point is that it breaks
one of the fundamental principles of OO programming and that is that derived classes
should respect the contract defined by the base class(es) (and or interfaces). The contract
that the base class ThreadPoolExecutor defines, is that it will call the hook methods
with your task as a parameter. ScheduledThreadPoolExecutor breaks this contract, as it
does not adhere to what its base class has promised.

This break of contract shouldn’t be taken lightly. It makes code that uses these
executors fragile: if for some reason someone decides to use the other class as
implementation of the general executor service, existing code might break. Put
differently: in order to make your code robust, you would to have to take into account
which executor implementation was chosen, at different points in your code. This
violates principles of encapsulation and abstraction: code should never depend on
implementation types, only on interfaces.

I was pretty disappointed that even in the concurrency API, such fundamental
mistakes can be found. Moreover, it appeared this is not the only break of contract, and that fixing this properly doesn’t seem to have any priority, but more on that later.