Download The Sample

Now that I am working in HK2, I shall share my experiences of HK2 with others via my blogs. I firmly believe that examples are a great way to learn a new technology. So, I will start with a "Hello World" type application. The fact that you are reading this blog makes me think that you already know what HK2 is. Although HK2 is being used in development of ultra light-weight, modular, next generation GlassFish application server, any Java SE programmer can use it to write modular applications. It has a very nice component model with IoC support. In fact, this sample has nothing to do with server side programing. The complete sample along with Maven build scripts, etc. can be downloaded from here.

Structure of the sample

hello-world-hk2-sample/
                      /pom.xml
                      /hello-startup/pom.xml
                                    /src/main/java/sahoo/hello/startup/MyStartup.java

As you notice, even though there is only one module, named hello-startup, I have decided to keep a top level pom.xml with packaging type pom and kept hello-startup module in a sub-project. I have done so because I know, in reality, one has multiple modules, so why not get used to that kind of structure from beginning?

Prerequisite:
1. Maven 2
2. Java SE 6 or above.
You can use Java SE 5, but you need to get hold of a StAX implementation and put it in classpath, for HK2 needs StAX at runtime.

How to build
mvn -f hello-world-hk2-sample/pom.xml install

(-f option to mvn instructs it to use a specified pom.xml. It is equivalent to cd to hello-world-hk2-sample and invoking 'mvn install')

How to run
There are a couple of options:
1. Using maven:
HK2 provides a plugin goal (hk2:run) which I find very handy to use. This goal must be invoked using the statup module's pom. So, you can invoke it like this:

mvn -f hello-world-hk2-sample/hello-startup/pom.xml hk2:run

2. Running a start up script:

./hello-world-hk2-sample/run.sh

run.sh is a very simple script that copies all the necessary HK2 jar files from your Maven local repository to a directory called ./lib. It also copies your application jar files to ./lib. Then it launches HK2 using the following command:

java -jar ./lib/hk2-0.2-SNAPSHOT.jar

Note: There are a couple of variables like JAVA_HOME and MAVEN_REPO_LOCAL in run.sh that you need to configure for your environment.

Sample Description:
Let's now take a look at our program.
1. First the pom.xml:
A. The packaging type is hk2-jar. Who provides this packaging support? HK2 provides a plugin called hk2-maven-plugin which provides this packaging support. It helps generating necessary manifest headers in our module jar. Since maven does not know about this plugin, we configure it in our build section.
B. We also specify dependency on HK2 module in the dependency section so that we can use HK2 APIs in our program. Please note that I specify the HK2 version as a property which is set in the parent pom.xml. This allows me to control it in one place only. Rest of the pom.xml needs no explanation.

2. Let's now take a look at our only class, MyStartup.java.
It is annotated as @Service and implements ModuleStartup. Both are needed because hello-startup is the primordial module - the first user supplied module to be started by HK2. When HK2 starts, it searches all the modules for a class that meets the above criteria. If it finds only one such class, then it considers the module containing the class as the main bundle. It then instantiates the class and calls the setStartupContext(). It then calls the run() method of the ModuleStartup interface. Our System.out.println code is part of the run().

Conclusion
I know this sample does not show how HK2 manages module dependency, class loading, component injection, etc. Stay tuned, more blogs about HK2 coming soon... As usual, comments are most welcome.

Useful Links:
How to develop module in HK2
More blogs about GlassFish