From Mon Nov 08 06:52:52 2010 Return-Path: Delivered-To: Received: (qmail 26771 invoked from network); 8 Nov 2010 06:52:51 -0000 Received: from unknown (HELO ( by with SMTP; 8 Nov 2010 06:52:51 -0000 Received: (qmail 45110 invoked by uid 500); 8 Nov 2010 06:53:23 -0000 Delivered-To: Received: (qmail 44976 invoked by uid 500); 8 Nov 2010 06:53:23 -0000 Mailing-List: contact; run by ezmlm Precedence: bulk list-help: list-unsubscribe: List-Post: Reply-To: List-Id: Delivered-To: mailing list Received: (qmail 44969 invoked by uid 99); 8 Nov 2010 06:53:23 -0000 Received: from (HELO ( by (qpsmtpd/0.29) with ESMTP; Mon, 08 Nov 2010 06:53:23 +0000 X-ASF-Spam-Status: No, hits=-1994.3 required=10.0 tests=ALL_TRUSTED,HTML_FONT_LOW_CONTRAST,HTML_MESSAGE,MIME_HTML_ONLY X-Spam-Check-By: Received: from [] (HELO ( by (qpsmtpd/0.29) with ESMTP; Mon, 08 Nov 2010 06:53:20 +0000 Received: from thor (localhost []) by (8.13.8+Sun/8.13.8) with ESMTP id oA86r09P015662 for ; Mon, 8 Nov 2010 06:53:00 GMT Date: Mon, 8 Nov 2010 01:53:00 -0500 (EST) From: To: Message-ID: <7827322.5241.1289199180034.JavaMail.confluence@thor> Subject: [CONF] Apache Geronimo v2.1 > Extensible Administration Console MIME-Version: 1.0 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Auto-Submitted: auto-generated

Extensible Administration Console

Page edited by maojia

Changes (1)

=20 =20

h2. Create a portlet
In their most fundamental= state, an ACE defines where to place new/old portlets in your console. Po= rtlets are the fundamental building block of the administrator console. We= are using Pluto 2.x as our portal engine since it closely conforms to [JSR= 168| 099_12/portal.1014/b14135/toc.htm]. 168| =3D168]. We will not go into the details of how to develop portlets= since you can find many tutorials and tools for this such as [Portlet Plug= in for Eclipse|]. You will= need the appropriate "web.xml" and "portlet.xml" files= defined. As a simple example, refer to the [HelloWorldPortlet|#Sample Exte= nsion] defined at the end of this section.

h2. Add an AdminConsoleE= xtensionGBean

Full Content

This document contains the following sections:

Introducti= on

The Extensible Administration Console is a new Administration Console de= signed to mirror the flexibility of Geronimo's architecture. While the prev= ious console was static, allowing configuration only for pre-defined compon= ents, the new Extensible Console changes dynamically with the components in= stalled on your server.

This framework allows Geronimo plugin developers to package extensions t= o the Administration Console (called ACEs) with their components. On instal= lation of a plugin, this new content will automatically be added to the Ext= ensible Administration Console, so that the user can manage all of the conf= iguration and tools from one place.


After reading this document, a Geronimo user will be able to

  1. Install the Extensible Administration Console into a Geronimo minima= l assembly (Tomcat or Jetty)
  2. =09
  3. Download and install an Administrative Console Extension


This document covers installing Geronimo's Administration Console into a= Geronimo minimal assembly and the process to install an ACE plugin. For mo= re information about the underlying architecture and ACE development, see t= he Administration Console Extension Developer's Guide.

<= /a>Who should read this document

These instructions are geared towards a basic user of Geronimo who wants= to install new components on the administration console. Knowledge of the = internal workings of the server is not necessary.


The reader should be familiar with the Geronimo application server and i= ts applications. The reader should also be familiar with the basics of Gero= nimo's plugin framework. For more information about the architecture, this = guide may also be a valuable resource: 1/04717854/DOWNLOAD/Pro_Apache_Geronimo_ch17.pdf.
The reader should have Apache Geronimo 2.1 Minimal ("Little-G") installed a= nd running, with either Tomcat6 or Jetty6 as the web container. The Java E= E assemblies already have the Extensible Aministration Console installed. = For more information about getting started or getting updated to the right = version, see this website: http://cwiki.apach=

In= stallation Planning

This section will prepare the user to install an ACE by providing the ne= cessary terminology and introducing the installation scenarios that will be= discussed.

Commo= n Terminology

=09Plugin - An archive file (.car or .war) that can be installed = into Geronimo to install a specific new service, such as ActiveMQ. For more= about plugins, or to look at available plugins, check out geronimoplugins.= com or
=09.CAR file (Configuration ARchive) - An archive file that stores G= eronimo-specific configurations, as well as the classes, libraries, web pag= es, and other information associated with an application.
=09.WAR file (Web ARchive)- An archive file that contains a web appl= ication, including all of its classes, libraries, HTML and JSP pages, and o= ther information. It can be deployed on any Java Enterprise compatible serv= let container.
=09ACE (Administration Console Extension) - An archive file (either = a .car or a .war), that includes Administration Console portlets. These por= tlets will be added to the Extensible Administration Console when the ACE i= s activated.
=09Extensible Administration console - A flexible version of Geronim= o's original administration console. Once installed it is available at http://localhost:8080/console, and includes some portlets that corr= espond to the currently activated services in Geronimo.
=09Service - a component or set of functionality for Geronimo - it m= ay be pre-installed, such as the Tomcat or Jetty web container, or it may b= e installed as a plugin
=09Minimal console - The administration console as it is first insta= lled - with only the services necessary for basic functionality
=09Portlet - A web user interface component that can be assembled to= gether with other similar components to create a web (portal) page. See t= he Portlet Specification JSR 168.

I= nstallation Scenarios

  1. Installing the extensible administration console into a Geronimo min= imal assembly
  2. =09
  3. Installing an ACE in the .war format from disk
  4. =09
  5. Installing an ACE in the .car format from an online repository
    3D""Which kind of file format do I want ?=
    • Need console extensions for a component you already have? If = you are planning to add Administration Console portlets for a component tha= t is already installed on your server, a .war file is simplest. A .war-form= at ACE has only the needed portlets, and is dependent on the component alre= ady being installed.
    • =09
    • Need the component and its extensions? If you need to install= both a new component and its associated Admin Console portlets, a .car fil= e is the right choice. This will look up and download all the necessary com= ponents and dependencies, and will also install the new ACE file. A .car fi= le can also be used if the component is already installed.
    • =09
    • Not sure? If you aren't sure that you have all the pre-requis= ites installed, a .car is the safest option. This will work regardless of w= hether the component is pre-installed or not.
    3D""What about installing a .car file fro= m disk?
    Unfortunately, it is not possible to install a .car file f= rom disk with the current Geronimo Administration Console. However you can = still use the "deploy install-plugin" tool from the command line. For more = information, read up on the deployer tool at

Installing the Extensible Administration Console

This section covers all the necessary steps to install the new Extensibl= e Administration Console on your Geronimo 2.1 Minimal Server. The Geronim= o 2.1 Java EE servers already have the console installed.

Prerequis= ites

  1. Geronimo 2.1 - Minimal is installed ("Little-G")
  2. =09
  3. No other Geronimo administration console is currently installed

Instal= l as a plugin

  1. Start Geronimo
  2. =09
  3. Use the deploy/list-plugins command to download and install the admi= n console from the online plugin catalog. Depending on the web container su= pport in your minimal server, choose:
    ./gsh deploy/list-plugins -r
    mo-2.1/ org.apache.geronimo.plugins/console-tomcat/2.1/car


    ./gsh deploy/list-plugins -r
    mo-2.1/ org.apache.geronimo.plugins/console-jetty/2.1/car
3D""Plugin Directory not updated with rel= eased plugins
The plugins directory (ht= tp:// has not yet been update= d with the released versions of the 2.1 plugins.

Once updated, we need to verify this (and subsequent) steps. There may b= e a dependency issue with Pluto...

Now you can point your web browser to http://localhost:8080/cons= ole and see the newly installed console.

Installing an ACE in .war format from an archive file=

An ACE in .war format will install only the console extension. Its pre-r= equisite must already be installed on your system. For example, if you were= installing a console extension to monitor a Derby database, Derby would ne= ed to be pre-installed on your server.

  1. You have a .war-format ACE to be installed.
  2. =09
  3. The Extensible Administration Console is already deployed, as descri= bed above.
  4. =09
  5. Any pre-requisites for the ACE are already installed.
  6. =09
  7. Open the administrative console in an internet browser at address http://localhost:8080/console.
  8. =09
  9. Select Deploy New on the left navigation bar.
  10. =09
  11. Click browse and navigate to the ACE file.
  12. =09
  13. Click Deploy.
  14. =09
  15. Refresh your browser. Your new component will show up on the left si= de navigation menu.

Installing an Administration= Console Extension in .car format from a repository

An ACE in the .car format installs a component and adds its configuratio= n portlets to the Extensible Administration Console.

  1. Your plugin provider already has specified a repository URL. For a l= arger selection of available plugins, checking i= s a good place to start.
  2. =09
  3. The Extensible Administration Console already installed, as describe= d in the previous section.

Instructio= ns

1. Access the Extensible Administration Console by pointing a web browse= r to the following address http://localhost:8080/console.
2. Select Plugins on the left navigation bar.
3. Under Install Geronimo Plugins, choose the plugin's repository address. =

3D""How do I choose the repository addres= s?
a. If the correct address does not appear in the Repository lis= t, select Add Repository.
b. In the New Repository textbox, enter the repository's address. Don't for= get to include the forward-slash ( / ) at the end of the address. Select A= dd Repository.
c. Select Update Repository List. The new address will now appear in the Re= pository list.

4. With the correct repository displayed in the Repository box, select S= how Plugins in selected repository.
5. Choose the plugin from the Available Plugins list by clicking directly o= n the plugin name.

3D""Where's the plugin I want?
a= . If the desired plugin is not a hyperlink, there are a number of potential= reasons:
i. If already installed is displayed next to the plugin name, the plugin ma= y already be installed on your server. Check for its name on the System Mod= ules tab to make sure it is running, and to start or uninstall it if necess= ary.
ii. If Not available is displayed next to the plugin name, it may require a= different version of Geronimo or a different web container (Tomcat or Jett= y). Select View Details for more information.
b. If the list of Available Plugins does not display, or the desired plugin= is not listed, you may have entered the wrong repository address. Try ente= ring it again. If problems continue, contact the plugin provider or email t= he user mailing list at

6. Select Install on the next screen if the information is correct, or R= eturn to return to the previous screen.
7. When the plugin installation is complete, refresh your browser. A new me= nu item will appear on the left. You can now configure this plugin's settin= gs from the newly installed portlets.


Installing the HelloWorld ACE (.war file)

This is an example of a simple ACE file. It is not attached to any compo= nents - it simply adds a new "Hello World" portlet to the Extensible Admini= stration Console.

1. Download example-extension-new.war example_extension_new.war
2. Access the Extensible Administration Console by pointing your web browse= r to http://localhost:8080/console.
3. Select Deploy New on the left navigation bar.
4. Click browse next to Archive and select the example-extension-new.war fi= le. Leave the Plan box blank, Start app after install checked, and Redeploy= application unchecked.

5. Click Install. Your new component will show up on the left side navigati= on menu.

Customiza= tion

Often times when a user installs Geronimo, the Administration Console wi= ll be the first place they go in order to configure their application serve= r. For this reason, it is important that the administration console be a fe= ature that provides users with the necessary functionality to easily manage= plugins and components of the server. The administration console allows = dynamic control over administration features. As such, it reflects the high= ly flexible and pluggable underlying architecture of Geronimo. What we have= done here is to provide a framework for plugin developers to include admin= istration console extensions for their plugins. The aim has been to provide= an easy and flexible solution with a simple architecture such that users o= f Geronimo can intuitively configure components, and developers can easily = expand upon the foundation laid out here.

The purpose of the remainder of this document is to provide developers w= ith the necessary instructions to utilize the infrastructure provided by th= e administration console to add customized console extensions for their Apa= che Geronimo plugins. The first portion will describe the plumbing of the s= ystem and how it works, and the latter portions will provide a solid exampl= e of what to expect in order to actually create your own functioning consol= e extension.

Architectu= re

Below we have a high level view of the interactions between a new plugin= and Pluto. This is essentially the 'plumbing' beneath the administration c= onsole.

<= img src=3D"/confluence/download/attachments/77481/HighLevelPluto.JPG?versio= n=3D2&modificationDate=3D1212661075000" style=3D"border: 0px solid blac= k" />
Figure 1 - High level view of Pluto's interaction with a deployable WAR


We have a WAR file containing portlet information and the definition of = an Administration Console Extension (ACE) GBean on the left. The ACE GBean = is the way in which we can invoke operations on Pluto (this will be covered= shortly).

The portlet container that we use is Apache Pluto 1.2. Pluto allows for = dynamically adding and removing pages and portlets without restarting the p= ortlet container. The approach is important from a user interface standpoin= t, because we are not forced into performance bottle necks by restarting se= rver components unnecessarily.

The dashed box around Pluto and its Pluto's API is intended to describe = the approach taken to decouple Pluto's implementation from our own. This is= a design decision to allow Pluto to be replaced by a different portlet eng= ine for possible future development.

Understanding Through Usecases

Let's dig into the architecture a bit more now. It should be noted that = the intended purpose of this architecture is to leverage Geronimo's flexibl= e nature, as well as have the actual administration console be reflective o= f Geronimo's pluggability. The infrastructure should be simple to understan= d and easy to build on top of.

The first use case we will look at will also be used to describe the ind= ividual pieces that make administration console function.

<= img src=3D"/confluence/download/attachments/77481/startcase.jpg?version=3D1= &modificationDate=3D1212661052000" style=3D"border: 0px solid black" />=
Figure 2 - Use case for adding features to the console

On the left, we begin with a simple Geronimo deployment plan (geronimo-w= eb.xml, for instance). This deployment plan is the same deployment plan inc= luded in any archive that you may wish to deploy into Geronimo. In this cas= e, the deployment plan includes the definition for a special AdminConsoleEx= tensionGBean. The specifics of what goes into an AdminConsoleExtensionGBean= will be described in more detail later.

On the right, we have Pluto. When Pluto starts, a PortalContainerService= sGBean is started. This is how we access Pluto. When we deploy our archive,= an AdminConsoleExtensionGBean containing portlet configuration information= is started (based on the configuration specified in the deployment descrip= tor). The AdminConsoleExtensionGBean is where the developer specifies the i= nformation for the portlets and pages they are adding to the administration= console.

The AdminConsoleExtensionGBean implements GBeanLifecycle. When the Admin= ConsoleExtensionGBean is started, it asks the kernel for the PortalContaine= rServicesGBean (1). The AdminConsoleExtensionGBean gets the service (2) - n= ow the AdminConsoleExtensionGBean can access Pluto through its API. We want= to add a portlet to our administration console, so we invoke Pluto's addPo= rtlet method, which will update Pluto's internal model.

In the above image, each of the grayed out GBeans is an AdminConsoleExte= nsionGBean instantiated by a deployment descriptor. Each AdminConsoleExtens= ionGBean modifies or adds exactly one page in the administration console. T= his essentially means that portlets may be added to an existing page by spe= cifying the name of an existing page, or a separate page can be created if = one with the specified name does not exist.

A deployment plan may also include definitions for multiple AdminConsole= ExtensionGBeans. This means that a deployment plan, if it chooses to do so,= may add as many pages to the console as it wants to.

<= img src=3D"/confluence/download/attachments/77481/stopcase.jpg?version=3D1&= amp;modificationDate=3D1212661052000" style=3D"border: 0px solid black" /><= /span>
Figure 3 - Use case for removing features from the console

Removing pages (Figure 3) from the console follows a similar process. Be= cause the AdminConsoleExtensionGBean implements the GBeanLifecycle, when th= e installed component is stopped, its AdminConsoleExtensionGBean will also = be stopped. When this happens, we once more ask the kernel for the PortalCo= ntainerServiceGBean, which is used to call removePortlet on Pluto through i= ts API. From the view of the administration console, the user will see the = page has disappeared from the navigation menu (Figure 4). If the user start= s the component again, the GBeanLifecycle's doStart calls addPortlet on Plu= to Container, and the administration console extension reappears on the nav= igation menu (Figure 5).

<= img src=3D"/confluence/download/attachments/77481/noext.jpg?version=3D1&= ;modificationDate=3D1212661052000" style=3D"border: 0px solid black" />
Figure 4 - We see no administration extensions to the left for the stopped = component

Figure 5 - We see the administration feature for the HelloWorldPortlet appe= ar in the navigation

Class/Dependency Structure

3D""Dependency relationship of the pieces
  • PortalContainer =09
    • PortalContainerServiceGBean =09=09
      • AdminConsoleExtensionGBean
      • =09=09
    • =09=09
    • Pluto Portal =09=09
      • Administration Console =09=09=09
        • New Portlet
        • =09=09=09
      • =09=09
    • =09

The PortalContainer is the base requirement for the administration conso= le. The Pluto Portal and the PortalContainerServiceGBean are the base requi= rements to install anything into the framework of the console. The administ= ration console and the AdminConsoleExtensionGBean depends on the PortalCont= ainerServiceGBean and the Pluto Portal. In order to add new console extensi= ons, all of the described components must be in place.

The key here is that the requirements for adding a console extention is = an AdminConsoleExtensionGBean and the New Portlet files. This means that th= e required dependencies that need to be specified in the deployment descrip= tor are the Administration Console and the PortalContainerServicesGBean.

How to Develop an Administrator Console Exten= sion (ACE)

In order to develop your own console extension, you will need to perform= the following steps:

  1. Create a portlet
  2. =09
  3. Add an AdminConsoleExtensionGBean to the deployment plan
  4. =09
  5. Build the WAR or CAR
  6. =09
  7. Deploy the application
  8. =09
  9. Verify the installation

Each step is further detailed below.

= Different ways of structuring

The whole concept behind creating an ACE for Geronimo is that you are ad= ding an extension in the form of portlets to the administrator console. Yo= u can package this however you like. Some options are as follows:

  1. Your portlets
  2. =09
  3. Your portlets + your related component
  4. =09
  5. Your portlets which declares a dependency on your related component<= /li>

Create a= portlet

In their most fundamental state, an ACE defines where to place new/old p= ortlets in your console. Portlets are the fundamental building block of th= e administrator console. We are using Pluto 2.x as our portal engine since= it closely conforms to JSR 168. We will not go in= to the details of how to develop portlets since you can find many tutorials= and tools for this such as Portlet Plugin for E= clipse. You will need the appropriate "web.xml" and "portlet.xml" file= s defined. As a simple example, refer to the HelloWorldPortlet defined at the end of = this section.

Add an AdminConsoleExtensionGBean

To add an AdminConsoleExtensionGBean to your deployable archive file, yo= u need to include the following to your "geronimo-web.xml" deployment plan:=

  1. Declare a dependency on the "pluto-portal"
  2. =09
  3. Define an AdminConsoleExtensionGBean
    <gbean name=3D"examp=
    le" class=3D"org.apache.geronimo.pluto.Ad=
        <attribute name=3D"pageTitle">Testing</attribu=
        <attribute name=3D"portletContext">/HelloWorldPortlet</attribute>
        <attribute name=3D"portletList">[HelloWorldPortlet]</attribute>

    where the attributes are defined as follows:

  • pageTitle: The name of the page to add these portlets to (new or exi= sting)
  • =09
  • portletContext: The context of where the portlets are installed. =09
  • portletList: A comma-delimited list of the portlets to be added to t= his page.
Sample geronimo-web.xml
<web-app xmlns=3D"ht=
            <dependency> <!-- Put a dependancy on the =
hosting portal (pluto) -->
    <!-- This is w=
here the files are accessed from. (aka - portletContext) -->
span class=3D"code-tag"></context-root>
    <!-- Start off=
 a ACEGBean, this is the lifecycle for the portlet -->
    <gbean name=3D"P=
lutoTest" class=3D"
        <attribute name=3D"pageTitle">Hello</attri=
        <attribute name=3D"portletContext">/HelloWorldPortlet</attribute>
        <attribute name=3D"portletList">[HelloWorldPortlet]</attribute>
        <reference name=3D"PortalContainerServices">

Putti= ng it together

Add your modified "geronimo-web.xml" deployment plan to your WAR or CAR = in the WEB-INF folder. Also, if you are including portlets, your archive f= ile should contain the appropriate class files as well as the "web.xml" and= "portlet.xml" files.

3D""What is an example structure for a si= mple war?
  • HelloWorldPortlet.war =09
    • WEB-INF/ =09=09
      • classes/ =09=09=09
        • (portlet class files)
        • =09=09=09
      • =09=09=09
      • geronimo-web.xml
      • =09=09=09
      • portlet.xml
      • =09=09=09
      • web.xml
      • =09=09
    • =09

Deploying the application

Deploy the archive as you normally would either using the "deploy" comma= nd or by using the Administrator Console's "Deploy New" or "Plugins".

  1. Command Line: <geronimo bin folder>/deploy.bat= deploy <path to war>
    cd c:/g/target/geronimo-tomcat6-minimal-2.0-SNAPSHOT/bin/ deploy.bat deploy c:/HelloWorldPortlet.war
  2. =09
  3. Using the Admin Console:

    <= img src=3D"/confluence/download/attachments/77481/InstApp.jpg?version=3D1&a= mp;modificationDate=3D1212661112000" style=3D"border: 0px solid black" />

V= erifying installation

Go to http://localhost:8080/console/ to verify that the por= tlets were added to the correct page. (You may need to refresh the browser= if you deployed from the command line.)

Sample = Extension

This is a working simple example of an Administration Console Extension.=
Download the example WAR=

package org.apache.pluto.examples;


import javax.portlet.GenericPortlet;
import javax.portlet.PortletException;
import javax.portlet.RenderRequest;
import javax.portlet.RenderResponse;

 * A very simple portlet example.
 * This portlet displays 'Hello World' to the end user
public class HelloWorldPortlet extends GenericPortlet {

    // This function is called when a user req=
uests to view this portlet (by
    // navigating to the webpage in Plu=
    public void doView(RenderReq=
uest request, RenderResponse response)
            throws PortletException, IO=
Exception {

        // Set the response to read HTML

        // Required call for use of getWriter() and getPortletOutputStream()
        PrintWriter out =3D response.getWriter();
        // Write content to the portlet
        out.println("<h1>Hello Worl=