Writing Controls Applications on JavaTM

An overview of the infrastructure for the user application development in Accelerator Controls Department.

June 30, 2003

Andrey Petrov

Agenda

1.1. Application FrameworkApplication Framework

2.2. Application IndexApplication Index

Covered: Development of console user applications.

Not covered: Development of Open Access Clients, servelts, and other server-side programs.

I

Application Application FrameworkFramework

Application Framework Definition

A library of reusable components for the development of console user applications.

Reference guide is Beams-doc-688, or http://www-bd.fnal.gov/controls/java/ framework/af-guide.pdf

Application Framework Functions

Interacts with Application Index services (property repository, heartbeat service, central logging, operation locks, etc.);

Provides a uniform application's look-and-feel (for swing applications);

Implements some common functions (printing, image capture, DAE connection, message window, etc.).

Classpath

framework.jar (gov.jar is not enough), or framework-lite.jar (without swing) mail.jar activation.jar jhall.jar jlfgr-1_0.har govcore.jar jconn2.jar

af_bunch.jar

for DAE connection

Core Application Framework Classes

ApplicationManager – implements most of the functions, not related to GUI;

DaeSupport – serves the DAE connection; Implementations of user interfaces:JControlsFrame, JSimpleControlsFrame, JControlsDialog0, …1, …2.

Application Manager

Singleton; All public methods are static; Must be initialized at the application startup:

public static void main( String[] args ) { ApplicationManager.init( args ); /* rest of the code */ }

Frame & Dialog Hierarchy

Graphical User Interface[JControlsFrame]

JControlsFrame Features

Dynamic GUI generation from the interface descriptors (text files);

Persistent frame size and location; Predefined actions; A "smart" default close operation:

1st frame – EXIT_ON_CLOSE, others – DISPOSE_ON_CLOSE;

Splash screen for the first frame.

Interface Descriptor

An XML file, that describes the appearance of the whole frame, menu bar, toolbar, and status bar;

Has the same name, as the corresponding frame (with .xml extension), and must be placed in the same directory;

Supports inheritance; Three logical levels.

Interface DescriptorStructure

<frame … > 1. root element

<menu id="…"> 2. element description

item1 3. sub-element IDs item2 item3

</menu>

</frame>

Inheritance of Interface Descriptors

Interface Descriptor Example I

<frame menuBarID="MenuBar" toolBarID="ToolBar" statusBarID="StatusBar" restoreSize="true" restoreLocation="true" visibleOnStartup="true">

<!-- code omitted -->

</frame>

Interface Descriptor Example II

<tool_bar id="ToolBar">

Cut Copy Paste

</tool_bar>

<item id="Cut" mnemonic="t" actionCommand= "CutAction" accelerator= "Ctrl+X" icon="…" enabled="false"

/>

Interface Descriptor Example III

MyFrame.xml

<tool_bar id="ToolBar">

!default Delete

</tool_bar>

JControlsFrame.xml

<tool_bar id="ToolBar">

Cut Copy Paste

</tool_bar>

Polymorphism

<item id="Cut"mnemonic="t"actionCommand= "CutAction"accelerator= "Ctrl+X"icon="…"enabled="false"

/>

Getting GUI Components

ControlsWidget w = getWidget( "Cut" );

w.setEnabled( true );w.setSelected( false ); // radio buttonsw.setText( "Any Key" );

Object[] objs = w.getComponents();

Handling Events

Action a = new AbstractAction() {public void actionPerformed( ActionEvent e ) { System.out.println( "!!!" ); }}

getActionMap().put( "CutAction", a );

Predefined Actions

Export To File Send Mail Post E-log Message Print Page Setup Cut Copy Copy Special Paste

Select All DAE Connection Message Viewer Application Properties Logging Help Topics About Exit

Custom Frame Initialization

jbInit method is used for the custom initialization of the frame (e.g., placing elements on the content pane).

jbInit should not be called explicitly (this is a duty of JControlsFrame);

The local variables are not initialized when jbInit is invoked — see documentation…

"Hidden" Functions ofApplication Framework

Access to the property repository; Self-determination service (application finds

itself in the Application Index database); Heartbeat service (application notifies

Application Index, that it is running); Operation locks; Central logging.

Application Properties

Named string values, used for program configuration and keeping of persistent data;

Properties are stored in local files and on the server;

Name and value < 256 chars both.

Property Sources

1. Global framework configuration file(the user can not change it);

2. Application property file(optional, created by the user);

3. Property repository on the server(user may have write access).

Loading order: 1 2 3.

Application Property File

<app_name>.properties,where app_name – name of the main class; property file must be placed in the same directory.

application.title=Test Application application.version=0.1.2 application.author=Andrey Petrovdae.connect=1

Property Repository

http://www-bd.fnal.gov/appix/select/props

Used to manage properties online and store data changed in running applications (e.g., user e-mail).

Properties can be user-specific and application-specific.

Properties, changed in running applications, are always user-specific.

