Project structure

The structure of the project is fairly straightforward, but big enough to demonstrate some of the features that gradle has to offer. It consists of two modules:

• App
• Web-ui

We are creating an Axonframework sample, the app contains the command handling and for now the query part as well. The web-ui contains the spring mvc app with the controllers and the authentication using the spring-security framework. For now we make use of an in memory database and we want to be able to start the application without a lot of hassle. Using jetty in this case.

The modules have some shared dependencies for testing and logging. We also want to centralize the definition of some dependency versions.

Multi module gradle build

Gradle was build with multi module support from the start. So what do you need to create a multi-module build. We need a settings.gradle that defines the available modules. Next to that we need the main build.gradle as well as the modules build.gradle. Oke you can do without the per module configuration, but in my case that was not the intention. Let us focus first on the main build.gradle.

Main build.gradle

The main build.gradle is used to define some of the versions of the dependencies. The following code block shows the complete script.

axonVersion = "0.6"
springVersion = "3.0.4.RELEASE"
springSecurityVersion = "3.0.3.RELEASE"
slf4jVersion = "1.5.8"
sourceCompatibility = 1.6

subprojects {
    apply plugin: 'java'

    configurations {
        all*.exclude group: "commons-logging", module: "commons-logging"
    }

    repositories {
        mavenCentral()
    }

    dependencies {
        compile "org.slf4j:jcl-over-slf4j:$slf4jVersion",
                "org.slf4j:jul-to-slf4j:$slf4jVersion"
        runtime "org.slf4j:slf4j-log4j12:$slf4jVersion"

        compile("log4j:log4j:1.2.15") {
            exclude group: "com.sun.jdmk", module: "jmxtools"
            exclude group: "com.sun.jmx", module: "jmxri"
            exclude group: "javax.mail", module: "mail"
            exclude group: "javax.jms", module: "jms"
        }

        testCompile 'junit:junit:4.7'
    }

    group = 'org.axonframework.samples.trader'
    version = '1.0-SNAPSHOT'
    sourceCompatibility = 1.6
}

As you can see, the script starts with the definition of the versions of dependencies. Than the script contains information for all the subprojects. You see we define the java plugin for all subprojects. Next to that the repositories and the dependencies are defined. Have a look at the mechanism to exclude transitive dependencies. For log4j we explicitly exclude some transitive dependencies. We also use a mechanism to exclude commons-logging from the complete build. Using the configurations hook we exclude it for all phases.

Finally we also define the group, version and source compatibility in the build configuration.

That is it, the following code block shows the required settings.gradle and after that we move on with the build.gradle of the app and web-ui subprojects.

include "app", "web-ui"

Subprojects build.gradle

The build.gradle for the app project is almost to easy to show. But I promised I would, so here we go:

dependencies {
    compile "org.axonframework:axon-core:$axonVersion"

    compile "org.hibernate:hibernate-entitymanager:3.4.0.GA",
            "c3p0:c3p0:0.9.1",
            "org.hsqldb:hsqldb:1.8.0.10"

    compile "org.springframework:spring-tx:$springVersion",
            "org.springframework:spring-orm:$springVersion",
            "org.springframework:spring-jdbc:$springVersion"

    compile "com.thoughtworks.xstream:xstream:1.3.1"

    testCompile "org.axonframework:axon-test:$axonVersion"
}

The configuration only contains dependencies. I would like to be able to simplify the dependencies on the spring projects. Would be nice if I could group them somehow, like:

compile group:”org.springframework”, version:”$springVersion”, module:["spring-webmvc", "spring-aop"]

But the build config looks pretty clean. Now we move on to the creation of the war for the web project.

apply plugin: 'war'

