PageCursor (Neo4j - IO 3.1.1 API)

java.lang.Object
- org.neo4j.io.pagecache.PageCursor

All Implemented Interfaces:

AutoCloseable
```
public abstract class PageCursor
extends Object
implements AutoCloseable
```
A PageCursor is returned from PagedFile.io(long, int), and is used to scan through pages and process them in a consistent and safe fashion.
A page must be processed in the following manner:
```
     try ( PageCursor cursor = pagedFile.io( pageId, pf_flags ) )
     {
         // Use 'if' for processing a single page,
         // use 'while' for scanning through pages:
         if ( cursor.next() )
         {
             do
             {
                 processPage( cursor );
             } while ( cursor.shouldRetry() );
             // Any finalising, non-repeatable post-processing
             // goes here.
         }
     }
     catch ( IOException e )
     {
         // handle the error, somehow
     }
 
```
There are a couple of things to this pattern that are worth noting:
- We use a try-with-resources clause to make sure that the resources associated with the PageCursor are always released properly.
- We use an if-clause for the next() call if we are only processing a single page, to make sure that the page exist and is accessible to us.
- We use a while-clause for next() if we are scanning through pages.
- We do our processing of the page in a do-while-retry loop, to make sure that we processed a page that was in a consistent state.
You can alternatively use the next(long) method, to navigate the pages you need in a non-linear fashion.

Field Summary

Fields
Modifier and Type Field and Description

static long UNBOUND_PAGE_ID

static int UNBOUND_PAGE_SIZE

Fields
Modifier and Type	Field and Description
`static long`	`UNBOUND_PAGE_ID`
`static int`	`UNBOUND_PAGE_SIZE`

Constructor Summary

Constructors
Constructor and Description

PageCursor()

