FourMS
Class SequenceSubaction

java.lang.Object
  FourMS.SequenceSubaction

All Implemented Interfaces:

SubActionCompletionListenerOperations, java.lang.Runnable

Direct Known Subclasses:

UpdateOpticalComponentList

public abstract class SequenceSubaction
extends java.lang.Object
implements java.lang.Runnable, SubActionCompletionListenerOperations

This is a base class which will be used by the instrument controller tasks to create compound high level, sequence actions. For example in the case of the PFIP controller, there exists a single subaction which can be used to set the position of both of the ADC elements.

This class provides base functionality which can be inherited and subsequently used by such classes. Note that this class is abstract and should only be used as a super class.

Author:

Craige Bevil

Field Summary

protected SubActionCompletionListener	ActionCompletionListener A CORBA reference to the action completion listener which can be used by a subclass in order to pass things about
protected SubActionCompletionListenerImpl	ActionCompletionListenerImpl This is a CORBA listener object which will be called when a subaction that this object has initiated completes.
protected int	ActionState This is the current state of the action.
protected int	ExpectedNoOfArgs Indicates the number of arguments which are expected for this subaction when initiated by a CORBA client.
protected java.lang.String	InstrumentName Name of the Instrument
protected int	NumberOfSubactionsInSequenceOutstanding Number of subactions which have been started by the subclass simultaneously and need to be tracked for completion.
protected org.omg.CORBA.ORB	Orb The CORBA request broker or ORB which will be used for handling CORBA requests
protected iParameterNoticeBoard.ParameterNoticeBoardSupplier	ParameterNoticeBoard This is reference to the remote proxy CORBA object which will be used to access the parameter noticeboard
protected org.omg.PortableServer.POA	Poa The portable object adapter which will be used by this class
protected org.omg.CosNaming.NamingContextExt	RootNamingServiceContext This is a reference to the COS naming service
protected int	SecondsBeforeTimeout This holds the amount of time before the subaction sequence times out.
protected SubActionCompletionListener	SequenceSubActionInitiatorCB If specified by the CORBA client when the subaction sequence was initiated, a CORBA subaction completion object which will be informed when the sequence subaction has completed.
protected java.lang.String	SequenceSubactionName This is the name of the sequence subaction
protected java.lang.String[]	SubactionArgumentList This is a copy of the list of arguments associated with the current invocation of the subaction, this will be set when the subaction is initiated
protected java.lang.Thread	SubactionThread This is a thread which the subaction can run within so control can immediately be returned to the caller should it be necessary.
protected MessageHandler	SyslogMessageHandler An instance of the a syslog message handler which will be used to put messages into the syslog.
protected int	TimeOut This is the timeout for an an a 4MS dialogue sequence to complete before the subaction is considered failed.

Constructor Summary

SequenceSubaction()
The default constructor, this should only be used if you are NOT intending using any of the functionality within the super class

SequenceSubaction(java.lang.String InstrumentName, org.omg.PortableServer.POA Poa, org.omg.CORBA.ORB Orb, MessageHandler SyslogMessageHandler, org.omg.CosNaming.NamingContextExt RootNamingServiceContext, java.lang.String SequenceSubactionName)
This is the constructor and will be used to create a subaction listener which can be used to listen for subactions completing

Method Summary

boolean	cancelAction() We have to specify this but we do not implement it.
protected void	informSubactionInitiator() Informs the subaction initiator that the subaction that he initiated has completed, it uses the data items returned by the last subaction initiated by this subclass when reporting that the subaction has finished.
protected void	informSubactionInitiator(java.lang.String SubactionName, java.lang.String MechanismName, java.lang.String InstrumentName, int ReasonCode, java.lang.String Reason, int CmdError, java.lang.String CmdErrorStr, int MechError, java.lang.String Severity, java.lang.String MechErrorStr) Used to inform a subaction initiator that a subaction is completed.
void	registerSubactionInNameService(SubActionPOATie SubActionPseudoImpl) Registers the sequence subaction with the name service so that other CORBA clients can use it.
protected void	returnResult(java.lang.String Message, int SubactionCompletionState) Packages up the code which informs the sequence subaction client of the result of the subaction.
boolean	startAction(java.lang.String[] subactionArgs, SubActionCompletionListener subActionInitiator) This method starts the subaction.
void	subActionEnded(java.lang.String SubactionName, java.lang.String MechanismName, java.lang.String InstrumentName, int ReasonCode, java.lang.String Reason, int CmdError, java.lang.String CmdErrorStr, int MechError, java.lang.String Severity, java.lang.String MechErrorStr) This is the contractual obligation of this class to implement the callback for the SubActionCompletionListenerOperations interface.
boolean	waitForActionToComplete(java.lang.String ErrorString) This method is called if the subclass wants to execute the current subaction of the sequence subaction synchronously.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Runnable

run

