How to provide hibernate persistence support along with class libraries

Suppose you want to encapsulate some kind of functionality in a class library, and you want to provide an easy way for the clients of your library to persist certain entities from your library with hibernate. I think the most straight forward way to do this, is to provide hibernate UserType implementations along with the entities in the class library that the client might want to persist. Joda Time for example, uses this approach. Joda Time is a class library to work with dates and times, and the Joda Time Hibernate Support project provides hibernate UserType implementations for many of the entities from Joda Time.

This approach works perfectly well, but it is limited to what one can express in a hibernate UserType. One of those limitations is that you can not (or almost not) use a single UserType to persist an entity that has a one2many relationship with something else (probably a value type). I encountered this problem when writing a class library to manage IP address pools (an IP address pool is a continuous range of IP addresses of which some are "free" and some are "allocated"). I represent an IP address pool as a class (IpAddressPool) which contains a sorted set of free sub-ranges in the pool. Persisting this would naturally result in a one2many mapping (using hibernate to map the SortedSet). Writing a single UserType which is capable of persisting IpAddressPool instances (including the one2many mapping) is (almost) not possible. I say almost, because it might be possible to access the JDBC connection directly and do everything by hand, but obviously I would like hibernate to manage the one2many relation.

So, when UserType implementations are not an option, what other options do we have?

• we can simply do nothing and leave it up to the client to create the necessary hibernate mappings;
• we can provide a mapping and a perhaps even a DAO and let the client use that by "injecting" its session factory into it;
• we can do the same with annotations;
• we can prevent the one2many mapping by serializing the sorted set into a single string representation or something like that, and use a simple UserType after all;
• ... ?

The first solution is not really a solution at all. Apart from not helping the client of your library with the persistence aspect, it also means that we need to expose the internals of our classes such that clients can write correct hibernate mapping files for them.

The second solution is a bit better, but still not as good as the UserType approach. It typically results in having two mapping files (one from the class library, one from the client application) and thus complicates things like schema generation. It also makes it more cumbersome to integrate it with your client application. The provided DAO for example, might not be aligned with the DAO style of the client application, or the DAO might not provide certain queries the user wants to perform. Also, the client application might use annotations to express the hibernate mappings, while the class library uses an XML mapping file. Querying on properties of the entity in the class library is possible, but it means the internal representation has to be exposed. The UserType (and more specifically CompositeUserType) API has a nicer way to expose properties on which HQL queries can be performed without having to expose the internals of the entities in your class library, which can unfortunately not be used in this solution. It also becomes a bit problematic if you have multiple entities in your class library of which a client might only use a few.

The third solution is basically the same concept as the previous, except we could use annotations in stead of mapping files in the class library. It has all the typical advantages of annotations, but also means that the class library now needs a dependency on hibernate, even if the client doesn't care about persistence.

The fourth solution is more a workaround than a real solution. I think it might be appropriate in some situations though. In the IP address pool example this actually works very well, although it could become a problem for very large pools with lots of fragmentation (many entries in the sorted set of free sub-ranges) and it also complicates manual SQL database queries.

 

If anybody has better suggestions, or if anybody can prove me wrong on the claim that this is not feasible with a UserType, I'd be happy to hear about it.
 

Modernizing MultithreadedTC: JUnit 4 integration