dependencies {
    compile project(':app')

    compile "org.springframework:spring-webmvc:$springVersion",
            "org.springframework:spring-aop:$springVersion"

    compile "org.springframework.security:spring-security-web:$springSecurityVersion",
            "org.springframework.security:spring-security-config:$springSecurityVersion"

    compile "javax.validation:validation-api:1.0.0.GA",
            "org.hibernate:hibernate-validator:4.0.2.GA"

    runtime "javax.servlet:jstl:1.1.2",
            "taglibs:standard:1.1.2",
            "opensymphony:sitemesh:2.4.2"

    providedCompile "javax.servlet:servlet-api:2.5"
}

Again a pretty straightforward config. We use more types of dependencies. We now introduce the providedCompile. Jars that need not be included in the war should have this config for the dependency. Do mark that we have an apply plugin line at the top for creating the war. Finally have a look at the mechanism to show we have a dependency on another module of the project. We use the compile project (‘:app’) to make the war include this created jar as well.

Running with Jetty

You think the jetty plugin for maven is easy, well check this out. We have to change only one word in the web project config. Look for the first line with apply plugin. Change the word war into jetty and you are done. Now you can run jetty with the following command from the root of the project:

gradle :web-ui:jettyRun

The wrapper

People that have gradle installed on their system can easily build the project and run jetty. But some people might not have gradle installed. You can help them to make it very easy. Gradle comes with a wrapper that downloads gradle and makes sure it’s on your path etc. The only thing the user needs to do is the following in the root of the project:

gradlew build

Pay attention to the ‘w’ at the end of the gradle command. Next step is to start jetty. This is done with the same command as before with one change, the w at the end. To help your users with this, you need to do one thing. You have to add the following task to the main build.gradle. Than run gradle wrapper, checkin the generated files into your source control system. The gradlew script can be used by the people to build the project. Good stuff or not?

task wrapper(type: Wrapper) {
    gradleVersion = '0.9-rc-1'
    jarPath = 'wrapper'
}

Intellij integration

Oke, this kinda hurts to say, but intellij support is not at a level that you would like to. At least that is what I could find out. You can easily run gradle builds from intellij. That is all nice. But I am really missing the dependency management part. Would be great to have support like for maven to setup your complete project. Wouldn’t it be great to have the import from external model feature for gradle as well? For now let us all vote for this issue, it might help:

http://youtrack.jetbrains.net/issue/IDEA-57755

I hope someone from jetbrains reeds this at thinks I am important enough to start creating this plugin

Performance

The last remarks I want to make are about the performance of gradle. At the moment I have this build for maven as well as gradle and maven2 is twice as fast as gradle. I know work is being done on this. Gradle 0.9.1 will support a new feature that at least will speed up building the project of you have to do it a lot during the day. It will do something with a running gradle service that you can call each time you start a build. There are some items on the mailing list about this specific topic if you are interested.

http://gradle.markmail.org/thread/xbqna6lowvsmm4ve

Concluding

Well that was part one of the experiment. I have not touched everything by a long run. Still I found out I like the configuration of gradle a lot better than I like maven. It is a lot cleaner and let’s you focus on the things that are important. I prefer groovy for this kind of work over xml. Still gradle has some ground to cover. For starters, tool integration. We must have something that makes working with intellij a lot better. In the future I will have a better look at plugins for release management and other stuff that I think is necessary for a good project build.

But the spec is there for a reason, so let’s try to adhere to it first. The specification is up to the following two interfaces and one exception.

• HttpContext – Enables bundles to use provided information about a servlet or resource during registration.
• HttpService – Enables other bundles to dynamically register sevlets or resources into the Http Service URI namespace.
• NamespaceException – Thrown when a problem arises during registration of a servlet or resource into the Http Service UIR namespace.

At first I tried to create my own implementation for these interfaces. It did not look to hard, but in the end I found the following patch which made my life a lot easier.
jetty6 patch

