OCSEPICS
Class ProcessVariable

java.lang.Object
  java.util.TimerTask
      OCSEPICS.StatusVariable
          OCSEPICS.ProcessVariable

All Implemented Interfaces:

gov.aps.jca.event.ConnectionListener, gov.aps.jca.event.MonitorListener, java.lang.Runnable, java.util.EventListener

public class ProcessVariable
extends StatusVariable
implements gov.aps.jca.event.ConnectionListener, gov.aps.jca.event.MonitorListener

This class wraps up an EPICS process variable (PV) into a object which can be used throughout an OCS EPICS application. It will allow the setting and reading back of the process variable in addition to being able to convert the units backwards and forwards between engineering and logical units. Conversion between logical and engineering units is done automatically by the system before data is sent to the PV and sent up to the noticeboard.

Clients can request to be informed when there is an event on the PV by means of a callback mechanism. They need to register themselves as a listener using the CAEventListener interface.

It's worth pointing out that I have done the best I can with the Java EPICS interface, the documentation is completely rubbish and I have had to work out how to use it myself rather from a definitive source.

The class will listen for events on the monitored PV (if specified), and convert from engineering values to logical units and then write the value into the parameter noticeboard.

Version:

$Id: ProcessVariable.java,v 1.5 2007/03/02 10:31:47 cb Exp $

Author:

Craige Bevil

Field Summary

(package private) gov.aps.jca.Monitor	ChannelMonitor This the monitor on the PV if it is being monitored
private static int	ConversionUniqueSeqCode Static variable which is used for indexing the parameter conversions
private java.sql.Connection	DBConnection This is a live connection to the database
private java.lang.String	EngineeringArgType This is the argument type of the PV when it is to be written into the noticeboard
private gov.aps.jca.Context	EPICSContext This is the EPICS context which we will use
private java.util.ArrayList<CAEventListener>	EventListeners A list of listeners which are interested on events which occur on this PV.
private java.lang.String	HostName This is the name of the EPICS host which is home to the process variable which is to be monitored by this class
private java.lang.String	InstrumentName This is the name of the instrument which is associated with this PV
private java.lang.String	LogicalArgType This is the logical type of the PV once it has been converted from it's engineering value into a logical value.
private java.lang.String	LogicalNBParameterName This is the name of the parameter which is to be written into the noticeboard.
private java.lang.String	MechName This is the name of the mechanism which is associated with this PV if there is one
(package private) boolean	MonitorCreated Whether a monitor has been created on this PV
private int	ParameterConversionCode This code will be used to uniquely identify the parameter conversion to be used (if at all) on this PV.
private gov.aps.jca.Channel	PVChannel This is the EPICS channel which is associated with the PV
private boolean	PVConnected Indicates whether we are connected to the PV in the IOC or not.
private java.util.Timer	PVInitialisationTimer This is a timer object which will be used for scheduling the intialisation of the PV
private boolean	PVMonitoringInitialised Whether we have intialised the class or not
private java.lang.String	PVName This is the textual name of the PV
private java.lang.String	RawUnitsLabel This is raw units which are associated with the engineering value
private java.lang.Boolean	ToBeMonitored Whether the PV is to be monitored by the class

Fields inherited from class OCSEPICS.StatusVariable

OCSCorba, ParameterConvertor, ParameterNoticeBoard, StatusVariableName, SyslogMessageHandler, UnitConversionMethod

Constructor Summary

ProcessVariable(java.sql.Connection DBConnection, java.lang.String PVName, gov.aps.jca.Context EPICSContext, MessageHandler SyslogMessageHandler, FourMS.FourMSParameterConverter ParameterConvertor, OCSCORBAHelper OCSCorba)
This is the constructor for this class.

Method Summary

