gr.uoa.di.madgik.grs.buffer
Class QueueBuffer

java.lang.Object
  extended by gr.uoa.di.madgik.grs.buffer.QueueBuffer
All Implemented Interfaces:
IBuffer

public class QueueBuffer
extends java.lang.Object
implements IBuffer

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()

Author:
gpapanikos

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

DefaultCapacity

public static int DefaultCapacity
The default buffer capacity. This is the default value for the configuration parameter set otherwise though setCapacity(int)


DefaultConcurrentPartial

public static int DefaultConcurrentPartial
The default value of concurrently served partial Records. This is the default value for the configuration parameter set otherwise though setConcurrentPartialCapacity(int)


DefaultThreshold

public static float DefaultThreshold
The default threshold value. This is the default value for the configuration parameter set otherwise though QueueBuffer#setNotificationThreshold(float)


DefaultInactivityTimeout

public static long DefaultInactivityTimeout
The default inactivity timeout value. This is the default value for the configuration parameter set otherwise though setInactivityTimeout(long)


DefaultInactivityTimeUnit

public static java.util.concurrent.TimeUnit DefaultInactivityTimeUnit
The default inactivity timeout time unit value. This is the default value for the configuration parameter set otherwise though setInactivityTimeUnit(TimeUnit)


DefaultMirrorBufferFactor

public static float DefaultMirrorBufferFactor
The default mirror buffer scaling factor over the set buffer capacity. This is the default value for the configuration parameter set otherwise though setMirrorBuffer(int)

Constructor Detail

QueueBuffer

public QueueBuffer()
Method Detail

setMirror

public void setMirror(IMirror mirror)
Sets the IMirror implementation that serves this IBuffer. If null, no mirror is used between the writer and reader and the share the same IBuffer instance

Specified by:
setMirror in interface IBuffer
Parameters:
mirror - the mirror serving the synchronization of the IBuffer between the reader and writer
See Also:
IBuffer.setMirror(gr.uoa.di.madgik.grs.proxy.mirror.IMirror)

getMirror

public IMirror getMirror()
Retrieves the IMirror implementation that serves this IBuffer. If null, no mirror is used between the writer and reader and the share the same IBuffer instance

Specified by:
getMirror in interface IBuffer
Returns:
the IMirror implementation that serves this IBuffer
See Also:
IBuffer.getMirror()

getLastActivityTime

public long getLastActivityTime()
Retrieves the last activity time of the IBuffer. This value is used in conjunction with the timeout configuration values available through IBuffer.getInactivityTimeout() and IBuffer.getInactivityTimeUnit()

Specified by:
getLastActivityTime in interface IBuffer
Returns:
the last activity time
See Also:
IBuffer.getLastActivityTime()

markSimulateActivity

public void markSimulateActivity()
Sets the simulate activity status and updates last activity time of the 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.

Specified by:
markSimulateActivity in interface IBuffer
See Also:
IBuffer.markSimulateActivity()

getSimulateActivity

public boolean getSimulateActivity()
Retrieves the simulate activity status of the IBuffer. The status will be reset after calling this method.

Specified by:
getSimulateActivity in interface IBuffer
Returns:
the simulate activity status of the IBuffer
See Also:
IBuffer.getSimulateActivity()

getRecordDefinitions

public RecordDefinition[] getRecordDefinitions()
                                        throws GRS2BufferDisposedException
Retrieves the definitions of the Records provided using IBuffer.setRecordDefinitions(RecordDefinition[])

Specified by:
getRecordDefinitions in interface IBuffer
Returns:
the record definitions
Throws:
GRS2BufferDisposedException - if the buffer's dispose() has already been invoked
See Also:
IBuffer.getRecordDefinitions()

setRecordDefinitions

public void setRecordDefinitions(RecordDefinition[] definitions)
                          throws GRS2BufferInitializationException
Sets the definitions of the 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

Specified by:
setRecordDefinitions in interface IBuffer
Parameters:
definitions - the record definitions
Throws:
GRS2BufferInitializationException - when the buffer's status is not IBuffer.Status.Init
See Also:
IBuffer.setRecordDefinitions(gr.uoa.di.madgik.grs.record.RecordDefinition[])

