Admin Package Summary

Provides an administration server and a browser-based GUI applet that works as an admin client to offer an easy remote GUI for various P2J administration tasks.

Author	Nick Saxon
Date	December 4, 2009
Access Control	CONFIDENTIAL

Introduction
Architecture
Admin Interface
Admin API Implementation
Server Side Extension Plugin
Custom ACL Editors
Client Side Extension Plugin
Private Extension APIs
Adding Base Menu Items
Adding Custom Menu Items
Client Screens
Printing

Introduction

This package is an implementation of the administration subsystem for P2J servers. The Admin Server component implements the admin package interface APIs which are typical P2J net package exports. The APIs are protected as a separate admin resource and ACLs can be created to provide a very refined access to some admin APIs.

A built-in JETTY server provides the initial page to access the admin client as an applet. When the applet loads, it than creates a GUI and allows logging into the admin server.

Architecture

The main principle of the admin package design is the extendability. There is a core set of APIs and the architecture allows extensions to the server and to the APIs (server side plugin), and to the admin clients and their menus (client side plugin). The server side plugin can, in turn, expose some additional private APIs, which the client side plugin can use to talk with the server extension directly.

The server side extension is specified in the /security/config/extensions/server directory node. The plugin must implement the AdminAccountExtension interface. The goal of the server side plugin is to handle the user account extensions - pieces of data that are kept in the directory per account.

The client side extension is specified in the /security/config/extensions/client directory node. The plugin must implement the ClientAccountExtension and AdminCustomMenu interfaces. The goal of the client side plugin is to extend the GUI to include all custom account extensions into the account editors and to add custom menu items to the admin client GUI. The custom menu items, if added, would require calling the private APIs exposed by the server side plugin to perform any server side processing.

Admin Interface

The admin interface is defined in the AdminExports.java There are the following major API classes:

admin session control API
live system console API
general server configuration API
account management API
access control list management API
per server runtime configuration API
per account/server runtime configuration

The admin session control API allows:

get the server name
query the master/slave status of the server
set the session target as the live system or a directory file
refresh the security cache on the live system
manage admin server messages
get the dynamic admin definitions
get the permissions profile for this session

The live system console API allows:

safely reread the directory
backup the directory
list all server sessions
terminate a session
list all locked records
initiate server shutdown

The general server configuration API allows:

list abstract resource names
get resource type by its name
change the set of abstract resources
get and edit the authentication config object
get and edit the list of holidays
get and edit the security audit in effect

The account management API allows:

list, create, clone, edit, delete groups
edit group users
list, create, clone, edit, delete users
edit user groups
list, create, clone, edit, delete processes
list, create, clone, edit, move, delete certificates

The access control list management API allows:

list ACl instances
list ACLs for an instance
get ACLS for an instance
get effective vew of ACLs
create, clone, move, edit and delete ACLs
renumber all ACLs for an instance

The per server runtime configuration API allows management of branches of the directory that are server-specific.
The per account/server runtime configuration API allows management of branches of the directory that are account specific.

Admin API Implementation

All APIs are defined as static methods in the AdminServerImpl.java and often call their worker counterparts implemented in SecurityAdmin.java. When the admin client logs in, the session context is created. It is kept till the logoff. The session context maintains its own copy of the security cache, which gets rebuilt after many directory edits. This copy works as a safety measure to find possible directory problems as early as possible. The session context also indicates the type of the current session target - a live system or a directory file.

Server Side Extension Plugin

The server side extension plugin manages the account extension data. The core routines of the server can recognize only a predefined set of directory nodes that serve as account definitions. Customers may need to keep some extra data per account. To make it possible, a server side extension plugin has to be written. The plugin should plan to use the child nodes of the account nodes in the directory, to store all extra data. Besides being children of the accounts, these extra nodes are fully transparent to the core P2J server. The plugin can chose the number and the format for the account extensions.

The plugin interface methods are called by the server at some key points. The methods are listed below:

isExtended - checks whether the given account node has custom extensions or not
addExtension - creates the directory nodes to save the extensions data to the directory
setExtension - changes the directory nodes that represent the extensions to match the new set of data
cloneExtension - clones existing extension data into another account directory node
deleteExtension - removes the existing extension data, if any

Custom ACL Editors

