Data Typeswritten 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 12 2010

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 http://pvmanager.sourceforge.net

JavaDocs (with actual documentation) at http://pvmanager.sourceforge.net/apidocs/index.html

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<T>, 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<Double>• Alarm• Time• Display

Let’s go through details of all interfaces

Scalar<T>

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<Double>, Alarm, Time, Display VInt - Scalar<Integer>, Alarm, Time, Display Explicitly no VFloat, VShort, VByte…

• Is VBoolean needed?

VString - Scalar<String>, Alarm, Time VEnum - Scalar<String>, Enum, Alarm, Time

Enumeration

Enum defines:• List<String> getLabels();

VEnum defines:• int getIndex();

Should the index be byte, short or int?

Scalar types

Multi dimensional arrays

VDoubleArray - Array<Double>, Alarm, Time, Display

VFloatArray - Array<Float>, Alarm, Time, Display VIntArray - Array<Integer>, Alarm, Time, Display VShortArray - Array<Byte>, Alarm, Time, Display VByteArray - Array<Byte>, Alarm, Time, Display (VBooleanArray ?) VStringArray - Array<String>, Alarm, Time VEnumArray - Array<String>, Enum, Alarm, Time

Array<T>

Defines:• List<Integer> 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<VDouble>, Alarm, Time, Display<Double>

VMultiInt: MultiScalar<VInt>, Alarm, Time, Display<Integer>

VMultiString: MultiScalar<VString>, Alarm, Time VMultiEnum: MultiScalar<VEnum>, Enum, Alarm,

Time (May need others VMultiDoubleArray, ... ?)

MultiScalar<T>

Defines:• List<T> getValues();• List<String> 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<Double> 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<Condition> 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