Page History

...

1. Install the Extensible Administration Console into a Geronimo minimal Framework assembly (Tomcat or Jetty)
2. Download and install an Administrative Console Extension

...

The reader should be familiar with the Geronimo application server and its applications. The reader should also be familiar with the basics of Geronimo's plugin framework. For more information about the architecture, this guide may also be a valuable resource: http://media.wiley.com/product_ancillary/31/04717854/DOWNLOAD/Pro_Apache_Geronimo_ch17.pdf.
The reader should have Apache Geronimo 23.1 Minimal ("Little-G") 0 Minimal+Web Container assembly installed and running, with either Tomcat6 Tomcat7 or Jetty6 Jetty8 as the web container. The Java EE 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.apache.org/GMOxDOC22GMOxDOC30/installation.html.

Installation Planning

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

...

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, 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 168286.

Installation Scenarios

1. Installing the extensible administration console into a Geronimo minimal assembly
2. Installing an ACE in the .war format from disk
3. Installing an ACE in the .car format from an online repository

   Note
   title 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 that is already installed on your server, a .war file is simplest. A .war-format ACE has only the needed portlets, and is dependent on the component already being installed. Need the component and its extensions? If you need to install both a new component and its associated Admin Console portlets, a .car file is the right choice. This will look up and download all the necessary components and dependencies, and will also install the new ACE file. A .car file can also be used if the component is already installed. Not sure? If you aren't sure that you have all the pre-requisites installed, a .car is the safest option. This will work regardless of whether the component is pre-installed or not.

   Note
   title What about installing a .car file from disk?
   Unfortunately, it is not possible to install a .car file from 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 http://cwiki.apache.org/GMOxDOC11/deployer-tool.html

...

This section covers all the necessary steps to install the new Extensible Administration Console on your Geronimo 23.1 0 Minimal Server. The Geronimo 23.1 0 Java EE servers already have the console installed.

Prerequisites

1. Geronimo 23.1 0 - Minimal is installed ("Little-G")
2. No other Geronimo administration console is currently installed

Install as a plugin

1. Start Geronimo
2. Use the deploy/:list-plugins command to download and install the admin administration console from the online plugin catalogrepository. Depending on the web container support in your minimal server, choose:

   No Format
   ./gsh deploy/:list-plugins -r http://geronimo.apache.org/plugins/geronimo-23.10/ org.apache.geronimo.plugins/console-tomcat/23.10/car

   or

   No Format
   ./gsh deploy/:list-plugins -r http://geronimo.apache.org/plugins/geronimo-23.10/ org.apache.geronimo.plugins/console-jetty/23.1/car

...

...

1. 0/car

Once updated, we need to verify this (and subsequent) steps.

...

...

...

...

...

...

...

...

...

...

1. With the correct repository displayed in the Repository box, select Show Plugins in selected repository.

...

1. Choose the plugin from the Available Plugins list by clicking directly on the plugin name.

...

...

1. • If the Installable field of the desired plugin is

...

1. • marked as a red-cross, the plugin may already be installed on your server. Check for its name on the System Modules tab to make sure it is running, and to start or uninstall it if necessary.

...

1. • If

...

1. • the list of Available Plugins does not display, or the desired plugin is not listed, you may have entered the wrong repository address. Try entering it again. If problems continue, contact the plugin provider or email the user mailing list at user@geronimo.apache.org.
     6. Select

...

1. • the plugins to be added and then click *Install at the bottom of the page.
     7. When the plugin installation is complete, refresh your browser. A new menu item will appear on the left. You can now configure this plugin's settings from the newly installed portlets.

Examples

Installing the HelloWorld ACE (.war file)

...

On the left, we begin with a simple Geronimo deployment plan (, for example, 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.

On the right, we have Pluto. When Pluto starts, a PortalContainerServicesGBean 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 descriptor). The AdminConsoleExtensionGBean is where the developer specifies the information for the portlets and pages they are adding to the administration console.

The AdminConsoleExtensionGBean implements GBeanLifecycle. When the AdminConsoleExtensionGBean is started, it asks the kernel for the PortalContainerServicesGBean (1). The AdminConsoleExtensionGBean gets the service (2) - now the 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 AdminConsoleExtensionGBean instantiated by a deployment descriptor. Each 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 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.

...

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 dostart() method of GBeanLifecycle calls{{addPortlet()}} method on Pluto Container, and the administration console extension reappears on the navigation menu (Figure 5).

...

The PortalContainer is the base requirement for the administration console. The Pluto Portal and the PortalContainerServiceGBean are the base requirements to install anything into the framework of the console. The administration console and the AdminConsoleExtensionGBean depends on the 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 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 PortalContainerServicesGBean.

How to Develop an Administrator Console Extension (ACE)

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

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

...

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 286 [link to JSR 1682868]. 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 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" porta plugin

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

2. Define an AdminConsoleExtensionGBean

   Code Block
   XML XML borderStyle solid
   <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 is the name of the page to add these portlets to (new or existing)
• portletContext: The is the context of where the portlets are installed.
• portletList: A is a comma-delimited list of the portlets to be added to this page.

...

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.

HelloWorldPortlet.war
{indent:1} |-

WEB-INF/

{indent}
{indent:2} |-classes/{indent}
{indent:3} |-(portlet class files){indent}
{indeng:2} |-geronimo-web.xml{indent}
{indent:2} |-portlet.xml{indent}
{indent:2} |-web.xml{indent}

Deploying the application

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

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

   No Format
   deploy:deploy c:/HelloWorldPortlet.war

2. Using the Admin Console:

   Center

...

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

Sample Extension

...