FourMS
Class SubAction

java.lang.Object
  java.util.TimerTask
      FourMS.SubAction

All Implemented Interfaces:

i4MSMessageSender, SubActionOperations, java.lang.Runnable

public class SubAction
extends java.util.TimerTask
implements i4MSMessageSender, java.lang.Runnable, SubActionOperations

This class describes a dialogue which may take place between the 4MS and a client. Each dialogue is assigned a unique name which describes a sequence of messages that are sent to the controller and are expected to be received in turn from the 4MS. The SubAction will be informed via it's parent mechanism object that it is associated with when a message is sent back from the 4MS controller which might have been initiated by itself.

The subaction is informed of incoming messages which were bound for it's associated mechanism and if any of them satisfy what is expected to be returned for this subaction and in the order dictated, it is noted and once all the expected replies have come back from the 4MS, the subaction will be considered completed.

In the meanwhile, the subaction may optionally have a timeout associated with it and if all of the expected replies have not been received by the time that we expect, then we timeout and cancel the subaction. Note that the SubAction is a CORBA object and therefore operations on the object will be invoked by remote clients. The subaction client (the subaction initiator), if registered will be informed when the subaction completes for whatever reason. Unfortunately it is not possible in the 4MS protocol to absolutely identify a response with the message that initiated it. This is a serious shortcoming which will violate the integrity of any proposed solution. Each of the subactions will in fact be a CORBA object upon which actions can be started and completed. We can however ensure that expected replies arrive in the order that we expect and that we we should discount any replies until an ACK has been received in reply to the original message that was sent to the 4MS, was acknowledged by the 4MS receiver at the other end of the wire.

Version:

$Id: SubAction.java,v 1.11 2006/04/07 08:03:16 cb Exp $

Author:

Craige Bevil

Field Summary

private int	ActionState This is the current state of the action.
private boolean	AlwaysTimeoutSubactions This is for testing, when set to true, subactions which are initiated will never complete, use with extreme caution and always reset for a live system.
private FourMSMessageHandler	ER412MessageHandler This will be used in order to send messages to the 4MS microprocessor (or the simulator)
private FourMSParameterConverter	ER412ParameterConverter This will be used by a sub-action object to convert input and output parameters to be sent or received from the 4MS microprocessor.
private java.util.ArrayList<FourMSDBSchemaDerivedClasses.OM_SubMessageComponent>	ExpectedSubactionIncomingMsgTypes This is a tally of the number of expected subaction sub-messages returned after the latest invocation of the subaction.
private java.util.ArrayList<FourMSDBSchemaDerivedClasses.OM_SubMessageComponent>	IncomingSubActionComponents This is an array list of the subaction components which are read from the database for messages coming in from the 4MS.
private boolean	InitialMessageACKed This is a flag which is record whether or not we have received the ACK from the message that we sent out to the 4MS transceiver on initiation of the subaction
private java.lang.String	InstrumentName This is the name of the instrument which the subaction is associated with
private int	LastSubactionCompletionState The state of the action after the last execution.
private java.lang.String	MechanismName This is the name of the mechanism which the subaction is associated with
private int	NextExpectedIncomingMessageIndex This is an index into the ExpectedSubactionIncomingMsgTypes array which details the delivery position number of the next incoming message from ER412 transmitter
private java.util.ArrayList<FourMSDBSchemaDerivedClasses.OM_SubMessageComponent>	OutgoingSubActionComponents This is an array list of the subaction components which are read from the database for messages going out to the 4MS
private Mechanism	ParentMechanism This is the mechanism which this subactions is associated with
private int	SecondsBeforeTimeout This holds the amount of time that a subaction has to go before it timesout
private SubActionCompletionListener	SubActionInitiatorCB This is a reference to the last object that initiated this subaction.
java.lang.String	SubActionName This is the name of the subaction
private static java.util.Timer	SubActionTimer This is a timer object which will be used for scheduling timer based operations on the subaction.
private MessageHandler	SyslogMessageHandler This is a syslog object which will be used to report errors etc
private int	TimeOut This is the timeout for an an a 4MS dialogue sequence to complete before the subaction is considered failed.

Constructor Summary

SubAction(java.lang.String SubActionName, int TimeOut, java.lang.String InstrumentName, java.lang.String MechanismName, Mechanism ParentMechanism, java.sql.Connection DBConnection, MessageHandler SyslogMessageHandler, FourMSParameterConverter ER412ParameterConverter, FourMSMessageHandler ER412MessageHandler)
This is the constructor and will result in the configuration data from the WHTOCS database being read in and the subaction configured accordingly

Method Summary

boolean	cancelAction() This method allows a sub-action to be cancelled it actually does nothing to the 4MS but resets the state of the SubAction to SUBACTIONIDLE so that it may be called again.
int	getSubActionState() This returns the state that the subaction finds itself in.
void	informMessageDeliveryStatus(boolean DeliveredSuccessfully, java.lang.String OriginalMessage) This is a callback which is used to inform the subaction initiator subaction completion callback if there was a problem in the initial transmission of the message to the ER412 receiver.
private void	informSubactionInitiator(int ReasonCode, java.lang.String Reason) This method will inform the client who initiated the subaction that the subaction has terminated.
boolean	mechanismMessageReceived(FourMSMessage MessageReply) This is a callback which is called when there is a message coming back from the 4MS which relates to a mechanism which may have been initiated by a outstanding subaction.
void	run() This subaction runs in a thread, we need to keep track of when a subaction is running so that we can work out if a subaction has timed out.
boolean	startAction(java.lang.String[] subactionArgs, SubActionCompletionListener subActionInitiator) This method will be used to send a command to the 4MS controller.

Methods inherited from class java.util.TimerTask

cancel, scheduledExecutionTime

Methods inherited from class java.lang.Object

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

Field Detail

AlwaysTimeoutSubactions

private final boolean AlwaysTimeoutSubactions

This is for testing, when set to true, subactions which are initiated will never complete, use with extreme caution and always reset for a live system. The use of this is only intended for development purposes

See Also:

Constant Field Values

TimeOut

private 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.

ActionState

private 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. InProgress

SubActionName

public java.lang.String SubActionName

This is the name of the subaction

MechanismName

private java.lang.String MechanismName

This is the name of the mechanism which the subaction is associated with

InstrumentName

private java.lang.String InstrumentName

This is the name of the instrument which the subaction is associated with

OutgoingSubActionComponents

private java.util.ArrayList<FourMSDBSchemaDerivedClasses.OM_SubMessageComponent> OutgoingSubActionComponents

This is an array list of the subaction components which are read from the database for messages going out to the 4MS

IncomingSubActionComponents

private java.util.ArrayList<FourMSDBSchemaDerivedClasses.OM_SubMessageComponent> IncomingSubActionComponents

This is an array list of the subaction components which are read from the database for messages coming in from the 4MS. The order of the list is the order that we are expecting to have the messages sent to us

SubActionTimer

private static final java.util.Timer SubActionTimer

This is a timer object which will be used for scheduling timer based operations on the subaction. This will be used for keeping track of whether or not a scheduled subaction has not completed in time for instance

SecondsBeforeTimeout

private int SecondsBeforeTimeout

This holds the amount of time that a subaction has to go before it timesout

LastSubactionCompletionState

private int LastSubactionCompletionState

The state of the action after the last execution. Should be one of the following from the FourMSConstants class SUBACTIONCOMPLETEDOK SUBACTIONTIMEDOUT SUBACTIONFAILED

InitialMessageACKed

private boolean InitialMessageACKed

This is a flag which is record whether or not we have received the ACK from the message that we sent out to the 4MS transceiver on initiation of the subaction

ExpectedSubactionIncomingMsgTypes

private java.util.ArrayList<FourMSDBSchemaDerivedClasses.OM_SubMessageComponent> ExpectedSubactionIncomingMsgTypes

This is a tally of the number of expected subaction sub-messages returned after the latest invocation of the subaction. When the subaction is initially started, this tally will be set to the number of expected messages that come back as as they come in, this tally is decremented. Once it reaches 0, it means that all of the expected message sub-components have been returned and that this invocation of the subaction is now completed

NextExpectedIncomingMessageIndex

private int NextExpectedIncomingMessageIndex

This is an index into the ExpectedSubactionIncomingMsgTypes array which details the delivery position number of the next incoming message from ER412 transmitter

ER412ParameterConverter

private FourMSParameterConverter ER412ParameterConverter

This will be used by a sub-action object to convert input and output parameters to be sent or received from the 4MS microprocessor.

ER412MessageHandler

private FourMSMessageHandler ER412MessageHandler

This will be used in order to send messages to the 4MS microprocessor (or the simulator)

SyslogMessageHandler

private MessageHandler SyslogMessageHandler

This is a syslog object which will be used to report errors etc

ParentMechanism

private Mechanism ParentMechanism

This is the mechanism which this subactions is associated with

SubActionInitiatorCB

private SubActionCompletionListener SubActionInitiatorCB