Field Detail

TimeOut

protected int TimeOut

This is the timeout for an an a 4MS dialogue sequence to complete before the subaction is considered failed. By default the timeout is set to 0 to indicate that no timeout is in place.

ExpectedNoOfArgs

protected int ExpectedNoOfArgs

Indicates the number of arguments which are expected for this subaction when initiated by a CORBA client.

SubactionArgumentList

protected java.lang.String[] SubactionArgumentList

This is a copy of the list of arguments associated with the current invocation of the subaction, this will be set when the subaction is initiated

InstrumentName

protected java.lang.String InstrumentName

Name of the Instrument

SequenceSubactionName

protected java.lang.String SequenceSubactionName

This is the name of the sequence subaction

SequenceSubActionInitiatorCB

protected SubActionCompletionListener SequenceSubActionInitiatorCB

If specified by the CORBA client when the subaction sequence was initiated, a CORBA subaction completion object which will be informed when the sequence subaction has completed.

NumberOfSubactionsInSequenceOutstanding

protected int NumberOfSubactionsInSequenceOutstanding

Number of subactions which have been started by the subclass simultaneously and need to be tracked for completion. For instance in the case of the MOVE_ADC subaction in PFIP, there will be two subactions initiated which will result in both the ADI and the ADO being moved.

ActionCompletionListenerImpl

protected SubActionCompletionListenerImpl ActionCompletionListenerImpl

This is a CORBA listener object which will be called when a subaction that this object has initiated completes. This will be called as part of a one-way callback from the CORBA subaction that a subclass of this class initiates.

ActionCompletionListener

protected SubActionCompletionListener ActionCompletionListener

A CORBA reference to the action completion listener which can be used by a subclass in order to pass things about

SubactionThread

protected java.lang.Thread SubactionThread

This is a thread which the subaction can run within so control can immediately be returned to the caller should it be necessary. The subclass should override the run method in order to contain the semantics associated with the compound sequence subaction.

ActionState

protected int ActionState

This is the current state of the action. It can be in one of the following states

SUBACTIONIDLE

SUBACTIONINPROGRESS

Both of these constants can be found in the FourMSConstants class.

SecondsBeforeTimeout

protected int SecondsBeforeTimeout

This holds the amount of time before the subaction sequence times out. If this is set to 0 then no timeout will be used. Note that most of the subactions will have timeouts associated with them so there will be little need to use this feature as the lower level actions should time out automatically.

SyslogMessageHandler

protected MessageHandler SyslogMessageHandler

An instance of the a syslog message handler which will be used to put messages into the syslog.

RootNamingServiceContext

protected org.omg.CosNaming.NamingContextExt RootNamingServiceContext

This is a reference to the COS naming service

Orb

protected org.omg.CORBA.ORB Orb

The CORBA request broker or ORB which will be used for handling CORBA requests

Poa

protected org.omg.PortableServer.POA Poa

The portable object adapter which will be used by this class

ParameterNoticeBoard

protected iParameterNoticeBoard.ParameterNoticeBoardSupplier ParameterNoticeBoard

This is reference to the remote proxy CORBA object which will be used to access the parameter noticeboard

Constructor Detail

SequenceSubaction

public SequenceSubaction()

The default constructor, this should only be used if you are NOT intending using any of the functionality within the super class

SequenceSubaction

public SequenceSubaction(java.lang.String InstrumentName,
                         org.omg.PortableServer.POA Poa,
                         org.omg.CORBA.ORB Orb,
                         MessageHandler SyslogMessageHandler,
                         org.omg.CosNaming.NamingContextExt RootNamingServiceContext,
                         java.lang.String SequenceSubactionName)

This is the constructor and will be used to create a subaction listener which can be used to listen for subactions completing

Method Detail

subActionEnded

public void subActionEnded(java.lang.String SubactionName,
                           java.lang.String MechanismName,
                           java.lang.String InstrumentName,
                           int ReasonCode,
                           java.lang.String Reason,
                           int CmdError,
                           java.lang.String CmdErrorStr,
                           int MechError,
                           java.lang.String Severity,
                           java.lang.String MechErrorStr)

This is the contractual obligation of this class to implement the callback for the SubActionCompletionListenerOperations interface.

Note that in the case of the compound subactions, not all of these fields will be relevent.

Specified by:

subActionEnded in interface SubActionCompletionListenerOperations

Parameters:

SubactionName - This is the name of the subaction which has completed

MechanismName - This is the name of the mechanism which is associated with the subaction which has completed

InstrumentName - This is the name of the instrument

ReasonCode - This is the code associated with any failure

Reason - This is the textual representation of any failure to execute a command

CmdError - This is the command error code associated with a subaction completing

CmdErrorStr - This is the textual representation of the command error code

MechError - This is the error code associated with any mechanism failure.

Severity - This is the severity of any error which was encountered

