...

This document is organized in the following sections:

Architecture

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

...

We have a WAR file containing portlet information and the definition of an ACE Gbean 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 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 engine 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 flexible nature, as well as have the actual administration console be reflective of Geronimo's pluggability. The infrastructure should be simple to understand and easy to build on top of.

...

On the left, we begin with a simple Geronimo deployment plan (geronimo-web.xml, for instance). This deployment plan is the same deployment plan included in any archive that you may wish to deploy into Geronimo. In this case, the deployment plan includes the definition for a special ACEGBeanAdminConsoleExtensionGBean. The specifics of what goes into an ACEGBean AdminConsoleExtensionGBean will be described in more detail later.

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

The ACEGbean AdminConsoleExtensionGBean implements GBeanLifecycle. When the ACEGBean AdminConsoleExtensionGBean is started, it asks the kernel for the PlutoContainerServicesGBean PortalContainerServicesGBean (1). The ACEGBean AdminConsoleExtensionGBean gets the service (2) - now the ACEGBean AdminConsoleExtensionGBean can access Pluto through its API. We want to add a portlet to our administration console, so we invoke Pluto's addPortlet method, which will update Pluto's internal model.

In the above image, each of the grayed out GBeans is an ACEGBean AdminConsoleExtensionGBean instantiated by a deployment descriptor. Each ACEGbean AdminConsoleExtensionGBean modifies or adds exactly one page in the administration console. This essentially means that portlets may be added to an existing page by specifying 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 ACEGBeansAdminConsoleExtensionGBeans. This means that a deployment plan, if it chooses to do so, may add as many pages to the console as it wants to.

...

Removing pages (Figure 3) from the console follows a similar process. Because the ACEGbean AdminConsoleExtensionGBean implements the GBeanLifecycle, when the installed component is stopped, its ACEGBean AdminConsoleExtensionGBean will also be stopped. When this happens, we once more ask the kernel for the PlutoContainerServiceGBeanPortalContainerServiceGBean, which is used to call removePortlet on Pluto through its 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 starts the component again, the GBeanLifecycle's doStart calls addPortlet on Pluto Container, and the administration console extension reappears on the navigation menu (Figure 5).

Class/Dependency Structure

The PlutoContainer PortalContainer is the base requirement for the administration console. The Pluto Portal and the PlutoContainerServiceGBean PortalContainerServiceGBean are the base requirements to install anything into the framework of the console. The administration console and the ACEGBean AdminConsoleExtensionGBean depends on the PlutoContainerServiceGBean PortalContainerServiceGBean and the Pluto Portal. In order to add new console extensions, all of the described components must be in place.

The key here is that the requirements for adding a console extention is an ACEGBean AdminConsoleExtensionGBean and the New Portlet files. This means that the required dependencies that need to be specified in the deployment descriptor are the Administration Console and the PlutoContainerServicesGBeanPortalContainerServicesGBean.

How to Develop an Administrator Console Extension (ACE)

TODO: An intro should go here

Different ways of structuring

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

1. Your portlets
2. Your portlets + your related component
3. Your portlets which declares a dependency on your related component

Create a portlet

In their most fundamental state, an ACE defines where to place new/old portlets in your console. Portlets 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 [link to JSR 168]. We will not go into the details of how to develop portlets since you can find many tutorials and tools that are much better at this. [many tutorial links here]. You will need the appropriate "web.xml" and "portlet.xml" files defined. As a simple example, refer to the [link to section] HelloWorldPortlet defined at the end of this section.

Add an

...

AdminConsoleExtensionGBean

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

1. Declare a dependency on the "pluto-portal"

   Code Block
   XML XML borderStyle solid
   <dependencies> ... <dependency> <groupId>org.apache.geronimo.portals<plugins</groupId> <artifactId>pluto-portal<support</artifactId> </dependency> </dependencies>

2. Define an ACEGBean AdminConsoleExtensionGBean

   Code Block
   XML XML borderStyle solid
   <gbean name="example" class="org.apache.geronimo.pluto.ACEGBeanAdminConsoleExtensionGBean"> <attribute name="pageTitle">Testing</attribute> <attribute name="portletContext">/HelloWorldPortlet</attribute> <attribute name="portletList">[HelloWorldPortlet]</attribute> </gbean>

   where the attributes are defined as follows:

...

<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.2">
    <environment>
        <moduleId>
            <groupId>org.apache.geronimo.portals<plugins</groupId>
            <artifactId>pluto-example</artifactId>
            <version>1.0-SNAPSHOT</version>
            <type>war</type>
        </moduleId>
        
        <dependencies>
            <dependency>
                <groupId>org.apache.geronimo.portals<plugins</groupId>
                <artifactId>pluto-container<support</artifactId>
            </dependency>
        </dependencies>
    </environment>
    
    <context-root>/HelloWorldPortlet</context-root>

    <gbean name="PlutoTest" class="org.apache.geronimo.pluto.ACEGBeanAdminConsoleExtensionGBean">
        <attribute name="pageTitle">Hello</attribute>
        <attribute name="portletContext">/HelloWorldPortlet</attribute>
        <attribute name="portletList">[HelloWorldPortlet]</attribute>
    </gbean>
</web-app>

Putting 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 file should contain the appropriate class files as well as the "web.xml" and "portlet.xml" files.

Deploying the application

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

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

   Center

Verifying installation

Go to http://localhost:8080/pluto/ to verify that the portlets 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

...