WAS 2.1 Setup

Custom server assemblies

The default download of Community Edition is a fully compliant, Java EE5-certified server assembly. Depending on your business requirements you may not need a complete server but just require a part of it. For example if your application comprises only the Web tier, you might only need Tomcat and exclude the other modules like OpenEJB, Active MQ etc. Previously extracting a custom server was a build-time operation, but with Community Edition V2.1 you can get a a customized snapshot of the existing server during runtime. There are two approaches to extract a custom server:

  • Application centric: You select one or more plug-ins required for your application to run successfully.
  • Function centric: You select the desired set of features required for your development environment.

We will discuss creating a custom server in great detail in the next sections. But first we need to understand the basic Community Edition architecture. It provides a plug-in architecture where servers are assembled completely out of the plug-ins. Every module in Community Edition is a plug-in, and each plug-in has associated dependencies. So we need to make sure that our assembled server has all the plug-ins it needs to operate.

In our sample we use an application-centric approach to define the contents of our custom server. We are using jsp-examples-war from our existing Community Edition samples (available with the Community Edition download). Follow these steps to create the custom server assembly:

  1. Modify the deployment plan for the application. This step is required because the default deployment of the sample installs the application as WAR, whereas Community Edition recognizes a plug-in as a CAR. Add the car tag to the deployment plan.
  2. Deploy the sample jsp-examples-war to Community Edition V2.1.
  3. You can launch the application and verify the functionality using http://localhost:8080/jsp-examples/.
  4. Next we identify the functional components and dependencies required by our application. This step can be simplified by using the Dependency Viewer portlet in the administrative console. Launch the administrative console using http://localhost:8080/console/.
  5. Log in using the default user name of system, and manager for the password.
  6. On the welcome page under Debug Views, launch the Dependency Viewer portlet as shown in Figure 1:

    Figure 1. Dependency Viewer portlet in administrative console
    Screen shot of Dependency Viewer portlet

  7. Since we have deployed a Web application, select WebModule. Under WebModule, select org.apache.geronimo.applications.examples/geronimo-jsp- examples/> dependencies, which displays the various dependencies required by our Web application (see Figure 2):

    Figure 2. Dependencies for jsp-examples-war application
    Screen shot of dependencies

  8. To get a minimal working server we also need to include the geronimo-boilerplate-minimal plug-in for start, stop and other functionalities.

We have now identified the dependencies required for our custom server. Next we assemble a custom server out of all these dependencies:

  1. In the Administrative Console under Applications, select Plugins, as Figure 3 shows:

    Figure 3. Plugin portlet in Administrative Console
    Screen shot of  Plug-in portlet

  2. Next select Assemble a server. On the next screen, enter org.apache.geronimo.customserver for the groupId and TestServer for the artifactId, as Figure 4 shows:

    Figure 4. Artifacts for the assembled server
    Screen shot of artifacts for the assembled server

  3. Now select the following plug-ins from the list displayed under Plugins in local server, and then click Assemble.
    • com.ibm.wasce.assemblies/wasce-boilerplate-minimal/
    • org.apache.geronimo.applications.examples/geronimo-jsp-examples/
    • org.apache.geronimo.configs/axis/2.1.1/car
    • org.apache.geronimo.configs/axis2/2.1.1/car
    • org.apache.geronimo.configs/j2ee-corba-yoko/2.1.1/car
    • org.apache.geronimo.configs/jasper/2.1.1/car
    • org.apache.geronimo.configs/openjpa/2.1.1/car
    • org.apache.geronimo.configs/tomcat6/2.1.1/car

    Figure 5. Selecting plug-ins
    Screen shot of  plug-ins to select

  4. The next screen (Figure 6) displays the list of all the plug-ins to include in the custom server. Click Install.

    Figure 6. List of all plug-ins to include in custom server
    Screen shot of all plug-ins for the custom server

  5. On the next screen (Figure 7) you should see a message indicating successful server assembly, that includes the location of the custom server (in our case /var/temp/assembly). Click Done.

    Figure 7. Successful server assembly
    Screen shot of message showing successful assembly

  6. Next we need to test the assembled server. Shut down the existing one, and start the new server from \var\temp\assembly\bin\startup.bat.
  7. Finally, you can launch the application using http://localhost:8080/jsp-examples/.

Note that our assembled server is a minimal server; you will not be able to get a graphical user interface for the administrative console.

