1 Introduction

1.1 Project/Component Working Name

Administration Console for GlassFish V3 Release

1.2 Name(s) and e-mail address of Document Author(s)/Supplier

Anissa Lam : anissa.lam@sun.com

Jason Lee: jasondlee at sun dot com

Ken Paulsen: ken.paulsen@sun.com

1.3 Date of This Document

Created: January 7, 2009

2 Project Summary

2.1 Project Description

Administration Console (GUI) is one of the tools for application server administrators to configure and monitor the application server.

2.2 Risks and Assumptions

1. GlassFish V3 Admin Console is not currently planned to be compliant with HCI-Admin guidelines. HIE support will be needed if compliance is to be targeted.
2. The Admin Console is written on top of the JSFTemplating framework, which is a java.net open source project. It is assumed that JSFTemplating will continue to evolve with features to support the Admin Console.
3. The Admin Console will be using the Woodstock components, a JSF component set. It is assumed that the released version, Woodstock 4.3, which will be integrated, will not have major fault that prevents the Admin Console from utilizing it.
4. Almost all of the features and enhancements depend on back end support, and that that an API will be provided.
5. Detecting the available modules for installation or update depends on the API provided by Update Center 2.0.
6. The console is expected to support management of a number of JavaEE 6 features. It is assumed that the specs will be complete, with reference implementations usable in a reasonable amount of time to allow the implementation of its supports in the console.
7. This release will have some UI refactoring.. While this work has the possibility of impacting timelines, it is expected that that will not be the case. Without this refactoring, there is a significant risk that problem areas in our application may impact the schedule (namely Tree-breadcrumb issues, and frameset issues).
8. Able to host the Online Help set online is a risk factor.
   

3 Problem Summary

3.1 Problem Area

3.2 Justification

The Administration Console was well received by the community and often viewed as a differentiator from other similar products in the market. For GlassFish V3, we need to continue to provide this user friendly administration tool. One of the more common complaints is performance, to ameliorate that issue, this release will contain several UI updates and changes that will improve performance and our ability to maintain and enhance the admin console. Some of the benefits of making these UI design changes include:

1. Modernize the look and feel of the application
2. Provide bookmarkable pages
3. Improve performance
4. Enable customizations
5. Provide a less coupled design which encourages community participation of additions to the admin console.
6. Mitigate use of complicated, unsupported components
   

4 Technical Description

4.1 New Functionality

This release will include full support for Java EE 6 features. See section 4.4 for features which are NOT in scope for this release.

4.1.1 Scripting

This is based on the Scripting Support One Pager .
There will be 2 plugin modules implemented by the GUI team. One plugin is to support administration and application configuration for JRuby framework (Rails, Merb). Another plugin to support administration and application configuration for Django applications. Console will provide UI to do the deployment and listing of the deployed apps. Appropriate UI widgets will be used so user can configure the properties spelled out in 4.7.1.1 section of the one pager.

Based on the scripting one pager, there is not enough info at this point regarding the configuration for Jython/Django application. This one pager will be updated later.

There will be support for monitoring of the JRuby container. This will include both the configuration and viewing of the monitor data. More details coming ...

4.1.2 Application management

This is based on the Application Management One Pager .
Console will provide the UI for user to edit the and of the deployment descriptor as specified in the above one pager. This will be supported for web application only as no other container team has approached the GUI team for such support.
A table will be provided that listed out all the customized and , the default value specified in the deployment descriptor, and allows user to override that.

4.1.3 Non-war deployments

In v3 prelude, only war deployment is supported. For this release, all Java EE application types will be supported. This includes war, ear, jar, rar files, including wars with ejb jars. Gui will pass the bundle to the backend (upload to server side if needed), leaving the backend to determine what type of applications is deployed. Same for the case when user specifies the directory. Listing of applications in the tree node will be changed. We will not group the deployed applications into EAR, WebApp, EJB jar as we did in V2. This is because any deployed application can have multiple sniffers. Under the application tree node, all apps will be listed, and when user clicks on the app, the right frame will show all the sniffers associated with this app. For example, if there is ejb embedded in a war, the sniffer list will show both 'war' and 'ejb'.
Here is a snapshot of the table listing the applications

