IBuffer (gRS2 2.1.0-SNAPSHOT API)

All Known Implementing Classes:

QueueBuffer
```
public interface IBuffer
```
The IBuffer interface is the main enabling component acting as the Record buffer that is populated by a writer and read by a reader. All implementations of this class must declare a default constructor with no arguments since they may be instantiated using reflection under the default no argument constructor

Author:

gpapanikos

Nested Class Summary

Nested Classes
Modifier and Type	Interface and Description
`static class`	`IBuffer.Status` The current status of the `IBuffer`.
`static class`	`IBuffer.TransportDirective` The transport directive set for the `IBuffer` or its contained items.
`static class`	`IBuffer.TransportOverride` During remote transport of an item payload, the defined `IBuffer.TransportDirective` can be overridden to request a different behavior.

Method Summary

Methods
Modifier and Type	Method and Description
`int`	`availableRecords()` Retrieves the number of `Record`s that are currently available to be read
`void`	`close()` Closes the authoring side of the `IBuffer` after this invocation, no more `Record`s can be added to the `IBuffer` but a reader can still consume any `Record`s 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 `Record`s 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.
`TimeUnit`	`getInactivityTimeUnit()` Retrieves the timeout `TimeUnit` after which if the buffer has remained inactive is eligible for purging.
`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 `Record`s that the writer `IMirror`} will limit its sending phase to choke large transfers
`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 `Record`s by one
`RecordDefinition[]`	`getRecordDefinitions()` Retrieves the definitions of the `Record`s provided using `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`.
`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 `Record`s 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 `Record`s 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 `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 `Record`s 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(TimeUnit unit)` Sets the timeout `TimeUnit` after which if the buffer has remained inactive is eligible for purging.
`void`	`setKey(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 `Record`s that the writer `IMirror`} will limit its sending phase to choke large transfers.
`void`	`setRecordDefinitions(RecordDefinition[] definitions)` Sets the definitions of the `Record`s 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 `Record`s that have in total passed through the `IBuffer`.

- Method Detail
  - setBufferStore
```
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
    
    Parameters:
    store - the IBufferStore that provides the data that the IBuffer is serving
    
    Throws:
    
    GRS2BufferException - the status of the IBuffer does not allow for the definitions to be retrieved
  - setRecordDefinitions
```
void setRecordDefinitions(RecordDefinition[] definitions)
                          throws GRS2BufferException
```
    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
    
    Parameters:
    definitions - the record definitions
    
    Throws:
    
    GRS2BufferException - The status of the IBuffer does not allow the definitions to be set
  - getRecordDefinitions
```
RecordDefinition[] getRecordDefinitions()
                                        throws GRS2BufferException
```
    Retrieves the definitions of the Records provided using setRecordDefinitions(RecordDefinition[])
    
    Returns:
    the record definitions
    
    Throws:
    
    GRS2BufferException - the status of the IBuffer does not allow for the definitions to be retrieved
  - getCapacity
```
int getCapacity()
                throws GRS2BufferException
```
    Retrieves the capacity of the underlying bounded buffer that can store the Records that a writer adds to it
    
    Returns:
    the bounded buffer capacity
    
    Throws:
    
    GRS2BufferException - The status of the IBuffer does not allow for the operation to be executed
  - setCapacity
```
void setCapacity(int capacity)
                 throws GRS2BufferException
```
    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.
    
    Parameters:
    capacity - the bounded buffer capacity
    
    Throws:
    
    GRS2BufferException - The status of the IBuffer does not allow for the operation to be executed
  - getConcurrentPartialCapacity
```
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
    
    Returns:
    the concurrent number of partially retrieved records that can be used
    
    Throws:
    
    GRS2BufferException - The status of the IBuffer does not allow for the operation to be executed
  - setConcurrentPartialCapacity
```
void setConcurrentPartialCapacity(int capacity)
                                  throws GRS2BufferException
```
    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
    
    Parameters:
    capacity - the concurrent number of partially retrieved records that can be used
    
    Throws:
    
    GRS2BufferException - The status of the IBuffer does not allow for the operation to be executed
  - getInactivityTimeout