For your reference, you might want to include these plug-ins in your custom server:

  • org.apache.geronimo.plugins/console-tomcat/2.1.1/car: GUI-based administrative console
  • org.apache.geronimo.plugins/sysdb-console-tomcat/2.1.1/car: GUI-based Database portlet in administrative console
  • org.apache.geronimo.plugins/debugviews-console-tomcat/2.1.1/car: GUI-based Debug Views portlet in administrative console
  • org.apache.geronimo.plugins/activemq-console-tomcat/2.1.1/car: GUI-based JMS console in administrative console
  • org.apache.geronimo.plugins/plancreator-console-tomcat/2.1.1/car: GUI-based Deployment Plan Creator portlet in administrative console

As you can tell from our example, the custom server is a powerful feature that further harnesses the modular, extensible Geronimo plug-in architecture. You can quickly assemble numerous types of servers out of an existing running server.

Deployment Plan Creator wizard

To simplify the creation of server-specific deployment plans (like geronimo-web.xml), Community Edition now has a new portlet called Plan Creator in the administrative console.

Plan Creator takes a Web application archive (WAR) and walks the user through a sequence of steps to auto-generate the geronimo-web.xml file. It does not yet support creating geronimo-application.xml and openejb-jar.xml from EARs and EJB-JARs.

Some of the salient features of the Deployment Plan Creator include:

  • EJB, EJB Local, JDBC Connection Pool, JMS Connection Factory, JMS Destination, JavaMail Session & Web Service references declared in the Web-applications are auto discovered. You resolve them by listing available resources in the server environment to which they can be linked.
  • Any of the references described above that are declared inside the Java classes through annotations are also auto discovered.
  • Simplified configuration of security.

We will illustrate this with the jsp-examples-war application available in the Community Edition samples .

  1. In jsp-examples-war-, locate the Web application deployment plan (geronimo-web.xml) in the application archive under WEB-INF.

    Currently we have the deployment plan shown in Listing 1:

Listing 1. Deployment plan geronimo-web.xml
  <web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-2.0"


<sec:principal class="org.apache.geronimo.security.realm.providers.
GeronimoUserPrincipal" name="anonymous"/>
<sec:role role-name="tomcat">
<sec:principal class="org.apache.geronimo.security.

  1. Delete the deployment plan from the jsp-examples-war- archive.
  2. Launch the Community Edition administrative console and log in using the default user name and password.
  3. Under Applications, select Plan Creator, as Figure 8 shows:

    Figure 8. Plan Creator portlet in Administrative Console
    Screen shot of Plan Creator portlet

  4. In the next screen, click Browse and select jsp-examples-war- Click Configure, as Figure 9 shows:

    Figure 9. Selecting Web archive for creating deployment plan
    Screen shot of  WAR file

  5. The next screen suggests a Web application identity and class path configuration for our environment. You can set the WebContextRoot to PlanCreatorTest, and leave the rest of the values as the defaults, as Figure 10 shows. Click Next.

    Figure 10. Configuring Web application identity and class path
    Screen shot of identity and class path

  6. The next screen displays the configuration for security realm and role mappings. Select Principal for the role1 field. The Name and Class fields then appear. Name it TestUser, and select User Principal for the Class, as Figure 11 shows. Click Add.

    Figure 11. Selecting the class
    Screen shot showing how to select the class

    You should now see the Principal, Name and Class displayed as added to the deployment plan, as Figure 12 shows:

    Figure 12. Configuring role mapping for role1
    Screen shot of role1

  7. Next select Principal for the tomcat field. Name it TestGroup, and select Group Principal for the Class field. Select Add, as Figure 13 shows.

    Figure 13. Configuring role mapping for tomcat
    Screen shot of tomcat role mapping

    You should now see the Principal, Name, and Class displayed as added to the deployment plan. Select Next.

  8. The next screen suggests dependencies to select for the application. Our application does not have any, so we will keep the default selection. You could select dependencies like ejb, database pool, jms resources etc, but they aren’t required. Select Next.

  9. The next screen displays the generated deployment plan, as Listing 2 shows:

Listing 2. Generated deployment plan
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-2.0.1">
<dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/
<app:security xsi:type="sec:securityType"
<sec:role role-name="role1">
<sec:principal name="TestUser " class=
<sec:role role-name="tomcat">
<sec:principal name="TestGroup " class=

  1. Select Deploy WAR, as Figure 14 shows:

    Figure 14. Deploying WAR with deployment plan
    Screen shot showing how to deploy WAR with deployment plan

  2. You should see a message indicating the successful deployment of our Web application. Select Launch Web App to launch the Web application, as Figure 15 shows:

    Figure 15. Launching the Web application
    Screen shot showing the Web application

  3. As you can see in Figure 16, the application launches with a context root PlanCreatorTest. However, the original deployment plan (the one packaged with the Web application) had jsp-examples as the context root.

    Figure 16. Launched application with context root as PlanCreatorTest.
    Screen shot with content root set to PlanCreatorTest


