Oracle GlassFish Server 3.0.1 Add-On Component Development Guide

Chapter 3 Extending the Administration Console

The Administration Console is a browser-based tool for administering GlassFishTM Server. It features an easy-to-navigate interface and online help. Extending the Administration Console enables you to provide a graphical user interface for administering your add-on component. You can use any of the user interface features of the Administration Console, such as tree nodes, links on the Common Tasks page, tabs and sub-tabs, property sheets, and JavaServerTM Faces pages. Your add-on component implements a marker interface and provides a configuration file that describes how your customizations integrate with the Administration Console.

This chapter refers to a simple example called console-sample-ip that illustrates how to provide Administration Console features for a hypothetical add-on component. Instructions for obtaining and using this example are available at the example's project page. When you check out the code, it is placed in a directory named glassfish-samples/v3/plugin/adminconsole/console-sample-ip/ in your current directory. In this chapter, path names for the example files are relative to this directory.

The following topics are addressed here:

Administration Console Architecture

The Administration Console is a web application that is composed of OSGi bundles. These bundles provide all the features of the Administration Console, such as the Web Applications, Update Center, and Security content. To provide support for your add-on component, create your own OSGi bundle that implements the parts of the user interface that you need. Place your bundle in the modules directory of your GlassFish Server installation, along with the other Administration Console bundles.

To learn how to package the Administration Console features for an add-on component, go to the modules directory of your GlassFish Server installation and examine the contents of the files named console-componentname-plugin.jar. Place the console-sample-ip project bundle in the same place to deploy it and examine the changes that it makes to the Administration Console.

The Administration Console includes a Console Add-On Component Service. The Console Add-On Component Service is an HK2 service that acts as a façade to all theAdministration Console add-on components. The Console Add-On Component Service queries the various console providers for integration points so that it can perform the actions needed for the integration (adding a tree node or a new tab, for example). The interface name for this service is org.glassfish.api.admingui.ConsolePluginService.

For details about the Hundred-Kilobyte Kernel (HK2) project, see Hundred-Kilobyte Kernel and HK2 Component Model.

Each add-on component must contain a console provider implementation. This is a Java class that implements the org.glassfish.api.admingui.ConsoleProvider interface and uses the HK2 @Service annotation. The console provider allows your add-on component to specify where your integration point configuration file is located. This configuration file communicates to the Console Add-On Component Service the customizations that your add-on component makes to the Administration Console.

Implementing a Console Provider

The org.glassfish.api.admingui.ConsoleProvider interface has one required method, getConfiguration. The getConfiguration method returns the location of the console-config.xml file as a java.net.URL. If getConfiguration returns null, the default location, META-INF/admingui/console-config.xml, is used. The console-config.xml file is described in About Integration Points.

To implement the console provider for your add-on component, write a Java class that is similar to the following example.


Example 3–1 Example ConsoleProvider Implementation

This example shows a simple implementation of the ConsoleProvider interface:

package org.glassfish.admingui.plugin;

import org.glassfish.api.admingui.ConsoleProvider;
import org.jvnet.hk2.annotations.Service;

import java.net.URL;

@Service
public class SamplePlugin implements ConsoleProvider {

    public URL getConfiguration() { return null; }
}

This implementation of getConfiguration returns null to specify that the configuration file is in the default location. If you place the file in a nonstandard location or give it a name other than console-config.xml, your implementation of getConfiguration must return the URL where the file can be found.

You can find this example code in the file project/src/main/java/org/glassfish/admingui/plugin/SamplePlugin.java.


About Administration Console Templates

GlassFish Server includes a set of templates that make it easier to create JavaServer Faces pages for your add-on component. These templates use Templating for JavaServer Faces Technology, which is also known as JSFTemplating.

Examples of JSFTemplating technology can be found in the following sections of this chapter:

About Integration Points

The integration points for your add-on component are the individual Administration Console user interface features that your add-on component will extend. You can implement the following kinds of integration points:

