org.jlab.coda.et

Class EtEventImpl

java.lang.Object

org.jlab.coda.et.EtEventImpl

All Implemented Interfaces:

EtEvent

public class EtEventImpl
extends java.lang.Object
implements EtEvent

This class defines an ET event.

Author:

Carl Timmer

Constructor Summary

Constructors

Constructor and Description
EtEventImpl(EtEventImpl ev) Creates an event object by duplicating another.
EtEventImpl(int size) Creates an event object for users of Java-based ET systems or by the system itself.
EtEventImpl(int size, int limit, boolean isJava, boolean noBuffer) Creates an event object for ET system users when connecting to ET systems over the network.
EtEventImpl(int size, int limit, int id, int owner, int modify, int length, int priority, int byteOrder, boolean isTemp, java.nio.ByteBuffer buffer) Creates an event object for ET system users when connecting to local, C-based ET systems and using native methods to call et_events_new.
EtEventImpl(int size, int limit, int status, int id, int age, int owner, int modify, int length, int priority, int byteOrder, int[] control, boolean isTemp, java.nio.ByteBuffer buffer) Creates an event object for ET system users when connecting to local, C-based ET systems and using native methods to call et_events_get.

Method Summary

Modifier and Type	Method and Description
org.jlab.coda.et.enums.Age	getAge() Gets the age of the event, either Age.NEW if a new event obtained through calling EtSystem.newEvents(EtAttachment, org.jlab.coda.et.enums.Mode, int, int, int) or Age.USED if obtained through calling EtSystem.getEvents(EtAttachment, org.jlab.coda.et.enums.Mode, org.jlab.coda.et.enums.Modify, int, int).
java.nio.ByteOrder	getByteOrder() Gets the event data's byte order.
int[]	getControl() Gets a copy of the event's control array.
int[]	getControlNoCopy() Gets a reference to the event's control array without copying.
byte[]	getData() Gets the data array which is backing the event's data buffer if there is one.
java.nio.ByteBuffer	getDataBuffer() Gets the event's data buffer.
org.jlab.coda.et.enums.DataStatus	getDataStatus() Gets the status of the data (set by the system), which can be OK DataStatus.OK, corrupted DataStatus.CORRUPT, or possibly corrupted DataStatus.POSSIBLYCORRUPT.
int	getDataStatusValue() Get int value associated with DataStatus enum.
int	getGroup() Gets the group the event belongs to (1, 2, ...) if ET system events are divided into groups.
int	getId() Gets the event's id number.
int	getLength() Gets the length of the data in bytes.
int	getMemSize() Gets the size of the data buffer in bytes.
org.jlab.coda.et.enums.Modify	getModify() Gets the event's modify value when receiving it over the network.
int	getOwner() Gets the attachment id of the attachment which owns or got the event.
org.jlab.coda.et.enums.Priority	getPriority() Gets the event's priority, either high Priority.HIGH or low Priority.LOW.
int	getPriorityValue() Get int value associated with Priority enum.
int	getRawByteOrder() Gets the raw byte order data (0x04030201 or 0x01020304).
int	getSizeLimit() Gets the size limit of the data buffer in bytes when using a C-based ET system.
void	init() Initialize an event's fields.
boolean	isTemp() Gets whether this event is a temporary event or not.
boolean	needToSwap() Tells caller if the event data needs to be swapped in order to be the same byte order as the local JVM.
void	setAge(org.jlab.coda.et.enums.Age age) Sets the age of the event which is Age.NEW for new events obtained by calling EtSystem.newEvents(EtAttachment, org.jlab.coda.et.enums.Mode, int, int, int)), or Age.NEW for "used" event obtained by calling EtSystem.getEvents(EtAttachment, org.jlab.coda.et.enums.Mode, org.jlab.coda.et.enums.Modify, int, int)).
void	setByteOrder(java.nio.ByteOrder order) Set the event data's byte order.
void	setByteOrder(int endian) Set the event data's byte order by using values consistent with C-based ET systems, EtConstants.endianBig, EtConstants.endianLittle, EtConstants.endianLocal, EtConstants.endianNotLocal, or EtConstants.endianSwitch.
void	setControl(int[] con) Sets the event's control array by copying it into the event.
void	setData(byte[] data) Sets the event's data without copying.
void	setDataBuffer(java.nio.ByteBuffer dataBuffer) Sets the event's data buffer (must be backed by data array).
void	setDataStatus(org.jlab.coda.et.enums.DataStatus status) Sets the event's data status.
void	setGroup(int group) Sets the group the event belongs to: (1, 2, ...) if ET system events are divided into groups, or group = 1 if not.
void	setId(int id) Sets the event's id number.
(package private) void	setJava(boolean java) Sets flag specifying whether the ET system process is Java based or not.
void	setLength(int len) Sets the event's data length in bytes.
void	setLengthFromServer(int len) Set the length of valid data from server where sizeLimit may be 0.
void	setMemSize(int memSize) Sets the size of the data buffer in bytes.
void	setModify(org.jlab.coda.et.enums.Modify modify) Sets whether the user wants to read the event only, will modify only the event header (everything except the data), or will modify the data and/or header.
void	setOwner(int owner) Sets the owner of the event (attachment using event or system).
void	setPriority(org.jlab.coda.et.enums.Priority pri) Sets the event's priority, either high Priority.HIGH or low Priority.LOW.
void	setRawByteOrder(int byteOrder) Set the event data's byte order as big with 0x04030201 or as little with 0x01020304.
(package private) void	setSizeLimit(int sizeLimit) Sets the limit of the size of the data buffer in bytes.