```
long getInactivityTimeout()
                          throws GRS2BufferException
```
    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 getInactivityTimeUnit()
    
    Returns:
    the timeout period
    
    Throws:
    
    GRS2BufferException - The status of the IBuffer does not allow for the operation to be executed
  - setInactivityTimeout
```
void setInactivityTimeout(long timeout)
                          throws GRS2BufferException
```
    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 getInactivityTimeUnit(). This is a configuration parameter that can be set only before IBuffer initialization
    
    Parameters:
    timeout - the timeout period
    
    Throws:
    
    GRS2BufferException - The status of the IBuffer does not allow for the operation to be executed
  - getInactivityTimeUnit
```
TimeUnit getInactivityTimeUnit()
                               throws GRS2BufferException
```
    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 getInactivityTimeout()
    
    Returns:
    the timeout TimeUnit
    
    Throws:
    
    GRS2BufferException - The status of the IBuffer does not allow for the operation to be executed
  - setInactivityTimeUnit
```
void setInactivityTimeUnit(TimeUnit unit)
                           throws GRS2BufferException
```
    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 getInactivityTimeout(). This is a configuration parameter that can be set only before IBuffer initialization
    
    Parameters:
    unit - the timeout TimeUnit
    
    Throws:
    
    GRS2BufferException - The status of the IBuffer does not allow for the operation to be executed
  - getLastActivityTime
```
long getLastActivityTime()
```
    Retrieves the last activity time of the IBuffer. This value is used in conjunction with the timeout configuration values available through getInactivityTimeout() and getInactivityTimeUnit()
    
    Returns:
    the last activity time
  - markSimulateActivity
```
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.
  - getSimulateActivity
```
boolean getSimulateActivity()
```
    Retrieves the simulate activity status of the IBuffer. The status will be reset after calling this method.
    
    Returns:
    the simulate activity status of the IBuffer
  - setMirror
```
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
    
    Parameters:
    mirror - the mirror serving the synchronization of the IBuffer between the reader and writer
  - getMirror
```
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
    
    Returns:
    the IMirror implementation that serves this IBuffer
  - setMirrorBuffer
```
void setMirrorBuffer(int size)
                     throws GRS2BufferException
```
    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
    
    Parameters:
    size - the size of the mirroring window
    
    Throws:
    
    GRS2BufferException - The status of the IBuffer does not allow for the operation to be executed
  - getMirrorBuffer
```
int getMirrorBuffer()
                    throws GRS2BufferException
```
    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
    
    Returns:
    the size of the mirroring window
    
    Throws:
    
    GRS2BufferException - The status of the IBuffer does not allow for the operation to be executed
  - getTransportDirective
```
IBuffer.TransportDirective getTransportDirective()
                                                 throws GRS2BufferException
```
    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
    
    Returns:
    the set transport directive
    
    Throws:
    
    GRS2BufferException - The status of the IBuffer does not allow for the operation to be executed
  - setTransportDirective
```
void setTransportDirective(IBuffer.TransportDirective directive)
                           throws GRS2BufferException
```
    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
    
    Parameters:
    directive - the transport directive
    
    Throws:
    
    GRS2BufferException - The status of the IBuffer does not allow for the operation to be executed
  - resolveTransportDirective
```
IBuffer.TransportDirective resolveTransportDirective()
                                                     throws GRS2BufferException
```
    Resolves the set IBuffer.TransportDirective set for the IBuffer through 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
    
    Returns:
    the transport directive to be used by a component that has not resolved its {#link IBuffer.TransportDirective further down the item hierarchy
    
    Throws:
    
    GRS2BufferException - The status of the IBuffer does not allow for the operation to be executed
  - getWriterImmediateNotificationObject
```
Object getWriterImmediateNotificationObject()
                                            throws GRS2BufferException
```
    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
    
    Returns:
    the object that can be used for the synchronization
    
    Throws:
    
    GRS2BufferException - The status of the IBuffer does not allow for the operation to be executed
  - getReaderImmediateNotificationObject
```
Object getReaderImmediateNotificationObject()
                                            throws GRS2BufferException