This is a reference to the last object that initiated this subaction. It is stored as part of the subaction until the subaction completes. When it is completed, the subaction will call a method in the subaction initiator which will inform it of the result of the execution of the subaction. The initiator is expected to be a CORBA object and this is a CORBA oneway callback

Constructor Detail

SubAction

public SubAction(java.lang.String SubActionName,
                 int TimeOut,
                 java.lang.String InstrumentName,
                 java.lang.String MechanismName,
                 Mechanism ParentMechanism,
                 java.sql.Connection DBConnection,
                 MessageHandler SyslogMessageHandler,
                 FourMSParameterConverter ER412ParameterConverter,
                 FourMSMessageHandler ER412MessageHandler)

This is the constructor and will result in the configuration data from the WHTOCS database being read in and the subaction configured accordingly

Parameters:

SubActionName - This is the name of the subaction and will form part of the search query which will be used to look up the details of the subaction from the database

TimeOut - This is the amount of time that this subaction is expected to take before it is considered cancelled

InstrumentName - This is the name of the instrument which the subaction is associated with and will form part of the search query which will be used to look up the details of the subaction from the database

MechanismName - This is the name of the mechanism within the instrumetn which the subaction is associated with and will form part of the search query which will be used to look up the details of the subaction from the database

ParentMechanism - This is the mechanism object which the subaction is associated.

DBConnection - This is the database connection which will be used by the object to access the database

SyslogMessageHandler - This is will be instance of the * syslog message handling class which will be used for reporting

Method Detail

startAction

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

This method will be used to send a command to the 4MS controller. It will perform any conversion that needs to be done between input/output parameters to engineering units from logical units.

Note that the method is synchronized so that no other threads can access the object until the method has completed. This is to ensure that we don't receive a reply until the message has been sent!

Specified by:

startAction in interface SubActionOperations

Parameters:

subactionArgs - - This is a list of the arguments which are to be sent to the 4MS, they will be specified in logical units and then converted to engineering units ahead of being transferred to the 4MS.

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:

UnableToStartSubactionException

SubActionInProgressException

SubActionInProgressException

UnableToStartSubactionException

cancelAction

public boolean cancelAction()
                     throws SubActionNotInProgressException

This method allows a sub-action to be cancelled it actually does nothing to the 4MS but resets the state of the SubAction to SUBACTIONIDLE so that it may be called again. I should be noted that the current system does not actually stop anything from happening inside of the 4MS when a cancel command is issued. This method forms part of the CORBA interface to this object and be called remotely.

Specified by:

cancelAction in interface SubActionOperations

Returns:

boolean

Throws:

SubActionNotInProgressException

mechanismMessageReceived

public boolean mechanismMessageReceived(FourMSMessage MessageReply)

This is a callback which is called when there is a message coming back from the 4MS which relates to a mechanism which may have been initiated by a outstanding subaction. The subaction then decides whether or not the subaction dialogue has been completed and returns true or false accordingly. This is normally called from a mechanism object which is associated with the subaction

Parameters:

MessageReply - This is the message which was received from the ER412 transmitter at the other end of the wire decomposed into it's constituent parts.

Returns:

boolean True if the expected incoming messages have satisfied all the expected replies associated with this subaction

informSubactionInitiator

private void informSubactionInitiator(int ReasonCode,
                                      java.lang.String Reason)

This method will inform the client who initiated the subaction that the subaction has terminated.

Parameters:

ReasonCode - This is the status code associated with the termination of the subaction

Reason - This is a text string which indicates why the subaction completed

getSubActionState

public int getSubActionState()

This returns the state that the subaction finds itself in. It should return one of the following values to signify the state of the subaction

Returns:

int

informMessageDeliveryStatus

public void informMessageDeliveryStatus(boolean DeliveredSuccessfully,
                                        java.lang.String OriginalMessage)

This is a callback which is used to inform the subaction initiator subaction completion callback if there was a problem in the initial transmission of the message to the ER412 receiver. It will only be told if the transmission failed for some reason or if there was no expected reply to the outgoing message.

Specified by:

informMessageDeliveryStatus in interface i4MSMessageSender

Parameters:

DeliveredSuccessfully - True if the message was successfully ACKed by the receiver and false otherwise. We don't do anything if message was sent without error.

OriginalMessage - This is the text associated with the original message that was delivered

run

public void run()

This subaction runs in a thread, we need to keep track of when a subaction is running so that we can work out if a subaction has timed out.

Specified by:

run in interface java.lang.Runnable

Specified by:

run in class java.util.TimerTask