Methods inherited from class java.lang.Object

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

Constructor Detail

EtEventImpl

public EtEventImpl(int size)

Creates an event object for users of Java-based ET systems or by the system itself. Event objects are only created once in the ET system process - when the ET system is started up.

Parameters:

size - size of the data array in bytes

EtEventImpl

EtEventImpl(int size,
            int limit,
            boolean isJava,
            boolean noBuffer)

Creates an event object for ET system users when connecting to ET systems over the network. Called by EtSystem.getEvents(EtAttachment, org.jlab.coda.et.enums.Mode,Modify,int,int), and EtSystem.newEvents(EtAttachment, org.jlab.coda.et.enums.Mode,boolean,int,int,int,int).

Parameters:

size - size of the data array in bytes.

limit - limit on the size of the data array in bytes. Only used for C-based ET systems.

isJava - is ET system Java based?

noBuffer - forget about allocating byte array and ByteBuffer?

EtEventImpl

EtEventImpl(int size,
            int limit,
            int id,
            int owner,
            int modify,
            int length,
            int priority,
            int byteOrder,
            boolean isTemp,
            java.nio.ByteBuffer buffer)

Creates an event object for ET system users when connecting to local, C-based ET systems and using native methods to call et_events_new. The ByteBuffer object is created in JNI code and directly "wraps" the et data pointer from the ET event obtained through et_events_new_group. Tons of args since it's a lot easier in JNI to call one method with lots of args then to call lots of set methods on one object.

Parameters:

size - memSize

limit - sizeLimit

id - id

owner - owner

modify - modify

length - length

priority - modify

byteOrder - byteOrder

isTemp - isTemp

buffer - dataBuffer

EtEventImpl

EtEventImpl(int size,
            int limit,
            int status,
            int id,
            int age,
            int owner,
            int modify,
            int length,
            int priority,
            int byteOrder,
            int[] control,
            boolean isTemp,
            java.nio.ByteBuffer buffer)

Creates an event object for ET system users when connecting to local, C-based ET systems and using native methods to call et_events_get. The ByteBuffer object is created in JNI code and directly "wraps" the et data pointer from the ET event obtained through et_events_get. Tons of args since it's a lot easier in JNI to call one method with lots of args then to call lots of set methods on one object.

Parameters:

size - memSize

limit - sizeLimit

status - dataStatus

id - id

age - age

owner - owner

modify - modify

length - length

priority - modify

byteOrder - byteOrder

control - control

isTemp - isTemp

buffer - dataBuffer

EtEventImpl

public EtEventImpl(EtEventImpl ev)

Creates an event object by duplicating another.

Parameters:

ev - event to duplicate

Method Detail

init

public void init()

Initialize an event's fields. Called for an event each time it passes through GRAND_CENTRAL station.

Specified by:

init in interface EtEvent

getId

public int getId()

Gets the event's id number.

Specified by:

getId in interface EtEvent

Returns:

event's id number.

getAge

public org.jlab.coda.et.enums.Age getAge()

Gets the age of the event, either Age.NEW if a new event obtained through calling EtSystem.newEvents(EtAttachment, org.jlab.coda.et.enums.Mode, int, int, int) or Age.USED if obtained through calling EtSystem.getEvents(EtAttachment, org.jlab.coda.et.enums.Mode, org.jlab.coda.et.enums.Modify, int, int).

Specified by:

getAge in interface EtEvent

Returns:

age of the event.

getGroup

public int getGroup()

Gets the group the event belongs to (1, 2, ...) if ET system events are divided into groups. If not, group = 1. Used so some producers don't hog events from others.

Specified by:

getGroup in interface EtEvent

Returns:

the group the event belongs to.

getPriority

public org.jlab.coda.et.enums.Priority getPriority()

Gets the event's priority, either high Priority.HIGH or low Priority.LOW. Low priority is normal while high priority events get placed at the front of stations' input and output event lists.

Specified by:

getPriority in interface EtEvent

Returns:

event's priority.

getPriorityValue

