gr.uoa.di.madgik.grs.reader
Class ForwardReader<T extends Record>

java.lang.Object
  extended by gr.uoa.di.madgik.grs.reader.ForwardReader<T>
Type Parameters:
T - The type of Record specialization that is to be returned by the get operations
All Implemented Interfaces:
IRecordReader<T>, java.lang.Iterable<T>

public class ForwardReader<T extends Record>
extends java.lang.Object
implements IRecordReader<T>, java.lang.Iterable<T>

The ForwardReader class provides access over an authored IBuffer in a forward only fashion. The Records retrieved can be defined to be cast to the specific Record extending class

Author:
gpapanikos

Field Summary
static int DefaultIteratorTimeout
          The default timeout to be used by the ForwardReaderIterators initialized by this reader when retrieving records or checking if more records are available.
static java.util.concurrent.TimeUnit DefaultIteratorTimeUnit
          The default time unit to be used by the ForwardReaderIterators initialized by this reader when retrieving records or checking if more records are available.
 
Constructor Summary
ForwardReader(java.net.URI locator)
          Creates a new reader accessing the IBuffer referenced by the provided locator
ForwardReader(java.net.URI locator, int capacity)
          Creates a new reader accessing the IBuffer referenced by the provided locator.
 
Method Summary
 int availableRecords()
          The number of readily available for consumption Records.
 void close()
          Closes and disposes the underlying buffer.
 long currentRecord()
          The index of the last Record retrieved through the reader.
 void emit(BufferEvent event)
          Emits the provided event to the writer.
 T get()
          Retrieves the next available Record from the IBuffer.
 T get(long timeout, java.util.concurrent.TimeUnit unit)
          Retrieves the next available Record from the IBuffer.
 int getCapacity()
          The underlying IBuffer capacity used.
 int getConcurrentPartialCapacity()
          The underlying IBuffer concurrent partial capacity used
 long getInactivityTimeout()
          Retrieves the Inactivity timeout set for the lifecycle management of the underlying IBuffer.
 java.util.concurrent.TimeUnit getInactivityTimeUnit()
          Retrieves the Inactivity time unit set for the lifecycle management of the underlying IBuffer.
 long getIteratorTimeout()
          The timeout that is used by the Iterators that are created by this reader.
 java.util.concurrent.TimeUnit getIteratorTimeUnit()
          The time unit that is used by the Iterators that are created by this reader.
 RecordDefinition[] getRecordDefinitions()
          Retrieves the RecordDefinitions that define the Records that are accessible through the reader.
 IBuffer.Status getStatus()
          Retrieves the status of the underlying IBuffer.
 java.util.Iterator<T> iterator()
          
 BufferEvent receive()
          Receives a previously emitted event from a writer.
 long seek(long len)
          Seeks the number of Records provided in the list of Records available.
 void setIteratorTimeout(long iteratorTimeout)
          The timeout that should be used by the Iterators that are created by this reader.
 void setIteratorTimeUnit(java.util.concurrent.TimeUnit iteratorTimeUnit)
          The time unit that should be used by the Iterators that are created by this reader.
 long totalRecords()
          The number of total Records that have passed through the IBuffer this far.
 boolean waitAvailable(long timeout, java.util.concurrent.TimeUnit unit)
          Makes sure that within the provided time frame, there is a Record that can be retrieved without blocking.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DefaultIteratorTimeout

public static final int DefaultIteratorTimeout
The default timeout to be used by the ForwardReaderIterators initialized by this reader when retrieving records or checking if more records are available. This value should be interpreted in conjunction with the value of DefaultIteratorTimeUnit

See Also:
Constant Field Values

DefaultIteratorTimeUnit

public static final java.util.concurrent.TimeUnit DefaultIteratorTimeUnit
The default time unit to be used by the ForwardReaderIterators initialized by this reader when retrieving records or checking if more records are available. This value should be interpreted in conjunction with the value of DefaultIteratorTimeout

Constructor Detail

ForwardReader

public ForwardReader(java.net.URI locator)
              throws GRS2ReaderException
Creates a new reader accessing the IBuffer referenced by the provided locator

Parameters:
locator - the locator identifying the IBuffer to consume
Throws:
GRS2ReaderException - the operation could not be completed

ForwardReader

public ForwardReader(java.net.URI locator,
                     int capacity)
              throws GRS2ReaderException
Creates a new reader accessing the IBuffer referenced by the provided locator. The IBuffer will have the specified capacity, if possible

Parameters:
locator - the locator identifying the IBuffer to consume
capacity - a desired capacity for the IBuffer which will be consumed. Used as a hint to the underlying IReaderProxy, which might or might not honor it depending on its strategy
Throws:
GRS2ReaderException - the operation could not be completed
Method Detail