MultithreadedTC is a nice library to help writing tests for multi threaded applications (go check out their website for some examples, I can 't explain it better). Writing and testing multi threaded applications is not an easy task, so having a decent test suite for to help with that task is no luxury at all. I think MultithreadedTC does a nice job, it certainly helped me to write better and more elegant tests than I would have been able to without the library.

One thing I find it a bit frustrating though, is that it doesn't integrate with JUnit (4) very nicely. Basically, with MultithreadedTC, you have to write a class which extends MultithreadedTestCase, with some methods that start with "thread" (a naming convention for MultithreadedTC to know what to run in which threads)

class MyMultithreadedTest extends MultithreadedTestCase {
  public void threadFoo() {
    ...
  }
}

To execute this "multi threaded test case", you have to instantiate it and pass it on to one of the static methods in the TestFramework

TestFramework.runOnce(new MyMultithreadedTest());

Although the name MultithreadedTestCase suggests it is a JUnit test, it is not. To get it all bootstrapped in a JUnit test, you typically end up with an inner class (extending MultithreadedTestCase) inside a JUnit test, and a single JUnit test method to call the TestFramework.runOnce() method

public class SomeTest {
  class MyMultithreadedTest extends MultithreadedTestCase {
    public void threadFoo() {
      ...
    }

    ...
  }
  
  @Test
  public void test() {
    TestFramework.runOnce(new MyMultithreadedTest());
  }
}

This obviously works, but I think we can do better.

I updated the MultithreadedTC library such that multi threaded tests are real JUnit tests (including all the benefits that has, such as using the @After and @Before annotations), in stead of merely something which can be bootstrapped from within JUnit. I also added some annotations for the "thread" methods, in stead of the naming conventions.

The above now looks like this

public class SomeTest {

  @Thread("Foo")
  public void threadFoo() {
    ...
  }
  
  @Test
  public void test() {
    ...
  }
}

Consider the first example on the authors website for a more complete example. This can now be written like this:

public class MTCCompareAndSetTest extends MultithreadedTestCase
{

    AtomicInteger ai;

    @Before
    public void initialize()
    {
        ai = new AtomicInteger(1);
    }

    @Threaded
    public void getTwoSetThree()
    {
        while (!ai.compareAndSet(2, 3)) Thread.yield();
    }

    @Threaded
    public void getOneSetTwo()
    {
        assertTrue(ai.compareAndSet(1, 2));
    }

    @Test
    public void resultShouldBeThree()
    {
        assertEquals(ai.get(), 3);
    }
}

Advantages of this approach include: no inner classes, no explicit TestFramework.runOnce() method calls, usage of standard JUnit annotations, test class is a JUnit class, annotations in stead of naming conventions, ...

Let me know if you are interested in a tgz file which contains the code of this modified MultithreadedTC library. It also contains all the tests of the original sourcecode, adapted to the more modern version.

I have tried to contact the authors of MultithreadedTC, asking them if they are interested. I am willing to share my modifications with them to get them included in the MultithreadedTC library, but I'm still awaiting their reply. Maybe they are deadlocked ;-)

High frequency task scheduling with inaccurate system clock in Java

Java has two general purpose scheduling implementations: java.util.Timer (further referenced as "Timer") and java.util.concurrent.ScheduledThreadPoolExecutor (further referenced as "STPE"). STPE is generally concieved as the successor of Timer and their should normally not be a reason to use Timer any longer. However, both Timer and STPE rely on the underlying system clock, and can thus not be more accurate then the accuracy of that clock.

I happen to have access to a machine where the accuracy of the clock is 20 milliseconds. This means that when you try to make a thread sleep for a single millisecond

public class SleepTest
{
    public static void main(String[] args) throws InterruptedException
    {
        while (true)
        {
            long start = System.nanoTime();
            Thread.sleep(1);
            System.out.println((System.nanoTime() - start) / 1000000);
        }
    }
}

the thread will actually sleep for about 20 milliseconds every time

20
19
19
19
20
20
19
19
...

This also has an impact on the scheduling behaviour with Timer and STPE. Note that the Timer javadoc explicitely mentions this, while the STPE javadoc doesn't.

For example timing a task to execute every 10ms "with fixed delays" using Timer or STPE results in the task being executed every 20ms in stead:

running task [elapsed nanos since previous = 20157000]
running task [elapsed nanos since previous = 19999000]
running task [elapsed nanos since previous = 19895000]
running task [elapsed nanos since previous = 19940000]
running task [elapsed nanos since previous = 19987000]
running task [elapsed nanos since previous = 19991000]
running task [elapsed nanos since previous = 20013000]
running task [elapsed nanos since previous = 20011000]
running task [elapsed nanos since previous = 19980000]
...

When using Timer or STPE to schedule "at fixed rate", two tasks are being executed in immidiate succession every 20ms. This is also consistent with the documentation: it tries to "catch up".

running task [elapsed nanos since previous = 19808000]
running task [elapsed nanos since previous = 187000]
running task [elapsed nanos since previous = 19813000]
running task [elapsed nanos since previous = 185000]
running task [elapsed nanos since previous = 19842000]
running task [elapsed nanos since previous = 185000]
running task [elapsed nanos since previous = 19803000]
running task [elapsed nanos since previous = 214000]
...

Note that the "fixed delay" of Timer doesn't take the execution time of the task itself into account, while the STPE "fixed delay" does, but that is not something I was trying to measure here. The task I am executing is just an empty Runnable.run() method.

Now imagine you are in a situation where you actually need to schedule something at a higher frequency then what the underlying system clock can handle (sending out a UDP stream at a fixed rate for example). Scheduling with "fixed delay" clearly is no option; both Timer and STPE will only give you a frequency equal to the accuracy of the underlying clock, nothing higher. The only option is to schedule "at fixed rate". Both Timer and STPE will "catch up" in this mode, so the average throughput corresponds to the requested frequency to execute the tasks with. The tasks will be executed in bursts though: one burst with a few tasks every time the underlying clock reports a new time value (every 20ms in my example). The problem with "fixed rate" scheduling is that you don't really have a way to control these bursts. If for example your application is blocked for a longer time for some reasons (garbage collection for example), there will be a gap in the task execution, and then a "big" burst to catch up all the tasks it missed.

This is where Timer offers an advantage over STPE. With STPE you schedule runnables, so inside the task there is not really an API to find out information about the scheduling of the task. With Timer, you schedule TimerTask instances. TimerTask has a method scheduledExecutionTime which returns the time the task "should have run". By comparing this to the actual time, you can discover "big bursts" and for example decide not to execute the task. I haven't found a practical way to do that with STPE.

I discovered this when trying to send out a UDP data stream at a fixed rate. The requirement was that a few missed packets were not so bad (a little drop in the speed), but big bursts with many packets (more then about 10 in a row) caused a problematically high peak in the data rate (because then the stream was "clipped" further down the path resulting in dropped packets) and should thus never happen.

Note that in my tests I used System.nanoTime() to measure the time between task executions. This gives me a higher accuracy then the System.currentTimeMillis() which makes me wonder why there is no scheduler with the same accuracy in Java. Something I should look into...

Runtime dispatch between different versions of the same library in Java

Java can (at least not yet?) dispatch between different versions of the same library at runtime. In fact, Java doesn't even know about the concept of library versions.

I was recently faced with a problem where it was required to dispatch between different versions of the same library at runtime. We have this architecture where network management software (lets call it the "master") has to communicate with different other software components somewhere on (remote) hardware devices in the network. This communication goes over various protocols, some Java specific (for example RMI using springs http invoker), some not (for example telnet). We also have the requirement to support different versions of these remote devices from within this single "master".

This UML diagram (click to enlarge) shows an example possible situation where the "master" needs to communicate with two different versions of two devices. There are two instances of device A in the network, one with version X and one with version Y. There are also two instances of device B, one with version Z and one with version Q. A driver implementation exists for every version of the device, but ultimately each device type (A or B) has a single interface to be used by the "master". It is the drivers job to abstract away the differences between different versions of the same device type. If the protocol is telnet or something like that, we wouldn't really need different driver implementations. A naive implementation of the "master" could simply switch around the different possible versions with "if" statements (if this version send telnet command X, if that version send telnet command Y, etc). If the protocol is Java, this becomes a problem, because you then typically depend on a library which specifies the interfaces and types used for the communication. This is technically not required of course (you could manually write RMI to a raw byte output stream), but it is what you generally want. Event for the non Java protocols, you might want to abstract away the different commands required for different versions behind a single interface in different implementation libraries.

We discussed (and experimented with) different alternative solutions to this problem. I'll go through each of them, and explain the pros and cons.

idea 1: custom class loading magic

The first idea was to package the driver implementation libraries in jar files (together with their dependencies), and class load the appropriate version of such a driver at runtime. This also requires the usage of reflection to actually instantiate such a driver. The usage of reflection prevents compile time dependencies on the driver implementation libraries (this is impossible because we would have to depend on different implementations of the same driver interface at the same time). The compile time dependencies are from the "master" to the driver interfaces, and from the driver implementation libraries to the remote device interfaces.

To make this idea work, the class loaders of the "master" and the driver implementation libraries have to be separated. On the other hand, the driver interfaces (used to communicate between the two) have to be known by both. In Java, this is only possible if they both use the driver interface classes from the same class loader. This means that the driver class loader has to have a dependency on the "master" class loader, such that driver interfaces are loaded from there. Having the "master" class loader as parent from the driver library class loader solves this problem.

As a consequence, the driver will find all its libraries in the parent class loader first, unless they are not available there. For libraries on which the driver and the "master" both depend (in our situation, spring was such a library), this is a problem, because from within these classes, the classes loaded by the class loader from the driver itself are not visible. We found a solution to this problem by writing a custom class loader which inverses the regular pattern for finding classes (first in own class loader, then in parent, in stead of first in the parent). This solves the problem, but we have to make sure that the driver interfaces are loaded from the parent class loader (by not packaging them together with the driver implementation libraries).

In the end, this approach does work, but the implementation is scattered around the different components. The "class loading magic" happens in the "master", but it only works if the driver implementation libraries are correctly packaged. This correct packaging depends on whether certain libraries are used by the master and the driver together, or only by the driver interface, etc.

idea 2: deploy the drivers as WAR files

The second idea was to package the driver implementation libraries as WAR files, and to give them a remote interface (RMI or something like that). This would imply that the container would take care of all the separation of class loaders, which is nice.

To understand the downside of this approach, you should know that the "master" doesn't simply uses these drivers once when it has to communicate with a remote device, and then forgets about them. The "master" does lots of interesting things with the drivers: it caches them (for example to reuse the same TCP connection to the device the next time), it manages concurrent access to the drivers (allowed on some, disallowed on others), etc... This means the master needs to have control over the lifetime of the drivers.

If we deploy the drivers as WAR files, we loose this functionality. We would effectively have to make the drivers stateless, or we would have to move a lot of the functionality from the "master" into the individual drivers.

idea 3: OSGi to the rescue

Our next idea was to use OSGi. If we make every driver implementation an OSGi bundle, we could decide at runtime which service of which bundle to invoke, and OSGi would do all the class loading separation for us. I did some experiments which proved that this would be a feasible solution (although I didn't look into the possibilities for lifetime management of the drivers in detail), but apparently OSGi is a bit of an all or nothing approach. There are of course many more components in our architecture than what is shown in the above UML diagram, and at the time it was not feasible to introduce OSGi in all of them. It seems that we would have to deal with the same class loading problems as in the first idea on the boundaries between non-OSGi and OSGi components.

A colleague of mine found a library (transloader) which was created to solve this problem. The transloader library is not tight to OSGi though, it is a general solution to bridge the gap between different class loaders within Java. This led us to our fourth idea.

idea 4: class loading magic revisited

If this transloader library can bridge the gap between different class loaders, why not use it to implement our first idea? We now have the same architecture as in the first idea, but without custom class loaders and without weird packaging constraints on the driver implementation libraries. All we have to do is package the drivers together with all their dependencies (no exceptions) and use the transloader library for the communication between the "master" and the drivers.

Check out the transloader tutorial to learn more, it was really easy to set up and use.

Conclusion

Built in support for modules and library versions in Java would probably still be the most desirable solution. I think until then, something like OSGi can be a nice solution too, if you can introduce it in your architecture. If that is not an option, the above described approach offers a valid alternative (at least in our use case) with a fairly simple architecture. We will be using this idea in production in the coming months, lets see if it lives up to our expectations.

analyzing maven dependencies with UML tools

Maven is very good in managing dependencies in large projects with many different artifacts, but unfortunately maven doesn't provide an easy way to visualize and analyze these dependencies. The dependency report that comes by default with a maven generated web site provides some information, but it is textual only and it only provides information about outgoing dependencies: it tells you what artifacts project X depends on, but not what other projects depend on project X.

Some maven dependency visualization tools exist. The best I could find is the dependency analyzer from jfrog. It's a standalone java application that allows you to open a pom.xml file and graphically explore its dependencies in a swing GUI. It does however not provide advanced analyzing tools, its merely a visualization tool.

Existing UML modeling tools (e.g. magicdraw) typically allow you to do much more advanced kinds of analyzes on dependency and other UML diagrams. They also allow you to represent dependencies in different ways (as a diagram, as a matrix, ...). Why not use the power of these tools to analyze maven dependencies?

maven xmi plugin

In this blog entry, I present a maven plug in that generates an XMI model from a pom.xml file and it's dependencies. XMI is an XML standard most commonly used to represent UML models. Most professional modeling tools can read XMI files. The XMI itself is not directly a visualization of the dependencies, but with a decent modeling tool, all kinds of fancy visualizations are possible.

To give you an idea, this screen shot (click to enlarge) shows a diagram created with magicdraw for the dependencies of the xmi maven plugin itself.

using the maven xmi plugin

First, you'll have to check out the code of the xmi-plugin from subversion:

svn checkout http://xmi-plugin.googlecode.com/svn/trunk/ xmi-plugin

Then you can install the xmi-plugin in your local maven repository, by invoking "mvn install" in the checkout directory. Now you are ready to use the plugin on your favorite maven project. Simply run

mvn xmi:xmi

in the root directory of your project (where the pom.xml file is located). The resulting XMI model will be generated in the target directory of your project, with the name ${artifactid}-${version}.xmi. You can now start analyzing the XMI model in an UML tool.

more information

The xmi-plugin is hosted on google code, for more information go to http://code.google.com/p/xmi-plugin/.