GShell is a framework for building rich command line applications. GShell is a command line processing environment for executing most of the Community Edition commands. Table 2 displays the various GShell commands:

Table 2. Gshell commands
Commands Description
help or ? Display help information
echo or print Print arguments to STDOUT
source or . Load a file or URL to the current shell
clear Clear the terminal screen
set Set a variable
unset Unset a variable
exit or quit Exit GShell
geronimo/start-server Start a server
geronimo/stop-server Stop the server
geronimo/wait-for-server Wait for the server to start
geronimo/start-client Start an application client
deploy/connect Connect to a WASCE server
deploy/disconnect Disconnect from a WASCE server
deploy/deploy Deploy a module
deploy/redeploy Redeploy a module
deploy/undeploy Undeploy a module
deploy/distribute Distribute a module
deploy/start Start a module
deploy/restart Restart a module
deploy/stop Stop a module
deploy/list-modules List modules
deploy/list-targets List targets
deploy/list-plugins Install plug-ins into the server
deploy/install-library Install library
deploy/install-plugin Install a plug-in
deploy/assemble Extract a WASCE server from the current one

Let’s look at an example of using GShell. Community Edition has a batch file gsh.bat to start GShell, available in /bin. Launch GShell by running gsh.bat from a command prompt, as Figure 17 shows:

Figure 17. Starting GShell
Screen shot of command prompt after running gsh.bat

To start the server using GShell, enter the command geronimo/start-server, as Figure 18 shows:

Figure 18. Starting a server using GShell
Screen shot of command prompt after starting the server

To list the modules deployed on the server, enter the command deploy/list-modules. Enter the default user name and password, as Figure 19 shows:

Figure 19. Listing the modules deployed on the server
Screen shot of command prompt after listing the modules

Expert mode

In the Community Edition administrative console, under Applications, various portlets (WebAppWARs, system modules, application EARs, EJB JARs, J2EE Connectors, app clients) display the various modules (Web applications modules, system modules, enterprise application modules, EJB modules, connector modules, application clients, respectively). From these portlets you can start, stop, restart and uninstall various modules. The default console displays these operations grayed out for various modules.

Expert mode lets advanced users have more control over the processes running on the Community Edition server. By default you cannot modify critical processes. However, the Expert mode option enables full control over these processes, and is embedded into all the portlets previously mentioned. The following example shows you how to use Expert mode in Community Edition.

  1. Launch the administrative console and login using default user name and password
  2. Under Applications, select WebAppWARs. As you can see in Figure 20, stop, restart and uninstall commands for various modules are grayed out.

    Figure 20. Default display of WebAppWARs portlet
    Screen shot of WebAppWARs's defaults

  3. Select the checkbox for Expert User on the top left of the Installed Web Applications screen. You’ll see that the grayed out commands are enabled, as shown in Figure 21. Now you have full control of all the modules installed on the server.

    Figure 21. WebAppWARs portlet after enabling Expert User
    Screen shot of WebAppWAR for Expert User

Monitoring console plug-in

The health of the server can be critical; anticipating server crashes is crucial to any running application. Usually such server crashes ends with lots of troubleshooting and loss of critical data. To avoid such catastrophic situations, you need to continuously monitor server health and reconfigure it to perform at an optimum level. This monitoring in turn increases the productivity of your production environment. To address this issue, the Community Edition V2.1 administrative console is integrated with a new Monitoring plug-that continuously monitors various statistics, such as:

  • Transaction Manager
  • JVM
  • AJP/Web/WebSSL connector
  • ThreadPool
  • Web application

However, you should only monitor your required components, rather than enabling everything. The rule of thumb is well established -- the more components you monitor, the greater the impact on server performance.

The default installation of Community Edition is pre-deployed with the Monitoring plug-in. This portlet has three panes: View, Servers and Graphs. Let’s discuss each one of them in turn in the context of an example:

  1. Launch the administrative console and log in using the default user name and password.
  2. In the console navigation, under Server, select Monitoring to launch the portlet. You will see the View, Servers and Graphs panes. On the right side you see +Create View, +Add Server, +Add Graph, as Figure 22 shows. You use these to add a new View, Server and Graph respectively.

    Figure 22. Default View of Monitoring portlet
    Screen shot of Monitoring portlet's default view


