Category Archives: retepMicroKernel

It’s been a busy couple of months

It’s been a couple of busy months with most of my time being taken up with my day job.

Most of my time has been spent with either tracking down issues with our live environment, or trying to finish off a couple major projects (both related to XMPP) interspersed with the usual major partner getting in the way.

Any how, over the last couple of weeks I’ve been finishing off some new features which cover most of my public projects and this post will hopefully cover some of the details.

Hopefully these will be released this weekend, time allowing.

The new features are:

RetepTools
* the builder api within retepTools has been updated
* the jaxb plugin library has been cleaned up with common generation code split out to enable reuse
* retepTools as a project is almost ready for deployment to maven central
* a new pligun has been added to jaxb which generates builders for jaxb objects

RetepMicroKernel
* spring has been updated to the latest version 3 (it was on 2.5)
* the core module has been broken up into individual & independent modules
* a new groovy module which enables groovy scripts to be run from the command line
* a major bug fix where exceptions thrown during application startup causes the process to hang has been fixed
* web applications can now be deployed as a war with either jetty or tomcat (they are both supported with their own modules)
* you can now embed Apache Derby within the environment

I’m leaving out the retepXMPP changes out of this list as they need their own article. Suffice it to say, I’ve got a lot waiting for release, just need the time.

Finally, this post is also a test of submitting a blog post from a BlackBerry using the WordPress app so the formatting may be off a tad – won’t know how it goes until I see it in a real browser.

Using the retepMicroKernel – Part 2

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”&gt;

    <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&gt;

        </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&gt;

        </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.

Using the retepMicroKernel – Part 1

In the first of four posts introducing the retepMicroKernel project, I will describe what the project is, it’s goals and how it can be used to implement lightweight server side application running either standalone or within a J2EE environment. Part 2 will show how to write an application for the kernel and Part 3 will show how to add a web console to your application while Part 4 will show how to integrate an application into a J2EE environment.

Overview

The retepMicroKernel comprises four distinct components:

  • Binary launcher
  • MicroKernel
  • WebConsole
  • Apache Maven plugin

overview.WV81M45VscxD.e25JeA5bsoLE.jpg

Binary launcher

The binary launcher is a platform specific binary who’s job is to configure the application, start the Java virtual machine and finally start the application by bootstrapping the microKernel.

Currently the following platforms are supported:

  • Linux (both 32 and 64 bit ). This is compiled under Ubuntu but is tested on RHEL4 so should work on most x86 and amd64 distributions
  • Mac OSx (Leopard 10.5.x and Java 6 required)
  • Windows XP (not tested on Vista, currently console only)

Other platforms will be supported as an when I get a working virtual image of those platforms.

MicroKernel

This is the core kernel comprising the microKernel, annotations and core services like the in-memory JNDI server.

WebConsole

The WebConsole is an optional component that, when installed, provides a simple but comprehensive console for your application by utilising the built in web server provided by Java 6. With it you can monitor various statistics about your application using any web browser, and add additional actions to your application for management purposes.

Apache Maven plugin

The Apache Maven plugin enables an application to be built, ensuring that all artifacts are present and installed in the correct locations required by the kernel.

Directory Layout

Each microKernel application is organised so that the final application is self contained. Here’s the directory structure – here the application is called myapp:

  • bin – The binary launchers
  • etc – The application’s configuration
  • lib – The microKernel’s jar files
  • lib/myapp – The jar files for the myapp application

The contents of these directories will be covered in Part 2, but the layout is such that you can have multiple applications deployed in the same directory structure – simply have a copy of the binaries with the correct name, configuration under etc and a directory under lib with the application specific jars. In addition, the maven plugin handles all of this for you as it will generate the entire directory structure, ensure the correct artifacts are installed and generate a zip, tar.gz or tar.bz2 artifact containing the final application.

That’s all for the introduction, next in Part 2 I’ll go into depth on how to write a simple application with beans defined either in the standard spring xml fashon, or by utilising the supplied annotations.

Follow

Get every new post delivered to your Inbox.

Join 1,767 other followers