Skip to main content

Getting started with HK2 - Part I

Posted by ss141213 on January 28, 2008 at 9:30 AM EST

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 coming soon... As usual, comments are most welcome.

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

Related Topics >>
Blog Links >>

Comments

by ss141213 - 2008-09-17 08:31

I have updated the sample zip file. It now uses latest version of HK2.

by ss141213 - 2008-01-31 09:01

I am glad it helped you. There is a second tutorial available. Just check my latest blog.

Yes, it is normal to get that message. You are getting that message because the framework discovered the primordial module for you instead of you specifying it to the framework. I think I should change that to a INFO message rather than a warning.

Thanks, Sahoo

by antsh - 2008-01-31 07:30

Is it normal that I am getting an message when I run the hk.jar: WARNING: No Main-Bundle module found in manifest of C:\Java_files\workspace\test\lib\hk2-core-0.2-SNAPSHOT.jar

by antsh - 2008-01-31 07:25

Thx for the tutorial, real help!!! You saved me a lot of time and nerves :)

by anthavio - 2008-01-28 14:39

Because sun. They like to disregard other's work and create own less then mediocre solutions. But I must admit hk2 ioc is quite springish

by secretplot - 2008-01-28 10:01

why not osgi?

com.sun.enterprise:h k2-maven-plugin:0.3.23:package': Unable to

by yangjungis - 2010-04-19 23:38

