Data Types written by Gabriele Carcassi performed by Bob Dalesio based on ideas/requirements from Bob Dalesio, Kay Kasemir, Ralph Lange, James Roland, Guobao Shen, Greg White Oct

Scope and requirements  Java interfaces define client side data structures to represent data for control systems and high level applications pvData structure define data structure that represent information passed on the wire  Compatibility between Epics 3 and 4  Java interfates as part of PVManager for convenience; no dependencies on PVManager nor PVManager depends on them

References and documentation  Project available at  JavaDocs (with actual documentation) at l l  Package org.epics.pvmanager.data

Design guidelines  All data types defined through interfaces  Two types of interfaces Full type (e.g. VDouble, VMultiInt, VStatistics): they represent types that are actually implemented and can be asked; they all look like VXxx (where V is value) Partial type (e.g. Scalar, Alarm, Time): they represent common parts of data across different full types; they are defined separately so that we have one definition and so that clients can code to that partial interface  Full types are made up as collections of partial types (mostly don’t define new methods)

VDouble  Let’s start with the most common one, VDouble Scalar Alarm Time Display  Let’s go through details of all interfaces

Scalar  Defines: T getValue()  Returns the value of some type.

Alarm  Defines: AlarmSeverity getAlarmSeverity(); AlarmStatus getAlarmStatus();  AlarmSeverity: NONE, MINOR, MAJOR, INVALID, UNDEFINED (3 bits)  AlarmStatus: DEVICE, DRIVER, RECORD, DB, CONF, UNDEFINED, CLIENT, NONE (4 bits)  Gives the highest alarm and where it originates; first pass, generic information VExtendedAlarm is for more detailed information

Time  Defines: TimeStamp getTimeStamp(); Integer getTimeUserTag(); boolean isValid();  TimeStamp is a nanosecond accuracy instant Investigating use of JSR-310 Date and Time API javax.time.Instant (64 bit second + 32 bit nanosecond)  TimeUserTag can be used to identify fill patterns or anything your heart desires  isValid() used to flag when the time source is “bad” (time was not set, returns always EPICS time 0, …)

Display  Defines: Double getLower/UppterDisplayLimit(); Double getLower/UppterCtrlLimit(); Double getLower/UppterAlarmLimit(); Double getLower/UppterWarningLimit(); String getUnits(); NumberFormat getFormat();  Limits are always in double, regardless of the numeric type

VDouble  VDouble is one type, and defines all those elements.  One can still have partial implementations, that throw UnsupportedOperationException on the pieces that they do not implement or return null.  We want to avoid 2^4 combinations

All scalar types  VDouble – Scalar, Alarm, Time, Display  VInt - Scalar, Alarm, Time, Display  Explicitly no VFloat, VShort, VByte… Is VBoolean needed?  VString - Scalar, Alarm, Time  VEnum - Scalar, Enum, Alarm, Time

Enumeration  Enum defines: List getLabels();  VEnum defines: int getIndex();  Should the index be byte, short or int?

Scalar types

Multi dimensional arrays  VDoubleArray - Array, Alarm, Time, Display  VFloatArray - Array, Alarm, Time, Display  VIntArray - Array, Alarm, Time, Display  VShortArray - Array, Alarm, Time, Display  VByteArray - Array, Alarm, Time, Display  (VBooleanArray ?)  VStringArray - Array, Alarm, Time  VEnumArray - Array, Enum, Alarm, Time

Array  Defines: List getSizes();  The list of sizes for the multi dimensional array. One dimensional array can simply disregard this field. Difference between primitives and objects forces the array in the Full type. VDoubleArray: double[] getArray(); VIntArray: int[] getArray(); VEnumArray, VStringArray: String[] getArray(); - VEnumArray also defines int[] getIndexes(); …

Multi Channel arrays  Multiple values coming from different channels (e.g. all X BPM readbacks)  VMultiDouble: MultiScalar, Alarm, Time, Display  VMultiInt: MultiScalar, Alarm, Time, Display  VMultiString: MultiScalar, Alarm, Time  VMultiEnum: MultiScalar, Enum, Alarm, Time  (May need others VMultiDoubleArray,... ?)

MultiScalar  Defines: List getValues(); List getNames();  Should labels for enums be the same across all values, or can they be different? (Note: VEnumArray already may cover the case for same metadata)  Should metadata for numeric data be forced to the same? Or should each carry their own? (Note: numeric arrays may cover the case for same metadata)

Multi Channel Array

Statistics  VStatistics: Statistics, Alarm, Time, Display  Statistics define: Double getAverage(); Double getStdDev(); Double getMin(); Double getMax(); Integer getNSamples();  Does not define how it’s calculated (different weights)

VTable  Defines: int getColumnCount(); int getRowCount(); Class getColumnType(int column); String getColumnName(int column); Object getColumnArray(int column);  A table is a list of columns. A column is an array of elements of a particular type plus a name.  Different column may have different size: rowCount is the maximum across all columns

VTable

VImage  Defines: int getHeight(); int getWidth(); byte[] getData(); VTable getMetadata();  How do we describe encoding?  Is VTable good enough for metadata? Is it too much? Do we need to divide metadata for each image from the metadata that does not change for each image?  Should this have Time and Alarm?

VImage

VExtendedAlarm  Defines: List getConditions(); String getMessage();  Condition defines: String getName(); AlarmSeverity getSeverity(); boolean isActive();  VExtendedAlarm gives you the full list of alarms for a device. It says which ones are active. It provides an error message  Should each condition also have the AlarmStatus?

Status  Many types are already operational in PVManager with Epics 3, simulated generation and aggregation  Scalar and Array types can be directly generated by JCADataSource and simulated sources  VTable used in client-side aggregation  VImage used in clieant-side computation  VMultiDouble used for synchronized array reconstruction