boolean	addPVListener(CAEventListener listener) Add external listener to be informed when there are events on the PV.
private org.omg.CORBA.Any	castConvertedParameter(java.lang.String ParameterToConvert, java.lang.String ConversionType) This is responsible for casting the input value to the type which is indicated by the conversiontype parameter and then packaging it up into an a CORBA Any which can then be used to update the noticeboard by the caller.
void	connectionChanged(gov.aps.jca.event.ConnectionEvent ev) This is the obligation of the ConnectionListener interface.
private java.lang.String	convertDBRType(gov.aps.jca.dbr.DBR valueToConvert) This method will be called to convert the EPICS DBR type specified to a string.
void	finalize()
java.lang.String	getLogicalArgType() Used to get the type of the logical argument
java.lang.String	getPVName() Gets the name of the process variable
ing.status.StatusItemValue[]	getStatusValue() This method will be used for getting the value of the PV from the IOC, updating the noticeboard accordingly and returning the value to the caller.
private void	informListeners(ing.status.StatusItemValue statusValue) Informs the PV listeners of a change in the value of a PV when there is an event.
private void	informListeners(ing.status.StatusItemValue[] statusValues) Informs the PV listeners of a change in the value of a PV when there is an event.
static void	main(java.lang.String[] args) main() method which can be used to run some tests on the process variable class.
void	monitorChanged(gov.aps.jca.event.MonitorEvent ev) This is the obligation to the MonitorListener interface which will be called when the value of the underlying monitored PV changes.
ing.status.StatusItemValue[]	performEngineeringToLogicalUnitConversion(gov.aps.jca.dbr.DBR rawValue) Converts the input parameter which is an EPICS DBR type from it's engineering value to it's logical value if required and then update noticeboard with both the engineering and the logical values.
java.lang.String	performLogicalToEngineeringUnitConversion(java.lang.String InputValue) This method can be used to convert a logical value to an engineering value.
void	putProcessVariable(java.lang.String ValueToWrite) This will be used for putting a value into the PV on the IOC.
void	run() This is the obligation of the TimerTask base class.

Methods inherited from class OCSEPICS.StatusVariable

updateParameterNoticeboard, updateParameterNoticeboard

Methods inherited from class java.util.TimerTask

cancel, scheduledExecutionTime

Methods inherited from class java.lang.Object

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

Field Detail

ConversionUniqueSeqCode

private static int ConversionUniqueSeqCode

Static variable which is used for indexing the parameter conversions

ParameterConversionCode

private int ParameterConversionCode

This code will be used to uniquely identify the parameter conversion to be used (if at all) on this PV. This is set once.

MonitorCreated

boolean MonitorCreated

Whether a monitor has been created on this PV

ChannelMonitor

gov.aps.jca.Monitor ChannelMonitor

This the monitor on the PV if it is being monitored

PVChannel

private gov.aps.jca.Channel PVChannel

This is the EPICS channel which is associated with the PV

PVInitialisationTimer

private final java.util.Timer PVInitialisationTimer

This is a timer object which will be used for scheduling the intialisation of the PV

DBConnection

private java.sql.Connection DBConnection

This is a live connection to the database

PVConnected

private boolean PVConnected

Indicates whether we are connected to the PV in the IOC or not.

PVName

private java.lang.String PVName

This is the textual name of the PV

HostName

private java.lang.String HostName

This is the name of the EPICS host which is home to the process variable which is to be monitored by this class

MechName

private java.lang.String MechName

This is the name of the mechanism which is associated with this PV if there is one

InstrumentName

private java.lang.String InstrumentName

This is the name of the instrument which is associated with this PV

RawUnitsLabel

private java.lang.String RawUnitsLabel

This is raw units which are associated with the engineering value

LogicalArgType

private java.lang.String LogicalArgType

This is the logical type of the PV once it has been converted from it's engineering value into a logical value.

EngineeringArgType

private java.lang.String EngineeringArgType

This is the argument type of the PV when it is to be written into the noticeboard

LogicalNBParameterName

private java.lang.String LogicalNBParameterName