Constructors
Constructor and Description
`PageCursor()`

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`abstract boolean`	`checkAndClearBoundsFlag()` Discern whether an out-of-bounds access has occurred since the last call to `next()` or `next(long)`, or since the last call to `shouldRetry()` that returned `true`, or since the last call to this method.
`abstract void`	`checkAndClearCursorException()` Check if a cursor error has been set on this or any linked cursor, and if so, remove it from the cursor and throw it as a `CursorException`.
`abstract void`	`clearCursorException()` Unconditionally clear any error condition that has been set on this or any linked cursor, without throwing an exception.
`abstract void`	`close()` Relinquishes all resources associated with this cursor, including the cursor itself, and any linked cursors opened through it.
`abstract int`	`copyTo(int sourceOffset, PageCursor targetCursor, int targetOffset, int lengthInBytes)` Copy the specified number of bytes from the given offset of this page, to the given offset of the target page.
`abstract byte`	`getByte()` Get the signed byte at the current page offset, and then increment the offset by one.
`abstract byte`	`getByte(int offset)` Get the signed byte at the given offset into the page.
`abstract void`	`getBytes(byte[] data)` Fill the given array with bytes from the page, beginning at the current offset into the page, and then increment the current offset by the length of the array.
`abstract void`	`getBytes(byte[] data, int arrayOffset, int length)` Read the given length of bytes from the page into the given array, starting from the current offset into the page, and writing from the given array offset, and then increment the current offset by the length argument.
`abstract File`	`getCurrentFile()` Get the file the cursor is currently bound to, or `null` if next() has not yet been called on this cursor, or returned false.
`abstract long`	`getCurrentPageId()` Get the file page id that the cursor is currently positioned at, or UNBOUND_PAGE_ID if next() has not yet been called on this cursor, or returned false.
`abstract int`	`getCurrentPageSize()` Get the file page size of the page that the cursor is currently positioned at, or UNBOUND_PAGE_SIZE if next() has not yet been called on this cursor, or returned false.
`abstract int`	`getInt()` Get the signed int at the current page offset, and then increment the offset by one.
`abstract int`	`getInt(int offset)` Get the signed int at the given offset into the page.
`abstract long`	`getLong()` Get the signed long at the current page offset, and then increment the offset by one.
`abstract long`	`getLong(int offset)` Get the signed long at the given offset into the page.
`abstract int`	`getOffset()` Get the current offset into the page, which is the location on the page where the next interaction would take place through the read and write methods that do not take a specific offset as an argument.
`abstract short`	`getShort()` Get the signed short at the current page offset, and then increment the offset by one.
`abstract short`	`getShort(int offset)` Get the signed short at the given offset into the page.
`abstract boolean`	`next()` Moves the cursor to the next page, if any, and returns true when it is ready to be processed.
`abstract boolean`	`next(long pageId)` Moves the cursor to the page specified by the given pageId, if any, and returns true when it is ready to be processed.
`abstract PageCursor`	`openLinkedCursor(long pageId)` Open a new page cursor with the same pf_flags as this cursor, as if calling the `PagedFile.io(long, int)` on the relevant paged file.
`abstract void`	`putByte(byte value)` Set the signed byte at the current offset into the page, and then increment the offset by one.
`abstract void`	`putByte(int offset, byte value)` Set the signed byte at the given offset into the page.
`abstract void`	`putBytes(byte[] data)` Write out all the bytes of the given array into the page, beginning at the current offset into the page, and then increment the current offset by the length of the array.
`abstract void`	`putBytes(byte[] data, int arrayOffset, int length)` Write out the given length of bytes from the given offset into the the given array of bytes, into the page, beginning at the current offset into the page, and then increment the current offset by the length argument.
`abstract void`	`putInt(int value)` Set the signed int at the current offset into the page, and then increment the offset by one.
`abstract void`	`putInt(int offset, int value)` Set the signed int at the given offset into the page.
`abstract void`	`putLong(int offset, long value)` Set the signed long at the given offset into the page.
`abstract void`	`putLong(long value)` Set the signed long at the current offset into the page, and then increment the offset by one.
`abstract void`	`putShort(int offset, short value)` Set the signed short at the given offset into the page.
`abstract void`	`putShort(short value)` Set the signed short at the current offset into the page, and then increment the offset by one.
`abstract void`	`raiseOutOfBounds()` Explicitly raise the out-of-bounds flag.
`abstract void`	`rewind()` Rewinds the cursor to its initial condition, as if freshly returned from an equivalent io() call.
`abstract void`	`setCursorException(String message)` Set an error condition on the cursor with the given message.
`abstract void`	`setOffset(int offset)` Set the current offset into the page, for interacting with the page through the read and write methods that do not take a specific offset as an argument.
`abstract boolean`	`shouldRetry()` Returns true if the page has entered an inconsistent state since the last call to next() or shouldRetry().

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - UNBOUND_PAGE_ID
```
public static final long UNBOUND_PAGE_ID
```
    See Also:
    
    Constant Field Values
  - UNBOUND_PAGE_SIZE
```
public static final int UNBOUND_PAGE_SIZE
```
    See Also:
    
    Constant Field Values
- Constructor Detail
  - PageCursor
```
public PageCursor()
```
- Method Detail
  - getByte
```
public abstract byte getByte()
```
    Get the signed byte at the current page offset, and then increment the offset by one.
  - getByte
```
public abstract byte getByte(int offset)
```
    Get the signed byte at the given offset into the page. Leaves the current page offset unchanged.
  - putByte
```
public abstract void putByte(byte value)
```
    Set the signed byte at the current offset into the page, and then increment the offset by one.
  - putByte
```
public abstract void putByte(int offset,
                             byte value)
```
    Set the signed byte at the given offset into the page. Leaves the current page offset unchanged.
  - getLong
```
public abstract long getLong()
```
    Get the signed long at the current page offset, and then increment the offset by one.
  - getLong
```
public abstract long getLong(int offset)
```
    Get the signed long at the given offset into the page. Leaves the current page offset unchanged.
  - putLong
```
public abstract void putLong(long value)
```
    Set the signed long at the current offset into the page, and then increment the offset by one.
  - putLong
```
public abstract void putLong(int offset,
                             long value)
```
    Set the signed long at the given offset into the page. Leaves the current page offset unchanged.
  - getInt
```
public abstract int getInt()
```
    Get the signed int at the current page offset, and then increment the offset by one.
  - getInt
```
public abstract int getInt(int offset)
```
    Get the signed int at the given offset into the page. Leaves the current page offset unchanged.
  - putInt
