com.devexperts.qd
Interface DataIterator

All Known Implementing Classes:
BufferedDataIterator, DataBuffer, RecordBuffer

public interface DataIterator

The DataIterator defines protocol of serial access to the data using Iterator pattern. It allows data consumer with complicated data storage effectively receive data from external data provider.

Specifically, DataIterator allows data consumer to take proper synchronization locks only once per large data block (and not per iterated entity) and save on navigation through data storage by calculating and caching locally required references and indices.

Therefore, the implementor of DataIterator must perform its operations quickly without need for synchronization and prolonged external actions for each step. If data provider in its turn requires synchronized access or is otherwise slow, then it should accept DataVisitor as a destination for data and use intermediate data buffer (DataBuffer or equivalent).

The DataIterator iterates all available data records and for each record it iterates all fields in their serial order (see DataRecord). The corresponding state diagram is shown below (note that the number and types of iterated fields exactly matches number and types of the fields in the current record):

 +-----> [Ready]
 |          |
 |          1 nextRecord
 |          |
 |          V
 |  +--> [Iterating Int]
 |  |       |
 |  +-------* nextIntField
 |          |
 |          V
 |  +--> [Iterating Obj]
 |  |       |
 |  +-------* nextObjField
 |          |
 +----------+
 
NOTE: if iteration is ever aborted in a state different from [Ready], then behavior of both parties (data iterator and data consumer) is undefined.

FUTURE DEPRECATION NOTE: New code shall not implement this interface due to its complexity and inherent slowness. Implement RecordSource or use RecordBuffer as a high-performance implementation of it. New code is also discouraged from using this interface unless it is need for interoperability with legacy code. Various legacy APIs will be gradually migrated to NG interfaces and classes.


Method Summary
 int getCipher()
          Returns cipher for the current record returned by last call to nextRecord().
 java.lang.String getSymbol()
          Returns symbol for the current record returned by last call to nextRecord().
 int nextIntField()
          Returns next Int-field within current record being iterated.
 java.lang.Object nextObjField()
          Returns next Obj-field within current record being iterated.
 DataRecord nextRecord()
          Returns next record.
 

Method Detail

getCipher

int getCipher()
Returns cipher for the current record returned by last call to nextRecord(). Returns 0 if not encoded or if no current record is being iterated.


getSymbol

java.lang.String getSymbol()
Returns symbol for the current record returned by last call to nextRecord(). Returns null if encoded or if no current record is being iterated.


nextRecord

DataRecord nextRecord()
Returns next record. Returns null if no more records available.

Throws:
java.lang.IllegalStateException - if iterator is not in [Ready] state.

nextIntField

int nextIntField()
Returns next Int-field within current record being iterated.

Throws:
java.lang.IllegalStateException - if iterator is not in a state to iterate Int-field.

nextObjField

java.lang.Object nextObjField()
Returns next Obj-field within current record being iterated.

Throws:
java.lang.IllegalStateException - if iterator is not in a state to iterate Obj-field.