getRecordDefinitions

public RecordDefinition[] getRecordDefinitions()
                                        throws GRS2ReaderException
Retrieves the RecordDefinitions that define the Records that are accessible through the reader.

Specified by:
getRecordDefinitions in interface IRecordReader<T extends Record>
Returns:
the RecordDefinitions as were provided by the corresponding writer
Throws:
GRS2ReaderException - the operation could not be completed
See Also:
IRecordReader.getRecordDefinitions()

getInactivityTimeout

public long getInactivityTimeout()
                          throws GRS2ReaderException
Retrieves the Inactivity timeout set for the lifecycle management of the underlying IBuffer. This value should be interpreted in conjunction with the value of IRecordReader.getInactivityTimeUnit().

Specified by:
getInactivityTimeout in interface IRecordReader<T extends Record>
Returns:
the inactivity timeout
Throws:
GRS2ReaderException - the operation could not be completed
See Also:
IRecordReader.getInactivityTimeout()

getInactivityTimeUnit

public java.util.concurrent.TimeUnit getInactivityTimeUnit()
                                                    throws GRS2ReaderException
Retrieves the Inactivity time unit set for the lifecycle management of the underlying IBuffer. This value should be interpreted in conjunction with the value of IRecordReader.getInactivityTimeout()

Specified by:
getInactivityTimeUnit in interface IRecordReader<T extends Record>
Returns:
the inactivity time unit
Throws:
GRS2ReaderException - the operation could not be completed
See Also:
IRecordReader.getInactivityTimeUnit()

setIteratorTimeout

public void setIteratorTimeout(long iteratorTimeout)
The timeout that should be used by the Iterators that are created by this reader. This value is interpreted in conjunction with the value of IRecordReader.getIteratorTimeUnit()

The Iterators which will use the timeout are instances of ForwardReaderIterator.

Specified by:
setIteratorTimeout in interface IRecordReader<T extends Record>
Parameters:
iteratorTimeout - the timeout
See Also:
IRecordReader#setIteratorTimeout(long)}

getIteratorTimeout

public long getIteratorTimeout()
The timeout that is used by the Iterators that are created by this reader. This value is interpreted in conjunction with the value of IRecordReader.getIteratorTimeUnit(). The Iterators which use the timeout are instances of ForwardReaderIterator.

Specified by:
getIteratorTimeout in interface IRecordReader<T extends Record>
Returns:
the timeout
See Also:
IRecordReader#getIteratorTimeout()}

setIteratorTimeUnit

public void setIteratorTimeUnit(java.util.concurrent.TimeUnit iteratorTimeUnit)
The time unit that should be used by the Iterators that are created by this reader. This value is interpreted in conjunction with the value of IRecordReader.getIteratorTimeout()

The Iterators which will use the time unit are instances of ForwardReaderIterator.

Specified by:
setIteratorTimeUnit in interface IRecordReader<T extends Record>
Parameters:
iteratorTimeUnit - the time unit
See Also:
IRecordReader#setIteratorTimeUnit(TimeUnit)}

getIteratorTimeUnit

public java.util.concurrent.TimeUnit getIteratorTimeUnit()
The time unit that is used by the Iterators that are created by this reader. This value is interpreted in conjunction with the value of IRecordReader.getIteratorTimeout()

The Iterators which use the time unit are instances of ForwardReaderIterator.

Specified by:
getIteratorTimeUnit in interface IRecordReader<T extends Record>
Returns:
the time unit
See Also:
IRecordReader#getIteratorTimeUnit()}

getCapacity

public int getCapacity()
                throws GRS2ReaderException
The underlying IBuffer capacity used.

Specified by:
getCapacity in interface IRecordReader<T extends Record>
Returns:
the buffer capacity
Throws:
GRS2ReaderException - the operation could not be completed
See Also:
IRecordReader.getCapacity()

getConcurrentPartialCapacity

public int getConcurrentPartialCapacity()
                                 throws GRS2ReaderException
The underlying IBuffer concurrent partial capacity used

Specified by:
getConcurrentPartialCapacity in interface IRecordReader<T extends Record>
Returns:
the concurrency partial record buffer capacity
Throws:
GRS2ReaderException - the operation could not be completed
See Also:
IRecordReader.getConcurrentPartialCapacity()

getStatus

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

Specified by:
getStatus in interface IRecordReader<T extends Record>
Returns:
the status of the underlying buffer
See Also:
IRecordReader.getStatus()

close

public void close()
           throws GRS2ReaderException
Closes and disposes the underlying buffer. After this method has been invoked, all associated resources are disposed.

Specified by:
close in interface IRecordReader<T extends Record>
Throws:
GRS2ReaderException - the operation could not be completed
See Also:
IRecordReader.close()