[INFO] Scanning for projects... [INFO] Reactor build order: [INFO] Hello World HK2 Sample [INFO] Startup module for Hello World HK2 Sample [WARNING] POM for 'com.sun.istack:istack-commons-test:pom:1.0:runtime' is invali d. Its dependencies (if any) will NOT be available to the current build. [INFO] ------------------------------------------------------------------------ [INFO] Building Hello World HK2 Sample [INFO] task-segment: [install] [INFO] ------------------------------------------------------------------------ [INFO] [site:attach-descriptor {execution: default-attach-descriptor}] [INFO] [install:install {execution: default-install}] [INFO] Installing E:\mywork\hello-world-hk2-sample\pom.xml to C:\Users\yangjungi s@126.com\.m2\repository\sahoo\hello\1.0-SNAPSHOT\hello-1.0-SNAPSHOT.pom [INFO] ------------------------------------------------------------------------ [INFO] Building Startup module for Hello World HK2 Sample [INFO] task-segment: [install] [INFO] ------------------------------------------------------------------------ [INFO] [resources:resources {execution: default-resources}] [WARNING] Using platform encoding (GBK actually) to copy filtered resources, i.e . build is platform dependent! [INFO] skip non existing resourceDirectory E:\mywork\hello-world-hk2-sample\hell o-startup\src\main\resources [INFO] [hk2:hk2-compile {execution: default-hk2-compile}] [INFO] Nothing to compile - all classes are up to date [INFO] [resources:testResources {execution: default-testResources}] [WARNING] Using platform encoding (GBK actually) to copy filtered resources, i.e . build is platform dependent! [INFO] skip non existing resourceDirectory E:\mywork\hello-world-hk2-sample\hell o-startup\src\test\resources [INFO] [hk2:hk2-test-compile {execution: default-hk2-test-compile}] [INFO] No sources to compile [INFO] [surefire:test {execution: default-test}] [INFO] No tests to run. ----------------------------------------------------- this realm = app0.child-container[com.sun.enterprise:hk2-maven-plugin:0.3.23] urls[0] = file:/C:/Users/yangjungis@126.com/.m2/repository/com/sun/enterprise/hk 2-maven-plugin/0.3.23/hk2-maven-plugin-0.3.23.jar urls[1] = file:/C:/Users/yangjungis@126.com/.m2/repository/com/sun/enterprise/hk 2-maven/0.3.23/hk2-maven-0.3.23.jar urls[2] = file:/C:/Users/yangjungis@126.com/.m2/repository/com/sun/enterprise/hk 2-core/0.3.23/hk2-core-0.3.23.jar urls[3] = file:/C:/Users/yangjungis@126.com/.m2/repository/com/sun/enterprise/co nfig/0.3.23/config-0.3.23.jar urls[4] = file:/C:/Users/yangjungis@126.com/.m2/repository/com/sun/enterprise/au to-depends/0.3.23/auto-depends-0.3.23.jar urls[5] = file:/C:/Users/yangjungis@126.com/.m2/repository/com/sun/enterprise/ti ger-types-osgi/0.3.23/tiger-types-osgi-0.3.23.jar urls[6] = file:/C:/Users/yangjungis@126.com/.m2/repository/org/codehaus/plexus/p lexus-utils/1.0.4/plexus-utils-1.0.4.jar urls[7] = file:/C:/Users/yangjungis@126.com/.m2/repository/junit/junit/4.3.1/jun it-4.3.1.jar urls[8] = file:/C:/Users/yangjungis@126.com/.m2/repository/org/apache/maven/mave n-archiver/2.0.4/maven-archiver-2.0.4.jar urls[9] = file:/C:/Users/yangjungis@126.com/.m2/repository/org/codehaus/plexus/p lexus-archiver/1.0-alpha-4/plexus-archiver-1.0-alpha-4.jar urls[10] = file:/C:/Users/yangjungis@126.com/.m2/repository/org/osgi/osgi_R4_cor e/1.0/osgi_R4_core-1.0.jar urls[11] = file:/C:/Users/yangjungis@126.com/.m2/repository/com/sun/enterprise/h k2-dependency-verifier/0.3.23/hk2-dependency-verifier-0.3.23.jar urls[12] = file:/C:/Users/yangjungis@126.com/.m2/repository/org/apache/bcel/bcel /5.2/bcel-5.2.jar urls[13] = file:/C:/Users/yangjungis@126.com/.m2/repository/com/sun/enterprise/t est-harness/0.3.23/test-harness-0.3.23.jar urls[14] = file:/C:/Users/yangjungis@126.com/.m2/repository/ant/ant/1.6.5/ant-1. 6.5.jar urls[15] = file:/C:/Users/yangjungis@126.com/.m2/repository/com/sun/istack/istac k-commons-test/1.0/istack-commons-test-1.0.jar urls[16] = file:/C:/Users/yangjungis@126.com/.m2/repository/com/sun/enterprise/c onfig-generator/0.3.23/config-generator-0.3.23.jar urls[17] = file:/C:/Users/yangjungis@126.com/.m2/repository/com/sun/enterprise/a uto-depends-plugin/0.3.23/auto-depends-plugin-0.3.23.jar urls[18] = file:/C:/Users/yangjungis@126.com/.m2/repository/com/sun/xml/bind/jax b-xjc/2.1.3/jaxb-xjc-2.1.3.jar urls[19] = file:/C:/Users/yangjungis@126.com/.m2/repository/com/sun/xml/bind/jax b-impl/2.1.3/jaxb-impl-2.1.3.jar urls[20] = file:/C:/Users/yangjungis@126.com/.m2/repository/javax/xml/bind/jaxb- api/2.1/jaxb-api-2.1.jar urls[21] = file:/C:/Users/yangjungis@126.com/.m2/repository/javax/xml/stream/sta x-api/1.0/stax-api-1.0.jar urls[22] = file:/C:/Users/yangjungis@126.com/.m2/repository/javax/activation/act ivation/1.1/activation-1.1.jar urls[23] = file:/D:/Java/jdk1.6.0_18/jre/../lib/tools.jar urls[24] = file:/C:/Users/yangjungis@126.com/.m2/repository/com/sun/xml/stream/s jsxp/1.0/sjsxp-1.0.jar urls[25] = file:/C:/Users/yangjungis@126.com/.m2/repository/org/apache/maven/plu gins/maven-compiler-plugin/2.0.2/maven-compiler-plugin-2.0.2.jar urls[26] = file:/C:/Users/yangjungis@126.com/.m2/repository/org/codehaus/plexus/ plexus-compiler-api/1.5.3/plexus-compiler-api-1.5.3.jar urls[27] = file:/C:/Users/yangjungis@126.com/.m2/repository/org/codehaus/plexus/ plexus-compiler-manager/1.5.3/plexus-compiler-manager-1.5.3.jar urls[28] = file:/C:/Users/yangjungis@126.com/.m2/repository/org/codehaus/plexus/ plexus-compiler-javac/1.5.3/plexus-compiler-javac-1.5.3.jar urls[29] = file:/C:/Users/yangjungis@126.com/.m2/repository/qdox/qdox/1.6.1/qdox -1.6.1.jar urls[30] = file:/C:/Users/yangjungis@126.com/.m2/repository/org/apache/ant/ant/1 .7.0/ant-1.7.0.jar urls[31] = file:/C:/Users/yangjungis@126.com/.m2/repository/org/apache/ant/ant-l auncher/1.7.0/ant-launcher-1.7.0.jar urls[32] = file:/C:/Users/yangjungis@126.com/.m2/repository/org/apache/maven/sha red/maven-osgi/0.2.0/maven-osgi-0.2.0.jar urls[33] = file:/C:/Users/yangjungis@126.com/.m2/repository/biz/aQute/bndlib/0.0 .203/bndlib-0.0.203.jar Number of imports: 10 import: org.codehaus.classworlds.Entry@a6c57a42 import: org.codehaus.classworlds.Entry@12f43f3b import: org.codehaus.classworlds.Entry@20025374 import: org.codehaus.classworlds.Entry@f8e44ca4 import: org.codehaus.classworlds.Entry@92758522 import: org.codehaus.classworlds.Entry@ebf2705b import: org.codehaus.classworlds.Entry@bb25e54 import: org.codehaus.classworlds.Entry@bece5185 import: org.codehaus.classworlds.Entry@3fee8e37 import: org.codehaus.classworlds.Entry@3fee19d8 this realm = plexus.core urls[0] = file:/D:/apache-maven-2.2.1/bin/../lib/maven-2.2.1-uber.jar Number of imports: 10 import: org.codehaus.classworlds.Entry@a6c57a42 import: org.codehaus.classworlds.Entry@12f43f3b import: org.codehaus.classworlds.Entry@20025374 import: org.codehaus.classworlds.Entry@f8e44ca4 import: org.codehaus.classworlds.Entry@92758522 import: org.codehaus.classworlds.Entry@ebf2705b import: org.codehaus.classworlds.Entry@bb25e54 import: org.codehaus.classworlds.Entry@bece5185 import: org.codehaus.classworlds.Entry@3fee8e37 import: org.codehaus.classworlds.Entry@3fee19d8 ----------------------------------------------------- [INFO] ------------------------------------------------------------------------ [ERROR] BUILD ERROR [INFO] ------------------------------------------------------------------------ [INFO] Internal error in the plugin manager executing goal 'com.sun.enterprise:h k2-maven-plugin:0.3.23:package': Unable to load the mojo 'com.sun.enterprise:hk2 -maven-plugin:0.3.23:package' in the plugin 'com.sun.enterprise:hk2-maven-plugin '. A required class is missing: org/apache/maven/archiver/MavenArchiveConfigurat ion org.apache.maven.archiver.MavenArchiveConfiguration [INFO] ------------------------------------------------------------------------ [INFO] For more information, run Maven with the -e switch [INFO] ------------------------------------------------------------------------ [INFO] Total time: 3 seconds [INFO] Finished at: Tue Apr 20 13:36:34 CST 2010 [INFO] Final Memory: 13M/33M [INFO] ------------------------------------------------------------------------