Creating a FirstSpirit web-module: Part 3 – Understanding the module

Author: feddersen
Publication Date: 9/16/2010 8:00

You got the web-application example running? Great! So let's examine the module.xml a bit closer:

<!DOCTYPE module SYSTEM "../lib/module.dtd">
<module>
    <name>FirstSpirit WebApp Example Module</name>
    <version>@VERSION@</version>
    <description>FirstSpirit WebApp Example Module</description>
    <vendor>e-Spirit AG</vendor>
    <class>de.espirit.firstspirit.opt.examples.webapp.configuration.WebAppModule</class>
    <components>
        <web-app>
            <name>FirstSpirit WebApp Example Module</name>
            <description>Web component of FIRSTspirit integration.</description>
            <class>de.espirit.firstspirit.opt.examples.webapp.configuration.WebApp</class>
            <configurable>de.espirit.firstspirit.opt.examples.webapp.configuration.WebAppConfiguration</configurable>
            <web-xml>web.xml</web-xml>
            <resources>
                <resource>lib/webapp-example-@VERSION@.jar</resource>
            </resources>
            <web-resources>
                <resource>HelloWorld.tld</resource>
                <resource>configuration.properties</resource>
                <resource>lib/webapp-example-@VERSION@-webapp.jar</resource>
            </web-resources>
        </web-app>
   </components>
</module>

Module interface

The first interesting xml tag is

<class>de.espirit.firstspirit.opt.examples.webapp.configuration.WebAppModule</class>

Basically the "main class" of our module, it needs to implement the Module interface. Our implementation is very simple and just returns the module's name.

package de.espirit.firstspirit.opt.examples.webapp.configuration;

import de.espirit.firstspirit.module.Module;
import de.espirit.firstspirit.module.ServerEnvironment;
import de.espirit.firstspirit.module.descriptor.ModuleDescriptor;

/**
 * You don't need this class if you just want to create a simple webapp,
 * but it might be useful if your module will contain multiple components.
 */
public class WebAppModule implements Module {
    /*
     *  Initializes this component with the given descriptor and environment.
     */
    public void init(final ModuleDescriptor descriptor, final ServerEnvironment env) {
    }

    /*
     * Use this method to install templates or create other elements
     */
    public void installed() {
    }

    /*
     * Use this method to uninstall templates and to perform a cleanup
     */
    public void uninstalling() {
    }

    /*
     * Use this method to update templates or alter configuration settings during an update
     */
    public void updated(final String oldVersionString) {
    }


    @Override
    public String toString() {
        return "FirstSpirit WebApp Example Module";
    }
}

Hint: You can use the installed(), uninstalling(), updated() methods to perform actions (like installing templates into a project).

WebApp component

Since our module does only contain a web-application, we just need to define one component. As you might have guessed, the component is a "web-app". A web-app needs a "main-class" as well, which is referenced by:

<class>de.espirit.firstspirit.opt.examples.webapp.configuration.WebApp</class>

The class looks like this:

package de.espirit.firstspirit.opt.examples.webapp.configuration;

import de.espirit.firstspirit.module.AbstractWebApp;

/**
 * We need to implement the web application interface for your webapp component.
 * More advanced webapplication will use the methods to install/update/delete additional
 * elements.
 */
public class WebApp extends AbstractWebApp {

    /**
     * This method will be called if the component has been installed successfully.
     * Use it to install additional elements
     */
    @Override
    public void installed() {
        super.installed();
    }

    /**
     * Called when component was uninstalled.
     * Use this method to cleanup any files that might have been created by your component.
     */
    @Override
    public void uninstalling() {
        super.uninstalling();
    }

    /**
     * Called when component has been updated successfully
     */
    @Override
    public void updated(String oldVersionString) {
        super.updated(oldVersionString);
    }

    @Override
    public void createWar() {
        super.createWar();
    }
}

Again, nothing fancy.

WebApp Configuration

The <configurable> tag is more interesting. The referenced class implements the swing based configuration dialog. You can omnit this tag (and class) if you don't want to offer a custom configuration dialog. So what does this class do?

• the hasGui() method returns true – indicating that we do want to show a GUI.
• it creates a swing gui
• it read/writes the configuration.properties file that get's deployed

Location of web.xml

FirstSpirit needs to know the location of your web.xml, basically for two reasons:

1. As you've seen, the administrator can edit the web.xml in the admin console
2. FirstSpirit will merge all web.xml from all installed web-applications while creating the consolidated war file.

Our ant task copies the web.xml into the root directory of the fsm, so we just define

<web-xml>web.xml</web-xml>

Resources and web-resources

It might be a bit confusing at first sight, but you need to define two different kind of resources for a WebApp component.

Resources

Resources are all classes/jars that you need on the FirstSpirit server. That's the entire de.espirit.firstspirit.opt.examples.webapp.configuration package in our example. Luckily, the lib/webapp-example-@VERSION@.jar does contain just that package.

Web-Resources

Define all classes/jars/files, that should be included in the consolidated war file, as a web-resource.

• Our taglib file HelloWorld.tld
• the configuration file
• the lib/webapp-example-@VERSION@-webapp.jar, contain the servlet and taglib class

Don't list the web.xml here, that's already covered by the dedicated <web-xml> tag.

Wrap-up

This tutorial covered all necessary steps to develop a FirstSpirit WebApp module. It's a good idea to do so, because it makes managing and deploying web-application so much easier. Simple WebApps are created in a couple of minutes, configurable WebApps will take just a bit longer. Feel free to use our example as a starting point for your own WebApp.

Tags: api, development, fs4.2, knowledgebase, module, webapp