January 2008 Archives
Getting started with HK2 - Part II
Posted by ss141213 on January 28, 2008 at 12:29 PM | Permalink
| Comments (5)
Download The Sample
This is a sequel to my last blog where I described a Hello World sample running on HK2. As promised there, I am going to expand that sample to show module management, class loading, component injection, instantiation cascading features of HK2 working.
Structure of the sample
hello-world-hk2-sample2/
/pom.xml
/hello2-startup/pom.xml
/src/main/java/sahoo/hello/startup/MyStartup.java
/hello2-impl/pom.xml
/src/main/java/sahoo/hello/api/Foo.java
/src/main/java/sahoo/hello/api/Bar.java
/src/main/java/sahoo/hello/impl/FooImpl.java
/src/main/java/sahoo/hello/impl/BarImpl.java
The modules are organized the same way as our earlier example except that I have added a new module called hello2-impl. The new module holds some implementation details. It is introduced to show how inter-module dependency is managed by HK2.
Instructions to build and run remain unchanged. You can run mvn -f hello-world-hk2-sample-2/pom.xml install to build the sample. To run it, do one of the following:
mvn -f hello-world-hk2-sample-2/hello2-startup/pom.xml hk2:run
or
hello-world-hk2-sample-2/run.sh
Refer to the earlier blog for an explanation of the above steps.
Let's go through the contents, first our new module, hello-impl.
Step 1. Make it a HK2 module:
To do this, we need to specify packaging type as hk2-jar in its pom.xml. Since this is a custom packaging type, we need to configure the pom.xml with the plugin, hk2-maven-plugin, which provides such support. Since this plugin as well as HK2 modules are not available in standard Maven repo, you have to configure some extra repositories in the parent POM (you can do it in your ~/.m2/settings.xml as well, if you want to avoid doing it every time).
Step 2: Choose the packages you want to export:
Next, let's see how to choose the packages we want to export. By default, HK2 module management exports all packages from a module to other modules. This is just opposite to how OSGi behaves. hello2-impl module has two packages, viz: sahoo.hello.api and sahoo.hello.impl. The former one contains interfaces that we would like to export, where as the latter one contains implementation details that we would like to hide from others. Currently, there is no package level annotations defined in HK2 to mark some packages for exporting, hence we have to manually configure our hk2-maven-plugin in pom.xml to generate the following manifest entry:
HK2-Export-Package: sahoo.hello.api
It is achieved by configuring the hk2-maven-plugin in pom.xml as follows:
<build>
<plugins>
<plugin>
<groupId>com.sun.enterprise</groupId>
<artifactId>hk2-maven-plugin</artifactId>
<version>...</version>
<extensions>true</extensions>
<configuration>
<archive>
<manifestEntries>
<HK2-Export-Package>
sahoo.hello.api
</HK2-Export-Package>
</manifestEntries>
</archive>
</configuration>
</plugin>
</plugins>
</build>
The above syntax is same as what is applicable to maven-jar-plugin.
Step 3: Define contract classes Foo.java and Bar.java
In HK2, a contract is a Java interface which is annotated with @Contract. Typically a service or a component has two parts, viz: an interface class which defines the public interface of the service and an implementation class. HK2 allows you to develop a contract-less component as well. In HK2, the interface is annotated with @Contract, where as the implementation is annotated with @Service.
If you don't know why HK2 requires you to use @Contract, don't worry, it will be cleared in due course of time.
In our case, both Foo.java
Foo.java and Bar.java have such annotations in place. Keeping the true spirit of modularisation, we have defined Foo and Bar in sahoo.hello.api package, which is the package that is being exported by hello-impl module. The implementations are hidden from other modules.
Step 4:Decide the scope of components
There is something called scope attribute in @Contract. The default value for scope is Singleton.class. As the name suggests, when you ask the component manager for a component, it uses this information to decide whether to create a new instance or return an existing instance. If it decides to return an existing instance, the scope can further control where it searches for an existing instance. Singleton, as the name suggests, implies that there will be no more than one such instance of this contract type. There is another scope defined in HK2 called PerLookup.class which means every time you ask for such a component, a new instance is created by HK2 component manager as if you called the constructor. A very powerful feature of HK2 is the notion of user defined scope. I have a sample ready that shows how to use your own scope, but let me defer discussion on that to another day.
In our case, we are relying on the default scope.
Step 5:Define component classes FooImpl.java and BarImpl.java
They are both defined in a package called sahoo.hello.impl, which is not exported by our module. Now let's take a closer look at our component classes.
A component class must be annotated with @Service.
A component class must have public, no-arg constructor.
A component can depend on other components. To express such dependency, a component can use @Inject annotation. While specifying @Inject, one should specify the contract interface type in order to avoid tight coupling with any given implementation if possible. Our component Foo.java follows all these rules as shown below:
@Service
public class FooImpl implements Foo {
@Inject Bar bar;
public FooImpl() {
System.out.println("FooImpl() called");
}
public void doit() { bar.doit();}
}
A natural question is when does the injected field bar get initialized? It is initialized by HK2 framework after the constructor call, which means you should not be accessing this field in your default constructor. If you need to specify some business logic as part of construction, then make your component implement PostConstruct interface.
Step 6: Write a startup module
So far, we have described about hello-impl module which defines two contracts called Foo and Bar, but how does HK2 know about it? Who uses them? That's where our startup module comes into picture. Remember, in my previous blog, I told this is the primordial module? This is the module that consumes those contracts. Now let's look at the only class that is defined in this module:
@Service
public class MyStartup implements ModuleStartup
{
@Inject Habitat habitat;
@Inject Foo foo;
public void setStartupContext(StartupContext context) {
}
public void run() {
System.out.println("Hello World - My first HK2 Sample");
System.out.println("Injected foo = " + foo);
Foo lookedUpFoo = habitat.getComponent(Foo.class, null);
System.out.println("habitat.getByComponent(Foo.class, null) = " +
lookedUpFoo);
// Since Foo is Singleton scoped, the following assertion holds good
assert(foo == lookedUpFoo);
foo.doit();
}
}
It is itself a component, for it is annotated with @Service. What contract does it have? It's ModuleStartup. Since it is a component, it can use dependency injection. See how it is injected with a Foo object and a Habitat object. What is this Habitat object? Well, Habitat is the component manager in HK2.
Since, hello-startup module uses interfaces from hello-impl module, we have to set appropriate dependency in hello-startup's pom.xml. When we do this, out hk2-maven-plugin is smart enough to generate the following manifest headers in hello-startup's META-INF/MANIFEST.MF:
HK2-Import-Bundles: sahoo:hello2-impl, com.sun.enterprise:hk2
That's it. You are all set to build and run the sample.
Observations
You can see HK2 automatically starting hello2-impl module when it tries to start the primordial module. You can also see instantiation cascading: MyStartup -> Foo -> Bar because of Bar injected in Foo injected in MyStartup. Similarly, you can see Singleton scope in action. Next time, when the code asks for Foo type component to the component manager, it is returned the previous instance. To test package hiding, change the class to load FooImpl.class directly from MyStartup, and you will get a ClassNotFoundException.
Q1. Why does HK2 use @Contract and @Service?
It's an ease of development thing. Even Java SE platform provides a service framework, but that does not require any annotations, but why HK2 requires? Java SE requires programmers to generate META-INF/services file as described here, where as HK2 generates the appropriate meta-information by parsing the annotations at compile time. This is done by HK2 supplied hk2:compile goal.
Q2. What is Habitat in HK2?
This is the component manager in HK2. Think like JNDI Naming Manager in Java EE. Well, it's much more than that actually. More discussion on Habitat some other day. Got to sign off for the day.
Conclusion
I hope you found this useful. As usual, your comments are useful. Stay tuned for more on HK2 and GlassFish.
Getting started with HK2 - Part I
Posted by ss141213 on January 28, 2008 at 06:30 AM | Permalink
| Comments (5)
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
| 
java.net RSS Feeds
