The embedded container launcher

Wembed is a tiny utility that encapsulates servlet containers that can be embedded so they can be used more easily to test web applications. The idea is to allow developers to test web applications with different containers just by doing some small configuration changes, and also allowing them to be able to use those embedded containers in automatic tests with Ant.

Documentation index

• Quickstart
• Step by step installation
• Running YOUR web application with Wembed
• Showcasing your web application with different containers
• Using Wembed inside Ant to perform JUnit tests

Quickstart

• You need to have Java 6 properly installed.
• Go to the downloads section and grab the Wembed standalone release.
• Unpack the zip file to the directory of your liking.
• Edit bin/server.properties and set the base property to the directory where you have your web application deployed.
• Edit bin/server.properties and set the extra property to the directory where you have the extra jar files that your application requires and are usually provided by the container.
• Move to the bin directory and execute java -jar bin\Wembed-server.jar, or if you have the .jar files correctly associated, simply double-click on bin\Wembed-server.jar.
• Go to http://localhost:8080/ to see your application up & running.

Step by step installation

The first thing to do is to download Wembed from the downloads section. Let's suppose you grab the .zip version (Wembed_XX_standalone), download it and uncompress it in a folder.

• You need to have Java 6 installed and properly configured. To verify open a command window and type java -version, you should see something like:

 > java -version
 java version "1.6.0_11"
 Java(TM) SE Runtime Environment (build 1.6.0_11-b03)
 Java HotSpot(TM) Client VM (build 11.0-b16, mixed mode, sharing)

• Once you have Java 6 properly set up, open a command window and move to the directory where you just uncompressed Wembed. Then type java -jar bin\Wembed-server.jar. That's it!

After a brief splash screen, you should see a window open like this one:

You can then go and check the URL where the default web application is deployed (by default http://localhost:8080/) If everything went fine, you should see a page with the simple message “Hello wembed!”. If you want, you can also make sure that the datasources are also working fine by accessing the page http://localhost:8080/jdbc.jsp. There you should see a list of four items ordered alphabetically, which are the result of running a query against an embedded HSQL database, accessed through a container managed data source.

If anything goes wrong, push the button “Console Show/Hide” of the GUI and you will be able to see the server logs to find out what went wrong.

Running YOUR web application with Wembed

By default, Wembed mounts as a web application the folder called web at the installation directory. But don't worry, in order to use it with your own application, you don't need to copy your application in that folder, you just need to edit the bin/server.properties file and configure the base property to point to the directory where your web application has been deployed. So, for example, if your applications is deployed at the directory /home/me/Apps/MyWebApp, simply configure the property like this:

 # Default is ./web
 # base=./web
 base=/home/me/Apps/MyWebApp
 ...

Run the Wembed-server.jar again and you should see your application up & running it. Note that you can also do it through the command line, setting the base as a System property, like this:

  java -Dbase=/home/me/Apps/MyWebApp -jar Wembed-server.jar

Warning:: The embedded containers included with Wembed come with a very basic set of dependencies, enough to compile JSP pages, create a DataSource and access it through JNDI. So if you start your application and see various ClassNotFoundException, that's normal :). That's what the extra property is for. This setting configures a directory where you will be putting the extra .jar libraries that your application requires but are not included with it because they are usually shipped with the servlet container.

Showcasing your web application with different containers

Wembed provides encapsulates the embedded servlet container implementation so you can test you application with different containers. Wembed ships currently with two implementations:

• JettyEmbeddedContainer, using Jetty 6.1.7 as embedded container.
• TomcatEmbeddedContainer, using Tomcat 5.5 as embedded container.

and has another one shipped as a plugin (due to Resin redistribution license)

• ResinEmbeddedContainer, using Resin 4.0 as embedded container.

By default, Wembed uses the first container implementation that is found in the bin directory (of the lib-XXX form), so if you don't install one of them, it will automatically use the other. But if you want to choose specifically which container to use, you simply need to specify the container property to the name of the implementation you want to use. You can do it either through the server.properties file:

  # Default is the first one that appears in the classpath
  #container=jetty
  #container=tomcat
  #container=resin
  container=XXX
  ...

or setting the container system property when you execute the .jar file, like this:

  java -Dcontainer=XXX -jar Wembed-server.jar

Other containers have been tested and have a WIP implementation, and others are planned for when the servlet containers implement the proper hooks.

other interesting things to check

• Using Wembed inside Ant to perform JUnit tests
• Modifying the Wembed configuration
• Building Wembed from the source

Supported embedded containers

The list of containers that are currently supported by Wembed are the following:

• Jetty 6.1.7: Included with Wembed
• Tomcat 5.5: Included with Wembed
• Resin 4.0: Available but packaged separately (under the GPL)

Some other containers that are being tested or in the works

• WEMBED-10 -> Embedded GlassFish v3: GlassFish v3 itself is in beta and the embedded version is missing some basic features.
• WEMBED-11 -> Grizzly: It misses the abilty to add some extra classpath to the applications. Once it is implemented, it seems it will be very easy to add to the list.
• WEMBED-14 -> Tomcat 6.0: It won't be supported.

If you have a favourite embedded servlet container that is not in the list, feel free to suggest it to us. In order to be able to be integrated with Wembed, the basic features a container has to implement:

• Be able to be started/stop from Java code and be able to configure:
  • The listening port
  • The context name
• Be able to deploy an exploded application (a directory)
• Be able to set some extra classpath for the libraries that are not included by the application

Using icons from the Crystal project