```
public abstract void putInt(int value)
```
    Set the signed int at the current offset into the page, and then increment the offset by one.
  - putInt
```
public abstract void putInt(int offset,
                            int value)
```
    Set the signed int at the given offset into the page. Leaves the current page offset unchanged.
  - getBytes
```
public abstract void getBytes(byte[] data)
```
    Fill the given array with bytes from the page, beginning at the current offset into the page, and then increment the current offset by the length of the array.
  - getBytes
```
public abstract void getBytes(byte[] data,
                              int arrayOffset,
                              int length)
```
    Read the given length of bytes from the page into the given array, starting from the current offset into the page, and writing from the given array offset, and then increment the current offset by the length argument.
  - putBytes
```
public abstract void putBytes(byte[] data)
```
    Write out all the bytes of the given array into the page, beginning at the current offset into the page, and then increment the current offset by the length of the array.
  - putBytes
```
public abstract void putBytes(byte[] data,
                              int arrayOffset,
                              int length)
```
    Write out the given length of bytes from the given offset into the the given array of bytes, into the page, beginning at the current offset into the page, and then increment the current offset by the length argument.
  - getShort
```
public abstract short getShort()
```
    Get the signed short at the current page offset, and then increment the offset by one.
  - getShort
```
public abstract short getShort(int offset)
```
    Get the signed short at the given offset into the page. Leaves the current page offset unchanged.
  - putShort
```
public abstract void putShort(short value)
```
    Set the signed short at the current offset into the page, and then increment the offset by one.
  - putShort
```
public abstract void putShort(int offset,
                              short value)
```
    Set the signed short at the given offset into the page. Leaves the current page offset unchanged.
  - setOffset
```
public abstract void setOffset(int offset)
```
    Set the current offset into the page, for interacting with the page through the read and write methods that do not take a specific offset as an argument.
  - getOffset
```
public abstract int getOffset()
```
    Get the current offset into the page, which is the location on the page where the next interaction would take place through the read and write methods that do not take a specific offset as an argument.
  - getCurrentPageId
```
public abstract long getCurrentPageId()
```
    Get the file page id that the cursor is currently positioned at, or UNBOUND_PAGE_ID if next() has not yet been called on this cursor, or returned false. A call to rewind() will make the current page id unbound as well, until next() is called.
  - getCurrentPageSize
```
public abstract int getCurrentPageSize()
```
    Get the file page size of the page that the cursor is currently positioned at, or UNBOUND_PAGE_SIZE if next() has not yet been called on this cursor, or returned false. A call to rewind() will make the current page unbound as well, until next() is called.
  - getCurrentFile
```
public abstract File getCurrentFile()
```
    Get the file the cursor is currently bound to, or null if next() has not yet been called on this cursor, or returned false. A call to rewind() will make the cursor unbound as well, until next() is called.
  - rewind
```
public abstract void rewind()
```
    Rewinds the cursor to its initial condition, as if freshly returned from an equivalent io() call. In other words, the next call to next() will move the cursor to the starting page that was specified in the io() that produced the cursor.
  - next
```
public abstract boolean next()
                      throws IOException
```
    Moves the cursor to the next page, if any, and returns true when it is ready to be processed. Returns false if there are no more pages to be processed. For instance, if the cursor was requested with PF_NO_GROW and the page most recently processed was the last page in the file.
    NOTE: When using read locks, read operations can be inconsistent and may return completely random data. The data returned from a read-locked page cursor should not be interpreted until after shouldRetry() has returned false. Not interpreting the data also implies that you cannot throw exceptions from data validation errors until after shouldRetry() has told you that your read was consistent.
    
    Throws:
    
    IOException
  - next
```
public abstract boolean next(long pageId)
                      throws IOException
```
    Moves the cursor to the page specified by the given pageId, if any, and returns true when it is ready to be processed. Returns false if for instance, the cursor was requested with PF_NO_GROW and the page most recently processed was the last page in the file.
    NOTE: When using read locks, read operations can be inconsistent and may return completely random data. The data returned from a read-locked page cursor should not be interpreted until after shouldRetry() has returned false. Not interpreting the data also implies that you cannot throw exceptions from data validation errors until after shouldRetry() has told you that your read was consistent.
    
    Throws:
    
    IOException
  - close
```
public abstract void close()
```
    Relinquishes all resources associated with this cursor, including the cursor itself, and any linked cursors opened through it. The cursor cannot be used after this call.
    
    Specified by:
    
    close in interface AutoCloseable
    
    See Also:
    
    AutoCloseable.close()
  - shouldRetry
```
public abstract boolean shouldRetry()
                             throws IOException
```
    Returns true if the page has entered an inconsistent state since the last call to next() or shouldRetry(). If this method returns true, the in-page offset of the cursor will be reset to zero.
    
    Throws:
    
    IOException - If the page was evicted while doing IO, the cursor will have to do a page fault to get the page back. This may throw an IOException.
  - copyTo
```
public abstract int copyTo(int sourceOffset,
                           PageCursor targetCursor,
                           int targetOffset,
                           int lengthInBytes)
```
    Copy the specified number of bytes from the given offset of this page, to the given offset of the target page.
    If the length reaches beyond the end of either cursor, then only as many bytes as are available in this cursor, or can fit in the target cursor, are actually copied.
    
    Parameters:
    
    sourceOffset - The offset into this page to copy from.
    
    targetCursor - The cursor the data will be copied to.
    
    targetOffset - The offset into the target cursor to copy to.
    
    lengthInBytes - The number of bytes to copy.
    
    Returns:
    
    The number of bytes actually copied.
  - checkAndClearBoundsFlag
```
public abstract boolean checkAndClearBoundsFlag()
```
    Discern whether an out-of-bounds access has occurred since the last call to next() or next(long), or since the last call to shouldRetry() that returned true, or since the last call to this method.
    
    Returns:
    
    true if an access was out of bounds, or the raiseOutOfBounds() method has been called.
  - checkAndClearCursorException
```
public abstract void checkAndClearCursorException()
                                           throws CursorException
```
    Check if a cursor error has been set on this or any linked cursor, and if so, remove it from the cursor and throw it as a CursorException.
    
    Throws:
    
    CursorException
  - raiseOutOfBounds
```
public abstract void raiseOutOfBounds()
```
    Explicitly raise the out-of-bounds flag.
    
    See Also:
    
    checkAndClearBoundsFlag()
  - setCursorException
```
public abstract void setCursorException(String message)
```
    Set an error condition on the cursor with the given message.
    This will make calls to checkAndClearCursorException() throw a CursorException with the given message, unless the error has gotten cleared by a shouldRetry() call that returned true, a call to next() or next(long), or the cursor is closed.
    
    Parameters:
    
    message - The message of the CursorException that checkAndClearCursorException() will throw.
  - clearCursorException
```
public abstract void clearCursorException()
```
    Unconditionally clear any error condition that has been set on this or any linked cursor, without throwing an exception.
  - openLinkedCursor
```
public abstract PageCursor openLinkedCursor(long pageId)
```
    Open a new page cursor with the same pf_flags as this cursor, as if calling the PagedFile.io(long, int) on the relevant paged file. This cursor will then also delegate to the linked cursor when checking shouldRetry() and checkAndClearBoundsFlag().
    Opening a linked cursor on a cursor that already has a linked cursor, will close the older linked cursor. Closing a cursor also closes any linked cursor.
    
    Parameters:
    
    pageId - The page id that the linked cursor will be placed at after its first call to next().
    
    Returns:
    
    A cursor that is linked with this cursor.

Class PageCursor

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

UNBOUND_PAGE_ID

UNBOUND_PAGE_SIZE

Constructor Detail

PageCursor

Method Detail

getByte

getByte

putByte

putByte

getLong

getLong

putLong

putLong

getInt

getInt

putInt

putInt

getBytes

getBytes

putBytes

putBytes

getShort

getShort

putShort

putShort

setOffset

getOffset

getCurrentPageId

getCurrentPageSize

getCurrentFile

rewind

next

next

close

shouldRetry

copyTo

checkAndClearBoundsFlag

checkAndClearCursorException

raiseOutOfBounds

setCursorException

clearCursorException

openLinkedCursor