In Part 1 I gave a brief overview of the microkernel and how the application is constructed on disk. In this article I will go through how to actually write an application to run within the retepMicroKernel, from a simple application, one who’s beans are configurable after compile time, to integrating existing Spring applications and ending with how to build the application using Apache Maven.
Firstly, an application is simply a collection of beans deployed by Spring. However unlike a normal Spring application the microKernel provides additional services which make writing an application easier taking away the necessity to write those services into your application and enabling you to concentrate on writing your application.
Writing a deployed bean
Declaring the bean
A bean can be deployed within the kernel in one of two ways – by writing a standard Spring deployment descriptor which we will show later in this article, and by annotating the class with a @Bean annotation.
For example say you have a bean called myBean and you want it to be deployed in your application then simply annotate the class with the @Bean annotation:
import uk.org.retep.kernel.annotations.Bean;
@Bean( name=“myBean” )
public class MyBean
{
// bean implementation
}
Once annotated your bean will be deployed and constructed when it’s first referenced by another bean. Because beans are created lazily, your application must have at least one bean that is not lazily instantiated otherwise your application would do nothing. So for your core bean (or any bean you want to exist at startup) you need to tell the kernel that the bean is to be instantiated at startup. This is simply setting the lazyInit parameter to the @Bean annotation to false, ie.
@Bean( name=“myBean”, lazyInit=false )
In this way the bean is instantiated at startup.
Bean references and initial values
You can define initial values to your bean in two ways, in the constructor and by a bean accessor method. For both methods the kernel supplies two annotations for predefining values in your bean. @Value simply defines a constant value whilst @Reference defines a reference to another deployed bean.
For bean accessor methods, you simply add the annotation to the setter method:
import uk.org.retep.kernel.annotations.Bean;
import uk.org.retep.kernel.annotations.Reference;
import uk.org.retep.kernel.annotations.Value;
@Bean( name=“myBean” )
public class MyBean
{
private int myInteger;
private MyOtherBean myOtherBean;
public int getMyInteger()
{
return myInteger;
}
@Value( “10” )
public void setMyIntegr( finaly int myInteger )
{
this.myInteger = myInteger;
}
public MyOtherBean getMyOtherBean()
{
return myOtherBean;
}
@Reference( “myOtherBean” )
public void setMyOtherBean( final MyOtherBean myOtherBean )
{
this.myOtherBean = myOtherBean;
}
}
For a constructor you simply annotate the parameters of the constructor:
import uk.org.retep.kernel.annotations.Bean;
import uk.org.retep.kernel.annotations.Reference;
import uk.org.retep.kernel.annotations.Value;
@Bean( name=“myBean” )
public class MyBean
{
private int myInteger;
private MyOtherBean myOtherBean;
public MyBean(
@Value( “10” ) final int myInteger,
@Reference( “myOtherBean” ) final MyOtherBean myOtherBean )
{
this.myInteger = myInteger;
this.myOtherBean = myOtherBean;
}
}
Bean lifecycle
As the kernel uses Spring internally it supports the @PostCreate and @PreDestroy annotations for invoking methods when the bean is instantiated or destroyed. However as the Spring deployment descriptor supports defining the methods in the <bean> element, the kernel supplies two additional annotations @Init and @Destroy which like @Bean are detected at compile time so those methods will be called at instantiation or when it’s destroyed.
import uk.org.retep.kernel.annotations.Bean;
import uk.org.retep.kernel.annotations.Init;
@Bean( name=“myBean” )
public class MyBean
{
@Init
public void start()
throws Exception
{
// initialisation code
}
}
Although not really useful, this does mean you can annotate two methods with @PostCreate and @Init and both would be called. The same goes for @PreDestroy and @Destroy. The order these methods are called is indeterminate, hence why this is not really useful.
There is a third lifecycle annotation available – @PostInit. This annotation is unique to the kernel and indicates that the method should be called once all beans have been deployed and the application has been started. This annotation is useful when you want something to happen but you don’t know what beans are going to be available.
For example, say you are writing a desktop application with components implemented as plugins implemented as deployed beans. You have a bean that manages the main JFrame of your application. Your bean would have an @Init method that initialises the JFrame but does not make it visible. You then write each plugin component as a deployed bean with references to your frame bean, and they add themselves to the frame. Finally you then create another method in the frame bean annotated with @PostInit which then pack’s the JFrame and make it visible.
Because of how the kernel works, your plugins can be in additional jar’s within the application’s lib directory, so to add a new plugin you can simply place it’s jar into the applicartion’s lib directory and when the application runs your new plugin is available.
Bean Factories
The kernel supplies two annotations for implementing bean factories – @BeanFactory and @FactoryMethod.
For a deployed bean who’s instance is returned by a static method then you annotate the class with @Bean and the static method with @FactoryMethod. You can imagine this is making a traditional singleton bean deployed:
import uk.org.retep.kernel.annotations.Bean;
import uk.org.retep.kernel.annotations.FactoryMethod;
@Bean( name=“myBean” )
public class MyBean
{
private static final MyBean INSTANCE = new MyBean();
@FactoryMethod
public static MyBean getInstance()
{
return INSTANCE;
}
private MyBean()
{
}
}
The other type of factory is where the bean is returned by a getter method of another deployed bean. For example here MyBean is created by MyAnotherBean.getMyBean()
import uk.org.retep.kernel.annotations.Bean;
import uk.org.retep.kernel.annotations.Reference;
import uk.org.retep.kernel.annotations.Value;
@Bean( name=“myBean” )
@BeanFactory( factory=“myAnotherBean”, method=“getMyBean” )
public class MyBean
{
}
@Bean( name=“myAnotherBean” )
public class MyAnotherBean
{
private MyBean myBean;
public MyBean getMyBean()
{
return myBean;
}
}
Using Spring deployment descriptors
For existing applications that have their beans defined in a standard Spring deployment descriptor, the kernel can deploy those beans as long as the descriptor is placed in the etc directory. If the application is called myapp, then this descriptor should be called etc/myapp.xml, so if that file exists, it’s beans are included with any beans that have been annotated. Spring will then determine the deployment order and load the application.
Internally the annotations actually generate a standard Spring deployment descriptor, however this is placed in the jar file as META-INF/services/uk.org.retep.kernel.Kernel.xml When the kernel starts Spring it looks for all instances of this file along side the myapp.xml file to get the complete set of beans to deploy. This is how the plugin example above would work – adding a new jar file into the classpath makes it’s beans deployable automatically.
Now an alternate reason to provide a standard Spring deployment descriptor is for beans that require configuring after compilation, or for providing beans in classes in third-party jar files not compiled with the annotations.
For example, you have a bean that will open a socket on a port and listen for new connections. Although you could define that bean with the annotations, doing so would mean it would always use the same port number. To make it configurable you would write the bean without any annotations and define the bean in the traditional way in the myapp.xml file.
Logging
The kernel uses Apache’s log4j framework for logging. To support log4j, you can configure the file myapp.log4j.xml and the kernel will use that configuration for log4j. If the file is not available, the kernel will use a default configuration which logs to the console.
Here’s an example of logging to a file – in this case system.log in the current directory when the application is started:
<?xml version=”1.0” encoding=”UTF-8” ?>
<!DOCTYPE log4j:configuration SYSTEM “log4j.dtd”>
<log4j:configuration xmlns:log4j=”http://jakarta.apache.org/log4j/“>
<appender name=”FILE” class=”org.apache.log4j.DailyRollingFileAppender”>
<param name=”File” value=”system.log”/>
<param name=”Append” value=”true”/>
<param name=”Threshold” value=”INFO”/>
<param name=”DatePattern” value=”’.’yyyy-MM-dd”/>
<layout class=”org.apache.log4j.PatternLayout”>
<param name=”ConversionPattern” value=”%d %-5p [%c] %m%n”/>
</layout>
</appender>
<root>
<appender-ref ref=”FILE”/>
</root>
</log4j:configuration>
Building the application with maven
To compile the application with the annotations simply ensure that the kernel Jar file is present in the classpath. Doing so ensures that the annotation processors provided by the kernel run within javac and it will generate all the metadata required by the kernel at runtime.
However unless you are using Apache Maven you have to build the application yourself, however the kernel provides a Maven mojo that will build your application for you, ensuring that the relevent artifacts are in the correct place.
Say you have your application called myapp and you have the following structure for your sources:
myapp/pom.xml
myapp/src/main/java
myapp/src/main/etc
As for norml maven projects the java directory contains your source code, the etc directory contains the configuration destined to go into the etc directory of your application.
As for pom.xml, here’s an example that would build a simple application:
<?xml version=”1.0” encoding=”UTF-8”?>
<project xmlns=”http://maven.apache.org/POM/4.0.0” xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xsi:schemaLocation=”http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd”>
<modelVersion>4.0.0</modelVersion>
<groupId>org.mydomain</groupId>
<artifactId>myapp</artifactId>
<name>myApp</name>
<version>1.0-SNAPSHOT</version>
<!– The maven repositories –>
<repositories>
<repository>
<id>maven.retep.org</id>
<name>retep.org Maven 2 Repository</name>
<url>http://maven.retep.org/content/groups/public</url>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>maven.retep.org</id>
<name>retep.org Maven 2 Repository</name>
<url>http://maven.retep.org/content/groups/public</url>
</pluginRepository>
</pluginRepositories>
<!– the minimum dependencies –>
<dependencies>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>3.8.1</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>uk.org.retep</groupId>
<artifactId>retepTools</artifactId>
<version>[8.12,)</version>
</dependency>
<dependency>
<groupId>uk.org.retep.microkernel</groupId>
<artifactId>core</artifactId>
<version>[8.12,)</version>
</dependency>
</dependencies>
<build>
<plugins>
<!– All retep projects need JDK 1.6 as a minimum –>
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<version>2.0.2</version>
<configuration>
<source>1.6</source>
<target>1.6</target>
</configuration>
</plugin>
<!– plugin to generate the final application –>
<plugin>
<groupId>uk.org.retep.microkernel</groupId>
<artifactId>maven</artifactId>
<executions>
<execution>
<id>assemble-application</id>
<phase>package</phase>
<goals>
<goal>assemble-application</goal>
</goals>
<configuration>
<applicationName>myapp</applicationName>
<!– generate a zip containing the application –>
<zip>true</zip>
<!– generate a tar containing the application –>
<tar>false</tar>
<!– generate a tar compressed with GZip containing the application –>
<tarGz>true</tarGz>
<!– generate a tar compressed with BZip2 containing the application –>
<tarBZip2>false</tarBZip2>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
The pom above defines a reference to my public repository, a dependency on the kernel nd my tools library (which all of my projects use), sets the jdk to 1.6 and then uses the kernel’s maven mojo. The mojo generates the application ready to run under the target directory.
Under the configuration element the applicationName property sets the final application name, in this case myapp. With this set it would generate the following structure under the target directory:
myapp-1.0-SNAPSHOT/bin
myapp-1.0-SNAPSHOT/etc
myapp-1.0-SNAPSHOT/lib
myapp-1.0-SNAPSHOT/lib/myapp
The other configuration properties define how the application is bundled. Here we have tarGz and zip set to true so it would generate .tgz and .zip archives of the built application. The tar property is false but if it was true then an uncompressed .tar archive would be generated. Similarly tarBZip2 indicates if a .tar.bz2 archive is generated.
So with the above settings set to true then under target will be myapp-1.0-SNAPSHOT.zip and myapp-1.0-SNAPSHOT.tgz archives.
Note: Currently the generated application is not deployed to the local or remote repositories as an artifact. This is planned for a future release as soon as I can work out how to get maven to include additional artifacts to the deployment.
JNDI
The kernel provides a simple in-memory JNDI server which can be used by an application. By default it exposes all deployed beans within JNDI by prefixing the bean name with “kernel/” so if you have a bean called myBean then it’s accessible from JNDI using the name kernel/myBean
Binding by annotations
The kernel provides the @LocalBinding annotation which when applied against a bean’s class defines the name for binding the bean into JNDI.
Binding legacy beans into JNDI
In addition to the automatic JNDI binding provided by the kernel, you can bind a bean into any name. Usually this is used by binding a DataSource into JNDI with the DataSource deployed from within Spring. For example we have a DataSource that connects to a PostgreSQL database called mydb and the DataSource will be called ds/mydb.
To do this, within myapp.xml we define two beans. One is the actual DataSource with all of its required configuration – we will call it realds/mydb for this example. The other is a bean provided by the kernel called JNDIBinder. We will call tht jndi/mydb and it will bind the DataSource into JNDI. Once done then existing code expecting to use JNDI can access the DataSource using ds/mydb
<!– The DataSource provided by PostgreSQL –>
<bean name=”realds/tux” class=”org.postgresql.ds.PGPoolingDataSource”>
<property name=”serverName” value=“postgresql.mydomain.com”/>
<property name=”portNumber” value=”5432″/>
<property name=”databaseName” value=”mydb”/>
<property name=”user” value=”username”/>
<property name=”password” value=”password”/>
</bean>
<!– Deployment bean that will bind the DataSource into JNDI on startup –>
<bean name=”jndi/mydb” class=”uk.org.retep.kernel.naming.JNDIBinder” lazy-init=”false”>
<property name=”jndiName” value=”ds/mydb”/>
<property name=”value” ref=”realds/mydb”/>
</bean>
JMX
If a deployed bean implements an interface who’s name ends with MBean or MXBean or if the interface is annotated by javax.management.MXBean then the kernel will deploy that bean into the local JMX server. The ObjectName defaults to retep.kernel.beans:id= and the bean name unless the bean is annotated with @ObjectName in which case it will use that ObjectName when registering into JMX.
Thats all for Part 2. The next article will show how to use the optional manager module which provides a web interface to your application utilising the built in http server provided by Java 6.
Peter Mount's Blog 