au.gov.aao.drama
Class DramaMonitor

java.lang.Object
  au.gov.aao.drama.DramaPath.ResponseHandler
      au.gov.aao.drama.DramaMonitor

public class DramaMonitor
extends DramaPath.ResponseHandler

This class implements parameter monitoring in a DRAMA task written in Java - allowing a JAVA DRAMA task to set up DRAMA parameter monitoring in other DRAMA tasks.

This class extends DramaPath.ResponseHandler - that is, it implements a handler for DRAMA messages sent using a DramaPath object. The various constructors in this class use DramaPath.Monitor to send a DRAMA Monitor messages to the specified task. The arguments to the constructor determine what is being monitored. Both normal montior (parameter changes sent to task which initiated the monitor) and forward monitors (parameter changes sent to a third task) can be sent.

Each constructor takes an argument of class DramaMonitor.MonResponse. The DramaMonitor.MonResponse class provides for handling of each of the four possible monitor releated events, being SuccessCompletion (the monitor transaction has completed without error), ErrorCompletion (the monitor transaction has completed with error), Started (the monitor transaction has started) and Changed (The value of a monitored parameter has changed).

This class overrides the Success(), Trigger() and Error() methods of DramaPath.ResponseHandler and relies on its own versions of those methods to implement its functionality and thus these are tagged as final to prevent overriding of them.

DRAMA Monitor operations are started by the DramaMonitor constructors. There are two constructors - one which starts a normal monitor and one which starts a Forward monitor.

The normal monitor is started with the following constructor.

    public DramaMonitor(
       DramaPath Path,                   // Path to send the monitor to.
       DramaMonitor.MonResponse handler, // A handler to invoke with messages
       boolean SendCurrent,              // Are the current values sent now ?
       String parameters[])              // The parameters to monitor
         throws DramaException;

Foward monitors are started with this constructor

   public DramaMonitor(
       DramaPath Path,                   // Path to send the monitor to.
       String    Task,                   // Task to foward too
       String    Action,                 // Action in Task to forward too
       DramaMonitor.MonResponse handler, // A handler to invoke with messages
       boolean SendCurrent,              // Are the current values sent now ?
       String parameters[])              // The parameters to monitor
       throws DramaException;

Versions of these exist which take a single parameter instead of an array. Additional, versions which just start the montior but specify no parameters also exist.

DramaMonitor methods of interest are Add() to add a new parameter to the list being monitored, Delete() to remove a parameter from the list being monitored and Cancel() to cancel a monitor operation. See the class definition for details of the arguments for these methods. Note that these methods send DRAMA messages which peform the required interactions.

The DramaMonitor.MonResponse class is the handler for the responses ie. it provides a way for you to be notified of parameter value changes and other messages involved in the monitor operation. (this is the same role as a DramaPath.ResponseHandler class has for the DramaPath class).

You can sub-class DramaMonitor.MonResponse to override certain aspects of handling monitor messages. You might want to override the following methods.

public boolean SuccessCompletion(DramaMonitor, DramaTask) throws DramaException;