This is the name of the parameter which is to be written into the noticeboard.

ToBeMonitored

private java.lang.Boolean ToBeMonitored

Whether the PV is to be monitored by the class

EPICSContext

private gov.aps.jca.Context EPICSContext

This is the EPICS context which we will use

PVMonitoringInitialised

private boolean PVMonitoringInitialised

Whether we have intialised the class or not

EventListeners

private java.util.ArrayList<CAEventListener> EventListeners

A list of listeners which are interested on events which occur on this PV.

Constructor Detail

ProcessVariable

public ProcessVariable(java.sql.Connection DBConnection,
                       java.lang.String PVName,
                       gov.aps.jca.Context EPICSContext,
                       MessageHandler SyslogMessageHandler,
                       FourMS.FourMSParameterConverter ParameterConvertor,
                       OCSCORBAHelper OCSCorba)
                throws UnableToInitiatePVException,
                       java.lang.Exception

This is the constructor for this class. It will extract from the whtics database all of the details associated with the PV from the processvariable table and configure itself accordingly. Once done it will start a timer thread which will be responsible for initialising the connection to the PV and ensuring that it is monitored should it need to be.

Parameters:

DBConnection - This is an active connection to the database so that the class can look up the details of the PV from the WHT ICS database. The behaviour of the class is data driven by the contents of the ProcessVariable table in the database.

PVName - This is the name of PV which is to be controlled using this class.

EPICSContext - This is EPICS context within which we will create the process variable.

SyslogMessageHandler - This will be used to write information into the syslog message handler.

ParameterConvertor - This will be used sued to convert PV values between engineering and logical units

OCSCorba - Helper object for performing CORBA related activity.

Throws:

UnableToInitiatePVException

java.lang.Exception

Method Detail

finalize

public void finalize()
              throws java.lang.Throwable

Overrides:

finalize in class StatusVariable

Throws:

java.lang.Throwable

informListeners

private void informListeners(ing.status.StatusItemValue statusValue)

Informs the PV listeners of a change in the value of a PV when there is an event.

Parameters:

statusValue - A status item which contains the status value to be returned to the listener. Normally this verison of the method will be called when an error status item is to be returned to the caller.

informListeners

private void informListeners(ing.status.StatusItemValue[] statusValues)

Informs the PV listeners of a change in the value of a PV when there is an event.

Parameters:

statusValues - An arry of status items which contains the raw and the engineering value which is associated with the event on the PV. The method will determine which of the two values that the client is registered for and return only one of the status items.

addPVListener

public boolean addPVListener(CAEventListener listener)

Add external listener to be informed when there are events on the PV.

Parameters:

listener - This is an object which is to be informed when there is an event on the PV.

Returns:

boolean True when the listener has been added to the list of listeners to be informed when there is an event.

connectionChanged

public void connectionChanged(gov.aps.jca.event.ConnectionEvent ev)

This is the obligation of the ConnectionListener interface. This method will be called when there is a connection event on PV. This could be either the connection has been broken or that the connection has been established.

Specified by:

connectionChanged in interface gov.aps.jca.event.ConnectionListener

Parameters:

ev - This contains the details of the event

run

public void run()

This is the obligation of the TimerTask base class. This method is called intermittingly to ensure that we have initialised the class after first being instructed to do so. This will result in a channel which will be used to control the PV.

Should we fail in our attempt to initialise the PV, as part of the timer task, the method will be called again in 15 seconds time.

Specified by:

run in interface java.lang.Runnable

Overrides:

run in class StatusVariable

monitorChanged

public void monitorChanged(gov.aps.jca.event.MonitorEvent ev)

This is the obligation to the MonitorListener interface which will be called when the value of the underlying monitored PV changes. This value will then be converted to a logical unit if specified and wrote into the noticeboard in the correct type after being converted back from the native EPICS type. The engineering unit will be cast from the native EPICS type to a suitable CORBA type and then wrote into the noticeboard as well.

