Kepler Monitor Icons
Carlos Rueda
$Id: README.txt 6562 2007-10-28 00:13:44Z rueda $

Status: Experimental; the current version is intended to serve as
a proof of concept and as a means to facilitate feedback. The module 
is subject to change at any time.

Overview

	- For users
	- For developers
	
	
For users
---------
To associate monitoring icons to the entities in a workflow, just insert
an instance of the org.kepler.monitor.MonitorManager attribute. You can do 
this by using the "Instantiate attribute" option in the "Tools" menu.
A more direct mechanism will eventually be provided in a future version.

By default, the MonitorManager will associate monitoring icons for both
actors and opaque composite entities in the workflow. This is done at
execution time. The icons will be destroyed when the execution is
completed. A monitor icon is placed close to the monitored element, and 
its location is automatically updated whenever the monitored element is 
relocated; this follows a simple scheme for now.

Currently, the possible icon styles are:
	- traffic light (various styles)
	- progress bar (indeterminate and determinate a la JProgressBar)
	- simple label (eg., for counters)
	
A parameter in the MonitorManager allows to specify which style to be used
for the entities in the workflow, but this style is currently applied on 
all actors. Other parameters allow to specify if input and/or output
ports should be assigned monitor icons as token counters.

The style for each monitor attribute can be changed during execution by 
opening the corresponding parameter window, but the changes will apply 
only for the current execution.

Running a demo:
   cd $KEPLER
   ant -Dworkflow=workflows/test/monitor/monitor-0.xml run-wf

Some TODOs
----------
 - improve configurability for the user
 - properly handle composite entities
 - Counters for composite actor ports are not properly placed
 - fix bug: concurrent modification exceptions are thrown sometimes
 - for you: test and provide feedback :)


For developers
--------------
Package org.kepler.monitor.test contains some demo actors that explicitly
use some of the monitor icons. To run a test:
   cd $KEPLER
   ant -Dworkflow=workflows/test/monitor/monitor-1.xml run-wf


Design notes

Still very terse. Please, see source code for more details or send me an 
email.

Main package: org.kepler.monitor
	MonitorManager
	MonitorAttribute
	MonitorIcon
	MonitoredStatus
	FigureUpdater
Figure package: org.kepler.monitor.figure
	BaseFigure
	ProgressBarFigure
	TrafficLightFigure
Test package: org.kepler.monitor.test
	
The MonitorManager automatically associates monitoring icons to the entities
in a workflow including counters for input and output ports. Both actors and
(to some extent) composite entities are handled. The manager inserts a 
MonitorAttribute for each monitored element. A MonitorAttribute contains a 
MonitorIcon. All changes are made non-persistent. The actual appearance of 
the icons is determined by the figure in the icon. Various styles are included
in the org.kepler.monitor.figure package. The updates are triggered by a 
FigureUpdater object in reaction to property changes ocurring in a MonitoredStatus
 object. See the example code in the org.kepler.monitor.test package.

The MonitorManager registers a PortEventListener to each port of the monitored
entities to update the status of the figures. Also, MonitorManager registers an
Initializable object so the icons are created at runtime and destroyed when the
execution finishes. It also registers a GraphViewListener so the location of 
the icons are updated when their monitored objects are moved on the canvas.

