tuwien.auto.calimero.buffer
Class LDataObjectQueue

java.lang.Object
  tuwien.auto.calimero.buffer.cache.CacheObject
      tuwien.auto.calimero.buffer.LDataObject
          tuwien.auto.calimero.buffer.LDataObjectQueue

public class LDataObjectQueue
extends LDataObject

A CacheObject used for holding a list of CEMILData frames.

A KNX address is specified on creation, which will be used to generate the cache object key. A LDataObjectQueue is used for frames having all the same key like the one supplied on creation of a new queue. For each frame inserted into the queue, its own timestamp will get stored.
These different queue behaviors are available (optional):
A limit might be set for the maximum size of the queue. Reading of the queue can be consuming, i.e. a frame and its timestamp is removed after reading the frame. With a maximum queue size set, overwriting of old frames (according to insertion order) can be enabled, to allow storing a new frame when the queue got filled up by removing the oldest frames (i.e. a ring buffer).

Nested Class Summary

static class	LDataObjectQueue.QueueItem Represents an item in the queue, holding one L-Data frame and its timestamp.
static interface	LDataObjectQueue.QueueListener Listener for queue events.

Field Summary

Fields inherited from class tuwien.auto.calimero.buffer.cache.CacheObject

value

Constructor Summary

LDataObjectQueue(GroupAddress addr)
Creates a new LDataObjectQueue for KNX address addr.

LDataObjectQueue(GroupAddress addr, boolean consumingRead)
Creates a new LDataObjectQueue for KNX address addr.

LDataObjectQueue(GroupAddress addr, boolean consumingRead, int maxSize, boolean overwrite, LDataObjectQueue.QueueListener l)
Creates a new LDataObjectQueue for KNX address addr with a fixed maximum queue size.

Method Summary

void	clear() Clears the frame and timestamp queue.
CEMILData	getFrame() Returns a CEMILData frame contained in this cache object.
CEMILData[]	getFrames() Returns all L-Data frames currently hold by the queue.
LDataObjectQueue.QueueItem	getItem() Returns the next queued item in insertion order.
int	getSize() Returns the number of frames currently in the queue.
long[]	getTimestamps() Returns the timestamps of the frames hold by the queue.
java.lang.Object	getValue() Gets the value entry hold by this cache object.
boolean	isConsuming() Returns mode for consuming read behavior.
boolean	isOverwrite() Returns mode for overwrite used for this queue.
void	setFrame(CEMILData frame) Sets a new CEMILData frame for this cache object.

Methods inherited from class tuwien.auto.calimero.buffer.cache.CacheObject

getCount, getKey, getTimestamp, getUsage, incCount, resetCount, resetTimestamp, setUsage

Methods inherited from class java.lang.Object

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

Constructor Detail

LDataObjectQueue

public LDataObjectQueue(GroupAddress addr)

Creates a new LDataObjectQueue for KNX address addr.

There is no limit on the queue size used.

Parameters:

addr - KNX address to create the queue for, this address is used to generate the cache object key

LDataObjectQueue

public LDataObjectQueue(GroupAddress addr,
                        boolean consumingRead)

Creates a new LDataObjectQueue for KNX address addr.

There is no limit on the queue size used.

Parameters:

addr - KNX address to create the queue for, this address is used to generate the cache object key

consumingRead - set true to remove a frame from the queue the first time it gets requested for read (i.e. returned by a frame getter method), false to leave it in the queue

LDataObjectQueue

public LDataObjectQueue(GroupAddress addr,
                        boolean consumingRead,
                        int maxSize,
                        boolean overwrite,
                        LDataObjectQueue.QueueListener l)

Creates a new LDataObjectQueue for KNX address addr with a fixed maximum queue size.

Parameters:

addr - KNX address to create the queue for, this address is used to generate the cache object key

consumingRead - set true to remove a frame from the queue the first time it gets requested for read (i.e. returned by a frame getter method), false to leave it in the queue

maxSize - the maximum queue size, i.e. max. number of frames hold by the queue, maxSize has to be > 0

overwrite - set true if on full queue a new frame should replace the oldest frame in the queue (i.e. ring buffer semantics),
set false if on full queue new frames should be ignored

l - sets a queue listener to receive events from this queue, use null if no notifications are required

Method Detail

clear

public final void clear()

Clears the frame and timestamp queue.

The queue will be empty on return.

getFrame

public CEMILData getFrame()

Returns a CEMILData frame contained in this cache object.

On no frame available, null is returned. Frames are returned in insertion order. If consuming read behavior is enabled, the frame will be removed from the queue before return.

Overrides:

getFrame in class LDataObject

Returns:

the CEMILData frame, or null

getFrames

public final CEMILData[] getFrames()

Returns all L-Data frames currently hold by the queue.

The frames are returned in insertion order. If consuming read behavior is enabled, the internal queue buffer is cleared before return.
Note that on consuming read the associated timestamps of the frames will be cleared, too, before return of this method. In order to obtain the timestamps, getTimestamps() has to be called at first.

Returns:

the frame queue as CEMILData array

getItem

public LDataObjectQueue.QueueItem getItem()

Returns the next queued item in insertion order.

The item consists of the L-Data frame and its associated timestamp. This method behaves equal to getFrame() with respect to queueing behavior.
If the queue is empty, an empty QueueItem is returned.

Returns:

queued item as QueueItem object

getSize

public final int getSize()

Returns the number of frames currently in the queue.

Since each frame has its associated timestamp, this is also the number of timestamps at the same time.

Returns:

number of frames (timestamps) currently in the queue

getTimestamps

public final long[] getTimestamps()

Returns the timestamps of the frames hold by the queue.

The timestamps are returned in insertion order of the associated frames.
This means, if no setFrame(CEMILData) is called in between,

• getTimestamps()[i] belongs to getFrames()[i], where 0 <= i < getSize()
• getTimestamps().length == getFrames().length
.

Note that on consuming read, reading of timestamps does not trigger any removal of frames (see getFrames()).

Returns:

the timestamps of all contained frames as array of type long

See Also:

CacheObject.getTimestamp()

getValue

public java.lang.Object getValue()

Gets the value entry hold by this cache object.

Note that the value is guaranteed to be always a non null reference.
Note that the length of the returned buffer might be 0.
This method is equal to invoking getFrames().

Overrides:

getValue in class CacheObject

Returns:

the queue as CEMILData array

isConsuming

public final boolean isConsuming()

Returns mode for consuming read behavior.

Returns:

true if queued items get consumed on read, false if a read does not modify the queue

isOverwrite

public final boolean isOverwrite()

Returns mode for overwrite used for this queue.

Returns:

true if overwrite is used, false otherwise

setFrame

public void setFrame(CEMILData frame)

Sets a new CEMILData frame for this cache object.

The key generated out of frame (i.e. out of the KNX address of frame) has to be equal to the key of this LDataObject, as returned from CacheObject.getKey(). Otherwise a KNXIllegalArgumentException will be thrown.
Note that on successful set the timestamp is renewed.
If a maximum size is set and the queue already reached maximum size, if isOverwrite() evaluates to
- true, frame will replace the oldest inserted frame
- false, frame is ignored and not queued.

Overrides:

setFrame in class LDataObject

Parameters:

frame - the new CEMILData frame to set