```
    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
    
    Returns:
    the object that can be used for the synchronization
    
    Throws:
    
    GRS2BufferException - The status of the IBuffer does not allow for the operation to be executed
  - initialize
```
void initialize()
                throws GRS2BufferException
```
    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
    
    Throws:
    
    GRS2BufferException - The status of the IBuffer does not allow for the operation to be executed
  - getStatus
```
IBuffer.Status getStatus()
```
    Retrieves the IBuffer.Status of the IBuffer
    
    Returns:
    the status
  - close
```
void close()
           throws GRS2BufferException
```
    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
    
    Throws:
    
    GRS2BufferException - The status of the IBuffer does not allow for the operation to be executed
  - dispose
```
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
  - totalRecords
```
long totalRecords()
                  throws GRS2BufferException
```
    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
    
    Returns:
    the total number of Records
    
    Throws:
    
    GRS2BufferException - The status of the IBuffer does not allow for the operation to be executed
  - availableRecords
```
int availableRecords()
                     throws GRS2BufferException
```
    Retrieves the number of Records that are currently available to be read
    
    Returns:
    the number of available Records
    
    Throws:
    
    GRS2BufferException - The status of the IBuffer does not allow for the operation to be executed
  - put
```
boolean put(Record record)
            throws GRS2BufferException,
                   GRS2RecordException
```
    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, availableRecords(), is less than the IBuffer's capacity, getCapacity(). After a successful invocation, the available records are increased by one.
    
    Parameters:
    record - the Record to add
    
    Returns:
    true on successful addition, false otherwise
    
    Throws:
    
    GRS2BufferException - The status of the IBuffer does not allow for the operation to be executed
    
    GRS2RecordException - The status of the Record does not allow for the operation to be executed
  - get
```
Record get()
           throws GRS2BufferException
```
    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, availableRecords() is greater than 0. After a successful invocation, the available records are decreased by one.
    
    Returns:
    the retrieved Record or null of none is available
    
    Throws:
    
    GRS2BufferException - The status of the IBuffer does not allow for the operation to be executed
  - locate
```
Record locate(long recordIndex)
              throws GRS2BufferException
```
    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 getConcurrentPartialCapacity() then it must be made available
    
    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:
    
    GRS2BufferException - The status of the IBuffer does not allow for the operation to be executed
  - setKey
```
void setKey(String key)
            throws GRS2BufferException
```
    In case this IBuffer is registered to be served to a reader, the key by which it is registered is provided
    
    Parameters:
    key - the registry key
    
    Throws:
    
    GRS2BufferException - The status of the IBuffer does not allow for the operation to be executed
  - getKey
```
String getKey()
```
    Retrieves the key under which the IBuffer is registered and accessible through the registry
    
    Returns:
    the registry key
  - emit
```
void emit(BufferEvent event)
          throws GRS2BufferException
```
    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.
    
    Parameters:
    event - the event to emit
    
    Throws:
    
    GRS2BufferException - The status of the IBuffer does not allow for the operation to be executed
  - receive
```
BufferEvent receive(BufferEvent.EventSource source)
                    throws GRS2BufferException
```
    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.
    
    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:
    
    GRS2BufferException - The status of the IBuffer does not allow for the operation to be executed

Interface IBuffer

Nested Class Summary

Method Summary

Method Detail

setBufferStore

setRecordDefinitions

getRecordDefinitions

getCapacity

setCapacity

getConcurrentPartialCapacity

setConcurrentPartialCapacity

getInactivityTimeout

setInactivityTimeout

getInactivityTimeUnit

setInactivityTimeUnit

getLastActivityTime

markSimulateActivity

getSimulateActivity

setMirror

getMirror

setMirrorBuffer

getMirrorBuffer

getTransportDirective

setTransportDirective

resolveTransportDirective

getWriterImmediateNotificationObject

getReaderImmediateNotificationObject

initialize

getStatus

close

dispose

totalRecords

availableRecords

put

get

locate

setKey

getKey

emit

receive