Specify all the integration points in a file named console-config.xml. In the example, this file is in the directory project/src/main/resources/META-INF/admingui/. The following sections describe how to create this file.

In addition, create JavaServer Faces pages that contain JSF code fragments to implement the integration points. In the example, these files are in the directory project/src/main/resources/. The content of these files depends on the integration point you are implementing. The following sections describe how to create these JavaServer Faces pages.

For reference information on integration points, see Appendix A, Integration Point Reference.

Specifying the ID of an Add-On Component

The console-config.xml file consists of a console-config element that encloses a series of integration-point elements. The console-config element has one attribute, id, which specifies a unique name or ID value for the add-on component.

In the example, the element is declared as follows:

<console-config id="sample">
    ...
</console-config>

You will also specify this ID value when you construct URLs to images, resources and pages in your add-on component. See Adding a Node to the Navigation Tree for an example.

For example, a URL to an image named my.gif might look like this:

<sun:image url="/resource/sample/images/my.gif" />

The URL is constructed as follows:

Adding Functionality to the Administration Console

The integration-point elements in the console-config.xml file specify attributes for the user interface features that you choose to implement. The example file provides examples of most of the available kinds of integration points at this release. Your own add-on component can use some or all of them.

For each integration-point element, specify the following attributes.

id

An identifier for the integration point.

parentId

The ID of the integration point's parent.

type

The type of the integration point.

priority

A numeric value that specifies the relative ordering of integration points for add-on components that specify the same parentId. A lower number specifies a higher priority (for example, 100 represents a higher priority than 400). The integration points for add-on components are always placed after those in the basic Administration Console. You might need to experiment to place the integration point where you want it. This attribute is optional.

content

The content for the integration point, typically a JavaServer Faces page. In the example, you can find the JavaServer Faces pages in the directory project/src/main/resources/.


Note –

The order in which these attributes are specified does not matter, and in the example console-config.xml file the order varies. To improve readability, this chapter uses the same order throughout.


The following topics are addressed here:

Adding a Node to the Navigation Tree

You can add a node to the navigation tree, either at the top level or under another node. To add a node, use an integration point of type org.glassfish.admingui:navNode. Use the parentId attribute to specify where the new node should be placed. Any tree node, including those added by other add-on components, can be specified. Examples include the following:

tree

At the top level

applicationServer

Under the GlassFish Server node

applications

Under the Applications node

resources

Under the Resources node

configuration

Under the Configuration node

webContainer

Under the Web Container node

httpService

Under the HTTP Service node


Note –

The webContainer and httpService nodes are available only if you installed the web container module for the Administration Console (the console-web-gui.jar OSGi bundle).


If you do not specify a parentId, the new content is added to the root of the integration point, in this case the top level node, tree.


Example 3–2 Example Tree Node Integration Point

For example, the following integration-point element uses a parentId of tree to place the new node at the top level.

        <integration-point 
                id="sampleNode" 
                parentId="tree" 
                type="org.glassfish.admingui:treeNode" 
                priority="200" 
                content="sampleNode.jsf" 
        />

This example specifies the following values in addition to the parentId:

The example console-config.xml file provides other examples of tree nodes under the Resources and Configuration nodes.

Creating a JavaServer Faces Page for Your Node

A JavaServer Faces page for a tree node uses the tag sun:treeNode. This tag provides all the capabilities of the Project Woodstock tag webuijsf:treeNode.


Example 3–3 Example JavaServer Faces Page for a Tree Node

In the example, the sampleNode.jsf file has the following content:

<sun:treeNode 
        id="treeNode1"
        text="SampleTop"
        url="/sample/page/testPage.jsf?name=SampleTop"
        imageURL="/resource/sample/images/sample.png"
        >
    <sun:treeNode 
            id="treeNodeBB"
            text="SampleBB"
            url="/sample/page/testPage.jsf?name=SampleBB"
            imageURL="resource/sample/images/sample.png" />
</sun:treeNode>

This file uses the sun:treenode tag to specify both a top-level tree node and another node nested beneath it. In your own JavaServer Faces pages, specify the attributes of this tag as follows:

id

A unique identifier for the tree node.

text

The node name that appears in the tree.

url

The location of the JavaServer Faces page that appears when you click the node. In the example, most of the integration points use a very simple JavaServer Faces page called testPage.jsf, which is in the src/main/resources/page/ directory. Specify the integration point id value as the root of the URL; in this case, it is sample (see Specifying the ID of an Add-On Component). The rest of the URL is relative to the src/main/resources/ directory, where sampleNode.jsf resides.

The url tag in this example passes a name parameter to the JavaServer Faces page.

imageURL

The location of a graphic to display next to the node name. In the example, the graphic is always sample.png, which is in the src/main/resources/images/ directory. The URL for this image is an absolute path, /resource/sample/images/sample.png, where sample in the path is the integration point id value (see Specifying the ID of an Add-On Component).

Adding Tabs to a Page

You can add a tab to an existing tab set, or you can create a tab set for your own page. One way to add a tab or tab set is to use an integration point of type org.glassfish.admingui:serverInstTab, which adds a tab to the tab set on the main GlassFish Server page of the Administration Console. You can also create sub-tabs. Once again, the parentId element specifies where to place the tab or tab set.


Example 3–4 Example Tab Integration Point

In the example, the following integration-point element adds a new tab on the main GlassFish Server page of the Administration Console:

        <integration-point 
            id="sampleTab"
            parentId="serverInstTabs"
            type="org.glassfish.admingui:serverInstTab" 
            priority="500" 
            content="sampleTab.jsf"
        />

This example specifies the following values:


Example 3–5 Example Tab Set Integration Points

The following integration-point elements add a new tab with two sub-tabs, also on the main GlassFish Server page of the Administration Console:

        <integration-point 
            id="sampleTabWithSubTab"
            parentId="serverInstTabs"
            type="org.glassfish.admingui:serverInstTab" 
            priority="300" 
            content="sampleTabWithSubTab.jsf"
        />
        
        <integration-point 
            id="sampleSubTab1" 
            parentId="sampleTabWithSubTab"
            type="org.glassfish.admingui:serverInstTab" 
            priority="300" 
            content="sampleSubTab1.jsf"
        />
        <integration-point 
            id="sampleSubTab2" 
            parentId="sampleTabWithSubTab"
            type="org.glassfish.admingui:serverInstTab" 
            priority="400" 
            content="sampleSubTab2.jsf"
        />

These examples specify the following values:

Creating JavaServer Faces Pages for Your Tabs

A JavaServer Faces page for a tab uses the tag sun:tab. This tag provides all the capabilities of the Project Woodstock tag webuijsf:tab.


Example 3–6 Example JavaServer Faces Page for a Tab

In the example, the sampleTab.jsf file has the following content:

<sun:tab id="sampleTab" immediate="true" text="Sample First Tab">
    <!command
        setSessionAttribute(key="serverInstTabs" value="sampleTab");
        gf.redirect(page="#{request.contextPath}/page/tabPage.jsf?name=Sample%20First%20Tab");
    />
</sun:tab>


Note –

In the actual file there are no line breaks in the gf.redirect value.


In your own JavaServer Faces pages, specify the attributes of this tag as follows:

id

A unique identifier for the tab, in this case sampleTab.

immediate

If set to true, event handling for this component should be handled immediately (in the Apply Request Values phase) rather than waiting until the Invoke Application phase.

text

The tab name that appears in the tab set.

The JSF page displays tab content differently from the way the page for a node displays node content. It invokes two handlers for the command event: setSessionAttribute and gf.redirect. The gf.redirect handler has the same effect for a tab that the url attribute has for a node. It navigates to a simple JavaServer Faces page called tabPage.jsf, in the src/main/resources/page/ directory, passing the text “Sample First Tab” to the page in a name parameter.

The sampleSubTab1.jsf and sampleSubTab2.jsf files are almost identical to sampleTab.jsf. The most important difference is that each sets the session attribute serverInstTabs to the base name of the JavaServer Faces file that corresponds to that tab:

setSessionAttribute(key="serverInstTabs" value="sampleTab");
setSessionAttribute(key="serverInstTabs" value="sampleSubTab1");
setSessionAttribute(key="serverInstTabs" value="sampleSubTab2");

Adding a Task to the Common Tasks Page

You can add either a single task or a group of tasks to the Common Tasks page of the Administration Console. To add a task or task group, use an integration point of type org.glassfish.admingui:commonTask.

See Adding a Task Group to the Common Tasks Page for information on adding a task group.


Example 3–7 Example Task Integration Point

In the example console-config.xml file, the following integration-point element adds a task to the Deployment task group:

        <integration-point 
                id="sampleCommonTask" 
                parentId="deployment"
                type="org.glassfish.admingui:commonTask" 
                priority="200"
                content="sampleCommonTask.jsf"
        />

This example specifies the following values:

Creating a JavaServer Faces Page for Your Task

A JavaServer Faces page for a task uses the tag sun:commonTask. This tag provides all the capabilities of the Project Woodstock tag webuijsf:commonTask.


Example 3–8 Example JavaServer Faces Page for a Task

In the example, the sampleCommonTask.jsf file has the following content:

<sun:commonTask
        text="Sample Application Page"
        toolTip="Sample Application Page"
        onClick="return admingui.woodstock.commonTaskHandler('treeForm:tree:applications:ejb', 
        '#{request.contextPath}/sample/page/testPage.jsf?name=Sample%20Application%20Page');">
</sun:commonTask>


Note –

In the actual file, there is no line break in the onClick attribute value.


This file uses the sun:commonTask tag to specify the task. In your own JavaServer Faces pages, specify the attributes of this tag as follows:

text

The task name that appears on the Common Tasks page.

toolTip

The text that appears when a user places the mouse cursor over the task name.

onClick

Scripting code that is to be executed when a user clicks the task name.

Adding a Task Group to the Common Tasks Page

You can add a new group of tasks to the Common Tasks page to display the most important tasks for your add-on component. To add a task group, use an integration point of type org.glassfish.admingui:commonTask.


Example 3–9 Example Task Group Integration Point

In the example console-config.xml file, the following integration-point element adds a new task group to the Common Tasks page:

       <integration-point 
            id="sampleGroup" 
            parentId="commonTasksSection"
            type="org.glassfish.admingui:commonTask" 
            priority="500"
            content="sampleTaskGroup.jsf"
        />

This example specifies the following values:

Creating a JavaServer Faces Page for Your Task Group

A JavaServer Faces page for a task group uses the tag sun:commonTasksGroup. This tag provides all the capabilities of the Project Woodstock tag webuijsf:commonTasksGroup.


Example 3–10 Example JavaServer Faces Page for a Task Group

In the example, the sampleTaskGroup.jsf file has the following content:

<sun:commonTasksGroup title="My Own Sample Group">
    <sun:commonTask
            text="Go To Sample Resource"
            toolTip="Go To Sample Resource"
            onClick="return admingui.woodstock.commonTaskHandler('form:tree:resources:treeNode1', 
            '#{request.contextPath}/sample/page/testPage.jsf?name=Sample%20Resource%20Page');">
    </sun:commonTask>
    <sun:commonTask
            text="Sample Configuration"
            toolTip="Go To Sample Configuration"
            onClick="return admingui.woodstock.commonTaskHandler('form:tree:configuration:sampleConfigNode', 
            '#{request.contextPath}/sample/page/testPage.jsf?name=Sample%20Configuration%20Page');">
    </sun:commonTask>
</sun:commonTasksGroup>


Note –

In the actual file, there are no line breaks in the onClick attribute values.


This file uses the sun:commonTasksGroup tag to specify the task group, and two sun:commonTask tags to specify the tasks in the task group. The sun:commonTasksGroup tag has only one attribute, title, which specifies the name of the task group.

Adding Content to a Page

You can add content for your add-on component to an existing top-level page, such as the Configuration page or the Resources page. To add content to one of these pages, use an integration point of type org.glassfish.admingui:configuration or org.glassfish.admingui:resources.