public int getPriorityValue()

Get int value associated with Priority enum.

Returns:

int value associated with Priority enum

getOwner

public int getOwner()

Gets the attachment id of the attachment which owns or got the event. If it's owned by the system its value is EtConstants.system.

Specified by:

getOwner in interface EtEvent

Returns:

id of owning attachment or EtConstants.system if system owns it

getLength

public int getLength()

Gets the length of the data in bytes.

Specified by:

getLength in interface EtEvent

Returns:

length of the data in bytes.

getMemSize

public int getMemSize()

Gets the size of the data buffer in bytes.

Specified by:

getMemSize in interface EtEvent

Returns:

size of the data buffer in bytes

getSizeLimit

public int getSizeLimit()

Gets the size limit of the data buffer in bytes when using a C-based ET system.

Returns:

size size limit of the data buffer in bytes

getDataStatus

public org.jlab.coda.et.enums.DataStatus getDataStatus()

Gets the status of the data (set by the system), which can be OK DataStatus.OK, corrupted DataStatus.CORRUPT, or possibly corrupted DataStatus.POSSIBLYCORRUPT. Data is OK by default, it is never labeled as corrupt but can be labeled as possible corrupt if the process owning an event crashes and the system recovers it.

Specified by:

getDataStatus in interface EtEvent

Returns:

status of the data.

getDataStatusValue

public int getDataStatusValue()

Get int value associated with DataStatus enum.

Returns:

int value associated with DataStatus enum

getModify

public org.jlab.coda.et.enums.Modify getModify()

Gets the event's modify value when receiving it over the network. This specifies whether the user wants to read the event only, will modify only the event header (everything except the data), or will modify the data and/or header. Modifying the data and/or header is Modify.ANYTHING, modifying only the header is Modify.HEADER, else the default assumed, Modify.NOTHING, is that nothing is modified resulting in this event being put back into the ET system (by remote server) immediately upon being copied and that copy sent to the user.

Specified by:

getModify in interface EtEvent

Returns:

event's modify value.

getByteOrder

public java.nio.ByteOrder getByteOrder()

Gets the event data's byte order.

Specified by:

getByteOrder in interface EtEvent

Returns:

event data's byte order

getRawByteOrder

public int getRawByteOrder()

Gets the raw byte order data (0x04030201 or 0x01020304).

Specified by:

getRawByteOrder in interface EtEvent

Returns:

raw byte order data (0x04030201 or 0x01020304).

getControl

public int[] getControl()

Gets a copy of the event's control array. This is an array of integers which can be used for any purpose by the user.

Specified by:

getControl in interface EtEvent

Returns:

copy of event's control array.

getControlNoCopy

public int[] getControlNoCopy()

Gets a reference to the event's control array without copying. This is an additional method added later to facilitate minimizing garbage creation. This is an array of integers which can be used for any purpose by the user.

Specified by:

getControlNoCopy in interface EtEvent

Returns:

event's control array.

getData

public byte[] getData()
               throws java.lang.UnsupportedOperationException

Gets the data array which is backing the event's data buffer if there is one. Any changes to the array will be reflected in the buffer. If there is no backing data array, as is the case when a user connects to a local, C-based ET system (memory mapped buffer) then an exception is thrown.

Specified by:

getData in interface EtEvent

Returns:

data array which is backing the event's data buffer

Throws:

java.lang.UnsupportedOperationException - if there is no backing array

getDataBuffer

public java.nio.ByteBuffer getDataBuffer()

Gets the event's data buffer.

Specified by:

getDataBuffer in interface EtEvent

Returns:

event's data buffer.

isTemp

public boolean isTemp()

Gets whether this event is a temporary event or not. For java-based ET systems this is always false. If this event represents an event in a local, C-based ET system (through JNI), this can be true if its memory is larger than that of the normal events necessitating the temporary allocation of another chunk of shared memory just for this event.

Specified by:

isTemp in interface EtEvent

Returns:

true if this events represents a local, C-based ET system temp event, else false.

setId

public void setId(int id)

Sets the event's id number.

Parameters:

id - event's id number

setAge

public void setAge(org.jlab.coda.et.enums.Age age)

Sets the age of the event which is Age.NEW for new events obtained by calling EtSystem.newEvents(EtAttachment, org.jlab.coda.et.enums.Mode, int, int, int)), or Age.NEW for "used" event obtained by calling EtSystem.getEvents(EtAttachment, org.jlab.coda.et.enums.Mode, org.jlab.coda.et.enums.Modify, int, int)).

Parameters:

age - age of the event

setGroup

public void setGroup(int group)

Sets the group the event belongs to: (1, 2, ...) if ET system events are divided into groups, or group = 1 if not.

Parameters:

group - group the event belongs to

setPriority

public void setPriority(org.jlab.coda.et.enums.Priority pri)

