|
|
| Home > Documentation > Configuring and administering > Extensible Administration Console |
This document contains the following sections:
The Extensible Administration Console is a new Administration Console designed to mirror the flexibility of Geronimo's architecture. While the previous console was static, allowing configuration only for pre-defined components, the new Extensible Console changes dynamically with the components installed on your server.
This framework allows Geronimo plugin developers to package extensions to the Administration Console (called ACEs) with their components. On installation of a plugin, this new content will automatically be added to the Extensible Administration Console, so that the user can manage all of the configuration and tools from one place.
After reading this document, a Geronimo user will be able to
This document covers installing Geronimo's Administration Console into a Geronimo minimal assembly and the process to install an ACE plugin. For more information about the underlying architecture and ACE development, see the Administration Console Extension Developer's Guide.
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 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 3.0 Minimal+Web Container assembly installed and running, with either Tomcat7 or 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/GMOxDOC30/installation.html.
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 286.
Which kind of file format do I want ?
What about installing a .car file from disk?
You can use the deploy install-plugin tool from the command line. For more information, see https://cwiki.apache.org/GMOxDOC30/deploy.html
This section covers all the necessary steps to install the new Extensible Administration Console on your Geronimo 3.0 Minimal Server. The Geronimo 3.0 Java EE servers already have the console installed.
deploy list-plugins -r http://geronimo.apache.org/plugins/geronimo-3.0/ org.apache.geronimo.plugins/console-tomcat/3.0/car
deploy list-plugins -r http://geronimo.apache.org/plugins/geronimo-3.0/ org.apache.geronimo.plugins/console-jetty/3.0/car
Once updated, we need to verify this (and subsequent) steps.
Now you can point your web browser to http://localhost:8080/console and see the newly installed console.
An ACE in .war format will install only the console extension. Its pre-requisite must already be installed on your system. For example, if you were installing a console extension to monitor a Derby database, Derby would need to be pre-installed on your server.
Prerequisites
An ACE in the .car format installs a component and adds its configuration portlets to the Extensible Administration Console.
Prerequisites
This is an example of a simple ACE file. It is not attached to any components - it simply adds a new "Hello World" portlet to the Extensible Administration Console.
1. Download example-extension-new.war example_extension_new.war
2. Access the Extensible Administration Console by pointing your web browser 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 file. 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 navigation menu.
Often times when a user installs Geronimo, the Administration Console will be the first place they go in order to configure their application server. For this reason, it is important that the administration console be a feature 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 highly flexible and pluggable underlying architecture of Geronimo. What we have done here is to provide a framework for plugin developers to include administration console extensions for their plugins. The aim has been to provide an easy and flexible solution with a simple architecture such that users of 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 with the necessary instructions to utilize the infrastructure provided by the administration console to add customized console extensions for their Apache Geronimo plugins. The first portion will describe the plumbing of the system and how it works, and the latter portions will provide a solid example of what to expect in order to actually create your own functioning console extension.
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 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 portlet container. The approach is important from a user interface standpoint, because we are not forced into performance bottle necks by restarting server 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 engine for possible future development.
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.
The first use case we will look at will also be used to describe the individual pieces that make administration console function.
On the left, we begin with a simple Geronimo deployment plan, for example, geronimo-web.xml. 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 dostart() method of GBeanLifecycle calls{{addPortlet()}} method on Pluto Container, and the administration console extension reappears on the navigation menu (Figure 5).
Figure 4 - We see no administration extensions to the left for the stopped component
Figure 5 - We see the administration feature for the HelloWorldPortlet appear in the navigation
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.
In order to develop your own console extension, you will need to perform the following steps:
AdminConsoleExtensionGBean to the deployment planEach step is further detailed below.
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:
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 286 [link to JSR 2868]. 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. You will need the appropriate web.xml and portlet.xml files defined. As a simple example, refer to the HelloWorldPortlet defined at the end of this section.
AdminConsoleExtensionGBeanTo add an AdminConsoleExtensionGBean to your deployable archive file, you need to include the following to your geronimo-web.xml deployment plan:
pluto-porta plugin
<dependencies>
...
<dependency>
<groupId>org.apache.geronimo.plugins</groupId>
<artifactId>pluto-support</artifactId>
</dependency>
</dependencies>
AdminConsoleExtensionGBean
<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>
<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>
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
Deploy the archive as you normally would either using the deploy command or by using Deployer portlet from the Administration Console.
deploy deploy c:/HelloWorldPortlet.war
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.)
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>");
}
}
Bookmark this on Delicious
Digg this
|
Privacy Policy - Copyright © 2003-2013, The Apache Software Foundation, Licensed under ASL 2.0. |