Since the admin client GUI has to provide ACL editing capability, and ACLs are dependent on the abstract resource plugins, the editors can't be defined and implemented statically in the admin client. The way to do it is to load them dynamically. An ACL editor is a separate class, specific to the abstract resource it's connected with. ACL editors implement the RightsEditor interface. The interface is rather simple and provides the following methods:

initialize - called once after loading the class to give it chance to initialize
createDefaultRights - called whenever a new empty ACL is being created to fill it with what can be considered a good initial rights
edit - called to display a modal editor dialog, do the work, hide the dialog and return the result

Client Side Extension Plugin

The client side extension plugin perfoms the following functions:

it extends the user/process account edit/create dialog to include the extension data
it can add custom menu items, both the major items and submenu items
it performs the menu initiated actions

The interface that the plugin implements for the extension of the edit/create account is defined in the ClientAccountExtension.java. The main admin client code calls the corresponding methods and lets the plugin drive the edit/create dialog.

The interface that the plugin implements for adding custom menus is defined in the AdminCustomMenu.java:

attach - is called once when the plugin is loaded
insertCustomMenuItems - is called to give chance to the plugin to insert all extra menu items at once
removeCustomMenuItems - is called to remove the previously inserted extra menu items

Private Extension APIs

The client side extension plugin, that adds custom menu items, needs some backing services, or APIs, on the server. Those are private extension APIs. They can be implemented and exported in the server side extension plugin and accessed from the client side extension plugin, which must know the meaning of those APIs.

Adding Base Menu Items

If there is a need to extend the existing admin client menu structure, which is not customer-specific, the following two steps have to be taken:

The new menu items, either major or submenu items, have to be defined in the AdminMenu.java file, along with their event handlers.
The defining structure of the granular admin rights has to be adjusted accordingly to make sure the newly added functionality is protected by the AdminResource.java abstract resource plugin

The first task is straight forward. The second task requires changes to the AdminResource.java, as documented in "How to extend existing granular admin rights" document. Plus, the AdminMenu.java file also needs changes in the buildMenu() method where the permissions profile is inspected.

Adding Custom Menu Items

If there is a need to extend the existing admin client menu structure, which is customer-specific, the client side extension plugin should implement it in its insertCustomMenuItems() method. There is no granular admin protection for the custom menu items, though.

Client Screens

Some menu items work through modal dialogs, which are not persistent. Other items maintain some persistent GUI panels, which are called screens. The Admin Client GUI provides the way to switch between screens and preserve their state.

A screen is associated with a menu item. When the item is selected for the first time within the sessionfor a specific target, the event handler creates the screen and adds it to the switcher with some name. Subsequent selections simply switch to the named screen. Screens are implemented as panels of a container managed by the CardLayout in the AdminClient.java.

Screens are added to the switcher by calling the AdminClient.add() methods and can be switched by calling AdminClient.show(). There is a special blank screen, SCREEN_BLANK, that can be switched to whenever the current screen has to be hidden. Refer to the AdminGroupAccounts.java for an example of a screen creation.

Printing

Client screens described above have the capability to print the data on the screen in a tabular format. To print the currently displayed screen, use the Print menu item. The event handler is implemented in the AdminClient.java and handles the print requests for all screens by delegating the request to a screen-specific processor that must have been registered.

Thus, menu items that create printable screens, have to register their own print request processors, which implement the PrintRequest interface. The interface is defined in the PrintRequest.java and is made of the following:

print() - prints the screen's data
canPrintExtended() - queries whether the extended printing is implemented
printExtended() - prints extended data

The print processor may provide either just the regular printing, or both the regular and the extended printing. The regular printing may be sufficient for screens where there aren't too much detail and all pieces of information fit a simple table. If this is not the case, then the regular printing means printing a subset of data items, which are deemed to be the most important. Then, the admin is given an option to get the extended printing. The latter is a differently formatted table, where single item can take as many rows and cells as necessary to cover all data items.

The regular printing works directly with the table that provides data for the screen. It creates a temporary panel with the print preview, offering the choice of printing just the selection or the whole table. The preview panel is temporarily displayed and then the printing can be confirmed or cancelled.

Many of these actions are the same no matter what table is underneath. For this reason, the AdminClient.java implements a worker method printOn() which standardizes the final steps of the printing.

The extended printing creates a new temporary table, synchronizes its contents with the main table, but formats the cells differently. Whneh this work is done, the rest of the printing process is similar to the regular printing.

Another worker method, printExtendedOn() is implemented in the AdminClient.java() to facilitate this work.

Contents