Invoked when a monitor completes sucessfully. It should return false is the thread of control is complete or true if you have started another message (it is normally only invoked as a result of Cancel() being inovked.

public boolean ErrorCompletion(DramaMonitor, DramaTask) throws DramaException;

Invoked if the monitor completes with an error. It should return false is the thread of control is complete or true if you have started another message.

public void Started(DramaMonitor, DramaTask) throws DramaException;

Invoked when the monitor started message is received.

public void Changed(DramaMonitor, DramaTask, String, Arg) throws DramaException;

Invoked each time a monitored parameter changed (normal monitors only, not forward monitors). The name of the parameter which has changed and the Sds structure containing its value are supplied.

Version:

@(#) $Id: ACMM:DramaJava/DramaMonitor.java,v 3.52 17-Sep-2009 14:08:22+10 tjf $

Author:

Tony Farrell

See Also:

DramaTask, DramaPath, DramaException, DramaStatus, Arg, SdsID

Nested Class Summary

static class

DramaMonitor.MonResponse Used to handle DramaMonitor responses.

Field Summary

static String

RCSID The RCS (ACMM) ID.

Constructor Summary

DramaMonitor(DramaPath Path, DramaMonitor.MonResponse MRhandler)
Constructor - Start up a monitor operation (no parameters).

DramaMonitor(DramaPath Path, DramaMonitor.MonResponse MRhandler, boolean SendCurrent, String parameter)
Constructor - Start a monitor operation (single parameter).

DramaMonitor(DramaPath Path, DramaMonitor.MonResponse MRhandler, boolean SendCurrent, String[] parameters)
Constructor - Start a monitor operation (multiple parameters).

DramaMonitor(DramaPath Path, String MTask, String Action, DramaMonitor.MonResponse MRhandler)
Constructor - Start a forward monitor operation (no parameters).

DramaMonitor(DramaPath Path, String MTask, String Action, DramaMonitor.MonResponse MRhandler, boolean SendCurrent, String parameter)
Constructor - Start a forward monitor operation (single parameter).

DramaMonitor(DramaPath Path, String MTask, String Action, DramaMonitor.MonResponse MRhandler, boolean SendCurrent, String[] parameters)
Constructor - Start a forward monitor operation (multiple parameters).

Method Summary

void	Add(String Name, DramaPath.ResponseHandler Handler) Send a monitor ADD message to the task assocaited with this monitor.
void	Cancel(DramaPath.ResponseHandler handler) Send a monitor CANCEL message to the task assocaited with this monitor.
void	Delete(String Name, DramaPath.ResponseHandler handler) Send a monitor DELETE message to the task assocaited with this monitor.
boolean	Error(DramaPath path, DramaTask task) Override of DramaPath.ResponseHandler.Error() routine - used internally to implement functionally.
DramaPath	Path() Return the DRAMA Path assocaited with a monitor
boolean	Success(DramaPath path, DramaTask task) Override of DramaPath.ResponseHandler.Success() routine - used internally to implement functionally.
boolean	Trigger(DramaPath path, DramaTask task) Override of DramaPath.ResponseHandler.Trigger() routine - used internally to implement functionally.

Methods inherited from class au.gov.aao.drama.DramaPath.ResponseHandler

Ers, Forget, Forgotten, Msg

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

RCSID

public static final String RCSID

The RCS (ACMM) ID. This field returns the source code archive ID of this class's source file.

The returned string corresponds to the version string seen above (in the class description comments), but will contain the version details of the compiled class file's actual source file.

(ACMM is the source code archive system used by the AAO. If the string returned by RCSID does not contain the string ACMM, then it is likely the source code has been archived again outside the AAO).

See Also:

Constant Field Values

Constructor Detail

DramaMonitor

public DramaMonitor(DramaPath Path,
                    DramaMonitor.MonResponse MRhandler,
                    boolean SendCurrent,
                    String[] parameters)
             throws DramaException

Constructor - Start a monitor operation (multiple parameters).

Sends a DRAMA monitor message along the specified path to initiate monitoring of the specified parameters. The names any number of parameters may be specified.

Parameters:

Path - The Path of the task to send the monitor message to. The DramaMonitor.GetPath() method must have already been invoked and completed successfully.

MRhandler - The monitor response handler to use to respond to parameter value changed messages and other releated DRAMA messages.

SendCurrent - If true, the current values of parameters to be monitored are sent immediately instead of waiting for the first change.

parameters - The names of parameters in the task, indicated by path, which are to be monitored.

Throws:

DramaException - Thrown on errors in the DRAMA code.

DramaMonitor

public DramaMonitor(DramaPath Path,
                    DramaMonitor.MonResponse MRhandler,
                    boolean SendCurrent,
                    String parameter)
             throws DramaException

Constructor - Start a monitor operation (single parameter).

Sends a DRAMA monitor message along the specified path to initiate monitoring of the specified parameter. This version take the name of a single parameter to be monitored.

Parameters:

Path - The Path of the task to send the monitor message to. The DramaMonitor.GetPath() method must have already been invoked and completed successfully.

MRhandler - The monitor response handler to use to respond to parameter value changed messages and other releated DRAMA messages.

SendCurrent - If true, the current values of parameters to be monitored are sent immediately instead of waiting for the first change.

parameter - The name of a parameter in the task indicated by path, which is to be monitored.

Throws:

DramaException - Thrown on errors in the DRAMA code.

DramaMonitor

public DramaMonitor(DramaPath Path,
                    DramaMonitor.MonResponse MRhandler)
             throws DramaException

Constructor - Start up a monitor operation (no parameters).

Sends a DRAMA monitor message along the specified path to initiate monitoring of parameters. In this version, no parameters are specified. After the monitoring operation has started, You can use the

Parameters:

Path - The Path of the task to send the monitor message to. The DramaMonitor.GetPath() method must have already been invoked and completed successfully.

MRhandler - The monitor response handler to use to respond to parameter value changed messages and other releated DRAMA messages.

Throws:

DramaException - Thrown on errors in the DRAMA code.

DramaMonitor

public DramaMonitor(DramaPath Path,
                    String MTask,
                    String Action,
                    DramaMonitor.MonResponse MRhandler,
                    boolean SendCurrent,
                    String[] parameters)
             throws DramaException

Constructor - Start a forward monitor operation (multiple parameters).

Sends a DRAMA forward monitor message along the specified path to initiate monitoring of the specified parameters. The names any number of parameters may be specified. Instead of the sending task being notified of parameter value changes, the specified action is sent to the specified task with the new parameter value as the action argument.

Parameters:

Path - The Path of the task to send the monitor message to. The DramaMonitor.GetPath() method must have already been invoked and completed successfully.

MTask - The name of the task to send the value of the monitored parameters too.

Action - The action in MTask to invoked when the value of the monitored parameters change.

MRhandler - The monitor response handler to use to respond releated DRAMA messages.

SendCurrent - If true, the current values of parameters to be monitored are sent immediately instead of waiting for the first change.

parameters - The names of parameters in the task, indicated by path, which are to be monitored.

Throws:

DramaException - Thrown on errors in the DRAMA code.

DramaMonitor

public DramaMonitor(DramaPath Path,
                    String MTask,
                    String Action,
                    DramaMonitor.MonResponse MRhandler,
                    boolean SendCurrent,
                    String parameter)
             throws DramaException

Constructor - Start a forward monitor operation (single parameter).

Sends a DRAMA forward monitor message along the specified path to initiate monitoring of the specified parameters. The names a single parameter may be specified. Instead of the sending task being notified of parameter value changes, the specified action is sent to the specified task, with the new parameter value as the action argument.

Parameters:

Path - The Path of the task to send the monitor message to. The DramaMonitor.GetPath() method must have already been invoked and completed successfully.

MTask - The task to send the values of the monitored parameters too.

Action - The action in MTask to invoked when the value of the monitored parameters change.

MRhandler - The monitor response handler to use to respond releated DRAMA messages.

SendCurrent - If true, the current values of parameters to be monitored are sent immediately instead of waiting for the first change.

parameter - A single parameter in the task indicated by Path, which is to be monitored.

Throws:

DramaException - Thrown on errors in the DRAMA code.

DramaMonitor

public DramaMonitor(DramaPath Path,
                    String MTask,
                    String Action,
                    DramaMonitor.MonResponse MRhandler)
             throws DramaException

Constructor - Start a forward monitor operation (no parameters).

Sends a DRAMA forward monitor message along the specified path to initiate monitoring of the specified parameters. In this version, no parameter name are specified. After the monitoring operation has stared, You can use the

Parameters:

Path - The Path of the task to send the monitor message to. The DramaMonitor.GetPath() method must have already been invoked and completed successfully.

MTask - The task to send the values of the monitored parameters too.

Action - The action in MTask to invoked when the values of the monitored parameters change.

MRhandler - The monitor response handler to use to respond releated DRAMA messages.

Throws:

DramaException - Thrown on errors in the DRAMA code.

Method Detail

Path

public DramaPath Path()

Return the DRAMA Path assocaited with a monitor

Returns:

The path.

Success

public final boolean Success(DramaPath path,
                             DramaTask task)
                      throws DramaException

Override of DramaPath.ResponseHandler.Success() routine - used internally to implement functionally.

Overrides:

Success in class DramaPath.ResponseHandler

Parameters:

path - The DRAMA path indicating where DRAMA task the message is from.

task - The DRAMA task which originated the message.

Throws:

DramaException - Thrown on errors in the DRAMA code.

Error

public final boolean Error(DramaPath path,
                           DramaTask task)
                    throws DramaException

Override of DramaPath.ResponseHandler.Error() routine - used internally to implement functionally.

Overrides:

Error in class DramaPath.ResponseHandler

Parameters:

path - The DRAMA path indicating where DRAMA task the message is from.

task - The DRAMA task which originated the message.

Throws:

DramaException - Thrown on errors in the DRAMA code.

Trigger

public final boolean Trigger(DramaPath path,
                             DramaTask task)
                      throws DramaException

Override of DramaPath.ResponseHandler.Trigger() routine - used internally to implement functionally.

Overrides:

Trigger in class DramaPath.ResponseHandler

Parameters:

path - The DRAMA path indicating where DRAMA task the message is from.

task - The DRAMA task which originated the message.

Throws:

DramaException - Thrown on errors in the DRAMA code.

Add

public void Add(String Name,
                DramaPath.ResponseHandler Handler)
         throws DramaException

Send a monitor ADD message to the task assocaited with this monitor.

This method sends a MONITOR type message with name ADD to the task the DramaMonitor object refers to, adding the specified parameter to the list of parameters being monitored.

Parameters:

Name - The name of the parameter to add to those being monitored

Handler - Used to handle replies to this message. See DramaPath for details.

Throws:

DramaException - Thrown on errors in the DRAMA code.

Delete

public void Delete(String Name,
                   DramaPath.ResponseHandler handler)
            throws DramaException

Send a monitor DELETE message to the task assocaited with this monitor.

This method sends a MONITOR type message with name DELETE to the task the DramaMonitor object refers too, deleting the specified parameter to the list of parameters being monitored.

Parameters:

Name - The name of the parameter to delete from those being monitored

handler - Used to handle replies to this message. See DramaPath for details.

Throws:

DramaException - Thrown on errors in the DRAMA code.

Cancel

public void Cancel(DramaPath.ResponseHandler handler)
            throws DramaException

Send a monitor CANCEL message to the task assocaited with this monitor.

This method sends a MONITOR type message with name CANCEL to the task the DramaMonitor object refers too, causing the monitor transaction to be canclled.

Parameters:

handler - Used to handle replies to this message. See DramaPath for details.

Throws:

DramaException - Thrown on errors in the DRAMA code.