To be able to understand the implementation of an Http Service using jetty, you should understand the basics with respect to Jetty. In a forthcoming post I’ll talk more about these details. Within this post I’ll concentrate on the using of the service. I do need to make a few remarks. What if you do not want to apply the patch, change the pom, etc. Well you can download the one I have created from here : org.apache.felix.http.jetty-0.9.0-GRIDSHORE.jar. Another thing I would like to stress is the current state of the bundle. There are a lot of TODO’d in there. It looks like security is not implemented as it should. There is a completely different implementation at the ops4j website. One disadvantage is the level of control, need to look into that thing again. It is much more complicated, uses other bundles of the pax project. It does look interesting, but for me it is not easy enough. Another implementation is available at the sling website. But again a lot to graps before you can start. So for now I have chosen to continue with the slightly limited implementation, adhere to the spec and my bundles should work with the others as well.

Read more to learn about the sample using http.service and maven to build the bundle.

The sample

The goal was to play around with servlets and resources. I want to get a better idea about what OSGi can do. So I used the runner I introduced in my previous post (starting-with-osgi-using-apache-felix-step-1). Of course there are some other bundles and there is an extra property to configure the jetty intance:

configMap.put("org.osgi.service.http.port","9081"); // set the port to listen to for jetty
configMap.put(AutoActivator.AUTO_START_PROP + ".1",
    "file:" + BUNDLE_ROOT + "training-service/1.0-SNAPSHOT/training-service-1.0-SNAPSHOT.jar " +
    "file:" + BUNDLE_ROOT + "http-servlets/1.0-SNAPSHOT/http-servlets-1.0-SNAPSHOT.jar " +
    "file:" + JETTY_ROOT + "jetty/6.1.7/jetty-6.1.7.jar " +
    "file:" + JETTY_ROOT + "jetty-util/6.1.7/jetty-util-6.1.7.jar " +
    "file:" + JETTY_ROOT + "servlet-api-2.5/6.1.7/servlet-api-2.5-6.1.7.jar " +
    "file:bundle/org.osgi.compendium-1.0.0.jar " +
    "file:bundle/slf4j-api-1.4.3.jar " +
    "file:bundle/slf4j-simple-1.4.3.jar " +
    "file:bundle/org.apache.felix.http.jetty-0.9.0-GRIDSHORE.jar " + // use the created patched http.service
    "file:bundle/org.apache.felix.shell-1.0.0.jar " +
    "file:bundle/org.apache.felix.shell.tui-1.0.0.jar ");

The training service is a very easy service with one method returning a list of trainings. The more interesting bundle is the http-servlets bundle. This bundle contains the servlet that uses the training-service and some static resources like html pages, style sheets, etc. Let’s start with a look at the internal structure of the bundle. Please remember that we use the maven-bundle-plugin plugin. Therefore we adhere to basic maven project structure. The java files are in the src/main/java folder. The static resources are in the src/main/resources folder. The plugin than creates the right MANIFEST.MF file.

Manifest-Version: 1.0
Built-By: jettro
Created-By: Apache Maven Bundle Plugin
Bundle-Activator: nl.gridshore.samples.bundles.httpservlets.impl.Activ
 ator
Import-Package: javax.servlet;version="2.5",javax.servlet.http;version
 ="2.5",nl.gridshore.samples.bundles.trainingservice.api,org.osgi.fram
 ework;version="1.3",org.osgi.service.http;version="1.2",org.slf4j;ver
 sion="1.4"
Bnd-LastModified: 1204315796232
Bundle-Version: 1.0.0.SNAPSHOT
Bundle-Name: http-servlets
Build-Jdk: 1.5.0_13
Private-Package: htmls,htmls.css,htmls.images,nl.gridshore.samples.bun
 dles.httpservlets.impl
Bundle-ManifestVersion: 2
Bundle-SymbolicName: http-servlets
Tool: Bnd-0.0.227

Take good notice of the Private-Packge, here the directories are listed that are in the resources folder. So by default these resources are private. We need the http service to expose these resources. The next step is to have a look at the Activator of the http-servlets bundle. Let’s step through the separate methods that are important.