Sets the event's priority, either high Priority.HIGH or low Priority.LOW. Low priority is normal while high priority events get placed at the front of stations' input and output event lists.

Specified by:

setPriority in interface EtEvent

Parameters:

pri - event priority

setOwner

public void setOwner(int owner)

Sets the owner of the event (attachment using event or system).

Parameters:

owner - owner of event (attachment using event or system)

setLength

public void setLength(int len)
               throws org.jlab.coda.et.exception.EtException

Sets the event's data length in bytes.

Specified by:

setLength in interface EtEvent

Parameters:

len - data length

Throws:

org.jlab.coda.et.exception.EtException - if length is less than zero

setLengthFromServer

public void setLengthFromServer(int len)
                         throws org.jlab.coda.et.exception.EtException

Set the length of valid data from server where sizeLimit may be 0.

Parameters:

len - length of valid data

Throws:

org.jlab.coda.et.exception.EtException - if len is negative

setMemSize

public void setMemSize(int memSize)

Sets the size of the data buffer in bytes.

Parameters:

memSize - size of the data buffer in bytes

setSizeLimit

void setSizeLimit(int sizeLimit)

Sets the limit of the size of the data buffer in bytes.

Parameters:

sizeLimit - limit of the size of the data buffer in bytes.

setJava

void setJava(boolean java)

Sets flag specifying whether the ET system process is Java based or not.

Parameters:

java - if true, ET system is java-based, else it's C-based.

setDataStatus

public void setDataStatus(org.jlab.coda.et.enums.DataStatus status)

Sets the event's data status. It can be ok DataStatus.OK which is the default, corrupted DataStatus.CORRUPT which is never used actually, or possibly corrupted DataStatus.POSSIBLYCORRUPT which occurs when a process holding the event crashes and the system recovers it.

Parameters:

status - data status

setModify

public void setModify(org.jlab.coda.et.enums.Modify modify)

Sets whether the user wants to read the event only, will modify only the event header (everything except the data), or will modify the data and/or header. Modifying the data and/or header is Modify.ANYTHING, modifying only the header is Modify.HEADER, else the default assumed, Modify.NOTHING, is that nothing is modified resulting in this event being put back into the ET system (by remote server) immediately upon being copied and that copy sent to the user.

Parameters:

modify - is Modify.ANYTHING, Modify.HEADER, or Modify.NOTHING.

setByteOrder

public void setByteOrder(int endian)
                  throws org.jlab.coda.et.exception.EtException

Set the event data's byte order by using values consistent with C-based ET systems, EtConstants.endianBig, EtConstants.endianLittle, EtConstants.endianLocal, EtConstants.endianNotLocal, or EtConstants.endianSwitch.

Specified by:

setByteOrder in interface EtEvent

Parameters:

endian - endian value

Throws:

org.jlab.coda.et.exception.EtException - if argument is a bad value

setByteOrder

public void setByteOrder(java.nio.ByteOrder order)

Set the event data's byte order.

Specified by:

setByteOrder in interface EtEvent

Parameters:

order - data's byte order

setRawByteOrder

public void setRawByteOrder(int byteOrder)
                     throws org.jlab.coda.et.exception.EtException

Set the event data's byte order as big with 0x04030201 or as little with 0x01020304. This is how byte order is stored internally in this object and how it is stored in the C code.

Specified by:

setRawByteOrder in interface EtEvent

Parameters:

byteOrder - data's byte order as big with 0x04030201 or as little with 0x01020304.

Throws:

org.jlab.coda.et.exception.EtException - if argument is a bad value

setControl

public void setControl(int[] con)
                throws org.jlab.coda.et.exception.EtException

Sets the event's control array by copying it into the event.

Specified by:

setControl in interface EtEvent

Parameters:

con - control array

Throws:

org.jlab.coda.et.exception.EtException - if control array has the wrong number of elements

setData

public void setData(byte[] data)

Sets the event's data without copying. The length and memSize members of the event are automatically set to the data array's length. Used only by local Java ET system in newEvents to increase data array size.

Parameters:

data - data array

setDataBuffer

public void setDataBuffer(java.nio.ByteBuffer dataBuffer)

Sets the event's data buffer (must be backed by data array). This is used when reading data from shared memory and also if remote user gets new events with the no-buffer arg true. In the latter case, the user must set the data buffer explicitly or an exception will result when trying to put the event back. In any case, using this method should only be done by the expert user.

Parameters:

dataBuffer - event's data buffer (must be backed by data array)

needToSwap

public boolean needToSwap()

Tells caller if the event data needs to be swapped in order to be the same byte order as the local JVM. This method is not needed when accessing data through the ByteBuffer object and endianness is handled behind the scenes.

Specified by:

needToSwap in interface EtEvent

Returns:

true if swapping is needed, otherwise false