Page History

...

Plugin - 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 geronimoplugincentral.org.
.CAR file (Configuration ARchive) - An archive file that stores Geronimo-specific configurations, as well as the classes, libraries, web pages, and other information associated with an application.
.WAR file (Web ARchive)- An archive file that contains a web application, including all of its classes, libraries, HTML and JSP pages, and other information. It can be deployed on any Java Enterprise compatible servlet container.
ACE (Administration Console Extension) - An archive file (either a .car or a .war), that includes Administration Console portlets. These portlets will be added to the Extensible Administration Console when the ACE is activated.
Extensible Administration console - A flexible version of Geronimo's original administration console. Once installed it is available at http://localhost:8080/console^{Image Removed}, and includes some portlets that correspond to the currently activated services in Geronimo.
Service - a component or set of functionality for Geronimo - it may be pre-installed, such as the Tomcat or Jetty web container, or it may be installed as a plugin
Minimal console - The administration console as it is first installed - with only the services necessary for basic functionality
Portlet - A web user interface component that can be assembled together with other similar components to create a web (portal) page. See the Portlet Specification JSR 168.

...

...

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.

{center}
!HighLevelPluto.jpg!
Figure 1 - High level view of Pluto's interaction with a deployable WAR
{center}

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 first use case we will look at will also be used to describe the individual pieces that make administration console function.

{center}
!startcase.jpg!
Figure 2 - Use case for adding features to the console
{center}

On the left, we begin with a simple 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 AdminConsoleExtensionGBean. The specifics of what goes into an AdminConsoleExtensionGBean will be described in more detail later.

...

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

{center}
!stopcase.jpg!
Figure 3 - Use case for removing features from the console
{center}

Removing pages (Figure 3) from the console follows Removing pages (Figure 3) from the console follows a similar process. Because the AdminConsoleExtensionGBean implements the GBeanLifecycle, when the installed component is stopped, its AdminConsoleExtensionGBean will also be stopped. When this happens, we once more ask the kernel for the PortalContainerServiceGBean, 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).Container, and the administration console extension reappears on the navigation menu (Figure 5).

{center}
!noext.jpg!
Figure 4 - We see no administration extensions to the left for the stopped component


!withext.jpg!
Figure 5 - We see the administration feature for the HelloWorldPortlet appear in the navigation
{center}

Class/Dependency Structure

...

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

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

2. Define an AdminConsoleExtensionGBean

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

   where the attributes are defined as follows:

• pageTitle: The name of the page to add these portlets to (new or existing)
• portletContext: The context of where the portlets are installed.
• portletList: A comma-delimited list of the portlets to be added to this page.

<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.2">
    <environment>
        <moduleId>
            <groupId>org.apache.geronimo.portals</groupId>
            <artifactId>pluto-example</artifactId>
            <version>1.0-SNAPSHOT</version>
            <type>war</type>
        </moduleId>
        
        <dependencies>
            <dependency> <!-- Put a dependancy on the hosting portal (pluto) -->
                <groupId>org.apache.geronimo.plugins</groupId>
                <artifactId>pluto-support</artifactId>
            </dependency>
        </dependencies>
    </environment>
    
    <!-- This is where the files are accessed from. (aka - portletContext) -->
    <context-root>/HelloWorldPortlet</context-root>
    
    <!-- Start off a ACEGBean, this is the lifecycle for the portlet -->
    <gbean name="PlutoTest" class="org.apache.geronimo.pluto.AdminConsoleExtensionGBean">
        <attribute name="pageTitle">Hello</attribute>
        <attribute name="portletContext">/HelloWorldPortlet</attribute>
        <attribute name="portletList">[HelloWorldPortlet]</attribute>
        <reference name="PortalContainerServices">
            <name>PlutoPortalServices</name>
        </reference>
    </gbean>
</web-app>

...

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:

   Wiki Markup
   {center} !InstApp.jpg! {center}

Verifying installation

Go to http://localhost:8080/console/^{Image Removed} 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.)

...

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

package org.apache.pluto.examples;

import java.io.IOException; 
import java.io.PrintWriter;

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 requests to view this portlet (by
    // navigating to the webpage in Pluto)
    public void doView(RenderRequest request, RenderResponse response)
            throws PortletException, IOException {

        // Set the response to read HTML
        response.setContentType("text/html;charset=UTF-8");

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