public void start(BundleContext bundleContext) throws Exception {
    this.bundleContext = bundleContext;
    doRegister();
    synchronized (this) {
        bundleContext.addServiceListener(this,
                "(|(objectClass=" + TrainingService.class.getName() + ")" +
                "(objectClass=" + HttpService.class.getName() + "))");
    }
}

Two important things happen in the start method, we first try to register the servlet (more on that later). After that we add a service listener that listens to events related to the TrainingService class and the HttpService class. This means that if one of these instances are started, stopped or updated we are notified. This notification is important to unregister the servlet if the training service disappears. Of course it is also important to register the servlet if the http service becomes available. Let’s move on to the register methods.

private void register() throws InvalidSyntaxException, ServletException, NamespaceException {
    ServiceReference[] trainingReferences = bundleContext.getServiceReferences(TrainingService.class.getName(), null);
    TrainingService trainingService = null;
    if (trainingReferences != null) {
        trainingService = (TrainingService) bundleContext.getService(trainingReferences[0]);
    } else {
        logger.info("No training service available");
    }

    ServiceReference[] httpReferences = bundleContext.getServiceReferences(HttpService.class.getName(), null);
    HttpService httpService = null;
    if (httpReferences != null) {
        httpService = (HttpService) bundleContext.getService(httpReferences[0]);
    } else {
        logger.info("No http service available");
    }

    if ((trainingService != null) && (httpService != null)) {
        logger.info("training servlet will be registered.");
        httpService.registerServlet("/trainings", new TrainingsServlet(trainingService), null, null);
        httpService.registerResources("/","/htmls",null);
    } else {
        logger.info("No servlet to register, problem with training service or http service");
    }
}

private void doRegister() {
    try {
        register();
    } catch (InvalidSyntaxException e) {
        logger.error("Could not register servlet based on an Invalid Syntax",e);
    } catch (ServletException e) {
        logger.error("Could not register servlet based on an Servlet exception",e);
    } catch (NamespaceException e) {
        logger.error("Could not register servlet based on an Namespace exception",e);
    }
}

Concentrate on the register method. First we check for available training service references. If a reference is available, we get the actual service. Then the same is done for the http service. If both of them are availble, we use the http service to register a new servlet that accepts the training service to obtain trainings from. As you can see we first register the servlet, the two null parameters represent the servlet config parameters and the special HttpContext. By providing null a default context is created. We also register a folder with static resources. The first string is the path or alias where the user should access the resources. The second string is the path to the resources within the bundle. The final parameter is the same as for the servlet, the HttpContext, again null so the default value. There are to more methods I want to show, first for unregistering and second for handling change events.

private void unregister() throws InvalidSyntaxException {
    logger.info("Unregister a servlet");
    ServiceReference[] httpReferences = bundleContext.getServiceReferences(HttpService.class.getName(), null);
    if (httpReferences != null) {
        HttpService httpService = (HttpService) bundleContext.getService(httpReferences[0]);
        httpService.unregister("/trainings");
        httpService.unregister("/");
    }
}

private void doUnregister() {
    try {
        unregister();
    } catch (InvalidSyntaxException e) {
        logger.error("Could not unregister servlet",e);
    }
}

public void serviceChanged(ServiceEvent event) {
    String objectClass = ((String[]) event.getServiceReference().getProperty("objectClass"))[0];
    logger.info("Service change event occurred for : {}", objectClass );
    if (event.getType() == ServiceEvent.REGISTERED) {
        doRegister();
    } else if (event.getType() == ServiceEvent.UNREGISTERING) {
        doUnregister();
    } else if (event.getType() == ServiceEvent.MODIFIED) {
        doUnregister();
        doRegister();
    }
}

The unregister function is pretty obvious. So let’s have a better look at the serviceChanged method. I took the easy way out here. Just check the type of event. In case of a new registration, register the servlet and resources. In case of an unregistration, we unregister the servlet and in case of a change we just do an unregister and a register. This works oke for my situation. Using the following screendumps I’ll show what happens when we start all bundles, stop de training-service bundle, and in the end start it again. First the output from the console, then the screens.

