FourMS
Class MechanismBase

java.lang.Object
  java.util.TimerTask
      FourMS.MechanismBase

All Implemented Interfaces:

java.lang.Runnable

Direct Known Subclasses:

Mechanism

public abstract class MechanismBase
extends java.util.TimerTask

This class forms the base class for all mechanism type classes in the 4MS software control system. Methods in the class permit the intialisation of the data structures which will be used to hold the details of the mechanism information from the database and also permit the interpretation of messages in the 4MS format. This is an abstract class which should be extended by the subclass which should also implement the run method as well.

Version:

$Id: MechanismBase.java,v 1.9 2006/04/07 08:05:39 cb Exp $

Author:

Craige Bevil

Field Summary

protected java.lang.String	AssociatedInstrumentName This is the name of the instrument which is associated with the mechanism
protected int	CmdError This records the command error associated with this mechanism.
protected java.util.Hashtable<java.lang.Integer,FourMSDBSchemaDerivedClasses.OM_CommandErrors>	CommandErrorCodes This is a hash that contains all of the details of the command error codes which can be returned from the 4MSfor this instrument.
protected int	CurrentMechanismPosition This is the current position of the mechanism
protected int	DatumPosition This is the position that the mechanism should be in following a datum action
protected int	DatumTimeInSecs This is the time taken to initialise/datum the mechanism expressed in seconds.
protected java.sql.Connection	DBConnection This is a connection to the WHTOCS database which will be used to access configuration information
protected int	EncoderLowerLimit This is the optional lower limit of the encoder.
protected int	EncoderPosition The Encoder position for the mechanism if a mechanism has an encoder
protected int	EncoderUpperLimit This is the optional upper limit of the encoder.
protected FourMSParameterConverter	ER412ParameterConverter This object is used to convert parameters between logical and engineering unit to be sent backwards and forwards to the 4MS microprocessor.
protected java.util.Hashtable<java.lang.String,FourMSDBSchemaDerivedClasses.OM_FourMSMessage>	FourMsMechMsgTypes Contains references to all of the messages that can be sent and received for this mechanism
protected java.util.Hashtable<java.lang.Integer,FourMSDBSchemaDerivedClasses.OM_MechErrorCodes>	MechanismErrorCodes This hash is used to hold a has of OM_MechErrorCodes which in turn hold the details of the mechanism error codes which are available
protected int	MechanismState This is the current movement state of the mechanism.
protected int	MechError This is the mechanism error associated with the mechanism.
protected int	MechLowerLimit The lower limit on the movement of the mechanism.
protected int	MechMovementRatePerSec Rate of movement per second.
protected java.lang.String	MechName This is the three letter mnenomic associated with the mechanism.
protected int	MechUpperLimit The upper limit on the movement of the mechanism.
protected boolean	NeedsInitialisation This is set to true if this mechanism needs initalising before it can be moved.
private int	NextInputArgIndex This is the next argument to process when we are constructing 4MS messages
protected java.util.Hashtable<java.lang.String,java.util.HashSet>	RangeConversionLookups This is an array of the range conversions mapping which are to be applied to the parameters associated with this mechanism.
protected MessageHandler	SyslogMessageHandler This is a syslog object which will be used to report errors etc
protected boolean	UsesEncoder Whether there is a encoder associated with this mechanism.

Constructor Summary

MechanismBase(java.sql.Connection DBConnection, java.lang.String InstrumentName, java.lang.String MechanismName, MessageHandler SysLogMsgHandler, FourMSParameterConverter ER412ParameterConverter)
This is the constructor for this class.

Method Summary

java.lang.String	buildFourMSMessage(boolean ResetInputArgPointer, java.lang.String[] MessageInputArgs, short MessageType) This method will be used to build a string which will correspond to a valid command to a 4MS processor.
private void	castConvertedParameter(java.lang.String ParameterToConvert, java.lang.String FourMSParameterType, java.util.List ConvertedMessageParameters) This is responsible for casting the input value to the type dictacted by the FourMSParameterType and then add it to the list of converted message parameters.
protected FourMSDBSchemaDerivedClasses.OM_CommandErrors	getCurrentCommandError() This returns the details of the current command error should there be one, the details of the command error is returned by status calls to the 4MS and the details of the command error are extracted from the WHTOCS database
protected FourMSDBSchemaDerivedClasses.OM_MechErrorCodes	getCurrentMechanismError() This returns the details of the current mechanism error should there be one, the details of the mechanism error is returned by status calls to the 4MS and the details of the mechanism error are extracted from the WHTOCS database
int	getMechanismError() This method simply returns the current mechanism error to the caller
java.lang.String	getMechanismName() This method will return the name of the mechanism to the caller
java.util.List	interpret4MSMessage(boolean From4MS, java.lang.String Message, java.util.List UnconvertedMsgParameters) Interprets the incoming message based on the mechanism configuration data which has been extracted from the 4MS OCS database and examines the message in order to to ensure that it complies with the structure of the message as outlined in the the database configuration for that particular message
private java.lang.String	performRangeMapping(int MappingDirection, java.lang.String ParameterToMap, java.lang.String MessageNumber, int ParameterNumber) This perform the range conversion for a incoming or outgoing parameter.
abstract void	run() This is this classes obligation to implement the timer interface Any classes that want to inherit from this class and want to use timers should override this method
protected boolean	setEncoderPosition() This method will be called in order to set the value of the encoder position should the encoder be used.

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