totalRecords

public long totalRecords()
                  throws GRS2ReaderException
The number of total Records that have passed through the IBuffer this far.

Specified by:
totalRecords in interface IRecordReader<T extends Record>
Returns:
the number of total Records that have passed through the IBuffer this far
Throws:
GRS2ReaderException - the operation could not be completed
See Also:
IRecordReader.totalRecords()

availableRecords

public int availableRecords()
                     throws GRS2ReaderException
The number of readily available for consumption Records.

Specified by:
availableRecords in interface IRecordReader<T extends Record>
Returns:
the number of readily available for consumption records
Throws:
GRS2ReaderException - the operation could not be completed
See Also:
IRecordReader.availableRecords()

currentRecord

public long currentRecord()
                   throws GRS2ReaderException
The index of the last Record retrieved through the reader.

Specified by:
currentRecord in interface IRecordReader<T extends Record>
Returns:
the index of the last Record retrieved through the reader
Throws:
GRS2ReaderException - the operation could not be completed because no records were retrieved yet
See Also:
IRecordReader.currentRecord()

get

public T get()
                     throws GRS2ReaderException
Retrieves the next available Record from the IBuffer. An explicit cast is performed to the type provided in the generic declaration of the reader.

Specified by:
get in interface IRecordReader<T extends Record>
Returns:
the retrieved Record or null if none was readily available
Throws:
GRS2ReaderException - the operation could not be completed
See Also:
IRecordReader.get()

get

public T get(long timeout,
             java.util.concurrent.TimeUnit unit)
                     throws GRS2ReaderException
Retrieves the next available Record from the IBuffer. An explicit cast is performed to the type provided in the generic declaration of the reader. If no record is readily available the reader will block for a maximum of timeout unit units of time waiting for a record to become available or until the IBuffer uses the IBuffer.getReaderImmediateNotificationObject() to notify blocked readers.

Specified by:
get in interface IRecordReader<T extends Record>
Parameters:
timeout - the timeout to wait for
unit - the unit of time to use to interpret the timeout value
Returns:
the Record retrieved, or null if the timeout expired without a Record becoming available
Throws:
GRS2ReaderException - the operation could not be completed
See Also:
IRecordReader.get(long, TimeUnit)

seek

public long seek(long len)
          throws GRS2ReaderException
Seeks the number of Records provided in the list of Records available. Depending on the actual IRecordReader implementation, forward and/or backward seeks may be supported. Seeks the number of Records provided forward in the list of Records available. If the seek length is larger than the readily available Records, then the timeout and time unit available through getIteratorTimeout() and getIteratorTimeUnit()

Specified by:
seek in interface IRecordReader<T extends Record>
Parameters:
len - the number of Record}s to skip
Returns:
the number of Records actually skipped
Throws:
GRS2ReaderException - the operation could not be completed

iterator

public java.util.Iterator<T> iterator()

The iterator returned is an instance of ForwardReaderIterator

Specified by:
iterator in interface IRecordReader<T extends Record>
Specified by:
iterator in interface java.lang.Iterable<T extends Record>
See Also:
Iterable.iterator()

waitAvailable

public boolean waitAvailable(long timeout,
                             java.util.concurrent.TimeUnit unit)
                      throws GRS2ReaderException
Makes sure that within the provided time frame, there is a Record that can be retrieved without blocking. If the timeout defined expires and no Record has been made available, false is returned. Otherwise, or if there are already available Records, true is returned.

Specified by:
waitAvailable in interface IRecordReader<T extends Record>
Parameters:
timeout - the timeout value interpreted in conjunction with the unit value
unit - the time unit to use to interpret the timeout value
Returns:
true if there is a Record available before the timeout has expired, false otherwise
Throws:
GRS2ReaderException - the operation could not be completed
See Also:
IRecordReader#waitAvailable(long, TimeUnit)}

emit

public void emit(BufferEvent event)
          throws GRS2ReaderException,
                 GRS2ReaderInvalidArgumentException
Emits the provided event to the writer. The source of the event is set to BufferEvent.EventSource.Reader.

Specified by:
emit in interface IRecordReader<T extends Record>
Parameters:
event - the event to send to the writer
Throws:
GRS2ReaderException - the operation could not be completed
GRS2ReaderInvalidArgumentException - the event provided cannot be null
See Also:
IRecordReader.emit(BufferEvent)

receive

public BufferEvent receive()
                    throws GRS2ReaderException
Receives a previously emitted event from a writer.

Specified by:
receive in interface IRecordReader<T extends Record>
Returns:
the event received or null if no pending events exist
Throws:
GRS2ReaderException - the operation could not be completed
See Also:
IRecordReader.receive()