Any errors will result in both the engineering and the logical noticeboard items being set to an error state.

Specified by:

monitorChanged in interface gov.aps.jca.event.MonitorListener

Parameters:

ev - This contains the details of the channel access event

performLogicalToEngineeringUnitConversion

public java.lang.String performLogicalToEngineeringUnitConversion(java.lang.String InputValue)
                                                           throws FourMS.ConversionFailedException

This method can be used to convert a logical value to an engineering value. This will invoke the conversion logic which is associated with the PV. If no conversion can be performed then an exception is raised otherwise the converted value is returned.

Parameters:

InputValue - This is the value which is to be converted. It is expressed always as a string representation of the value.

Returns:

String This is the converted value.

Throws:

ConversionFailedException - Should the conversion fail.

performEngineeringToLogicalUnitConversion

public ing.status.StatusItemValue[] performEngineeringToLogicalUnitConversion(gov.aps.jca.dbr.DBR rawValue)
                                                                       throws UnableToPerformConversion

Converts the input parameter which is an EPICS DBR type from it's engineering value to it's logical value if required and then update noticeboard with both the engineering and the logical values.

Parameters:

rawValue - This is the EPICS value which is to be converted logical units.

Returns:

StatusItemValue[] The IDL types which represent the logical and the engineering values.

Throws:

UnableToPerformConversion - When a conversion cannot be performed.

castConvertedParameter

private org.omg.CORBA.Any castConvertedParameter(java.lang.String ParameterToConvert,
                                                 java.lang.String ConversionType)
                                          throws FourMS.ConversionFailedException

This is responsible for casting the input value to the type which is indicated by the conversiontype parameter and then packaging it up into an a CORBA Any which can then be used to update the noticeboard by the caller.

Parameters:

ParameterToConvert - This is the value which needs to be converted

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

Returns:

A CORBA any structure which contains the converted parameter in the correct type.

Throws:

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

getStatusValue

public ing.status.StatusItemValue[] getStatusValue()
                                            throws gov.aps.jca.CAException

This method will be used for getting the value of the PV from the IOC, updating the noticeboard accordingly and returning the value to the caller.

Returns:

StatusItemValue[] This is the value which was returned by the channel access get operation on the PV

Throws:

gov.aps.jca.CAException - If unable to get the value and perform unit conversion on the raw engineering unit.

putProcessVariable

public void putProcessVariable(java.lang.String ValueToWrite)
                        throws gov.aps.jca.CAException

This will be used for putting a value into the PV on the IOC. The caller specifies the value to put into the PV as a string and then the method will convert the value into the correct DBRtype according to the database configuration for this PV. Note that no unit conversions will be performed. It is assumed that the caller will have performed any logical to engineering conversions before it calls this method.

Parameters:

ValueToWrite - This is the raw value which is to be written to the PV. All unit conversions should have been performed by this point so the value represented here should be in engineering units.

Throws:

gov.aps.jca.CAException - Whenever there is a problem attempting to write the PV to the IOC.

convertDBRType

private java.lang.String convertDBRType(gov.aps.jca.dbr.DBR valueToConvert)
                                 throws UnableToConvertDBRTypeException

This method will be called to convert the EPICS DBR type specified to a string. This is required as the interface to the conversion methods require that the input parameter is of a String type.

Parameters:

valueToConvert - This is the EPICS DBR type which is to have it's value converted to a string

Returns:

A string representation of the EPICS value.

Throws:

UnableToConvertDBRTypeException - Thrown when unable to convert the value which is entered into the method.

main

public static void main(java.lang.String[] args)

main() method which can be used to run some tests on the process variable class.

getPVName

public java.lang.String getPVName()

Gets the name of the process variable

Returns:

String The name of the process variable

getLogicalArgType

public java.lang.String getLogicalArgType()

Used to get the type of the logical argument

Returns:

A string which contains the type of the logical argument