MechErrorStr - This is a textual representation of any error which ocurred with a mechanism

registerSubactionInNameService

public void registerSubactionInNameService(SubActionPOATie SubActionPseudoImpl)

Registers the sequence subaction with the name service so that other CORBA clients can use it. The object will be stored in the name service using the following nonemclature,

Controller/SequenceActions/

Parameters:

SubActionPseudoImpl - This is the CORBA object which is to be registered into the name service

informSubactionInitiator

protected void informSubactionInitiator(java.lang.String SubactionName,
                                        java.lang.String MechanismName,
                                        java.lang.String InstrumentName,
                                        int ReasonCode,
                                        java.lang.String Reason,
                                        int CmdError,
                                        java.lang.String CmdErrorStr,
                                        int MechError,
                                        java.lang.String Severity,
                                        java.lang.String MechErrorStr)

Used to inform a subaction initiator that a subaction is completed. It is a convenience method which bundles up all of the error handling also

Parameters:

SubactionName - This is the name of the subaction which has completed

MechanismName - This is the name of the mechanism which is associated with the subaction which has completed

InstrumentName - This is the name of the instrument

ReasonCode - This is the code associated with any failure

Reason - This is the textual representation of any failure to execute a command

CmdError - This is the command error code associated with a subaction completing

CmdErrorStr - This is the textual representation of the command error code

MechError - This is the error code associated with any mechanism failure.

Severity - This is the severity of any error which was encountered

MechErrorStr - This is a textual representation of any error which ocurred with a mechanism

informSubactionInitiator

protected void informSubactionInitiator()

Informs the subaction initiator that the subaction that he initiated has completed, it uses the data items returned by the last subaction initiated by this subclass when reporting that the subaction has finished. The idea is that if we are executing a string of subactions, then if one of them fails, we can bail out and have the status returned by last subaction attempted returned to the caller

startAction

public boolean startAction(java.lang.String[] subactionArgs,
                           SubActionCompletionListener subActionInitiator)
                    throws SubActionInProgressException,
                           UnableToStartSubactionException

This method starts the subaction. It performs some checking such as ensuring that the caller has specified the correct number of arguments for this subacion and then starts a new thread. The subclass should have specified a run method which will contain the semantics of the subaction. This method will then return to the caller indicating that the method started okay.

Once the subaction has completed, the subaction initiator will be informed using the standard subaction callback mechanism which is used throughout the application.

Parameters:

subactionArgs - - This is a list of the arguments which pertain to this subaction

subActionInitiator - - This is a reference to the object that has started the subaction and must implement the iActionFinishedInterface. The subaction will rely on this interface in order to inform the initiator that the subaction has terminated.

Returns:

boolean

Throws:

SubActionInProgressException - When the subaction is already in progress.

UnableToStartSubactionException - Thrown when unable to start the subaction.

cancelAction

public boolean cancelAction()
                     throws SubActionNotInProgressException

We have to specify this but we do not implement it. It is supposed to cancel a subaction

Returns:

boolean

Throws:

SubActionNotInProgressException

waitForActionToComplete

public boolean waitForActionToComplete(java.lang.String ErrorString)

This method is called if the subclass wants to execute the current subaction of the sequence subaction synchronously. This method should be called immediately after a subaction has been initiated by this subclass.

The use of the method is demonstrated in the following code. Note that when we started the telescope focus action, we passed as the action completion handler the ActionCompletionListener object which is a local attribute. This is very important so as the super class is informed once the subaction has completed and it can therefore perform any post subaction handling of errors etc. If the super class is not informed when the subaction is completed then the sequence subaction will wait indefinitely as it waits on the thread being woken up by the subaction ending.

   TelescopeFocusAction.startAction(subactionArgs,ActionCompletionListener);
 
   // Wait for the telescope to stop moving Now wait for the MFW to stop moving before we attempt to
   // refocus the telescope
 
   if (!waitForActionToComplete("Telescope focus did not complete")) {
      return;
   }
 

If the subaction that we are waiting for fails for whatever reason, if the initiator of the action registered a callback, the callback will be called and then subsequently the state of the subaction will be reset to IDLE. The calling process needs to do no more, the subaction should be ready to be used again.

Parameters:

ErrorString - A string that contains the error text that should be returned to the subaction initiator should there be a problem with executing the subaction

returnResult

protected void returnResult(java.lang.String Message,
                            int SubactionCompletionState)

Packages up the code which informs the sequence subaction client of the result of the subaction. This is a convenience method which wraps up the funcionality of a number of the other methods.

Parameters:

Message - A text string to be reported as the status of the subaction completion

SubactionCompletionState - This is the completion state of the subaction completion, this should be set to either FourMSConstants.SUBACTIONFAILED or to FourMSConstants.SUBACTIONCOMPLETEDOK If this is not set to this value, the method will assume SUBACTIONFAILED.