Using Properties In Application

Properties p = ApplicationManager.getProperties();

String s = p.getProperty( "foo" );

// "foo=new_value" will be stored// on the serverp.setProperty( "foo", "new_value" );

Self-determination Service

Determines the application's main class and type of the launcher (standalone, web-startable, etc.);

Search for the application's description in Application Index database;

ApplicationManager.getAppDescriptor();

Heartbeat Service

Notifies Application Index, that the application is launched or terminated;

Notifies Application Index, that the application is running (every 6 minutes); application usage history is available online.

Available only for the registered applications.

framework.heartbeat=0 disables

Operation Lock Service

Allows to set named locks in order to avoid the concurrent execution of critical routines in multiple instances of one application.

Locks are automatically released at the application termination;

Available only for the registered applications.

Operation Lock Example

try { ApplicationManager. setOperationLock( "foo" );} catch (Exception ex) { // The lock is already set}

ApplicationManager. releaseOperationLock( "foo" );

Central Logging

Instead of System.out.println( … ); Logging records are stored in a database on

the server side and available online; Automated purge (once a day), every

application may have an individual "storage time" for logging records (default – 1 day).

Available only for the registered applications.

Logging API

Logger log = Logger.getLogger( "…" );

log.warning( "This is a warning" );

try { // some code} catch (Exception ex) { log.log( Level.SEVERE, "Error", ex );}

Logging Configuration

Custom handlers: MessageViewerHandler, AppixHandler;

Configuration through application properties (default values – in property files);

Configuration at the runtime through GUI (stored in the property repository).

Logging Configuration Dialog

DAE Connection

DAE connection = getting of DaqUser object; For the console applications, DaqUser must

be obtained from Application Manager. Then DaqUser is used to create DAQ jobs.

DAE Connection Requirements

Client machine must be inside the firewall; Two libraries are required in the classpath: govcore.jar and jconn2.jar.

User, node, and application must have enough privileges to do settings.

DAE Connection GUI

Getting DaqUser

ApplicationManager.getDaqUser();

Returns either DaqUser instance, or null; Application (service) permissions are

automatically set in DaqUser; Do not cache DaqUser in the program!

DaeConnectionListener

public void daeStatusChange( short oldStatus, short newStatus );

public void settingsLockChange( boolean newVal );

public void daeException( Exception exception );

ApplicationManager.getDaeSupport(). addDaeConnectionListener( … );

Settings

By default, settings are locked, except of the Main Control Room users;

Maximum unlock time is considered; Settings may be unlocked from GUI. Do not unlock settings programmatically in

productional versions!

DAE Connection Configuration

dae.enabled 1/0 App. prop. file

dae.connect 1/0 App. prop. file

dae.name String On the server

dae.name.fixed String App. prop. file

dae.unlock.time(debug only!)

Int (minutes)

App. prop. file

DAE Security

DAE uses a user/node pair for authorization; If this pair is not found in DB, the Kerberos

authentication is requested; All users with valid user/node combination

are allowed to do readings; Users, nodes, and applications have settings

privileges and maximum unlock time;

DAE Security – Example

Security Service

Will be ready soon; “Single Sign-On” based on MIT Kerberos; In most cases will use existing cached

Kerberos ticket (JAAS extension); This ticket will be forwarded to the server

(servlets?), in order to present the client-side user (GSS-API).

II

Application IndexApplication Index

(APPiX)(APPiX)

Application Index Funtions

Keeps all information on applications in the database;

Provides GUI for editing and monitoring of application data;

Provides data for the running applications through web-services.

APPiX Architecture

Representation Of An Application In Database

Application Index GUI

Main page: http://www-bd.fnal.gov/appix An applet-based application launcher; Standalone application launcher; Read-only access for all (except of a small

restricted area); Authentication required to modify data; From outside Fermilab – read-only access

ever.

Launching An Application

Web launcher (based on an applet), and Standalone application browser (web-startable itself);

7 program types, each has own launching procedure;

Web launcher does not support STDALONE type;

Program Types

JWS-AUTO JRE

JWS-MANUAL JRE

STDALONE JRE, P:\

HTML –

SYNOPTIC SVG

EXCEL MS Excel

APPLET Java plug-in

JWS-AUTO Programs

A dynamic generation of JNLP file, basing on the application record in the database.

User does not have to write and maintain JNLP file.

JNLP generator is being kept up-to-date (to resolve certain JRE bugs, etc.).

Application Tree

Top level – machine name (B, C, F, …); There may be several references to one

application; Each reference may have individual

command line arguments (STDALONE, JWS-AUTO).

Information Needed To Register An Application

Application Name Application description < 256 chars; Help URL, if any; Responsible person; Program type; Main class (STDALONE, JWS-AUTO), or URL; Required libraries (jars); Desired place in the application tree;

Q & A

Project URL:http://www-bd.fnal.gov/appix

All questions:apetrov@fnal.govapetrov@fnal.gov