|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Objectgr.uoa.di.madgik.grs.buffer.QueueBuffer
public class QueueBuffer
The QueueBuffer is the main implementation of the IBuffer interface. The
QueueBuffer implements the IBuffer interface through two underlying queues.
Upon initialization, two queues are constructed, each with the capacity dictated by
setCapacity(int). One of the queues, the forward one is
used by the writer whenever a new Record is created and inserted in the buffer. The
other queue, the backward one, is used to place items that have been read by the reader.
Whenever a Record is moved out of the head of the forward queue, it is placed in the
end of the backward queue while records that overflow the head of the backward queue are
disposed. The backward buffer's capacity is increased at initialization time by the number
of concurrent partial record requests the setConcurrentPartialCapacity(int)
method has set. Therefore, when setting the two configuration values, one should make note that
the maximum number of Records that will at any time be consuming memory resources will
be 2 * getCapacity() + getConcurrentPartialCapacity()
| Nested Class Summary |
|---|
| Nested classes/interfaces inherited from interface gr.uoa.di.madgik.grs.buffer.IBuffer |
|---|
IBuffer.Status, IBuffer.TransportDirective, IBuffer.TransportOverride |
| Field Summary | |
|---|---|
static int |
DefaultCapacity
The default buffer capacity. |
static int |
DefaultConcurrentPartial
The default value of concurrently served partial Records. |
static long |
DefaultInactivityTimeout
The default inactivity timeout value. |
static java.util.concurrent.TimeUnit |
DefaultInactivityTimeUnit
The default inactivity timeout time unit value. |
static float |
DefaultMirrorBufferFactor
The default mirror buffer scaling factor over the set buffer capacity. |
static float |
DefaultThreshold
The default threshold value. |
| Constructor Summary | |
|---|---|
QueueBuffer()
|
|
| Method Summary | |
|---|---|
int |
availableRecords()
Retrieves the number of Records that are currently available to be read |
void |
close()
Closes the authoring side of the IBuffer after this invocation, no more Records can be added
to the IBuffer but a reader can still consume any Records that are still available. |
void |
dispose()
Disposes the IBuffer and all its underlying resources. |
void |
emit(BufferEvent event)
Emits a BufferEvent targeted to the other end of the IBuffer usage. |
Record |
get()
Attempts to retrieve a Record from the IBuffer. |
int |
getCapacity()
Retrieves the capacity of the underlying bounded buffer that can store the Records that a writer adds to it |
int |
getConcurrentPartialCapacity()
Retrieves the number of items that a reader can concurrently request more of its payload in case this payload is transported in IBuffer.TransportDirective.Partial mode. |
long |
getInactivityTimeout()
Retrieves the timeout after which if the buffer has remained inactive is eligible for purging. |
java.util.concurrent.TimeUnit |
getInactivityTimeUnit()
Retrieves the timeout TimeUnit after which if the buffer has remained inactive is eligible for purging. |
java.lang.String |
getKey()
Retrieves the key under which the IBuffer is registered and accessible through the registry |
long |
getLastActivityTime()
Retrieves the last activity time of the IBuffer. |
IMirror |
getMirror()
Retrieves the IMirror implementation that serves this IBuffer. |
int |
getMirrorBuffer()
If an IMirror is used to synchronize the IBuffer instances accessible to the reader and writer,
this value indicates the number of Records that the writer IMirror} will limit its sending
phase to choke large transfers |
java.lang.Object |
getReaderImmediateNotificationObject()
Using this object, a reader can be blocked using a standard synchronized / wait block to be notified by the IBuffer when the writer has increased its available Records by one |
RecordDefinition[] |
getRecordDefinitions()
Retrieves the definitions of the Records provided using IBuffer.setRecordDefinitions(RecordDefinition[]) |
boolean |
getSimulateActivity()
Retrieves the simulate activity status of the IBuffer. |
IBuffer.Status |
getStatus()
Retrieves the IBuffer.Status of the IBuffer |
IBuffer.TransportDirective |
getTransportDirective()
Retrieves the IBuffer.TransportDirective set for the IBuffer. |
java.lang.Object |
getWriterImmediateNotificationObject()
Using this object, a writer can be blocked using a standard synchronized / wait block to be notified by the IBuffer when the reader has reduced its available Records by one |
void |
initialize()
After all configuration values have been set, this method performs all the initialization needed to get the IBuffer ready to receive Records from a writer and serve them to a reader. |
Record |
locate(long recordIndex)
Attempts to locate the Record with the provided id in the underlying IBuffer structures. |
void |
markSimulateActivity()
Sets the simulate activity status and updates last activity time of the IBuffer to the current time. |
boolean |
put(Record record)
Attempts to place a Record to the IBuffer. |
BufferEvent |
receive(BufferEvent.EventSource source)
Receives a BufferEvent emitted by the other end of the IBuffer usage. |
IBuffer.TransportDirective |
resolveTransportDirective()
Resolves the set IBuffer.TransportDirective set for the IBuffer through
IBuffer.setTransportDirective(TransportDirective). |
void |
setBufferStore(IBufferStore store)
If the current IBuffer is served by a IBufferStore, the is set
so that its last activity time is set everytime the IBuffer's activity time is also
updated |
void |
setCapacity(int capacity)
Sets the capacity of the underlying bounded buffer that can store the Records that a writer adds to it. |
void |
setConcurrentPartialCapacity(int capacity)
Sets the number of items that a reader can concurrently request more of its payload in case this payload is transported in IBuffer.TransportDirective.Partial mode. |
void |
setInactivityTimeout(long timeout)
Sets the timeout after which if the buffer has remained inactive is eligible for purging. |
void |
setInactivityTimeUnit(java.util.concurrent.TimeUnit unit)
Sets the timeout TimeUnit after which if the buffer has remained inactive is eligible for purging. |
void |
setKey(java.lang.String key)
In case this IBuffer is registered to be served to a reader, the key by which it is registered is provided |
void |
setMirror(IMirror mirror)
Sets the IMirror implementation that serves this IBuffer. |
void |
setMirrorBuffer(int size)
If an IMirror is used to synchronize the IBuffer instances accessible to the reader and writer,
this value indicates the number of Records that the writer IMirror} will limit its sending
phase to choke large transfers. |
void |
setRecordDefinitions(RecordDefinition[] definitions)
Sets the definitions of the Records that are to be placed in the IBuffer. |
void |
setTransportDirective(IBuffer.TransportDirective directive)
Sets the IBuffer.TransportDirective set for the IBuffer. |
long |
totalRecords()
Retrieves the number of Records that have in total passed through the IBuffer. |
| Methods inherited from class java.lang.Object |
|---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Field Detail |
|---|
public static int DefaultCapacity
setCapacity(int)
public static int DefaultConcurrentPartial
Records. This is the default value
for the configuration parameter set otherwise though setConcurrentPartialCapacity(int)
public static float DefaultThreshold
QueueBuffer#setNotificationThreshold(float)
public static long DefaultInactivityTimeout
setInactivityTimeout(long)
public static java.util.concurrent.TimeUnit DefaultInactivityTimeUnit
setInactivityTimeUnit(TimeUnit)
public static float DefaultMirrorBufferFactor
setMirrorBuffer(int)
| Constructor Detail |
|---|
public QueueBuffer()
| Method Detail |
|---|
public void setMirror(IMirror mirror)
IMirror implementation that serves this IBuffer. If null, no mirror is
used between the writer and reader and the share the same IBuffer instance
setMirror in interface IBuffermirror - the mirror serving the synchronization of the IBuffer between the reader and writerIBuffer.setMirror(gr.uoa.di.madgik.grs.proxy.mirror.IMirror)public IMirror getMirror()
IMirror implementation that serves this IBuffer. If null, no mirror is
used between the writer and reader and the share the same IBuffer instance
getMirror in interface IBufferIMirror implementation that serves this IBufferIBuffer.getMirror()public long getLastActivityTime()
IBuffer. This value is used in conjunction with the
timeout configuration values available through IBuffer.getInactivityTimeout() and
IBuffer.getInactivityTimeUnit()
getLastActivityTime in interface IBufferIBuffer.getLastActivityTime()public void markSimulateActivity()
IBuffer to the current time. Used after
an operation which was not performed directly on the buffer, but should nevertheless be treated as producer/consumer
interaction has taken place.
markSimulateActivity in interface IBufferIBuffer.markSimulateActivity()public boolean getSimulateActivity()
IBuffer. The status will be reset after calling this method.
getSimulateActivity in interface IBufferIBufferIBuffer.getSimulateActivity()
public RecordDefinition[] getRecordDefinitions()
throws GRS2BufferDisposedException
Records provided using IBuffer.setRecordDefinitions(RecordDefinition[])
getRecordDefinitions in interface IBufferGRS2BufferDisposedException - if the buffer's dispose() has already been invokedIBuffer.getRecordDefinitions()
public void setRecordDefinitions(RecordDefinition[] definitions)
throws GRS2BufferInitializationException
Records that are to be placed in the IBuffer. All
records that are then inserted in the IBuffer must point to one of these definitions.
This is a configuration parameter that can be set only before IBuffer initialization.
The order by which these definitions are provided is maintained and can be used for reference
setRecordDefinitions in interface IBufferdefinitions - the record definitions
GRS2BufferInitializationException - when the buffer's status is not IBuffer.Status.InitIBuffer.setRecordDefinitions(gr.uoa.di.madgik.grs.record.RecordDefinition[])
public IBuffer.TransportDirective getTransportDirective()
throws GRS2BufferDisposedException
IBuffer.TransportDirective set for the IBuffer. This value is used by the contained
items in case they have defined IBuffer.TransportDirective.Inherit and it is not resolved further down the
item hierarchy. This value should be permitted to be IBuffer.TransportDirective.Inherit
getTransportDirective in interface IBufferGRS2BufferDisposedException - if the buffer's dispose() has already been invokedIBuffer.getTransportDirective()
public void setTransportDirective(IBuffer.TransportDirective directive)
throws GRS2BufferInitializationException,
GRS2BufferInvalidArgumentException
IBuffer.TransportDirective set for the IBuffer. This value is used by the contained
items in case they have defined IBuffer.TransportDirective.Inherit and it is not resolved further down the
item hierarchy. This value should be permitted to be IBuffer.TransportDirective.Inherit. This is a configuration
parameter that can be set only before IBuffer initialization
setTransportDirective in interface IBufferdirective - the transport directive
GRS2BufferInitializationException - when the buffer's status is not IBuffer.Status.Init
GRS2BufferInvalidArgumentException - if the provided directive is IBuffer.TransportDirective.InheritIBuffer.setTransportDirective(gr.uoa.di.madgik.grs.buffer.IBuffer.TransportDirective)
public IBuffer.TransportDirective resolveTransportDirective()
throws GRS2BufferDisposedException
IBuffer.TransportDirective set for the IBuffer through
IBuffer.setTransportDirective(TransportDirective). This is the operation that should used by the underlying
items when resolving their IBuffer.TransportDirective to avoid reaching the indecision point where they
end up with a final IBuffer.TransportDirective.Inherit directive. This method should never return a value
of IBuffer.TransportDirective.Inherit
In case the defined IBuffer.TransportDirective is IBuffer.TransportDirective.Inherit, the value is
overridden to IBuffer.TransportDirective.Full
resolveTransportDirective in interface IBufferIBuffer.TransportDirective
further down the item hierarchy
GRS2BufferDisposedException - if the buffer's dispose() has already been invokedIBuffer.resolveTransportDirective()
public int getCapacity()
throws GRS2BufferDisposedException
Records that a writer adds to it
getCapacity in interface IBufferGRS2BufferDisposedException - if the buffer's dispose() has already been invokedIBuffer.getCapacity()
public void setCapacity(int capacity)
throws GRS2BufferDisposedException,
GRS2BufferInitializationException,
GRS2BufferInvalidArgumentException
Records that a writer adds to it.
This is a configuration parameter that can be set only before IBuffer initialization.
setCapacity in interface IBuffercapacity - the bounded buffer capacity
GRS2BufferDisposedException - if the buffer's dispose() has already been invoked
GRS2BufferInitializationException - when the buffer's status is not IBuffer.Status.Init
GRS2BufferInvalidArgumentException - if the provided capacity is less or equal to 0IBuffer.setCapacity(int)
public int getConcurrentPartialCapacity()
throws GRS2BufferException
IBuffer.TransportDirective.Partial mode. This means that even after a reader has accessed the
Record, it should remain accessible for further requests to it. Finding a value larger than 1, permits
a willing reader to process in parallel more than one requests
getConcurrentPartialCapacity in interface IBufferGRS2BufferDisposedException - if the buffer's dispose() has already been invoked
GRS2BufferException - The status of the IBuffer does not allow for the operation to be executedIBuffer.getConcurrentPartialCapacity()
public void setConcurrentPartialCapacity(int capacity)
throws GRS2BufferDisposedException,
GRS2BufferInitializationException,
GRS2BufferInvalidArgumentException
IBuffer.TransportDirective.Partial mode. This means that even after a reader has accessed the
Record, it should remain accessible for further requests to it. Setting a value larger than 1, will enable
a willing reader to process in parallel more than one requests. This is a configuration parameter that can be set
only before IBuffer initialization
setConcurrentPartialCapacity in interface IBuffercapacity - the concurrent number of partially retrieved records that can be used
GRS2BufferDisposedException - if the buffer's dispose() has already been invoked
GRS2BufferInitializationException - when the buffer's status is not IBuffer.Status.Init
GRS2BufferInvalidArgumentException - if the provided partial concurrency capacity is less or equal to 0IBuffer.setConcurrentPartialCapacity(int)
public void setMirrorBuffer(int size)
throws GRS2BufferDisposedException,
GRS2BufferInitializationException
IMirror is used to synchronize the IBuffer instances accessible to the reader and writer,
this value indicates the number of Records that the writer IMirror} will limit its sending
phase to choke large transfers. This is a configuration parameter that can be set only before IBuffer
initialization
setMirrorBuffer in interface IBuffersize - the size of the mirroring window
GRS2BufferDisposedException - if the buffer's dispose() has already been invoked
GRS2BufferInitializationException - when the buffer's status is not IBuffer.Status.InitIBuffer.setMirrorBuffer(int)
public int getMirrorBuffer()
throws GRS2BufferDisposedException
IMirror is used to synchronize the IBuffer instances accessible to the reader and writer,
this value indicates the number of Records that the writer IMirror} will limit its sending
phase to choke large transfers
getMirrorBuffer in interface IBufferGRS2BufferDisposedException - if the buffer's dispose() has already been invokedIBuffer.getMirrorBuffer()
public java.util.concurrent.TimeUnit getInactivityTimeUnit()
throws GRS2BufferDisposedException
TimeUnit after which if the buffer has remained inactive is eligible for purging.
This value is interpreted with respect to the timeout defined through IBuffer.getInactivityTimeout()
getInactivityTimeUnit in interface IBufferTimeUnit
GRS2BufferDisposedException - if the buffer's dispose() has already been invokedIBuffer.getInactivityTimeUnit()
public void setInactivityTimeUnit(java.util.concurrent.TimeUnit unit)
throws GRS2BufferDisposedException
TimeUnit after which if the buffer has remained inactive is eligible for purging. This value
is interpreted with respect to the timeout defined through IBuffer.getInactivityTimeout().
This is a configuration parameter that can be set only before IBuffer initialization
setInactivityTimeUnit in interface IBufferunit - the timeout TimeUnit
GRS2BufferDisposedException - if the buffer's dispose() has already been invokedIBuffer.setInactivityTimeUnit(java.util.concurrent.TimeUnit)
public long getInactivityTimeout()
throws GRS2BufferDisposedException
TimeUnit defined through IBuffer.getInactivityTimeUnit()
getInactivityTimeout in interface IBufferGRS2BufferDisposedException - if the buffer's dispose() has already been invokedIBuffer.getInactivityTimeout()
public void setInactivityTimeout(long timeout)
throws GRS2BufferDisposedException
TimeUnit defined through IBuffer.getInactivityTimeUnit().
This is a configuration parameter that can be set only before IBuffer initialization
setInactivityTimeout in interface IBuffertimeout - the timeout period
GRS2BufferDisposedException - if the buffer's dispose() has already been invokedIBuffer.setInactivityTimeout(long)
public java.lang.Object getWriterImmediateNotificationObject()
throws GRS2BufferDisposedException
IBuffer when the reader has reduced its available Records by one
getWriterImmediateNotificationObject in interface IBufferGRS2BufferDisposedException - if the buffer's dispose() has already been invokedIBuffer.getWriterImmediateNotificationObject()
public java.lang.Object getReaderImmediateNotificationObject()
throws GRS2BufferDisposedException
IBuffer when the writer has increased its available Records by one
getReaderImmediateNotificationObject in interface IBufferGRS2BufferDisposedException - if the buffer's dispose() has already been invokedIBuffer.getReaderImmediateNotificationObject()public java.lang.String getKey()
IBuffer is registered and accessible through the registry
getKey in interface IBufferIBuffer.getKey()
public void setKey(java.lang.String key)
throws GRS2BufferInvalidArgumentException,
GRS2BufferInvalidOperationException
IBuffer is registered to be served to a reader, the key by which it is registered is provided
setKey in interface IBufferkey - the registry key
GRS2BufferInvalidArgumentException - if the provided key is null or empty
GRS2BufferInvalidOperationException - if the QueueBuffer has already been set with a keyIBuffer.setKey(java.lang.String)
public void initialize()
throws GRS2BufferDisposedException,
GRS2BufferInitializationException,
GRS2BufferInvalidArgumentException
IBuffer ready to receive Records from a writer and serve them to a reader. After this point no
configuration parameters can be set and the IBuffer.Status of the buffer is changed from IBuffer.Status.Init
to IBuffer.Status.Open. Initialization must only take place once per each IBuffer instance
This method updates the buffer's last activity time
initialize in interface IBufferGRS2BufferDisposedException - if the buffer's dispose() has already been invoked
GRS2BufferInitializationException - when the buffer's status is not IBuffer.Status.Init
GRS2BufferInvalidArgumentException - if the capacity or concurrency partial capacity set is less or
equal to 0, or the notification threshold is outside the lower and upper bounds of 0 and 1 respectivelyIBuffer.initialize()public IBuffer.Status getStatus()
IBuffer.Status of the IBuffer
getStatus in interface IBufferIBuffer.getStatus()
public int availableRecords()
throws GRS2BufferDisposedException,
GRS2BufferInitializationException
Records that are currently available to be read
availableRecords in interface IBufferRecords
GRS2BufferDisposedException - if the buffer's dispose() has already been invoked
GRS2BufferInitializationException - when the buffer's status is not IBuffer.Status.InitIBuffer.availableRecords()
public long totalRecords()
throws GRS2BufferDisposedException,
GRS2BufferInitializationException
Records that have in total passed through the IBuffer. If the IBuffer.Status of
the IBuffer is not IBuffer.Status.Close, then this number is not the final number of records. Once the
status has been set to IBuffer.Status.Close, this is the final number of Records moved though the
IBuffer
totalRecords in interface IBufferRecords
GRS2BufferDisposedException - if the buffer's dispose() has already been invoked
GRS2BufferInitializationException - when the buffer's status is not IBuffer.Status.InitIBuffer.totalRecords()
public void setBufferStore(IBufferStore store)
throws GRS2BufferException
IBuffer is served by a IBufferStore, the is set
so that its last activity time is set everytime the IBuffer's activity time is also
updated
setBufferStore in interface IBufferstore - the IBufferStore that provides the data that the IBuffer is serving
GRS2BufferDisposedException - if the buffer's dispose() has already been invoked
GRS2BufferInitializationException - when the buffer's status is not IBuffer.Status.Init
GRS2BufferException - the status of the IBuffer does not allow for the definitions to be retrievedIBuffer.setBufferStore(IBufferStore)
public boolean put(Record record)
throws GRS2BufferException,
GRS2RecordDefinitionException
Record to the IBuffer. If the operation was successful, true will be returned.
If the IBuffer has reached its capacity, false will be returned. This operation should be successful if
the number of available records, IBuffer.availableRecords(), is less than the IBuffer's capacity,
IBuffer.getCapacity(). After a successful invocation, the available records are increased by one.
This method updates the buffer's last activity time
After successfully adding the provided Record to the QueueBuffer's forward buffer,
the record's Record.bind(IBuffer) is invoked and the synchronization objects are used
to notify any waiting blocked readers
put in interface IBufferrecord - the Record to add
GRS2BufferDisposedException - if the buffer's dispose() has already been invoked
GRS2BufferInitializationException - when the buffer's status is not IBuffer.Status.Open
GRS2RecordDefinitionException - if the provided Record has not been properly provided with a valid RecordDefinition
GRS2BufferException - The status of the IBuffer does not allow for the operation to be executedIBuffer.put(gr.uoa.di.madgik.grs.record.Record)
public Record get()
throws GRS2BufferDisposedException,
GRS2BufferInitializationException
Record from the IBuffer. If the operation is successful, the Record
will be returned. If the number of available records is 0, then null will be returned. This operation should return
successfully with the Record if the number of available records, IBuffer.availableRecords() is greater
than 0. After a successful invocation, the available records are decreased by one.
This method updates the buffer's last activity time
After successfully retrieving the provided Record from the QueueBuffer's forward buffer,
head and removes it from the queue, it adds it to the tail of the backward queue, removing and disposing
any overflowing Record. Additionally, the synchronization objects are used
to notify any waiting blocked writers
get in interface IBufferRecord or null of none is available
GRS2BufferDisposedException - if the buffer's dispose() has already been invoked
GRS2BufferInitializationException - when the buffer's status is not IBuffer.Status.OpenIBuffer.get()
public Record locate(long recordIndex)
throws GRS2BufferDisposedException,
GRS2BufferInitializationException
Record with the provided id in the underlying IBuffer structures. If this
Record is available and not yet served to the reader or it has already been served but remains in the
overflow buffers the size of which is defined by IBuffer.getConcurrentPartialCapacity() then it must be
made available
Both backward and forward queues are checked to locate the requested Record
locate in interface IBufferrecordIndex - the Record id which as documented in the Record component must coincide with
the order by which it was placed to the IBuffer
Record if found, null otherwise
GRS2BufferDisposedException - if the buffer's dispose() has already been invoked
GRS2BufferInitializationException - when the buffer's status is still in IBuffer.Status.InitIBuffer.locate(long)
public void close()
throws GRS2BufferDisposedException,
GRS2BufferInitializationException
IBuffer after this invocation, no more Records can be added
to the IBuffer but a reader can still consume any Records that are still available. The status
of the IBuffer is changed to IBuffer.Status.Close
This method updates the buffer's last activity time
Any blocking readers or writers are notified using the respective synchronization objects
close in interface IBufferGRS2BufferDisposedException - if the buffer's dispose() has already been invoked
GRS2BufferInitializationException - when the buffer's status is still in IBuffer.Status.InitIBuffer.close()public void dispose()
IBuffer and all its underlying resources. After an invocation to this method, no operations
can be performed on the IBuffer. The status is changed to IBuffer.Status.Dispose. The implementations
of this method should make sure that they dispose all resources relevant to the IBuffer
If the buffer's status is already IBuffer.Status.Dispose, then the method returns immediately
Any Record in either the backward or forward queues is disposed
If a IMirror has been associated with the QueueBuffer, the IMirror is disposed
If a registry key is associated with the QueueBuffer, the registry's entry is removed
Any blocked readers or writers, are notified using the respective synchronization objects
dispose in interface IBufferIBuffer.dispose()
public void emit(BufferEvent event)
throws GRS2BufferInvalidArgumentException
BufferEvent targeted to the other end of the IBuffer usage. A BufferEvent
emitted by the writer will only be received by a reader and vice versa.
emit in interface IBufferevent - the event to emit
GRS2BufferInvalidArgumentException - if the provided event is null or the source is not recognizableIBuffer.emit(gr.uoa.di.madgik.grs.events.BufferEvent)
public BufferEvent receive(BufferEvent.EventSource source)
throws GRS2BufferInvalidArgumentException
BufferEvent emitted by the other end of the IBuffer usage. A BufferEvent
emitted by the writer will only be received by a reader and vice versa.
receive in interface IBuffersource - the events that are of interest are the ones of the defined source
GRS2BufferInvalidArgumentException - if the provided source is not recognizableIBuffer.receive(gr.uoa.di.madgik.grs.events.BufferEvent.EventSource)
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||