Example 3–11 Example Resources Page Implementation Point

In the example console-config.xml file, the following integration-point element adds new content to the top-level Resources page:

        <integration-point 
                id="sampleResourceLink"
                parentId="propSheetSection"
                type="org.glassfish.admingui:resources" 
                priority="100" 
                content="sampleResourceLink.jsf"
        />

This example specifies the following values:

Another integration-point element in the console-config.xml file places similar content on the Configuration page.

Creating a JavaServer Faces Page for Your Page Content

A JavaServer Faces page for page content often uses the tag sun:property to specify a property on a property sheet. This tag provides all the capabilities of the Project Woodstock tag webuijsf:property.


Example 3–12 Example JavaServer Faces Page for a Resource Page Item

In the example, the sampleResourceLink.jsf file has the following content:

<sun:property>
    <sun:hyperlink 
        toolTip="Sample Resource" 
        url="/sample/page/testPage.jsf?name=Sample%20Resource%20Page" >
        <sun:image url="/resource/sample/images/sample.png" />
        <sun:staticText text="Sample Resource" />
    </sun:hyperlink>
</sun:property>

<sun:property>
    <sun:hyperlink 
        toolTip="Another" 
        url="/sample/page/testPage.jsf?name=Another" >
        <sun:image url="/resource/sample/images/sample.png" />
        <sun:staticText text="Another" />
    </sun:hyperlink>
</sun:property>

The file specifies two simple properties on the property sheet, one above the other. Each consists of a sun:hyperlink element (a link to a URL). Within each sun:hyperlink element is nested a sun:image element, specifying an image, and a sun:staticText element, specifying the text to be placed next to the image.

Each sun:hyperlink element uses a toolTip attribute and a url attribute. Each url attribute references the testPage.jsf file that is used elsewhere in the example, specifying different content for the name parameter.

You can use many other kinds of user interface elements within a sun:property element.

Adding a Page to the Administration Console

Your add-on component may require new configuration tasks. In addition to implementing commands that accomplish these tasks (see Chapter 4, Extending the asadmin Utility), you can provide property sheets that enable users to configure your component or to perform tasks such as creating and editing resources for it.


Example 3–13 Example JavaServer Faces Page for a Property Sheet

Most of the user interface features used in the example reference the file testPage.jsf or (for tabs) the file tabPage.jsf. Both files are in the src/main/resources/page/ directory. The testPage.jsf file looks like this:

<!composition template="/templates/default.layout" guiTitle="TEST Sample Page Title">
<!define name="content">
<sun:form id="propertyForm">
            
<sun:propertySheet id="propertySheet">
    <sun:propertySheetSection id="propertySection">
       <sun:property id="prop1" labelAlign="left" noWrap="true" 
                     overlapLabel="false" label="Test Page Name:" >
            <sun:staticText text="$pageSession{pageName}" >
                <!beforeCreate
                    getRequestValue(key="name" value=>$page{pageName});
                />
            </sun:staticText>
        </sun:property>
    </sun:propertySheetSection>
</sun:propertySheet>
<sun:hidden id="helpKey" value="" />

</sun:form>
</define>
</composition>

The page uses the composition directive to specify that the page uses the default.layout template and to specify a page title. The page uses additional directives, events, and tags to specify its content.

Adding Internationalization Support

To add internationalization support for your add-on component to the Administration Console, you can place an event and handler like the following at the top of your page:

<!initPage 
    setResourceBundle(key="yourI18NKey" bundle="bundle.package.BundleName") 
/>

Replace the values yourI18NKey and bundle.package.BundleName with appropriate values for your component.

Changing the Theme or Brand of the Administration Console

To change the theme or brand of the Administration Console for your add-on component, use the integration point type org.glassfish.admingui:customtheme. This integration point affects the Cascading Style Sheet (CSS) files and images that are used in the Administration Console.


Example 3–14 Example Custom Theme Integration Point