4.1.4 Grizzly Configuration

This is based on the GrizzlyConfiguration One Pager
GUI team will provide the support for Grizzly Configuration based on the following assumption:
- there is HTTP API to connect to server and do the configuration.
- the conversion from the old <http-service> will be done when server starts up, according to the Compatibility Impact section specified in the one pager.

A new tree node representing the network-config element found in the DTD for Grizzly configuration will be provided. 
This is the navigation tree representing network-config

    *  Network Config Properties

    * Transports Properties
    * Transports   --  Table listing individal transport
          o T1     -- 12 attrs + properties
          o T2
    * Selection-Keys   -- Table listing handlers
          o SK1 --  2 attrs + properties
          o SK2

    * Protocols Properties
    * Protocols    -- Table listing Protocol
          o P1    -- General tab,   http tab,  ssl tab,  port-unification tab, protocol-chain-instance-handler tab, protocol chain tab, Protocol-Filters tab, Protocol-Finders tab.
          o P2

    * Network Listeners  Properties
    * Network Listeners -- Table listing all Network listeners
          o NL1 -- 7 attrs + properties
          o NL2
    * Thread Pools  -- Table listing Thread pools (1+)
          o TP1   -- 6 attrs + properties
          o TP2

  General Tab -- 2 attr +  properties
  http tab -- 14 attr + 4 attrs  for file-cache + properties
  ssl tab -- 11 atr + properties
  port-unification tab  --  2 attr + property table
  protocol-chain-instance-handler tab  -- 2 attr + properties
  protocol-chain-tab -- 3 attrs + property
  protocol-filters tab -- table list out list of filters, creating or editing will bring up the appropriate page.  Since filters are very low level, we will not show that in the navigation tree.
  protocol-finders tab -- table list out list of finders, creating or editing will bring up the appropriate page.  Since finders are very low level, we will not show that in the navigation tree.

According to the above design,  there will be 21 new screens added for this.

The old tree node named Http Service will still exist, but the tabs will be modified according to the 'new' http-serive element found in the updated DTD

4.1.5 Logging support

This is based on the Logging one pager

According to this, any logging.properties that is used to maintain the configuration, any logging related elements that are in the domain.xml file for v2 will be moved to the logging.properties file for v3. GUI will provide 2 screens for this functions: the Logger Settings and Log Level settings for each modules. Depending on the support from backend, the Log Viewer may or may not be available for this release.

To provide the GUI support, it is assumed that there will be HTTP like API  available and that will be responsible for reading and writing the properties to the properties file instead of domain.xml.

The one pager also mentions about supporting the 'retain-error-statistics-for-hours' properties. GUI will assume that the package 'com.sun.appserv.management.ext.logging' and all the interfaces under it, which is available in v2 will be available in v3 as well. Without this package, the current Log Statistics monitoring functionality will not be provided in GUI.

4.1.6 MQ Administration

The MQ Administration support for the v3 September release will achieve at least feature parity with v2.  This includes the following:

• tree node: Connection Factories
• tree node: Destination Resources
• tree node: JMS Hosts
• tree node: Physical Destinations

Based on some community feedback, the following nice-to-have features will be evaluated to determine if time and other resources allow their inclusion:

• Prune (delete) messages in destinations
• Display the number of messages in the destination. Browsing (e.g. displaying the message header, message id and especially the type: TextMessage, BytesMessage, ObjectMessage etc.) would be useful as well.
• Configuration of the max, current number of retries, redirection to DLQ etc. Configuration of the max # of messages in a destination.
• Configuration of transient / persistent destinations.
• Real time throughput monitoring (# msg/second - max and average)
• Display the listeners / receivers and senders / producers (e.g as fully qualified class name)

4.1.7  Nice To Have Features

4.1.7.1 Multi-Domain Support

4.1.7.2 Upgrade Notification

Provide a notification to users when there is a newer version of GlassFish available to allow them to try it out or decide to (manually) upgrade.

4.1.7.3 Dashboard

Customization of common tasks or similar page to have features similar to iGoogle (add various widgets and customize layout to user's preference). This feature could also be applied to the RSS feed page.

4.1.7.4 Server Message Notification

Ability to send important message to users (ex. GlassFish Portfolio Launch) as a pop-up when they log in (similar to registration reminder?)

4.1.7.5 Advertising Widget(s)

Widget to show banner adds to deliver promotions (ex. free training, etc.) - This can be a replacement of the bottom frame (Marketing)

4.1.7.6 Enhanced Web Service Support

• Metro / WSIT administration - setting up policy, etc.
• REST / JERSEY administration

4.2 PE Functionality

This section listed out all the PE functionality that is available in V2 Admin Console, but not in v3 Prelude. If there is any feature that is available in v2 developer profile, but not listed here, it means there is no plan to include that for v3 Sep. release. Any feature which is already in v3 prelude will be part of the sep. release.

4.2.1 EJB 3.1 Support

To provide support for EJB, the following Tree Nodes for navigation and GUI screens will be added. These screens exist in GF 2.1, and will be ported to v3. The following will be implemented as a plugin module to the admin console:

• tree node: EJB Container
  
• 3 tabs: EJB Settings, MDB Settings, EJB Timer Service

The attributes shown in the above screens will be based on the <ejb-container> element in sun-domain_1_3.dtd. If there is any changes in this element for v3, the EJB team should notify the GUI team.

issue: Do we need to provide the EJB Container Availability screen which exists in v2 ?

4.2.2 Transaction Service

To provide support for Transaction Service, the following Tree Node for navigation and GUI screens will be added. These screens exist in GF 2.1, and will be ported to v3. The following will be implemented as a plugin module to the admin console:

• tree node: Transaction Service
• screen: Transaction Service
• screen: Recover Transactions

The attributes shown in the above screens will based on the <transaction-service> element in sun-domain_1_3.dtd. If there is any changes in this element for v3, the EJB team should notify the GUI team.

The Transaction Service screen assumes that AMX mbeans will be available and provide the get/set method for the attributes as usual. However, the support for recovering transaction will need special method to handle it. It is the responsibility of the backend to provide such a method through an AMX Bean .

4.2.3 Resources

The following resource will be supported: Java Mail Resoruce, Connectors Resources, Connector Connection Pools, Admin Object Resources.
Based on input from Kedar, JMS Resources tree node will be removed.
There may not be backend support for JNDI : Custome Resources and External Resources, so GUI will not support this.
A 'Ping' feature will be added to the JDBC Resource, JavaMail Resource and Connector Resources.

4.2.4 Configuration

Assuming the backend support is there, the following will be supported, having the same UI as in v2: ORB IIOP Listeners, Thread Pools, Admin Service, Connector Service, Diagnostic Service, System Properties.
According to Kedar, Management Rules will not be in Sept. release, and so will not be in the GUI.

4.2.5 Monitoring

We will add additional monitoring pages for this release based on the new monitoring lightweight framework.  In V3 Prelude there were monitoring pages available in the admin console for HTTP Service, Web Container and JVM.  The monitoring statistics for these pages were displayed in a tabular form.  Below is a screen shot for the Web Container monitoring data in V3 Prelude:
:

Additional Monitoring Pages:
In the release we will include additional UI pages for displaying monitoring data for the following components.  The data will be presented in a tabular form as well.

a. JPA
b. EJB
c. JDBC
d. JRuby Container
e. (Grizzly) Thread Pool

Monitoring Configuration
In V3 Prelude the admin console provided configuration support for monitoring.  The ability to enable/disable monitoring will continue to be supported for the additional components at a very high level. In future releases there will be support for turning monitoring ON/OFF at the attribute levels.  Below is a screen shot for the monitoring configuration screen in V3 Prelude:


Monitoring Client-Side Script Support
In this release we will also provide the user with the ability to view monitoring data by deploying a client-side script through the admin console.  To learn about the supported scripting languages click here.  The client script can be uploaded or provided directly to the admin console through an html text area component.  We will not provide any client script validation.  The admin console will  provide the user with a list of available supported probes for monitoring.  These probes and their supported parameter names and types will be displayed in a table as a pop-up.  The user will be able to review these probes in the admin console and elect to register and listen to these monitoring probe events in their client-side script.  Once the admin console submits the script to the server for execution it will be necessary to establish a dedicated communication stream in order to display the monitoring responses in real time in the admin console.  This data will be displayed in a table and will be updated as new monitoring data is pushed to the client. The admin console will allow the user to stop the script(via a button) from being executed in order to close the dedicated communication stream.

4.2.6  OnLine Help

In order to decrease the download size of Admin Console, the OLH jar file will not be part of the admin console core module.  It will be hosted on the net such that when user press the Help button, we will bring up another browser window with the correct URL to open up that particular help topic.   Besides having the smaller size benefit,  this also allows any plugin module to host their help set on any machine.   This also solves the technical issues of merging different help set from different plugin module.    Another benefit is that the helpset can be updated anytime and can be localized to other language at a later time.

4.3 UI Design Changes

We will be making a number of User Interface changes. These changes are designed to increase our users' productivity while decreasing the complexity of our application to maintain and develop. These changes make our application more modern and consistent with typical designs that have appeared in web applications over the last several years. Below is a very rough screenshot depicting the features which we intend to introduce:

4.3.1 Remove frameset/frames

Framesets complicate our UI in many ways, as well as increase the load on both the client and the server. We will remove the framesets and use template pages which provide the page layout instead. This should allow the existing content pages in our application to remain mostly unchanged. In some cases we may choose to update content via asynchronous requests to achieve greater efficiency.

4.3.2 Bookmarkable URLs

We will ensure all new pages will be navigable via GET requests. Most existing pages already support this, we may port existing pages which do not support get URLs as time permits.

4.3.3 Move from tree-based navigation to a menu-based approach

We intend to remove the existing primary navigation tool (the tree) and replace it with a number of alternatives. One of the primary replacement schemes will be the use of menus. Menus provide an always visible navigation scheme, but do not consume large amounts of screen real estate. This will give a chance to create an action-oriented UI which is much more logical to users. Note: We need to evaluate how to best group the menus. We may also choose to consider providing multiple choices and/or ability to customize the menus to best server the majority of our users.

Above section removed due based on user response on the forum and blogs. A navigation tree like in v3 Prelude will be provided as before.

4.3.4 Allow tagging pages/windows and searching

We would like to provide a means of tagging and searching for content. This will enable our users for the first time to be able to find our pages via a search feature. A pop-up virtual window will be shown to the user when they press CTRL-F (or some similar shortcut combination, TBD), this dialog will accept tags in which to search from the user. It will then display pages which contain matching tags. Tags must be whole word matches for this release. Case will be ignored. Multiple keywords will return the intersection of the result sets of the given keywords.

Default tags will be defined for all pages we wish to be found via the search mechanism. We will also provide a mechanism for each page to be tagged by tags of our users' choosing. Tags added to pages will be shared across all admin users.

Feedback from community shows that we need to have a better UI for tagging support.  We are re-evaluating this, thus this may not be in the Sept. release.

4.3.5 Move to a more desktop-like approach (windows/dialogs, minimize/maximize, OS X-style dock bar, etc)

A "dock bar" would offer users a "quick launch" mechanism for quickly getting to commonly used pages, or to store access to pages which they already have "open". We will make the doc bar customizable per user so that common tasks for each user can be stored on the doc bar. We will evaluate using the doc bar to store "minimized" windows.

4.3.6 Make use of the Preferences API to allow for per-user customization

Many of the above features will require persistent storage of data on a per user, or across user basis. The Java Preferences API provides support for doing this. We already have API support to access the Preferences API from within our pages. We will leverage this support to store per-user and per-application data to enable a wide range of features: tagging, favorites, default values, menu custimization, personalized windows, etc.

4.4 Bug/RFE Number(s)

1. Display the list of virtual servers a webapp has been deployed to - 490
2. Dynamic reloading a webapp through GUI - 2644
3. Admin GUI should display the complete (un)deployment status message to the user - 3207
4. Add domain name to login screen of admin gui - 3298
5. Add restart link to application table - 3354
6. Allow JDBC driver upload - 3355
7. Improve GUI screen behavior when a config change is rejected on "Save" - 3440
8. Admin GUI behaves differently - 4038
9. Prefill redeploy data page - 4419
10. Use descriptive information found in deployment descriptor - 4486
11. EJB 3.1 Container Is Not Visible In the Admin Console - 5844
12. JPA Persistence Is Not Visible At All In The Admin UI - 5845
13. Rework UI to remove the nav tree and frame set - 6649
14. Editing default-web.xml via Administration UI - 6937
15. Admin-gui should be insulated from JSF (potentially others as well) library changes - 6966
16. Admin console should show deployed web services - 6975

4.5 In Scope

1. UI redesign
2. Full JavaEE 6 support

4.6 Out of Scope

1. High availability
2. Clustering
3. Load balancing
4. Replacing Woodstock

4.7 Interfaces

4.7.1 Exported Interfaces

Interface	Stability	Package Name	Comments
ConsolePluginService	Evolving	org.glassfish.admingui.plugin	Java API
Integration Point	Evolving	org.glassfish.admingui.plugin	through JSFT syntax

4.7.2 Imported interfaces

Interface	Stability	Exporting Project: Name, Specification or other Link.	Comments
HTTP API	Evolving	Generic HTTP API as specified in http://wiki.glassfish.java.net/attach/V3FunctionalSpecs/HTTPInterfaceForAdministartion.html
HK2	Evolving	org.jvnet.hk2.*
Woodstock components	External	http://woodstock.dev.java.net	version 4.3
JSFTemplating	External	http://jsftemplating.dev.java.net	version 1.2
JMaki	External	http://jmaki.dev.java.net	version 1.1
Update Center	External	http://wiki.updatecenter.java.net/Wiki.jsp?page=About	version 2.0
Yahoo! User Interface JavaScript Library (YUI)	External	http://developer.yahoo.com/yui	version 2.6

4.8 Doc Impact

The proposed UI changes will require much of the documentation and screen shots within the documentation to be updated to reflect the new navigation changes and look and feel.  As we are moving to have the OnLine Help set to be hosted on the internet,  this will impact the Doc team on creating the doc and hosting that.

4.9 Admin / Config Impact

4.10 HA Impact

This release will not support high availability, load balancing, clustering, etc.

4.11 I18N / L10N Impact

Localization of Admin Console is needed.

4.12 Packaging & Delivery

The Administration Console will be packaged as a web application archive and shipped with the application server. Updates will be delivered as IPS packages via the Update Center.

4.13 Security Impact

The UI redesign needs to ensure the cross-site scripting (XSS) and other scripting attacks are not possible.  The console must ensure protected content is not accessible to a non-authenticated user.  The console must be capable of running over SSL.

4.14 Compatibility Impact

The UI redesign will likely have some impact on any existing third party Prelude plugins, though this will be limited/mitigated as much as possible.

4.15 Dependencies

See section 4.7.2.

5 Reference Documents

• Jason Lee's blog discussing these changes in detail.

6 Schedule

6.1 Projected Availability

This version of the administration console will ship as part of the GlassFish v3, and will therefore follow its schedule.