getTransportDirective

public IBuffer.TransportDirective getTransportDirective()
                                                 throws GRS2BufferDisposedException
Retrieves the 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

Specified by:
getTransportDirective in interface IBuffer
Returns:
the set transport directive
Throws:
GRS2BufferDisposedException - if the buffer's dispose() has already been invoked
See Also:
IBuffer.getTransportDirective()

setTransportDirective

public void setTransportDirective(IBuffer.TransportDirective directive)
                           throws GRS2BufferInitializationException,
                                  GRS2BufferInvalidArgumentException
Sets the 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

Specified by:
setTransportDirective in interface IBuffer
Parameters:
directive - the transport directive
Throws:
GRS2BufferInitializationException - when the buffer's status is not IBuffer.Status.Init
GRS2BufferInvalidArgumentException - if the provided directive is IBuffer.TransportDirective.Inherit
See Also:
IBuffer.setTransportDirective(gr.uoa.di.madgik.grs.buffer.IBuffer.TransportDirective)

resolveTransportDirective

public IBuffer.TransportDirective resolveTransportDirective()
                                                     throws GRS2BufferDisposedException
Resolves the set 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

Specified by:
resolveTransportDirective in interface IBuffer
Returns:
the transport directive to be used by a component that has not resolved its {#link IBuffer.TransportDirective further down the item hierarchy
Throws:
GRS2BufferDisposedException - if the buffer's dispose() has already been invoked
See Also:
IBuffer.resolveTransportDirective()

getCapacity

public int getCapacity()
                throws GRS2BufferDisposedException
Retrieves the capacity of the underlying bounded buffer that can store the Records that a writer adds to it

Specified by:
getCapacity in interface IBuffer
Returns:
the bounded buffer capacity
Throws:
GRS2BufferDisposedException - if the buffer's dispose() has already been invoked
See Also:
IBuffer.getCapacity()

setCapacity

public void setCapacity(int capacity)
                 throws GRS2BufferDisposedException,
                        GRS2BufferInitializationException,
                        GRS2BufferInvalidArgumentException
Sets the capacity of the underlying bounded buffer that can store the Records that a writer adds to it. This is a configuration parameter that can be set only before IBuffer initialization.

Specified by:
setCapacity in interface IBuffer
Parameters:
capacity - the bounded buffer capacity
Throws:
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 0
See Also:
IBuffer.setCapacity(int)

getConcurrentPartialCapacity

public int getConcurrentPartialCapacity()
                                 throws GRS2BufferException
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. 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

Specified by:
getConcurrentPartialCapacity in interface IBuffer
Returns:
the concurrent number of partially retrieved records that can be used
Throws:
GRS2BufferDisposedException - if the buffer's dispose() has already been invoked
GRS2BufferException - The status of the IBuffer does not allow for the operation to be executed
See Also:
IBuffer.getConcurrentPartialCapacity()

setConcurrentPartialCapacity

public void setConcurrentPartialCapacity(int capacity)
                                  throws GRS2BufferDisposedException,
                                         GRS2BufferInitializationException,
                                         GRS2BufferInvalidArgumentException
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. 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

Specified by:
setConcurrentPartialCapacity in interface IBuffer
Parameters:
capacity - the concurrent number of partially retrieved records that can be used
Throws:
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 0
See Also:
IBuffer.setConcurrentPartialCapacity(int)

setMirrorBuffer

public void setMirrorBuffer(int size)
                     throws GRS2BufferDisposedException,
                            GRS2BufferInitializationException
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. This is a configuration parameter that can be set only before IBuffer initialization

Specified by:
setMirrorBuffer in interface IBuffer
Parameters:
size - the size of the mirroring window
Throws:
GRS2BufferDisposedException - if the buffer's dispose() has already been invoked
GRS2BufferInitializationException - when the buffer's status is not IBuffer.Status.Init
See Also:
IBuffer.setMirrorBuffer(int)

getMirrorBuffer

public int getMirrorBuffer()
                    throws GRS2BufferDisposedException
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

Specified by:
getMirrorBuffer in interface IBuffer
Returns:
the size of the mirroring window
Throws:
GRS2BufferDisposedException - if the buffer's dispose() has already been invoked
See Also:
IBuffer.getMirrorBuffer()

getInactivityTimeUnit

public java.util.concurrent.TimeUnit getInactivityTimeUnit()
                                                    throws GRS2BufferDisposedException
Retrieves the timeout 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()

Specified by:
getInactivityTimeUnit in interface IBuffer
Returns:
the timeout TimeUnit
Throws:
GRS2BufferDisposedException - if the buffer's dispose() has already been invoked
See Also:
IBuffer.getInactivityTimeUnit()

setInactivityTimeUnit

public void setInactivityTimeUnit(java.util.concurrent.TimeUnit unit)
                           throws GRS2BufferDisposedException
Sets the timeout 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

Specified by:
setInactivityTimeUnit in interface IBuffer
Parameters:
unit - the timeout TimeUnit
Throws:
GRS2BufferDisposedException - if the buffer's dispose() has already been invoked
See Also:
IBuffer.setInactivityTimeUnit(java.util.concurrent.TimeUnit)

getInactivityTimeout

public long getInactivityTimeout()
                          throws GRS2BufferDisposedException
Retrieves the timeout after which if the buffer has remained inactive is eligible for purging. This value is interpreted with respect to the TimeUnit defined through IBuffer.getInactivityTimeUnit()

Specified by:
getInactivityTimeout in interface IBuffer
Returns:
the timeout period
Throws:
GRS2BufferDisposedException - if the buffer's dispose() has already been invoked
See Also:
IBuffer.getInactivityTimeout()

setInactivityTimeout

public void setInactivityTimeout(long timeout)
                          throws GRS2BufferDisposedException
Sets the timeout after which if the buffer has remained inactive is eligible for purging. This value is interpreted with respect to the TimeUnit defined through IBuffer.getInactivityTimeUnit(). This is a configuration parameter that can be set only before IBuffer initialization

Specified by:
setInactivityTimeout in interface IBuffer
Parameters:
timeout - the timeout period
Throws:
GRS2BufferDisposedException - if the buffer's dispose() has already been invoked
See Also:
IBuffer.setInactivityTimeout(long)

getWriterImmediateNotificationObject

public java.lang.Object getWriterImmediateNotificationObject()
                                                      throws GRS2BufferDisposedException
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

Specified by:
getWriterImmediateNotificationObject in interface IBuffer
Returns:
the object that can be used for the synchronization
Throws:
GRS2BufferDisposedException - if the buffer's dispose() has already been invoked
See Also:
IBuffer.getWriterImmediateNotificationObject()

getReaderImmediateNotificationObject

public java.lang.Object getReaderImmediateNotificationObject()
                                                      throws GRS2BufferDisposedException
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

Specified by:
getReaderImmediateNotificationObject in interface IBuffer
Returns:
the object that can be used for the synchronization
Throws:
GRS2BufferDisposedException - if the buffer's dispose() has already been invoked
See Also:
IBuffer.getReaderImmediateNotificationObject()

getKey

public java.lang.String getKey()
Retrieves the key under which the IBuffer is registered and accessible through the registry

Specified by:
getKey in interface IBuffer
Returns:
the registry key
See Also:
IBuffer.getKey()

setKey

public void setKey(java.lang.String key)
            throws GRS2BufferInvalidArgumentException,
                   GRS2BufferInvalidOperationException
In case this IBuffer is registered to be served to a reader, the key by which it is registered is provided

Specified by:
setKey in interface IBuffer
Parameters:
key - the registry key
Throws:
GRS2BufferInvalidArgumentException - if the provided key is null or empty
GRS2BufferInvalidOperationException - if the QueueBuffer has already been set with a key
See Also:
IBuffer.setKey(java.lang.String)

initialize

public void initialize()
                throws GRS2BufferDisposedException,
                       GRS2BufferInitializationException,
                       GRS2BufferInvalidArgumentException
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. 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

Specified by:
initialize in interface IBuffer
Throws:
GRS2BufferDisposedException - 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 respectively
See Also:
IBuffer.initialize()

getStatus

public IBuffer.Status getStatus()
Retrieves the IBuffer.Status of the IBuffer

Specified by:
getStatus in interface IBuffer
Returns:
the status
See Also:
IBuffer.getStatus()

availableRecords

public int availableRecords()
                     throws GRS2BufferDisposedException,
                            GRS2BufferInitializationException
Retrieves the number of Records that are currently available to be read

Specified by:
availableRecords in interface IBuffer
Returns:
the number of available Records
Throws:
GRS2BufferDisposedException - if the buffer's dispose() has already been invoked
GRS2BufferInitializationException - when the buffer's status is not IBuffer.Status.Init
See Also:
IBuffer.availableRecords()

totalRecords

public long totalRecords()
                  throws GRS2BufferDisposedException,
                         GRS2BufferInitializationException
Retrieves the number of 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

Specified by:
totalRecords in interface IBuffer
Returns:
the total number of Records
Throws:
GRS2BufferDisposedException - if the buffer's dispose() has already been invoked
GRS2BufferInitializationException - when the buffer's status is not IBuffer.Status.Init
See Also:
IBuffer.totalRecords()

setBufferStore

public void setBufferStore(IBufferStore store)
                    throws GRS2BufferException
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

Specified by:
setBufferStore in interface IBuffer
Parameters:
store - the IBufferStore that provides the data that the IBuffer is serving
Throws:
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 retrieved
See Also:
IBuffer.setBufferStore(IBufferStore)

put

public boolean put(Record record)
            throws GRS2BufferException,
                   GRS2RecordDefinitionException
Attempts to place a 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

Specified by:
put in interface IBuffer
Parameters:
record - the Record to add
Returns:
true on successful addition, false otherwise
Throws:
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 executed
See Also:
IBuffer.put(gr.uoa.di.madgik.grs.record.Record)

get

public Record get()
           throws GRS2BufferDisposedException,
                  GRS2BufferInitializationException
Attempts to retrieve a 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

Specified by:
get in interface IBuffer
Returns:
the retrieved Record or null of none is available
Throws:
GRS2BufferDisposedException - if the buffer's dispose() has already been invoked
GRS2BufferInitializationException - when the buffer's status is not IBuffer.Status.Open
See Also:
IBuffer.get()

locate

public Record locate(long recordIndex)
              throws GRS2BufferDisposedException,
                     GRS2BufferInitializationException
Attempts to locate the 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

Specified by:
locate in interface IBuffer
Parameters:
recordIndex - the Record id which as documented in the Record component must coincide with the order by which it was placed to the IBuffer
Returns:
the Record if found, null otherwise
Throws:
GRS2BufferDisposedException - if the buffer's dispose() has already been invoked
GRS2BufferInitializationException - when the buffer's status is still in IBuffer.Status.Init
See Also:
IBuffer.locate(long)

close

public void close()
           throws GRS2BufferDisposedException,
                  GRS2BufferInitializationException
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. 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

Specified by:
close in interface IBuffer
Throws:
GRS2BufferDisposedException - if the buffer's dispose() has already been invoked
GRS2BufferInitializationException - when the buffer's status is still in IBuffer.Status.Init
See Also:
IBuffer.close()

dispose

public void dispose()
Disposes the 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

Specified by:
dispose in interface IBuffer
See Also:
IBuffer.dispose()

emit

public void emit(BufferEvent event)
          throws GRS2BufferInvalidArgumentException
Emits a 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.

Specified by:
emit in interface IBuffer
Parameters:
event - the event to emit
Throws:
GRS2BufferInvalidArgumentException - if the provided event is null or the source is not recognizable
See Also:
IBuffer.emit(gr.uoa.di.madgik.grs.events.BufferEvent)

receive

public BufferEvent receive(BufferEvent.EventSource source)
                    throws GRS2BufferInvalidArgumentException
Receives a 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.

Specified by:
receive in interface IBuffer
Parameters:
source - the events that are of interest are the ones of the defined source
Returns:
A previously emitted event or null if none is available
Throws:
GRS2BufferInvalidArgumentException - if the provided source is not recognizable
See Also:
IBuffer.receive(gr.uoa.di.madgik.grs.events.BufferEvent.EventSource)