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:
- As you've seen, the administrator can edit the web.xml in the admin console
- 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.
