geronimo-scm mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Geronimo v2.1 > Extensible Administration Console
Date Mon, 08 Nov 2010 06:53:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1810/9/1/_/styles/combined.css?spaceKey=GMOxDOC21&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/GMOxDOC21/Extensible+Administration+Console">Extensible
Administration Console</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~maojia508">maojia</a>
    </h4>
        <br/>
                         <h4>Changes (1)</h4>
                                 
    
<div id="page-diffs">
            <table class="diff" cellpadding="0" cellspacing="0">
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" > <br>h2. Create a portlet <br></td></tr>
            <tr><td class="diff-changed-lines" >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 <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">168|http://download.oracle.com/docs/cd/B14099_12/portal.1014/b14135/toc.htm].</span>
<span class="diff-added-words"style="background-color: #dfd;">168|http://www.jcp.org/en/jsr/detail?id=168].</span>
 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 Plugin for Eclipse|http://sourceforge.net/projects/portlet-eclipse/].
 You will need the appropriate &quot;web.xml&quot; and &quot;portlet.xml&quot;
files defined. As a simple example, refer to the [HelloWorldPortlet|#Sample Extension] defined
at the end of this section. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>h2. Add an AdminConsoleExtensionGBean
<br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
        </table>
</div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <p>This document contains the following sections:</p>
<div>
<ul>
    <li><a href='#ExtensibleAdministrationConsole-Introduction'>Introduction</a></li>
<ul>
    <li><a href='#ExtensibleAdministrationConsole-Objective'>Objective</a></li>
    <li><a href='#ExtensibleAdministrationConsole-Scope'>Scope</a></li>
    <li><a href='#ExtensibleAdministrationConsole-Whoshouldreadthisdocument'>Who
should read this document</a></li>
    <li><a href='#ExtensibleAdministrationConsole-Assumptions'>Assumptions</a></li>
</ul>
    <li><a href='#ExtensibleAdministrationConsole-InstallationPlanning'>Installation
Planning</a></li>
<ul>
    <li><a href='#ExtensibleAdministrationConsole-CommonTerminology'>Common Terminology</a></li>
    <li><a href='#ExtensibleAdministrationConsole-InstallationScenarios'>Installation
Scenarios</a></li>
</ul>
    <li><a href='#ExtensibleAdministrationConsole-InstallingtheExtensibleAdministrationConsole'>Installing
the Extensible Administration Console</a></li>
<ul>
    <li><a href='#ExtensibleAdministrationConsole-Prerequisites'>Prerequisites</a></li>
    <li><a href='#ExtensibleAdministrationConsole-Installasaplugin'>Install as
a plugin</a></li>
</ul>
    <li><a href='#ExtensibleAdministrationConsole-InstallinganACEin.warformatfromanarchivefile'>Installing
an ACE in .war format from an archive file</a></li>
    <li><a href='#ExtensibleAdministrationConsole-InstallinganAdministrationConsoleExtensionin.carformatfromarepository'>Installing
an Administration Console Extension in .car format from a repository</a></li>
<ul>
    <li><a href='#ExtensibleAdministrationConsole-Instructions'>Instructions</a></li>
</ul>
    <li><a href='#ExtensibleAdministrationConsole-Examples'>Examples</a></li>
<ul>
    <li><a href='#ExtensibleAdministrationConsole-InstallingtheHelloWorldACE%28.warfile%29'>Installing
the HelloWorld ACE (.war file)</a></li>
</ul>
    <li><a href='#ExtensibleAdministrationConsole-Customization'>Customization</a></li>
    <li><a href='#ExtensibleAdministrationConsole-Architecture'>Architecture</a></li>
<ul>
    <li><a href='#ExtensibleAdministrationConsole-UnderstandingThroughUsecases'>Understanding
Through Usecases</a></li>
</ul>
    <li><a href='#ExtensibleAdministrationConsole-Class%2FDependencyStructure'>Class/Dependency
Structure</a></li>
    <li><a href='#ExtensibleAdministrationConsole-HowtoDevelopanAdministratorConsoleExtension%28ACE%29'>How
to Develop an Administrator Console Extension (ACE)</a></li>
<ul>
    <li><a href='#ExtensibleAdministrationConsole-Differentwaysofstructuring'>Different
ways of structuring</a></li>
    <li><a href='#ExtensibleAdministrationConsole-Createaportlet'>Create a portlet</a></li>
    <li><a href='#ExtensibleAdministrationConsole-AddanAdminConsoleExtensionGBean'>Add
an AdminConsoleExtensionGBean</a></li>
    <li><a href='#ExtensibleAdministrationConsole-Puttingittogether'>Putting it
together</a></li>
    <li><a href='#ExtensibleAdministrationConsole-Deployingtheapplication'>Deploying
the application</a></li>
    <li><a href='#ExtensibleAdministrationConsole-Verifyinginstallation'>Verifying
installation</a></li>
</ul>
    <li><a href='#ExtensibleAdministrationConsole-SampleExtension'>Sample Extension</a></li>
</ul></div>

<h1><a name="ExtensibleAdministrationConsole-Introduction"></a>Introduction</h1>

<p>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.</p>

<p>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.</p>

<h2><a name="ExtensibleAdministrationConsole-Objective"></a>Objective</h2>

<p>After reading this document, a Geronimo user will be able to</p>
<ol>
	<li>Install the Extensible Administration Console into a Geronimo minimal assembly
(Tomcat or Jetty)</li>
	<li>Download and install an Administrative Console Extension</li>
</ol>


<h2><a name="ExtensibleAdministrationConsole-Scope"></a>Scope</h2>

<p>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.</p>

<h2><a name="ExtensibleAdministrationConsole-Whoshouldreadthisdocument"></a>Who
should read this document</h2>

<p>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.</p>

<h2><a name="ExtensibleAdministrationConsole-Assumptions"></a>Assumptions</h2>

<p>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: <a href="http://media.wiley.com/product_ancillary/31/04717854/DOWNLOAD/Pro_Apache_Geronimo_ch17.pdf"
class="external-link" rel="nofollow">http://media.wiley.com/product_ancillary/31/04717854/DOWNLOAD/Pro_Apache_Geronimo_ch17.pdf</a>.<br/>
The reader should have Apache Geronimo 2.1 Minimal ("Little-G") installed and running, with
either Tomcat6 or Jetty6 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: <a href="http://cwiki.apache.org/GMOxDOC21/installation.html"
class="external-link" rel="nofollow">http://cwiki.apache.org/GMOxDOC21/installation.html</a>.</p>

<h1><a name="ExtensibleAdministrationConsole-InstallationPlanning"></a>Installation
Planning</h1>

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

<h2><a name="ExtensibleAdministrationConsole-CommonTerminology"></a>Common
Terminology</h2>
<p>	<b>Plugin</b> - 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.<br/>
	<b>.CAR file</b> (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.<br/>
	<b>.WAR file</b> (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.<br/>
	<b>ACE</b> (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.<br/>
	<b>Extensible Administration console</b> - A flexible version of Geronimo's original
administration console. Once installed it is available at <a href="http://localhost:8080/console"
class="external-link" rel="nofollow">http://localhost:8080/console</a>, and includes
some portlets that correspond to the currently activated services in Geronimo. <br/>
	<b>Service</b> - 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<br/>
	<b>Minimal console</b> - The administration console as it is first installed
- with only the services necessary for basic functionality<br/>
	<b>Portlet</b> - 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.</p>

<h2><a name="ExtensibleAdministrationConsole-InstallationScenarios"></a>Installation
Scenarios</h2>

<ol>
	<li>Installing the extensible administration console into a Geronimo minimal assembly</li>
	<li>Installing an ACE in the .war format from disk</li>
	<li>Installing an ACE in the .car format from an online repository
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/warning.gif" width="16" height="16"
align="absmiddle" alt="" border="0"></td><td><b>Which kind of file format
do I want ?</b><br /><ul>
	<li><b>Need console extensions for a component you already have?</b> 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.</li>
	<li><b>Need the component and its extensions?</b> 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.</li>
	<li><b>Not sure?</b> 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.</li>
</ul>
</td></tr></table></div>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/warning.gif" width="16" height="16"
align="absmiddle" alt="" border="0"></td><td><b>What about installing
a .car file from disk?</b><br />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 <a href="http://cwiki.apache.org/GMOxDOC11/deployer-tool.html"
class="external-link" rel="nofollow">http://cwiki.apache.org/GMOxDOC11/deployer-tool.html</a></td></tr></table></div></li>
</ol>


<h1><a name="ExtensibleAdministrationConsole-InstallingtheExtensibleAdministrationConsole"></a>Installing
the Extensible Administration Console</h1>

<p>This section covers all the necessary steps to install the new Extensible Administration
Console on your Geronimo 2.1 Minimal Server.   The Geronimo 2.1 Java EE servers already have
the console installed.</p>

<h2><a name="ExtensibleAdministrationConsole-Prerequisites"></a>Prerequisites</h2>

<ol>
	<li>Geronimo 2.1 - Minimal is installed ("Little-G")</li>
	<li>No other Geronimo administration console is currently installed</li>
</ol>


<h2><a name="ExtensibleAdministrationConsole-Installasaplugin"></a>Install
as a plugin</h2>

<ol>
	<li>Start Geronimo</li>
	<li>Use the deploy/list-plugins command to download and install the admin console from
the online plugin catalog. Depending on the web container support in your minimal server,
choose:
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>./gsh deploy/list-plugins -r http://geronimo.apache.org/plugins/geronimo-2.1/ org.apache.geronimo.plugins/console-tomcat/2.1/car</pre>
</div></div>
<p>or</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>./gsh deploy/list-plugins -r http://geronimo.apache.org/plugins/geronimo-2.1/ org.apache.geronimo.plugins/console-jetty/2.1/car</pre>
</div></div></li>
</ol>


<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/warning.gif" width="16" height="16"
align="absmiddle" alt="" border="0"></td><td><b>Plugin Directory not
updated with released plugins</b><br />The plugins directory (<a href="http://geronimo.apache.org/plugins/geronimo-2.1/"
class="external-link" rel="nofollow">http://geronimo.apache.org/plugins/geronimo-2.1/</a>)
has not yet been updated with the released versions of the 2.1 plugins.

<p>Once updated, we need to verify this (and subsequent) steps. There may be a dependency
issue with Pluto...</p></td></tr></table></div>

<p>Now you can point your web browser to <a href="http://localhost:8080/console"
class="external-link" rel="nofollow">http://localhost:8080/console</a> and see the
newly installed console.</p>


<h1><a name="ExtensibleAdministrationConsole-InstallinganACEin.warformatfromanarchivefile"></a>Installing
an ACE in .war format from an archive file</h1>

<p>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.<br/>
Prerequisites</p>
<ol>
	<li>You have a .war-format ACE to be installed.</li>
	<li>The Extensible Administration Console is already deployed, as described <a href="#ExtensibleAdministrationConsole-InstallingtheExtensibleAdministrationConsole">above</a>.</li>
	<li>Any pre-requisites for the ACE are already installed.<br/>
Instructions</li>
	<li>Open the administrative console in an internet browser at address <a href="http://localhost:8080/console"
class="external-link" rel="nofollow">http://localhost:8080/console</a>.</li>
	<li>Select Deploy New on the left navigation bar.</li>
	<li>Click browse and navigate to the ACE file.</li>
	<li>Click Deploy.</li>
	<li>Refresh your browser. Your new component will show up on the left side navigation
menu.</li>
</ol>


<h1><a name="ExtensibleAdministrationConsole-InstallinganAdministrationConsoleExtensionin.carformatfromarepository"></a>Installing
an Administration Console Extension in .car format from a repository</h1>

<p>An ACE in the .car format installs a component and adds its configuration portlets
to the Extensible Administration Console.<br/>
Prerequisites</p>
<ol>
	<li>Your plugin provider already has specified a repository URL. For a larger selection
of available plugins, checking <a href="http://geronimo.apache.org/plugins/geronimo-2.1/repository/"
class="external-link" rel="nofollow">http://geronimo.apache.org/plugins/geronimo-2.1/repository/</a>
is a good place to start.</li>
	<li>The Extensible Administration Console already installed, as described in the previous
section.</li>
</ol>


<h2><a name="ExtensibleAdministrationConsole-Instructions"></a>Instructions</h2>

<p>1. Access the Extensible Administration Console by pointing a web browser to the
following address <a href="http://localhost:8080/console" class="external-link" rel="nofollow">http://localhost:8080/console</a>.<br/>
2. Select Plugins on the left navigation bar.<br/>
3. Under Install Geronimo Plugins, choose the plugin's repository address. </p>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/warning.gif" width="16" height="16"
align="absmiddle" alt="" border="0"></td><td><b>How do I choose the repository
address?</b><br />a. If the correct address does not appear in the Repository
list, select Add Repository.<br/>
b. In the New Repository textbox, enter the repository's address. Don't forget to include
the forward-slash ( / ) at the end of the address.  Select Add Repository.<br/>
c. Select Update Repository List. The new address will now appear in the Repository list.</td></tr></table></div>
<p>4. With the correct repository displayed in the Repository box, select Show Plugins
in selected repository.<br/>
5. Choose the plugin from the Available Plugins list by clicking directly on the plugin name.
</p>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/warning.gif" width="16" height="16"
align="absmiddle" alt="" border="0"></td><td><b>Where's the plugin I
want?</b><br />a. If the desired plugin is not a hyperlink, there are a number
of potential reasons:<br/>
i. If already installed is displayed next to the plugin name, 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.<br/>
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 Jetty). Select View Details for more information.<br/>
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 entering it again. If problems continue,
contact the plugin provider or email the user mailing list at user@geronimo.apache.org.</td></tr></table></div>
<p>6. Select Install on the next screen if the information is correct, or Return to
return to the previous screen.<br/>
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.</p>

<h1><a name="ExtensibleAdministrationConsole-Examples"></a>Examples</h1>

<h2><a name="ExtensibleAdministrationConsole-InstallingtheHelloWorldACE%28.warfile%29"></a>Installing
the HelloWorld ACE (.war file)</h2>

<p>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.</p>

<p>1. Download example-extension-new.war <a href="/confluence/download/attachments/77481/example_extension_new.war?version=1&amp;modificationDate=1212660904000">example_extension_new.war</a><br/>
2. Access the Extensible Administration Console by pointing your web browser to <a href="http://localhost:8080/console"
class="external-link" rel="nofollow">http://localhost:8080/console</a>.<br/>
3. Select Deploy New on the left navigation bar.<br/>
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.<br/>
<span class="image-wrap" style=""><img src="/confluence/download/attachments/77481/helloworld1.jpg?version=1&amp;modificationDate=1212660904000"
style="border: 0px solid black" /></span><br/>
5. Click Install. Your new component will show up on the left side navigation menu.<br/>
<span class="image-wrap" style=""><img src="/confluence/download/attachments/77481/helloworld2.jpg?version=1&amp;modificationDate=1212660904000"
style="border: 0px solid black" /></span></p>

<h1><a name="ExtensibleAdministrationConsole-Customization"></a>Customization</h1>

<p>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.</p>

<p>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.</p>

<h1><a name="ExtensibleAdministrationConsole-Architecture"></a>Architecture</h1>
<p>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.</p>
<div class="" align="center"><p><span class="image-wrap" style=""><img
src="/confluence/download/attachments/77481/HighLevelPluto.JPG?version=2&amp;modificationDate=1212661075000"
style="border: 0px solid black" /></span><br/>
Figure 1 - High level view of Pluto's interaction with a deployable WAR</p></div>


<p>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).</p>

<p>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.</p>

<p>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. </p>

<h2><a name="ExtensibleAdministrationConsole-UnderstandingThroughUsecases"></a>Understanding
Through Usecases</h2>
<p>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.</p>

<p>The first use case we will look at will also be used to describe the individual pieces
that make administration console function.</p>
<div class="" align="center"><p><span class="image-wrap" style=""><img
src="/confluence/download/attachments/77481/startcase.jpg?version=1&amp;modificationDate=1212661052000"
style="border: 0px solid black" /></span><br/>
Figure 2 - Use case for adding features to the console</p></div>


<p>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.</p>

<p>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.</p>

<p>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.</p>

<p>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.</p>

<p>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.</p>
<div class="" align="center"><p><span class="image-wrap" style=""><img
src="/confluence/download/attachments/77481/stopcase.jpg?version=1&amp;modificationDate=1212661052000"
style="border: 0px solid black" /></span><br/>
Figure 3 - Use case for removing features from the console</p></div>


<p>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).</p>

<div class="" align="center"><p><span class="image-wrap" style=""><img
src="/confluence/download/attachments/77481/noext.jpg?version=1&amp;modificationDate=1212661052000"
style="border: 0px solid black" /></span><br/>
Figure 4 - We see no administration extensions to the left for the stopped component</p>


<p><span class="image-wrap" style=""><img src="/confluence/download/attachments/77481/withext.jpg?version=1&amp;modificationDate=1212661052000"
style="border: 0px solid black" /></span><br/>
Figure 5 - We see the administration feature for the HelloWorldPortlet appear in the navigation</p></div>


<h1><a name="ExtensibleAdministrationConsole-Class%2FDependencyStructure"></a>Class/Dependency
Structure</h1>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/warning.gif" width="16" height="16"
align="absmiddle" alt="" border="0"></td><td>Dependency relationship of the
pieces
<ul>
	<li>PortalContainer
	<ul>
		<li>PortalContainerServiceGBean
		<ul>
			<li>AdminConsoleExtensionGBean</li>
		</ul>
		</li>
		<li>Pluto Portal
		<ul>
			<li>Administration Console
			<ul>
				<li>New Portlet</li>
			</ul>
			</li>
		</ul>
		</li>
	</ul>
	</li>
</ul>
</td></tr></table></div>

<p>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.</p>

<p>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.
</p>


<h1><a name="ExtensibleAdministrationConsole-HowtoDevelopanAdministratorConsoleExtension%28ACE%29"></a>How
to Develop an Administrator Console Extension (ACE)</h1>
<p>In order to develop your own console extension, you will need to perform the following
steps:</p>
<ol>
	<li>Create a portlet</li>
	<li>Add an AdminConsoleExtensionGBean to the deployment plan</li>
	<li>Build the WAR or CAR</li>
	<li>Deploy the application</li>
	<li>Verify the installation</li>
</ol>


<p>Each step is further detailed below.</p>

<h2><a name="ExtensibleAdministrationConsole-Differentwaysofstructuring"></a>Different
ways of structuring</h2>
<p>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:</p>
<ol>
	<li>Your portlets</li>
	<li>Your portlets + your related component</li>
	<li>Your portlets which declares a dependency on your related component</li>
</ol>


<h2><a name="ExtensibleAdministrationConsole-Createaportlet"></a>Create
a portlet</h2>
<p>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 <a href="http://www.jcp.org/en/jsr/detail?id=168"
class="external-link" rel="nofollow">JSR 168</a>.  We will not go into the details
of how to develop portlets since you can find many tutorials and tools for this such as <a
href="http://sourceforge.net/projects/portlet-eclipse/" class="external-link" rel="nofollow">Portlet
Plugin for Eclipse</a>.  You will need the appropriate "web.xml" and "portlet.xml" files
defined. As a simple example, refer to the <a href="#ExtensibleAdministrationConsole-SampleExtension">HelloWorldPortlet</a>
defined at the end of this section.</p>

<h2><a name="ExtensibleAdministrationConsole-AddanAdminConsoleExtensionGBean"></a>Add
an AdminConsoleExtensionGBean</h2>
<p>To add an AdminConsoleExtensionGBean to your deployable archive file, you need to
include the following to your "geronimo-web.xml" deployment plan:  </p>
<ol>
	<li>Declare a dependency on the "pluto-portal"
<div class="code panel" style="border-style: solid;border-width: 1px;"><div class="codeContent
panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;dependencies&gt;</span>
    ...
<span class="code-tag">&lt;dependency&gt;</span>
    <span class="code-tag">&lt;groupId&gt;</span>org.apache.geronimo.plugins<span
class="code-tag">&lt;/groupId&gt;</span>
    <span class="code-tag">&lt;artifactId&gt;</span>pluto-support<span
class="code-tag">&lt;/artifactId&gt;</span>
<span class="code-tag">&lt;/dependency&gt;</span>
<span class="code-tag">&lt;/dependencies&gt;</span>
</pre>
</div></div></li>
	<li>Define an AdminConsoleExtensionGBean
<div class="code panel" style="border-style: solid;border-width: 1px;"><div class="codeContent
panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;gbean name=<span class="code-quote">"example"</span>
class=<span class="code-quote">"org.apache.geronimo.pluto.AdminConsoleExtensionGBean"</span>&gt;</span>
    <span class="code-tag">&lt;attribute name=<span class="code-quote">"pageTitle"</span>&gt;</span>Testing<span
class="code-tag">&lt;/attribute&gt;</span>
    <span class="code-tag">&lt;attribute name=<span class="code-quote">"portletContext"</span>&gt;</span>/HelloWorldPortlet<span
class="code-tag">&lt;/attribute&gt;</span>
    <span class="code-tag">&lt;attribute name=<span class="code-quote">"portletList"</span>&gt;</span>[HelloWorldPortlet]<span
class="code-tag">&lt;/attribute&gt;</span>
<span class="code-tag">&lt;/gbean&gt;</span>
</pre>
</div></div>
<p>where the attributes are defined as follows:</p></li>
</ol>
<ul>
	<li>pageTitle: The name of the page to add these portlets to (new or existing)</li>
	<li>portletContext: The context of where the portlets are installed.</li>
	<li>portletList: A comma-delimited list of the portlets to be added to this page.</li>
</ul>


<div class="code panel" style="border-style: solid;border-width: 1px;"><div class="codeHeader
panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><b>Sample
geronimo-web.xml</b></div><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;web-app xmlns=<span class="code-quote">"http://geronimo.apache.org/xml/ns/j2ee/web-1.2"</span>&gt;</span>
    <span class="code-tag">&lt;environment&gt;</span>
        <span class="code-tag">&lt;moduleId&gt;</span>
            <span class="code-tag">&lt;groupId&gt;</span>org.apache.geronimo.portals<span
class="code-tag">&lt;/groupId&gt;</span>
            <span class="code-tag">&lt;artifactId&gt;</span>pluto-example<span
class="code-tag">&lt;/artifactId&gt;</span>
            <span class="code-tag">&lt;version&gt;</span>1.0-SNAPSHOT<span
class="code-tag">&lt;/version&gt;</span>
            <span class="code-tag">&lt;type&gt;</span>war<span class="code-tag">&lt;/type&gt;</span>
        <span class="code-tag">&lt;/moduleId&gt;</span>
        
        <span class="code-tag">&lt;dependencies&gt;</span>
            <span class="code-tag">&lt;dependency&gt;</span> <span
class="code-tag"><span class="code-comment">&lt;!-- Put a dependancy on the hosting
portal (pluto) --&gt;</span></span>
                <span class="code-tag">&lt;groupId&gt;</span>org.apache.geronimo.plugins<span
class="code-tag">&lt;/groupId&gt;</span>
                <span class="code-tag">&lt;artifactId&gt;</span>pluto-support<span
class="code-tag">&lt;/artifactId&gt;</span>
            <span class="code-tag">&lt;/dependency&gt;</span>
        <span class="code-tag">&lt;/dependencies&gt;</span>
    <span class="code-tag">&lt;/environment&gt;</span>
    
    <span class="code-tag"><span class="code-comment">&lt;!-- This is where
the files are accessed from. (aka - portletContext) --&gt;</span></span>
    <span class="code-tag">&lt;context-root&gt;</span>/HelloWorldPortlet<span
class="code-tag">&lt;/context-root&gt;</span>
    
    <span class="code-tag"><span class="code-comment">&lt;!-- Start off a
ACEGBean, this is the lifecycle for the portlet --&gt;</span></span>
    <span class="code-tag">&lt;gbean name=<span class="code-quote">"PlutoTest"</span>
class=<span class="code-quote">"org.apache.geronimo.pluto.AdminConsoleExtensionGBean"</span>&gt;</span>
        <span class="code-tag">&lt;attribute name=<span class="code-quote">"pageTitle"</span>&gt;</span>Hello<span
class="code-tag">&lt;/attribute&gt;</span>
        <span class="code-tag">&lt;attribute name=<span class="code-quote">"portletContext"</span>&gt;</span>/HelloWorldPortlet<span
class="code-tag">&lt;/attribute&gt;</span>
        <span class="code-tag">&lt;attribute name=<span class="code-quote">"portletList"</span>&gt;</span>[HelloWorldPortlet]<span
class="code-tag">&lt;/attribute&gt;</span>
        <span class="code-tag">&lt;reference name=<span class="code-quote">"PortalContainerServices"</span>&gt;</span>
            <span class="code-tag">&lt;name&gt;</span>PlutoPortalServices<span
class="code-tag">&lt;/name&gt;</span>
        <span class="code-tag">&lt;/reference&gt;</span>
    <span class="code-tag">&lt;/gbean&gt;</span>
<span class="code-tag">&lt;/web-app&gt;</span>
</pre>
</div></div>

<h2><a name="ExtensibleAdministrationConsole-Puttingittogether"></a>Putting
it together</h2>
<p>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.</p>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/warning.gif" width="16" height="16"
align="absmiddle" alt="" border="0"></td><td><b>What is an example structure
for a simple war?</b><br /><ul>
	<li>HelloWorldPortlet.war
	<ul>
		<li>WEB-INF/
		<ul>
			<li>classes/
			<ul>
				<li>(portlet class files)</li>
			</ul>
			</li>
			<li>geronimo-web.xml</li>
			<li>portlet.xml</li>
			<li>web.xml</li>
		</ul>
		</li>
	</ul>
	</li>
</ul>
</td></tr></table></div>

<h2><a name="ExtensibleAdministrationConsole-Deployingtheapplication"></a>Deploying
the application</h2>
<p>Deploy the archive as you normally would either using the "deploy" command or by
using the Administrator Console's "Deploy New" or "Plugins".</p>
<ol>
	<li><em>Command Line</em>: <tt><b>&lt;geronimo bin folder&gt;/deploy.bat
deploy &lt;path to war&gt;</b></tt><br/>
Example:<br/>
<tt><b>cd c:/g/target/geronimo-tomcat6-minimal-2.0-SNAPSHOT/bin/</b></tt><br/>
<tt><b>deploy.bat deploy c:/HelloWorldPortlet.war</b></tt></li>
	<li><em>Using the Admin Console</em>:
<div class="" align="center"><p><span class="image-wrap" style=""><img
src="/confluence/download/attachments/77481/InstApp.jpg?version=1&amp;modificationDate=1212661112000"
style="border: 0px solid black" /></span></p></div>
</li>
</ol>



<h2><a name="ExtensibleAdministrationConsole-Verifyinginstallation"></a>Verifying
installation</h2>
<p>Go to <a href="http://localhost:8080/console/" class="external-link" rel="nofollow">http://localhost:8080/console/</a>
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.)</p>

<h1><a name="ExtensibleAdministrationConsole-SampleExtension"></a>Sample
Extension</h1>
<p>This is a working simple example of an Administration Console Extension.<br/>
<a href="/confluence/download/attachments/77481/example_extension.war?version=1&amp;modificationDate=1212661075000">Download
the example WAR</a></p>
<div class="code panel" style="border-style: solid;border-width: 1px;"><div class="codeHeader
panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><b>HelloWorldPortlet.java</b></div><div
class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">package</span> org.apache.pluto.examples;

<span class="code-keyword">import</span> java.io.IOException; 
<span class="code-keyword">import</span> java.io.PrintWriter;

<span class="code-keyword">import</span> javax.portlet.GenericPortlet;
<span class="code-keyword">import</span> javax.portlet.PortletException;
<span class="code-keyword">import</span> javax.portlet.RenderRequest;
<span class="code-keyword">import</span> javax.portlet.RenderResponse;

/**
 * A very simple portlet example.
 * This portlet displays 'Hello World' to the end user
 */
<span class="code-keyword">public</span> class HelloWorldPortlet <span class="code-keyword">extends</span>
GenericPortlet {

    <span class="code-comment">// This function is called when a user requests to view
<span class="code-keyword">this</span> portlet (by
</span>    <span class="code-comment">// navigating to the webpage in Pluto)
</span>    <span class="code-keyword">public</span> void doView(RenderRequest
request, RenderResponse response)
            <span class="code-keyword">throws</span> PortletException, IOException
{

        <span class="code-comment">// Set the response to read HTML
</span>        response.setContentType(<span class="code-quote">"text/html;charset=UTF-8"</span>);

        <span class="code-comment">// Required call <span class="code-keyword">for</span>
use of getWriter() and getPortletOutputStream()
</span>        PrintWriter out = response.getWriter();
        <span class="code-comment">// Write content to the portlet
</span>        out.println(<span class="code-quote">"&lt;h1&gt;Hello World&lt;/h1&gt;"</span>);
    }
}
</pre>
</div></div>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/GMOxDOC21/Extensible+Administration+Console">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=77481&revisedVersion=10&originalVersion=9">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/GMOxDOC21/Extensible+Administration+Console?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message