Recently, SpringSource released the first version of their DM server. The SpringSource DM Server provides the ability to build enterprise web applications. In the basis, S2DM is a fine mixture of Equinox and Tomcat.

Building OSGi-based web applications was already possible, but it is tedious and error prone work. The typical hello-world example [...]]]>

Recently, SpringSource released the first version of their DM server. The SpringSource DM Server provides the ability to build enterprise web applications. In the basis, S2DM is a fine mixture of Equinox and Tomcat.

Building OSGi-based web applications was already possible, but it is tedious and error prone work. The typical hello-world example was easy to get going, but as soon as Hibernate or any other framework that helps in larger applications show up, so do your good old class loading problems. For classes to be visible in OSGi, a bundle must declare an Import-Package entry in the Manifest file. Chances are small that Hibernate (even if it were packaged as an OSGi bundle) has these entries for your persistent classes. This is where S2DM server comes in. It allows the more-than-hello-world web applications to be deployed in an environment where you can benefit from the best of OSGi, without the class loading misery. To do this, they have included some extra Manifest entries that are translated to OSGi-compliant directives at load time.

Comparable to the WAR, or better, EAR file, S2DM server supports the PAR file. A PAR file is much like a Jar, with some special headers in the Manifest file, containing all your bundle jars. Some of these jars may contain web bundles, while other typically contain domain classes or the service layer implementation. Contrary to EAR files, a PAR should only contain your own code. It is best practice to deploy frameworks and third party libraries separately. I’ll explain why later on.

With enterprise applications come enterprise development processes, using continuous integration, build servers and maven. In this post, I’ll lay out what you need to get maven to build S2DM server compliant bundles, and better, PAR files.

OSGi manifest headers

But before we move straight to maven, let’s have a look at what a Spring DM bundle looks like. Basically, a Spring DM bundle is an ordinary OSGi bundle. It has the same requirements for the MANIFEST.MF file, of which the major headers are listed below:

• Bundle-SymbolicName is the only mandatory manifest header. It represents the technical name of your bundle. This value, in combination with the Bundle-Version, if present, must be unique.
• Bundle-Version is not mandatory, but defaults to 0.0.0, which isn’t a meaningful version. An OSGi compatible version number has the format: <major>.<minor>.<micro>-<classifier>.
• The Import-Package header allows you to specify a list of packages that your bundle requires to operate. It is also possible to specify version ranges and that some packages are optional.
• DynamicImport-Package can be used to dynamically import packages at the moment they are required. Use a wildcard (*) to set package patterns to limit the dynamic import to.
• The last entry I’ll mention here is Export-Package. It specifies the packages of the current bundle that form its API. Classes in these packages are available for other bundles to use.

For more details about OSGi manifest headers, see the OSGi-core specification, section 3.2.

The OSGi specification requires you to import a package (which has to be exported by another bundle) for a class loader to find it. This lead to problems when using frameworks such as Hibernate, which has to instantiate classes from your application. There is no way a Hibernate OSGi bundle can know beforehand which classes it will instantiate. Another problem is that the number of packages you will have to import is probably very large. Frameworks sometimes offer large amounts of classes that have been grouped into numerous packages. To mention each of those packages in your Import-Package manifest header is a lot of work. You could use the DynamicImport-Package to import all packages you require, but that will create as many problems as it solves. OSGi is designed to only resolve bundles when all requirements have been met. By dynamically importing packages, the OSGi framework has no way to know whether requirements are met, and will resolve your bundle. During runtime, you could get class loader exceptions.

Spring DM specific manifest headers

To counter both the large number of imports and the class loading problems, Spring DM introduced some additional manifest headers. Not that these are not (yet) official OSGi compatible headers and are only evaluated by Spring DM compatible OSGi environments, such as Spring DM Server, for which there is a community and an enterprise version.

The most important additional Spring DM manifest headers for bundles are:

• Import-Library can be used to import a library. A library is a specification of a set of bundles that should be imported as a whole. Examples of libraries are Hibernate and the Spring Framework.
• Import-Bundle is used to import all the packages from a specific bundle, such as Spring-Core. Typically, this header is used in library specifications, but it may also be used in bundles manifests.
• Module-Type specifies the type of this bundle. At the time of writing, only “Web” is supported. When adding this header to the manifest, you indicate that this bundle is to be treated as a Web Module.
• Web-context path specifies the URL in which a Web Module must be deployed. It default to the module’s file name minus the extension.
• Web-FilterMappings is used to specify the filter names (that reference spring bean names) and their URL mappings
• Web-DispatcherServletUrlPatterns indicates the URLs that have to be mapped to the DispatcherServlet. In Spring DM, a dispatcher servlet is automatically initialized with the context files in META-INF/spring/*.xml.

Creating an OSGi bundle with maven

Now that we know which headers have to be generated, lets move on to maven to find how we can generate a manifest file for them. Obviously, you could generate one yourself. This is, however, tedious and error prone. It is best to conform yourself to some design standards, such as using .internal or .impl packages to store classes that are not part of your public API. When you do so, the maven-bundle-plugin.

The maven-bundle-plugin is used to generate an OSGi bundle from your module. In order to make it work, you have to make a few modifications to an otherwise normal pom.xmlfile:

1. The <packaging> element value must be set to bundle: <packaging>bundle<packaging>
2. Configure the org.apache.felix:maven-bundle-plugin

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.felix</groupId>
            <artifactId>maven-bundle-plugin</artifactId>
            <extensions>true</extensions>
            <configuration>
                <instructions>
                    ...
                </instructions>
            </configuration>
        </plugin>
    </plugins>
</build>

This configuration will generate OSGi compliant manifest files. The Bundle-SymbolicName will be formed from your modules groupId and artifactId and the Bundle-Version will be set to you module’s version. By default, all packages that are mentioned in your source code’s import statements will be imported by your bundle, even if these packages are also included in your bundle (see this post on the OSGi Alliance website). Furthermore, all packages available in your bundle will be exported, even the .impl and .internal packages.

Manifest-Version: 1.0
Export-Package: springdm.domain;uses:="javax.persistence",springdm.per
 sistence.impl;uses:="springdm.domain,org.springframework.transaction.
 annotation,springdm.persistence,javax.persistence,org.springframework
 .beans.factory",springdm.persistence;uses:="springdm.domain"
Private-Package: springdm.*.impl.*
Built-By: allard
Tool: Bnd-0.0.255
Bundle-Name: Spring DM Persistence
Import-Library: org.hibernate.ejb;version="[3.3.2.GA,3.3.2.GA]"
Created-By: Apache Maven Bundle Plugin
Import-Bundle: org.springframework.orm;version="[2.5.6.A,2.5.6.A]"
DynamicImport-Package: *
Build-Jdk: 1.6.0_06
Bundle-Version: 1.0.0.SNAPSHOT
Bnd-LastModified: 1230983705375
Bundle-ManifestVersion: 2
Bundle-SymbolicName: springdm.persistence
Import-Package: com.mysql.jdbc.jdbc2.optional,javax.persistence,javax.
 sql,org.hibernate.jdbc,org.springframework.beans.factory,org.springfr
 amework.transaction.annotation,springdm.domain,springdm.persistence,s
 pringdm.persistence.impl


I am not going into more detail about how to configure the bundle plugin to keep implementation packages private. See the felix documentation for more information about that.

Adding Spring DM manifest headers

Well, that actually quite easy. All you have to do is specify the name of the header as a sub element in the <instructions> element and the value of the header as the value of that element, for example:

<Import-Bundle>org.springframework.orm;version="[2.5.6.A,2.5.6.A]"</Import-Bundle>

The problem is to find out which bundles or libraries there are to import, and which versions they have. That’s why Spring started the Spring DM bundle repository. You can use it to find libraries and OSGi bundles for most commonly used frameworks. For each of thus libraries or bundles, it will tell you which maven dependency to use (for compilation) and which manifest entry has to be added to your bundle. Make sure that your maven dependencies and manifest entries are updated, otherwise you could run into problems at runtime.

For maven to find the artifacts in the bundle repository, you have to configure some repositories. You can find them here.

If your bundle is a Web Bundle, add the required <Module-Type>Web</Module-Type> element to the instructions, as well as any other required Web-* headers.

That’s actually it. That’s all it takes to generate Spring DM specific manifest entries.

Creating a PAR deployment unit

The PAR file is the deployment unit for Spring DM applications. It is a Jar file with special manifest headers that contains all application specific bundles. You should never include framework bundles in the par file. In conventional environments, class loaders would prevent you from having different versions of the same class on your class path. Therefore, you had to add frameworks to the WAR file, to prevent version conflicts with other applications. In OSGi, there is no problem with having the same class multiple times. You just specify a version restriction in your import headers and OSGi takes care of the resolution process. To keep PAR files small, you can deploy required libraries and bundles in the /repository/libraries/usr and /repository/bundles/usr folders respectively. Any application can reuse any existing framework bundles.

The PAR file has another advantage. Spring DM Server prevents bundles from outside the PAR file from accessing bundles inside the PAR file. This way, you can deploy applications without running the risk of classes and services intermingling.

Now, let’s get back to maven to create ourselves a par file. First, create a new module in your maven project. This module’s pom file should have <packaging> set to par. Next, add dependencies to each module you want to be included in the par file. The par plugin does not include transitive dependencies, since framework bundles should not be included. Finally, add the maven-par-plugin to your plugin configuration.

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-par-plugin</artifactId>
            <version>0.2.0</version>
            <extensions>true</extensions>
            <configuration>
                <fqn>true</fqn>
                <applicationSymbolicName>gridshore.samples.springdm</applicationSymbolicName>
                <applicationVersion>1.0.0</applicationVersion>
                <applicationDescription>Gridshore Spring DM sample</applicationDescription>
                <applicationName>Gridshore Spring DM sample</applicationName>
            </configuration>
            <executions>
                <execution>
                    <goals>
                        <goal>par</goal>
                    </goals>
                    <phase>package</phase>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

You probably need to configure a repository to find this plugin: http://repo.steademy.com/beta/maven2. You can find documentation of the maven-par-plugin here.

Now run mvn install and see your PAR being created for you. Since your PAR does not contain framework bundles, you have to install them separately. To make sure that all dependencies are available, you can use the maven-assembly-plugin to create a zip file with the PAR file as well as all the framework bundles you require.

Have fun!

This blog item gives you an inside scoop into the continuous integration environment at JTeam. You’ll learn about the why, what and how of continuous integration. The tools we use are mainly open source.

A number of years a go not many people new the term continuous integration. That [...]]]>

This blog item gives you an inside scoop into the continuous integration environment at JTeam. You’ll learn about the why, what and how of continuous integration. The tools we use are mainly open source.

Why continuous integration?

A number of years a go not many people new the term continuous integration. That has changed a lot. All people at JTeam know what it is about and all projects use an environment that is set up to actually do continuous integration. For those that do not know what continuous integration is and those that need a short recap, we briefly explain what we think continuous integration is. Let’s start with the definition from Martin Fowler:

Continuous Integration is a software development practice where members of a team integrate their work frequently, usually each person integrates at least daily – leading to multiple integrations per day. Each integration is verified by an automated build (including test) to detect integration errors as quickly as possible. Many teams find that this approach leads to significantly reduced integration problems and allows a team to develop cohesive software more rapidly

Key to continuous integration is delivering high quality artifacts. It is not the silver bullet, developers still need to create great code, but using a good continuous integration process helps finding bugs. Checking your quality standards a long the way increases the effect. Of course extra actions are still necessary. You can think about actions like: manual code reviews, performance tests, functional tests, etc.

JTeam has been using continuous integration from the start. Recently we implemented the second version of our continuous integration environment. We introduced new tools, the process however stayed the same.

What do you need?

Continuous integration is about a lot of different things. So lets review them here. First of all, we have sources and a build. We tend to write a lot of java code, but we also need configuration files, html, style sheets, etc. With maven the way to structure your files has been standardized. We are using maven 2 for all our projects. Maven makes the life of a developer a lot more efficient while doing the normal tasks. Team leads and project leads also have reasons to implement maven in there projects. Maven has a lot of plugins that enable the projects spectators to see what is happening at the project.

Most of our projects are executed by more than one person, therefore a good source repository becomes very important. The source repository gives us more advantages, which I’ll talk about later. Within JTeam we have chosen to use subversion for storing the sources of the projects.

You can share sources and you have an automated build. Of course maven integrates very well with some IDE’s and it integrates kinda with some others. One of the important features of Maven is that it downloads dependencies from an online repository. Dependencies are libraries your project depends on. To limit network bandwidth, to store locally created libraries and to make libraries that are not available in an online repository accessible, you can connect to an internal repository. In maven this is called a proxy or a mirror. At JTeam we use a repository called Artifactory. Artifactory is a product from jfrog.

Having an automated build is not enough for good continuous integration. The automated build must be a continuous build. There are a lot of tools available that can give you continuous build. Some examples are : Hudson, CruiseControl and Luntbuild. We use Teamcity from Jetbrains to integrate all subversion checkins, run all the tests and every night run the maven reports. These maven reports are then published on a server so everybody can check the current status of the project. Teamcity is not open source and, there is a free license available, we use the commercial license. I explain later on why.

The following image gives you an overview of all services you need to have available for you to use in your project. The image shows more tools then I have discussed so far. They are not directly related to continuous integration, still they are very important for you when doing projects. Jira is about keeping track of requirements, issues and time estimations as well as time spend. Confluence is our knowledge base in which we document all our knowledge we gather while doing projects. Both jira and confluence are products from atlassian and very well known.

A last thing I would like to mention is a plugin for maven, the dashboard plugin. We are using this plugin now for a few projects and it gives some nice overviews. Graphical views of checkstyle, pmd, cobertura. When combining it with a database there is also the possibility of historical data, which is working very nice as well. You can find more information on the website including a lot of sample reports. http://mojo.codehaus.org/dashboard-maven-plugin/