|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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
Nested Class Summary | |
---|---|
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 | |
---|---|
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. |
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 Record s 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 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 . |
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 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(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 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 |
---|
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
store
- the IBufferStore
that provides the data that the IBuffer
is serving
GRS2BufferException
- the status of the IBuffer
does not allow for the definitions to be retrievedvoid setRecordDefinitions(RecordDefinition[] definitions) throws GRS2BufferException
Record
s 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
definitions
- the record definitions
GRS2BufferException
- The status of the IBuffer
does not allow the definitions to be setRecordDefinition[] getRecordDefinitions() throws GRS2BufferException
Record
s provided using setRecordDefinitions(RecordDefinition[])
GRS2BufferException
- the status of the IBuffer
does not allow for the definitions to be retrievedint getCapacity() throws GRS2BufferException
Record
s that a writer adds to it
GRS2BufferException
- The status of the IBuffer
does not allow for the operation to be executedvoid setCapacity(int capacity) throws GRS2BufferException
Record
s that a writer adds to it.
This is a configuration parameter that can be set only before IBuffer
initialization.
capacity
- the bounded buffer capacity
GRS2BufferException
- The status of the IBuffer
does not allow for the operation to be executedint 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
GRS2BufferException
- The status of the IBuffer
does not allow for the operation to be executedvoid setConcurrentPartialCapacity(int capacity) 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. 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
capacity
- the concurrent number of partially retrieved records that can be used
GRS2BufferException
- The status of the IBuffer
does not allow for the operation to be executedlong getInactivityTimeout() throws GRS2BufferException
TimeUnit
defined through getInactivityTimeUnit()
GRS2BufferException
- The status of the IBuffer
does not allow for the operation to be executedvoid setInactivityTimeout(long timeout) throws GRS2BufferException
TimeUnit
defined through getInactivityTimeUnit()
.
This is a configuration parameter that can be set only before IBuffer
initialization
timeout
- the timeout period
GRS2BufferException
- The status of the IBuffer
does not allow for the operation to be executedjava.util.concurrent.TimeUnit getInactivityTimeUnit() throws GRS2BufferException
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()
TimeUnit
GRS2BufferException
- The status of the IBuffer
does not allow for the operation to be executedvoid setInactivityTimeUnit(java.util.concurrent.TimeUnit unit) throws GRS2BufferException
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
unit
- the timeout TimeUnit
GRS2BufferException
- The status of the IBuffer
does not allow for the operation to be executedlong getLastActivityTime()
IBuffer
. This value is used in conjunction with the
timeout configuration values available through getInactivityTimeout()
and
getInactivityTimeUnit()
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.
boolean getSimulateActivity()
IBuffer
. The status will be reset after calling this method.
IBuffer
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
mirror
- the mirror serving the synchronization of the IBuffer
between the reader and writerIMirror 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
IMirror
implementation that serves this IBuffer
void setMirrorBuffer(int size) throws GRS2BufferException
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. This is a configuration parameter that can be set only before IBuffer
initialization
size
- the size of the mirroring window
GRS2BufferException
- The status of the IBuffer
does not allow for the operation to be executedint getMirrorBuffer() throws GRS2BufferException
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
GRS2BufferException
- The status of the IBuffer
does not allow for the operation to be executedIBuffer.TransportDirective getTransportDirective() throws GRS2BufferException
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
GRS2BufferException
- The status of the IBuffer
does not allow for the operation to be executedvoid setTransportDirective(IBuffer.TransportDirective directive) throws GRS2BufferException
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
directive
- the transport directive
GRS2BufferException
- The status of the IBuffer
does not allow for the operation to be executedIBuffer.TransportDirective resolveTransportDirective() throws GRS2BufferException
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
IBuffer.TransportDirective
further down the item hierarchy
GRS2BufferException
- The status of the IBuffer
does not allow for the operation to be executedjava.lang.Object getWriterImmediateNotificationObject() throws GRS2BufferException
IBuffer
when the reader has reduced its available Record
s by one
GRS2BufferException
- The status of the IBuffer
does not allow for the operation to be executedjava.lang.Object getReaderImmediateNotificationObject() throws GRS2BufferException
IBuffer
when the writer has increased its available Record
s by one
GRS2BufferException
- The status of the IBuffer
does not allow for the operation to be executedvoid initialize() throws GRS2BufferException
IBuffer
ready to receive Record
s 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
GRS2BufferException
- The status of the IBuffer
does not allow for the operation to be executedIBuffer.Status getStatus()
IBuffer.Status
of the IBuffer
void close() throws GRS2BufferException
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. The status
of the IBuffer
is changed to IBuffer.Status.Close
GRS2BufferException
- The status of the IBuffer
does not allow for the operation to be executedvoid 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
long totalRecords() throws GRS2BufferException
Record
s 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 Record
s moved though the
IBuffer
Record
s
GRS2BufferException
- The status of the IBuffer
does not allow for the operation to be executedint availableRecords() throws GRS2BufferException
Record
s that are currently available to be read
Record
s
GRS2BufferException
- The status of the IBuffer
does not allow for the operation to be executedboolean put(Record record) throws GRS2BufferException, GRS2RecordException
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.
record
- the Record
to add
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 executedRecord get() throws GRS2BufferException
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.
Record
or null of none is available
GRS2BufferException
- The status of the IBuffer
does not allow for the operation to be executedRecord locate(long recordIndex) throws GRS2BufferException
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
recordIndex
- 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
GRS2BufferException
- The status of the IBuffer
does not allow for the operation to be executedvoid setKey(java.lang.String key) throws GRS2BufferException
IBuffer
is registered to be served to a reader, the key by which it is registered is provided
key
- the registry key
GRS2BufferException
- The status of the IBuffer
does not allow for the operation to be executedjava.lang.String getKey()
IBuffer
is registered and accessible through the registry
void emit(BufferEvent event) throws GRS2BufferException
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.
event
- the event to emit
GRS2BufferException
- The status of the IBuffer
does not allow for the operation to be executedBufferEvent receive(BufferEvent.EventSource source) throws GRS2BufferException
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.
source
- the events that are of interest are the ones of the defined source
GRS2BufferException
- The status of the IBuffer
does not allow for the operation to be executed
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |