com.devexperts.qd.ng
Class RecordCursor

java.lang.Object
  extended by com.devexperts.qd.ng.RecordCursor

public final class RecordCursor
extends java.lang.Object

The RecordCursor gives high-performance safe read (and optional write) access to one record (one row on information in DB terms) directly from any int[] and Object[] data arrays that might constitute a part of a larger data structure.

Data can be read directly with getInt and getObj methods and written with setInt, setObj, and other helper methods (unless cursor is in read-only mode). Users of the cursor cannot change the record and symbol this cursor works with. To update this information (and change the read-only mode) one must own the reference to Owner object for this Cursor and use Owner.setRecord, Owner.setSymbol, and Owner.setReadOnly methods.

RecordCursor and the corresponding Owner objects can be allocated with the following methods:

All freshly allocated cursors are not read-only. Use Owner.useReadOnly if you need them be read-only.

When you do not need Owner, then you can save on allocation of the corresponding Owner object by calling the following methods:

This class is not synchronized and is not thread-safe without external synchronization.


Nested Class Summary
 class RecordCursor.Owner
          RecordCursor contains an implicit reference to RecordCursor.
 
Constructor Summary
RecordCursor()
          Deprecated. This method will not be public in the future versions. Use one of RecordCusor.allocate(...) or RecordCusor.allocateOwner(...) methods.
 
Method Summary
static RecordCursor allocate(DataRecord record, int cipher, java.lang.String symbol)
          Allocates writable RecordCursor that points to a freshly allocated storage for a given record integer and object field values and also sets symbol.
static RecordCursor allocate(DataRecord record, java.lang.String symbol)
          Allocates writable RecordCursor that points to a freshly allocated storage for a given record integer and object field values and also sets symbol.
static RecordCursor allocate(RecordCursor source)
          Allocates RecordCursor that points to a freshly allocated storage with a copy of data from a given source.
static RecordCursor.Owner allocateOwner()
          Returns newly allocated record cursor owner object.
static RecordCursor.Owner allocateOwner(DataRecord record)
          Allocates writable RecordCursor.Owner that points to a freshly allocated storage for a given record integer and object field values.
static RecordCursor.Owner allocateOwner(DataRecord record, int cipher, java.lang.String symbol)
          Allocates writable RecordCursor.Owner that points to a freshly allocated storage for a given record integer and object field values and also sets symbol.
static RecordCursor.Owner allocateOwner(RecordCursor source)
          Allocates RecordCursor.Owner that points to a freshly allocated storage with a copy of data from a given source.
 void clearFields()
           
 void copyFrom(DataIterator iterator)
          Copies data from the specified iterator into this cursor overwriting everything unconditionally.
 void copyFrom(RecordCursor from)
          Copies data from the specified cursor into this cursor overwriting everything unconditionally.
 boolean examineData(DataVisitor visitor)
           
 int getCipher()
           
 int getInt(int int_field_index)
          Returns the value of the specified integer field for the record pointed to by this cursor.
 int getIntCount()
           
 void getIntsTo(int int_field_index, int[] to, int offset, int length)
           
 java.lang.Object getObj(int obj_field_index)
          Returns the value of the specified object field for the record pointed to by this cursor.
 int getObjCount()
           
 void getObjsTo(int obj_field_index, java.lang.Object[] to, int offset, int length)
           
 long getPosition()
          Returns position of this cursor.
 DataRecord getRecord()
           
 java.lang.String getSymbol()
           
 long getTime()
          Returns time of this record that is a long value composed of the value of the first two integer fields.
 boolean isIdenticalTo(RecordCursor other)
          Returns true when contents of this cursor are equal (identity-wise) to the contents of the other cursor.
 boolean isReadOnly()
          Returns true if this cursor is in read-only mode.
 void readFrom(com.devexperts.io.BufferedInput in)
          Reads field values from the specified buffered input.
 void readFrom(java.io.DataInput in)
          Deprecated. Use readFrom(in, SessionState.EMPTY) which is faster, because it works via BufferedInput class.
 void reset()
          Deprecated. This method will not be public in the future versions. Use RecordCursor.Owner.reset().
 void setAs(DataRecord record, int cipher, java.lang.String symbol, int[] int_flds, int int_offset, java.lang.Object[] obj_flds, int obj_offset, boolean writable)
          Deprecated. This method will be removed in the future versions. Use one of RecordCusor.allocateOwner(...) to get owner and use Onwner's setXXX(...) methods to configure the cursor as needed.
 void setInt(int int_field_index, int value)
           
 void setObj(int obj_field_index, java.lang.Object value)
           
 void setTime(long time)
           
 boolean updateFrom(RecordCursor from)
          Updates data from the specified cursor into this cursor, checking each field with DataIntField.equals(int,int) or DataObjField.equals(Object,Object) respectively.
 boolean updateIntsTo(int int_field_index, int[] to, int offset, int length)
           
 boolean updateObjsTo(int obj_field_index, java.lang.Object[] to, int offset, int length)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

RecordCursor

public RecordCursor()
Deprecated. This method will not be public in the future versions. Use one of RecordCusor.allocate(...) or RecordCusor.allocateOwner(...) methods.

Method Detail

allocate

public static RecordCursor allocate(RecordCursor source)
Allocates RecordCursor that points to a freshly allocated storage with a copy of data from a given source. This method is a shortcut to
 allocateOwner(source).cursor()
But this method does not actually allocate memory for Owner object.


allocate

public static RecordCursor allocate(DataRecord record,
                                    int cipher,
                                    java.lang.String symbol)
Allocates writable RecordCursor that points to a freshly allocated storage for a given record integer and object field values and also sets symbol. This method is a shortcut to
 allocateOwner(record, cipher, symbol).cursor()
But this method does not actually allocate memory for Owner object.


allocate

public static RecordCursor allocate(DataRecord record,
                                    java.lang.String symbol)
Allocates writable RecordCursor that points to a freshly allocated storage for a given record integer and object field values and also sets symbol. This method is a shortcut to
 allocate(record, record.getScheme().getCodec().encode(symbol), symbol)


allocateOwner

public static RecordCursor.Owner allocateOwner(RecordCursor source)
Allocates RecordCursor.Owner that points to a freshly allocated storage with a copy of data from a given source. This method is a shortcut to
 allocateOwner(source.getRecord(), source.getCipher(), source.getSymbol()).
     copyFrom(source)
.


allocateOwner

public static RecordCursor.Owner allocateOwner(DataRecord record,
                                               int cipher,
                                               java.lang.String symbol)
Allocates writable RecordCursor.Owner that points to a freshly allocated storage for a given record integer and object field values and also sets symbol. This method is a shortcut to
 allocateOwner(record).setSymbol(cipher, symbol)
.


allocateOwner

public static RecordCursor.Owner allocateOwner(DataRecord record)
Allocates writable RecordCursor.Owner that points to a freshly allocated storage for a given record integer and object field values. This method is a shortcut to
 Onwer oallocateOwner().setRecord(record,
     new int[record.getIntFieldCount()], 0,
     new Object[record.getObjFieldCount()], 0)
.


allocateOwner

public static RecordCursor.Owner allocateOwner()
Returns newly allocated record cursor owner object. The resulting owner and the cusor are not configured, use Owner.setRecord, Owner.setSymbol, and Owner.setReadOnly methods to configure the corresponding cursor.


getRecord

public DataRecord getRecord()

getCipher

public int getCipher()

getSymbol

public java.lang.String getSymbol()

getIntCount

public int getIntCount()

getInt

public int getInt(int int_field_index)
Returns the value of the specified integer field for the record pointed to by this cursor.

Parameters:
int_field_index - index of the field starting from 0.
Returns:
the value of integer field.
Throws:
java.lang.IndexOutOfBoundsException - if int_field_index is negative or more or equal to the number of integer fields in the corresponding record.

getObjCount

public int getObjCount()

getObj

public java.lang.Object getObj(int obj_field_index)
Returns the value of the specified object field for the record pointed to by this cursor.

Parameters:
obj_field_index - index of the field starting from 0.
Returns:
the value of object field.
Throws:
java.lang.IndexOutOfBoundsException - if obj_field_index is negative or more or equal to the number of object fields in the corresponding record.

getIntsTo

public void getIntsTo(int int_field_index,
                      int[] to,
                      int offset,
                      int length)

getObjsTo

public void getObjsTo(int obj_field_index,
                      java.lang.Object[] to,
                      int offset,
                      int length)

updateIntsTo

public boolean updateIntsTo(int int_field_index,
                            int[] to,
                            int offset,
                            int length)

updateObjsTo

public boolean updateObjsTo(int obj_field_index,
                            java.lang.Object[] to,
                            int offset,
                            int length)

getTime

public long getTime()
Returns time of this record that is a long value composed of the value of the first two integer fields. This value is used in history protocol.


setTime

public void setTime(long time)

isReadOnly

public boolean isReadOnly()
Returns true if this cursor is in read-only mode. Read-only cursor cannot be modified via setInt, setObj and other modification methods.


setInt

public void setInt(int int_field_index,
                   int value)

setObj

public void setObj(int obj_field_index,
                   java.lang.Object value)

clearFields

public void clearFields()

copyFrom

public void copyFrom(DataIterator iterator)
Copies data from the specified iterator into this cursor overwriting everything unconditionally.


copyFrom

public void copyFrom(RecordCursor from)
Copies data from the specified cursor into this cursor overwriting everything unconditionally. Symbol is not updated nor checked.

Throws:
java.lang.IllegalArgumentException - when from cursor has different record.

updateFrom

public boolean updateFrom(RecordCursor from)
Updates data from the specified cursor into this cursor, checking each field with DataIntField.equals(int,int) or DataObjField.equals(Object,Object) respectively. Symbol is not updated nor checked.

Returns:
true if anything was changed.
Throws:
java.lang.IllegalArgumentException - when from cursor has different record.

isIdenticalTo

public boolean isIdenticalTo(RecordCursor other)
Returns true when contents of this cursor are equal (identity-wise) to the contents of the other cursor. Symbol is not checked.

Throws:
java.lang.IllegalArgumentException - when other cursor has different record.

readFrom

public void readFrom(java.io.DataInput in)
              throws java.io.IOException
Deprecated. Use readFrom(in, SessionState.EMPTY) which is faster, because it works via BufferedInput class.

Reads field values from the specified data input.

Throws:
java.io.IOException

readFrom

public void readFrom(com.devexperts.io.BufferedInput in)
              throws java.io.IOException
Reads field values from the specified buffered input.

Throws:
java.io.IOException

examineData

public boolean examineData(DataVisitor visitor)

setAs

public void setAs(DataRecord record,
                  int cipher,
                  java.lang.String symbol,
                  int[] int_flds,
                  int int_offset,
                  java.lang.Object[] obj_flds,
                  int obj_offset,
                  boolean writable)
Deprecated. This method will be removed in the future versions. Use one of RecordCusor.allocateOwner(...) to get owner and use Onwner's setXXX(...) methods to configure the cursor as needed.


reset

public void reset()
Deprecated. This method will not be public in the future versions. Use RecordCursor.Owner.reset().


getPosition

public long getPosition()
Returns position of this cursor. This value is only valid when the cursor was acquired via one of the following RecordBuffer methods: next, current, add(record,cipher,symbol), add(cursor), cursorAt, writeCursorAt

Returns:
position.