Before we can start working with our Monitoring plug-in, we need to add a server. Using this pane, you can add multiple instances of Community Edition, which allows centralized monitoring of multiple machines. The following steps illustrate adding a server using the Monitoring plug-in:

  1. Click Add a Server, as Figure 23 shows:

    Figure 23. Adding a server in Monitoring Portlet
    Screen shot of adding a server

  2. On the next screen fill in the various fields as shown in Figure 24, and click Add.
    • Name: MyServer
    • IP/Hostname: localhost
    • Protocol: EJB
    • Port: 4201
    • Username: system
    • Password: manager

    Figure 24. Configuring the server in the Monitoring portlet
    Screen shot of configuring the portlet

  3. You are redirected to the default view of the Monitoring portlet, but this time you see a message reporting successful addition of the server, as Figure 25 shows. Also, the Servers pane has a new entry called MyServer. Currently the status of the query is stopped. Click +Enable Query to start the snapshot collection of data.

    Figure 25. Enabling snapshot collection of data
    Screen shot of enabling snapshot collection

  4. Now you should see the status of the query as Online, which collects a snapshot every 5 minutes. You can modify this by clicking Edit under Actions..

  5. On this screen change the Snapshot Duration to 1 minute, and click Save. You should see a message saying “Server has been updated”. Select Monitoring to go back to the default view of the portlet.

    Figure 26. Editing the existing server configuration
    Screen shot showing how to edit the server configuration

  6. In the Server pane, select MyServer to display the various statistics being monitored by that server. Figure 27 shows the statistics:

    Figure 27. Various statistics being monitored by our MyServer configuration
    Screen shot of monitered statistics

    Let’s take a closer look at various fields and functionalities on this page:

    • My Server shows the status, added timestamp, modified timestamp, IP Hostname, and snapshot duration for the current configuration.
    • Live Statistics shows the various components currently being monitored (for example JVM, Tomcat AJP Connector, Tomcat Web Connector, Tomcat Web SSL Connector, activemq-console-tomcat). You can also see two Web applications being monitored: SimpleJSF and jsp-examples-war- Each of these is associated with various fields.
    • On the right hand side you can see Statistics Collected, which shows the statistics currently being collected for the components. By each field you can see a ×, which can be used to stop the monitoring of a component.
    • The Statistics Available panel shows the various components available to be included in the current monitoring configuration. Selecting + adds a component to the Statistics Collected panel, causing the server to start monitoring the newly added component.
    • Actions panel provides various options to configure the current server monitoring configuration.

  7. On the same screen, try selecting some link under Live Statistics. Let’s select the Busy Threads Max link under TomcatAJPConnector, as Figure 28 shows:

    Figure 28. Selecting Busy Thread Max under TomcatAJPConnector
    Screen shot of selecting Busy Thread Max

  8. This link launches a portlet for adding a graph for the selected property, as shown in Figure 29. This is an easier way to create graphs, since a few fields are already populated by default. However we will look at creating a graph from scratch in the next section.

    Figure 29. Adding a Graph through MyServer configuration
    Screen shot of  adding a graph via MyServer


You can use this pane to create customized graphs. It also lets you perform mathematical operations like addition, subtraction, division, and multiplication on two statistics. Let’s add a graph for the current MyServer configuration.

  1. From the Monitoring portlet, select +Add Graph, as Figure 30 shows:

    Figure 30. Adding a graph
    Screen shot ot adding a graph via the Graph view

  2. On the next screen, fill in the following values, as shown in Figure 31. Click Add.
    • Server: MyServer-localhost
    • Name: TomcatAJP_BusyThread
    • Description: This is to monitor the Busy thread Max for Tomcat AJP Connector
    • X Axis label: Busy Threads
    • Y Axis label: Time
    • Timeframe: 5
    • Mbean: TomcatAJPConnector
    • Data series: As-is; Busy Threads Max
    • Math operation: none

    Figure 31. Filling the form for adding a graph
    Screen shot showing values for the graph

  3. You return to the default view of the Monitoring portlet, with a message reporting the successful addition of the Graph. Select the added graph to display the graph, as Figure 32 shows:

    Figure 32. Displaying graph
    Screen shot of  how to select the graph


Because of the many different graphs, Community Edition uses the concept of a "view" to bundle related graphs together for more manageable use. For example, you can bundle together all graphs related to a specific server, or all graphs showing the throughput of servers. Let’s walk through how to create a view:

  1. In the Monitoring portlet select +Create View.
  2. On the next screen give a name and description for the new view. You also see a Graphs field which displays a list of graphs available with the current configuration. So far we have added only one graph it, so there’s not much to choose from.. Select the check box and save the configuration as shown in Figure 33:

    Figure 33. Configuring a View
    Screen shot of configuring a view

  3. You return to the default view of the Monitoring portlet. Select MyView to view the current configuration, which displays the graph you added.

    Figure 34. Displaying the MyView configuration
    Screen shot of selecting MyView