Welcome to Felix.
=================

1 [FelixStartLevel] INFO nl.gridshore.samples.bundles.httpservlets.impl.Activator - No http service available
1 [FelixStartLevel] INFO nl.gridshore.samples.bundles.httpservlets.impl.Activator - No servlet to register, problem with training service or http service
org.mortbay.log:Logging to org.mortbay.log via org.apache.felix.http.jetty.LogServiceLog
org.mortbay.log:started org.mortbay.jetty.servlet.HashSessionIdManager@2b2057
org.mortbay.log:started org.mortbay.jetty.servlet.HashSessionManager@85c0de
org.mortbay.log:starting OsgiServletHandler@395aaf
org.mortbay.log:started OsgiServletHandler@395aaf
org.mortbay.log:starting SessionHandler@70b819
org.mortbay.log:started SessionHandler@70b819
org.mortbay.log:starting org.mortbay.jetty.servlet.Context@1b50a1{/,null}
org.mortbay.log:starting ErrorHandler@46ad8b
org.mortbay.log:started ErrorHandler@46ad8b
org.mortbay.log:started org.mortbay.jetty.servlet.Context@1b50a1{/,null}
org.mortbay.log:jetty-6.1.x
org.mortbay.log:started Realm[OSGi HTTP Service Realm]==[]
org.mortbay.log:started org.mortbay.thread.BoundedThreadPool@ebaf12
org.mortbay.log:starting Server@32e910
org.mortbay.log:started org.mortbay.jetty.nio.SelectChannelConnector$1@19549e
org.mortbay.log:Started SelectChannelConnector@0.0.0.0:9081
org.mortbay.log:started SelectChannelConnector@0.0.0.0:9081
org.mortbay.log:started Server@32e910
191 [FelixStartLevel] INFO nl.gridshore.samples.bundles.httpservlets.impl.Activator - Service change event occurred for : org.osgi.service.http.HttpService
191 [FelixStartLevel] INFO nl.gridshore.samples.bundles.httpservlets.impl.Activator - training servlet will be registered.
org.mortbay.log:started /trainings/*
org.mortbay.log:started /htmls
-> stop 1
36499 [Felix Shell TUI] INFO nl.gridshore.samples.bundles.httpservlets.impl.Activator - Service change event occurred for : nl.gridshore.samples.bundles.trainingservice.api.TrainingService
36499 [Felix Shell TUI] INFO nl.gridshore.samples.bundles.httpservlets.impl.Activator - Unregister a servlet
-> start 1
org.mortbay.log:started /trainings/*
org.mortbay.log:started /htmls
43500 [Felix Shell TUI] INFO nl.gridshore.samples.bundles.httpservlets.impl.Activator - Service change event occurred for : nl.gridshore.samples.bundles.trainingservice.api.TrainingService
43500 [Felix Shell TUI] INFO nl.gridshore.samples.bundles.httpservlets.impl.Activator - training servlet will be registered.
->

Try to follow the steps, you can see the bundle containing the servlet starts before the training-service of the http-service. Then the change event is received and the servlet is registered. Next we stop the training service and the servlet is unregistered. And the servlet is registered again after a start of the training-service bundle (number 1).

This is the initial screen. Notice the url, this is a static resource called index.html that loads a stylesheet and an image from the bundle.

Now we have stopped the training service bundle, which has resulted in a unregister of the servlet, therefore the page is not available anymore.

I have started the training service bundle again, so the servlet gets registered and now I have clicked the link for trainings. As you can see we have two very interesting trainings.

So that is about it, it turned out to become a pretty long post. Hope you liked it. Please leave a comment if you did, and of course if you did not. All your ideas and suggestions are welcome. If you want to have a look at the source, you can find everyting in the FelixTryout project at my google code website.

1. initialize the container with the required bundles.
2. Start up the jetty instance with a servlet listening to the default path
3. Add a servlet that uses a service and takes care of the lifecycle.

Setting up the context

I already talked in my previous post about starting felix and adding bundles to the context. The following block of code shows the bundles that we install after initialization. I install the training service and the sample client. The sample client contains the code to start jetty and install the servlet. Then there are three jars you need to install before you are able to use the jetty instance: jetty, jetty-util and servlet api. Beware, if you want to use jsp’s as well you need to add more jars. Check the following website: embedding jetty.

configMap.put(AutoActivator.AUTO_START_PROP + ".1",
    "file:" + BUNDLE_ROOT + "training-service/1.0-SNAPSHOT/training-service-1.0-SNAPSHOT.jar " +
    "file:" + BUNDLE_ROOT + "example-client/1.0-SNAPSHOT/example-client-1.0-SNAPSHOT.jar " +
    "file:" + JETTY_ROOT + "jetty/6.1.7/jetty-6.1.7.jar " +
    "file:" + JETTY_ROOT + "jetty-util/6.1.7/jetty-util-6.1.7.jar " +
    "file:" + JETTY_ROOT + "servlet-api-2.5/6.1.7/servlet-api-2.5-6.1.7.jar " +
    "file:bundle/slf4j-api-1.4.3.jar " +
    "file:bundle/slf4j-simple-1.4.3.jar " +
    "file:bundle/org.apache.felix.shell-1.0.0.jar " +
    "file:bundle/org.apache.felix.shell.tui-1.0.0.jar ");

Start the jetty instance

Starting a jetty instance is very easy. The following code shows you how to create a jetty instance while listening to a certain port. Next step is to initialize the context using a context url. In our case we use the root, so you should go to http://localhost:8091/ to have a look at the application. Second step is to add a HelloServlet instance listening to everything in the root path “/*”. The final step before actually starting the jetty instance might be a little less obvious. Here we define an empty servlet returning a non available message. The next step will show why. This servlet will be listening to the url “/trainings”

Server server = new Server(9081);
Context root = new Context(server, JETTY_CONTEXT_PATH, Context.SESSIONS);
root.addServlet(new ServletHolder(new HelloServlet()), MAIN_SERVLET_PATH_SPEC);
servletHolder = new ServletHolder();
servletHolder.setServlet(new NonAvailableServlet());
root.addServlet(servletHolder, TRAININGS_SERVLET_PATH_SPEC);
server.start();

Add training servlet if service is available

We start by registering a service listener that is listening to events related to objects with a name TrainingService :

bundleContext.addServiceListener(this,
    "(&(objectClass=" + TrainingService.class.getName() + "))");

You can add other properties to this query, but for now we do not need that. Since the activator class implements the ServiceListener interface we need to implement the following method. That method receives events that comply to the provided filter.

public void serviceChanged(ServiceEvent event) {
    if (event.getType() == ServiceEvent.REGISTERED) {
        logger.info("Training service is registered");
        servletHolder.setServlet(new TrainingsServlet(
            (TrainingService)bundleContext.getService(event.getServiceReference())));
    } else if (event.getType() == ServiceEvent.UNREGISTERING) {
        logger.info("Training service is unregistered");
        servletHolder.setServlet(new NonAvailableServlet());
    } else if (event.getType() == ServiceEvent.MODIFIED) {
        logger.info("Training service is modified");
        servletHolder.setServlet(new TrainingsServlet(
            (TrainingService)bundleContext.getService(event.getServiceReference())));
    }
}

As you can see from the code there are three type of events we support. We get an event when the service is registered, unregistered or changed. This gives us the opportunity to register the servlet that uses the training service if the service is available and to register the empty servlet when the training service is not available.

You can find the complete source code here (look for the FelixTryout project). and the specific Activator containing the jetty stuff here.

That is about it, hope you liked the article. Use the comments if you have questions. If you would like to read the previous articles, click on them here or click on felix in the tag cloud.
step 1 – step 2