ER412ParameterConverter

protected FourMSParameterConverter ER412ParameterConverter

This object is used to convert parameters between logical and engineering unit to be sent backwards and forwards to the 4MS microprocessor.

MechError

protected int MechError

This is the mechanism error associated with the mechanism. If the mechanism error is set, it is not reset until there is a message sent to the simulator which is NOT a status request.

EncoderPosition

protected int EncoderPosition

The Encoder position for the mechanism if a mechanism has an encoder

CurrentMechanismPosition

protected int CurrentMechanismPosition

This is the current position of the mechanism

MechanismState

protected int MechanismState

This is the current movement state of the mechanism. It can be in one of the following states. This can be one of the following; STOPPED IDLE MOVING INITIALISING UNINITIALISED

UsesEncoder

protected boolean UsesEncoder

Whether there is a encoder associated with this mechanism. If this is true, then a simulated encoder position is calculated for the mechanism.

NeedsInitialisation

protected boolean NeedsInitialisation

This is set to true if this mechanism needs initalising before it can be moved.

DatumPosition

protected int DatumPosition

This is the position that the mechanism should be in following a datum action

EncoderLowerLimit

protected int EncoderLowerLimit

This is the optional lower limit of the encoder. A value of -1 indicates that the encoder limit is not in use.

MechMovementRatePerSec

protected int MechMovementRatePerSec

Rate of movement per second. Normally there will be a range associated with a mechanism and when it is moved then it will be moved at this rate. A value of 0 means that the mechanism will reach it's target position immediately.

MechLowerLimit

protected int MechLowerLimit

The lower limit on the movement of the mechanism.

MechUpperLimit

protected int MechUpperLimit

The upper limit on the movement of the mechanism.

DatumTimeInSecs

protected int DatumTimeInSecs

This is the time taken to initialise/datum the mechanism expressed in seconds.

MechName

protected java.lang.String MechName

This is the three letter mnenomic associated with the mechanism.

FourMsMechMsgTypes

protected java.util.Hashtable<java.lang.String,FourMSDBSchemaDerivedClasses.OM_FourMSMessage> FourMsMechMsgTypes

Contains references to all of the messages that can be sent and received for this mechanism

EncoderUpperLimit

protected int EncoderUpperLimit

This is the optional upper limit of the encoder. A value of -1 indicates that the encoder limit is not in use.

CmdError

protected int CmdError

This records the command error associated with this mechanism. The values that this variable can hold are standardised across all of the 4MSs

AssociatedInstrumentName

protected java.lang.String AssociatedInstrumentName

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

RangeConversionLookups

protected java.util.Hashtable<java.lang.String,java.util.HashSet> RangeConversionLookups

This is an array of the range conversions mapping which are to be applied to the parameters associated with this mechanism. It will consist of a one-to-one mapping between logical and engineering units and will be read from the WHT OCS database

MechanismErrorCodes

protected java.util.Hashtable<java.lang.Integer,FourMSDBSchemaDerivedClasses.OM_MechErrorCodes> MechanismErrorCodes

This hash is used to hold a has of OM_MechErrorCodes which in turn hold the details of the mechanism error codes which are available

CommandErrorCodes

protected java.util.Hashtable<java.lang.Integer,FourMSDBSchemaDerivedClasses.OM_CommandErrors> CommandErrorCodes

This is a hash that contains all of the details of the command error codes which can be returned from the 4MSfor this instrument. Note that the command errors return not specific to the a mechanism

NextInputArgIndex

private int NextInputArgIndex

This is the next argument to process when we are constructing 4MS messages

DBConnection

protected java.sql.Connection DBConnection

This is a connection to the WHTOCS database which will be used to access configuration information

SyslogMessageHandler

protected MessageHandler SyslogMessageHandler

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

Constructor Detail

MechanismBase

public MechanismBase(java.sql.Connection DBConnection,
                     java.lang.String InstrumentName,
                     java.lang.String MechanismName,
                     MessageHandler SysLogMsgHandler,
                     FourMSParameterConverter ER412ParameterConverter)

This is the constructor for this class. It reads in the details of the mechanism from the database so it has all of the simulation parameters which are needed for that particular mechanism.

Parameters:

DBConnection - - This is a connection to the database so that the method can extract the details from the database which it will use to simulate this mechanism.

InstrumentName - This is the name of the instrument which this mechanism is associated with

MechanismName - This is the name of the mechanism which will be simulated and will be used as the index when looking up the details in the database.

SysLogMsgHandler - This is a reference to a error handling object which will be used

ER412ParameterConverter - This is a reference to a parameter convertor which will be used for converting between logical and engineering units

Method Detail

run

public abstract void run()

This is this classes obligation to implement the timer interface Any classes that want to inherit from this class and want to use timers should override this method

Specified by:

run in interface java.lang.Runnable

Specified by:

run in class java.util.TimerTask

setEncoderPosition

protected boolean setEncoderPosition()

This method will be called in order to set the value of the encoder position should the encoder be used. It calculates the encoder position based on the physical position of the mechanism taking into the account the encoder range that was specified. This is a rough approximation of the function of a encoder.

Returns:

boolean Returns true if able to calculate the encoder position.

interpret4MSMessage

public java.util.List interpret4MSMessage(boolean From4MS,
                                          java.lang.String Message,
                                          java.util.List UnconvertedMsgParameters)
                                   throws Malformed4MSMessageException

Interprets the incoming message based on the mechanism configuration data which has been extracted from the 4MS OCS database and examines the message in order to to ensure that it complies with the structure of the message as outlined in the the database configuration for that particular message

Parameters:

From4MS - This is used to indicate if the message is coming FROM the 4MS or going TO the 4MS This is relevent in the case of the simulator and the 4MS controlling software. The controlling software will only be interested in ensuring that messages that come from the 4MS are well formed and that the message and that the routine should only check it's catalogue of messages which have their origins in the 4MS. Likewise the simulator is only interested in ensuring that the messages that are sent to the 4MS are well formed.

Message - This is the message in 4MS protocol which needs to be. The message should come be sent in the following format

UnconvertedMsgParameters - The parameters associated with the incoming message will be stored in this list before any parameter conversion is applied < > XXXNNN([p,

Returns:

List This is a list of the parameters contained in the incoming message after parameter conversion has been applied. Note that the first element of the list is the message type associated with the incoming message.

Throws:

FourMSSimulator.Malformed4MSMessageException

Malformed4MSMessageException

getMechanismError

public int getMechanismError()

This method simply returns the current mechanism error to the caller

Returns:

int The current value of the mechanism error

getMechanismName

public java.lang.String getMechanismName()

This method will return the name of the mechanism to the caller

Returns:

String The name of the mechanism

buildFourMSMessage

public java.lang.String buildFourMSMessage(boolean ResetInputArgPointer,
                                           java.lang.String[] MessageInputArgs,
                                           short MessageType)
                                    throws UnableToConstruct4MSMessageException

This method will be used to build a string which will correspond to a valid command to a 4MS processor. It will accept a number of parameters which should at least match the number of expected parameters for the specified message type for this mechanism. The method will then contruct a message of the sort MFW101(4) for instance which will be returned to the caller.

Parameters:

ResetInputArgPointer - Whether we should reset the subaction input pointer to the start of the input arguments, otherwise we keep a track of the position of the next argument to be called between calls of this method

MessageInputArgs - An array which holds a number of arguments which should contain at least the number of arguments expected to create the underlying 4MS message as specified by the MessageType argument. These arguments should match the expected type of these arguments as well.

MessageType - This is the message type of the message which is to be created.

Returns:

String

Throws:

UnableToConstruct4MSMessageException - This is thrown if for any reason we are unable to construct the expected message.

UnableToConstruct4MSMessageException

getCurrentMechanismError

protected FourMSDBSchemaDerivedClasses.OM_MechErrorCodes getCurrentMechanismError()

This returns the details of the current mechanism error should there be one, the details of the mechanism error is returned by status calls to the 4MS and the details of the mechanism error are extracted from the WHTOCS database

Returns:

OM_MechErrorCodes The details of the mechanism error code, null is returned if there is no mechanism error found in the catalogue

getCurrentCommandError

protected FourMSDBSchemaDerivedClasses.OM_CommandErrors getCurrentCommandError()

This returns the details of the current command error should there be one, the details of the command error is returned by status calls to the 4MS and the details of the command error are extracted from the WHTOCS database

Returns:

OM_CommandErrors The details of the command error code, null is returned if there is no command error found in the catalogue

performRangeMapping

private java.lang.String performRangeMapping(int MappingDirection,
                                             java.lang.String ParameterToMap,
                                             java.lang.String MessageNumber,
                                             int ParameterNumber)

This perform the range conversion for a incoming or outgoing parameter.

Parameters:

MappingDirection - This is the direction of the mapping, whetherwe are mapping to engineering units or to logical units

ParameterToMap - This is the value of the parameter to map

MessageNumber - This is the ER412 message number associated with the message that this parameter belongs to, it will be used in looking up the range converter if present.

ParameterNumber - This is the parameter number associated with the message that this parameter belongs to, it will be used in looking up the range converter if present.

Returns:

java.lang.String

castConvertedParameter

private void castConvertedParameter(java.lang.String ParameterToConvert,
                                    java.lang.String FourMSParameterType,
                                    java.util.List ConvertedMessageParameters)
                             throws ConversionFailedException

This is responsible for casting the input value to the type dictacted by the FourMSParameterType and then add it to the list of converted message parameters.

Parameters:

ParameterToConvert - This is the value which needs to be converted

FourMSParameterType - The is the code which dictates the type of the value which will be returned by the method. This should agree with one of the standard 4MS types such as r,h,s,x,d.

ConvertedMessageParameters - This is a list of converted message parameters to which the converted parameter will be appended.

Throws:

ConversionFailedException - This is thrown if there is an error converting the parameter