WADI clustering

An application server cluster is a group of servers that transparently provide enterprise services, such as Servlets and JavaServer Pages (JSP) support, as if it was a single server. The servers, typically running on separate systems, exchange messages to synchronize data, allowing any individual node to process requests for a distributed application and to take over a user's session when its node fails. Configuring multiple servers into a cluster is commonly called clustering.

Currently, Community Edition implements clusters using the session replication support from either Apache Tomcat or WADI (Web Application Distributed Infrastructure).

Tomcat clusters have some limitations.

  • They do not replicate stateful session Enterprise JavaBeans (EJBs). You need to avoid stateful session EJBs in your distributed applications.
  • They do not replicate dynamic updates to the Java Naming and Directory Interface (JNDI). You need to configure all the JNDI names used by your distributed applications in every node of the cluster.
  • They do not replicate distributable Web applications to other nodes in the cluster. You need to deploy your distributable Web applications to every node.

Community Edition V2.1 improves on Tomcat clusters in the following ways:

  • You can now use WADI with Tomcat configurations of Community Edition, to support the replication of HTTP Session state among multiple Community Edition servers.
  • You can now deploy applications to administratively-defined groups of Community Edition servers, which makes it easier to manage a single application across a number of Community Edition servers.

You can now use WADI to support clustering of Web applications for configurations that use Tomcat Web containers. To cluster these components, their deployment descriptors are augmented with specific XML elements. These elements define various clustering parameters controlling how the underlying WADI's components are wired and set-up upon application deployment.

WADI also provides the concept of farming:

  • Farming -provides cluster-wide hot deployment of Web applications. In a server farm, you deploy a Web application by copying an application's WAR file to only one node in the cluster. Farming takes care of deploying the Web application across the entire cluster. Similarly, removing the WAR file from a single cluster node removes the Web application from all the nodes in the cluster. You can deploy a configuration to a cluster of Community Edition servers via a single logical deployment step. Once deployed to a cluster, this configuration can then be transparently started, stopped or removed across all the cluster members.
  • Farm deployment- Deploying a application to configured members of cluster.

For more information, see the Community Edition documentation on clustering.

Community Edition Eclipse plug-in

The Community Edition Eclipse plug-in (hereafter WEP) v2.1 has undergone a major architectural change in its model framework, from the Eclipse Modelling Framework (EMF) to the Java Architecture on XML Binding (JAXB). This was done to enables some major improvements in WEP's Deployment Plan Editors. So expect some intelligent editors in a future release!

Also, with v2.1 WEP has shed a lot of weight -– the WEP footprint is now just 5MB, down from 13MB in the previous release. In addition, WEP contains numerous bug fixes, leading to a smoother experience using WEP.

Other enhancements

  • The administrative console is now component-based to mirror the server capabilities. When you create a custom server assembly, only the corresponding portlets that are used by the selected functions or modules are incorporated.
  • Community Edition V2.1 now includes support for IBM DB2 8.2, 9.1 and 9.5 JDBC drivers as well as Oracle Real Application Cluster (RAC) support.
  • Community Edition V2.1 is now compatible with Red Hat Fedora 9, Ubuntu 8.04 Long Term Support(LTS) and recommends the AIX Version 6 Update 1 operating system. Java support includes recommendations for IBM Java 32bit/64 bit SE 5 SR6b and compatibility with Sun Java 32bit SE 5 Update 15 or later.
  • Some new samples have been added, including:
    • Bank- demonstrates EJB 3.0 Session Bean, JPA and OpenEJB client technologies.
    • jms-mdb-sample- demonstrates the Message-Driven Bean in EJB 3.0
    • sendmail- demonstrates the Mail Session in Community Edition.
  • The Community Edition console has been rebranded with new look and feel. Several enhancements have been applied to the administrative console to improve the user experience. Enhancements include renaming various links on the left pane of the console navigation for increased usability, for example under Server, the JVM portlet has been renamed to Java System Info, and Common Libs has been renamed to Repository.
  • Various component modules have been updated in Community Edition V2.1. Please see Table 1 for an updated list of modules.
  • The config.xml in Community Edition V2.1 now includes all the available attributes for Tomcat Web, AJP and SSL attributes.
  • A new gbean TomcatClusteringBuilder helps with clustering support. Config-substitution.properties has also been modified to include various new configuration parameters like MaxThreadPoolSize, ResourceBindingsQuery, clusterName, ResourceBindingsFormat,and TmId.