gr.uoa.di.madgik.grs.reader

Class RandomReader<T extends Record>

java.lang.Object

gr.uoa.di.madgik.grs.reader.RandomReader<T>

Type Parameters:

T - The type of Record specialization that is to be returned by the get operations

All Implemented Interfaces:

IRecordReader<T>, Iterable<T>

public class RandomReader<T extends Record>
extends Object
implements IRecordReader<T>, Iterable<T>

The RandomReader class provides access over an authored IBuffer in a random access fashion. The Records retrieved can be defined to be cast to the specific Record extending class. The random way of record access is enabled through the use of a IRecordStore that persists all the records that are retrieved in the forward fashion. This way whenever a previous record than the current forward record, it is retrieved by the record store. The deserialization from the record store is not performed on a per record only fashion, but a window can be defined that will include a number of pre-stored records

Author:

gpapanikos

Field Summary

Fields

Modifier and Type	Field and Description
static int	DefaultIteratorTimeout The default timeout to be used by the RandomReaderIterators initialized by this reader when retrieving records or checking if more records are available.
static TimeUnit	DefaultIteratorTimeUnit The default time unit to be used by the RandomReaderIterators initialized by this reader when retrieving records or checking if more records are available.
static int	DefaultWindowSize The default size of the window used to resume records that are already in the IRecordStore and need to be made available in memory.

Constructor Summary

Constructors

Constructor and Description
RandomReader(URI locator) Creates a new reader accessing the IBuffer referenced by the provided locator
RandomReader(URI locator, int capacity) Creates a new reader accessing the IBuffer referenced by the provided locator The IBuffer will have the specified capacity, if possible

Method Summary

Methods

Modifier and Type	Method and Description
int	availableRecords() The number of readily available for consumption Records
protected boolean	canCallNext() Checks if according to the IRecordStore and the current window a client can request a next to the current Record
protected boolean	canCallPrevious() Checks if according to the IRecordStore and the current window a client can request a previous to the current Record
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, 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.
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.
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.
int	getWindowSize() Retrieves the window size that will be used whenever a pre-read record is requested.
Iterator<T>	iterator()
ListIterator<T>	listIterator() The iterator returned is an instance of RandomReaderIterator
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(TimeUnit iteratorTimeUnit) The time unit that should be used by the Iterators that are created by this reader.
void	setWindowSize(int windowSize) Sets the window size that will be used whenever a pre-read record is requested.
long	totalRecords() The number of total Records that have passed through the IBuffer this far.
boolean	waitAvailable(long timeout, 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

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DefaultIteratorTimeout

public static final int DefaultIteratorTimeout

The default timeout to be used by the RandomReaderIterators 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 TimeUnit DefaultIteratorTimeUnit

The default time unit to be used by the RandomReaderIterators 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

DefaultWindowSize

public static final int DefaultWindowSize

The default size of the window used to resume records that are already in the IRecordStore and need to be made available in memory. Currently set to 1

See Also:

Constant Field Values

Constructor Detail

RandomReader

public RandomReader(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

RandomReader

public RandomReader(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:

IBuffer.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 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()}

setWindowSize

public void setWindowSize(int windowSize)

Sets the window size that will be used whenever a pre-read record is requested. Other than just the requested record, an additional number of records will be resumed from the IRecordStore and made available

Parameters:

windowSize - the size of the window

getWindowSize

public int getWindowSize()

Retrieves the window size that will be used whenever a pre-read record is requested. Other than just the requested record, an additional number of records will be resumed from the IRecordStore and made available

Returns:

the window size

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 RandomReaderIterator.

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 RandomReaderIterator.

Specified by:

getIteratorTimeout in interface IRecordReader<T extends Record>

Returns:

the timeout

See Also:

IRecordReader#getIteratorTimeout()}

setIteratorTimeUnit

public void setIteratorTimeUnit(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 RandomReaderIterator.

Specified by:

setIteratorTimeUnit in interface IRecordReader<T extends Record>

Parameters:

iteratorTimeUnit - the time unit

See Also:

IRecordReader#setIteratorTimeUnit(TimeUnit)}

getIteratorTimeUnit

public 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 RandomReaderIterator.

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:

IRecordStore.dispose(), 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()}

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

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:

IBuffer.availableRecords()

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. If the request can be served by the IRecordStore then only the local store is touched and not the IBuffer

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:

IBuffer.get()

get

public T get(long timeout,
    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. If the request can be served by the IRecordStore then only the local store is touched and not the IBuffer

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:

IBuffer.get()

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 or backward in the list of Records available depending on whether the provided length is a positive or negative number. If the seek length is larger than the readily available Records, then the timeout and time unit available through ForwardReader.getIteratorTimeout() and ForwardReader.getIteratorTimeUnit(). If the seek can be completely served by the local IRecordStore then the IBuffer is not used.

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 Iterator<T> iterator()

The iterator returned is an instance of RandomReaderIterator

Specified by:

iterator in interface IRecordReader<T extends Record>

Specified by:

iterator in interface Iterable<T extends Record>

See Also:

Iterable.iterator()

listIterator

public ListIterator<T> listIterator()

The iterator returned is an instance of RandomReaderIterator

Returns:

the list iterator instance

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

waitAvailable

public boolean waitAvailable(long timeout,
                    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. If the request can be served by the local IRecordStore then the IBuffer is not used

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

canCallPrevious

protected boolean canCallPrevious()

Checks if according to the IRecordStore and the current window a client can request a previous to the current Record

Returns:

true if a previous record can be requested based on the store window

canCallNext

protected boolean canCallNext()

Checks if according to the IRecordStore and the current window a client can request a next to the current Record

Returns:

true if a next record can be requested based on the store window