For example, the following integration point specifies a custom theme:

        <integration-point 
                id="myOwnBrand" 
                type="org.glassfish.admingui:customtheme" 
                priority="2" 
                content="myOwnBrand.properties" 
        />

The priority attribute works differently when you specify it in a branding integration point from the way it works in other integration points. You can place multiple branding add-on components in the modules directory, but only one theme can be applied to the Administration Console. The priority attribute determines which theme is used. Specify a value from 1 to 100; the lower the number, the higher the priority. The integration point with the highest priority will be used.

Additional integration point types also affect the theme or brand of the Administration Console:

org.glassfish.admingui:masthead

Specifies the name and location of the include masthead file, which can be customized with a branding image. This include file will be integrated on the masthead of the Administration Console.

org.glassfish.admingui:loginimage

Specifies the name and location of the include file containing the branding login image code that will be integrated with the login page of the Administration Console.

org.glassfish.admingui:loginform

Specifies the name and location of the include file containing the customized login form code. This code also contains the login background image used for the login page for the Administration Console.

org.glassfish.admingui:versioninfo

Specifies the name and location of the include file containing the branding image that will be integrated with the content of the version popup window.


Example 3–15 Example of Branding Integration Points

For example, you might specify the following integration points. The content for each integration point is defined in an include file.

       <integration-point
               id="myOwnBrandMast"
               type="org.glassfish.admingui:masthead"
               priority="80"
               content="branding/masthead.inc"
       />
       <integration-point
               id="myOwnBrandLogImg"
               type="org.glassfish.admingui:loginimage"
               priority="80"
               content="branding/loginimage.inc"
       />
       <integration-point
               id="myOwnBrandLogFm"
               type="org.glassfish.admingui:loginform"
               priority="80"
               content="branding/loginform.inc"
       />
       <integration-point
               id="myOwnBrandVersInf"
               type="org.glassfish.admingui:versioninfo"
               priority="80"
               content="branding/versioninfo.inc"
       />

To provide your own CSS and images to modify the global look and feel of the entire application (not just the Administration Console), use the theming feature of Project Woodstock. Create a theme JAR file with all the CSS properties and image files that are required by your Woodstock component. Use a script provided by the Woodstock project to clone an existing theme, then modify the files and properties as necessary. Once you have created the theme JAR file, place it in the WEB-INF/lib directory of the Administration Console so that the Woodstock theme component will load the theme. In addition, edit the properties file specified by your integration point (MyOwnBrand.properties, for example) to specify the name and version of your theme.

Creating an Integration Point Type

If your add-on component provides new content that you would like other people to extend, you may define your own integration point types. For example, if you add a new page that provides tabs of monitoring information, you might want to allow others to add their own tabs to complement your default tabs. This feature enables your page to behave like the existing Administration Console pages that you or others can extend.

ProcedureTo Create an Integration Point Type

  1. Decide on the name of your integration point type.

    The integration point type must be a unique identifier. You might use the package name of your integration point, with a meaningful name appended to the end, as in the following example:

    org.company.project:myMonitoringTabs
  2. After you have an integration point ID, use handlers to insert the integration point implementation(s).

    Include code like the following below the place in your JavaServer Faces page where you would like to enable others to add their integration point implementations:

    <event>
        <!afterCreate 
            getUIComponent(clientId="clientId:of:root" 
                           component=>$attribute{rootComp});
            includeIntegrations(type="org.company.project:myMonitoringTabs" 
                                root="#{rootComp}");
        />
    </event>

    Change clientId:of:root to match the clientId of the outermost component in which you want others to be able to add their content (in this example, the tab set is the most likely choice). Also include your integration point ID in place of org.company.project:myMonitoringTabs. If you omit the root argument to includeIntegrations, all components on the entire page can be used for the parentId of the integration points.

  3. To enable others to use this integration point, document it at the GlassFish Integration Point wiki page.

    Document the integration point only if your content is publicly available.

    You or others can now provide an integration point that will be integrated into this page.

See Also

For more information, see the JSFTemplating API documentation.