PageCursor (Neo4j - IO 2.2.5 API)

All Superinterfaces:

AutoCloseable
```
public interface PageCursor
extends 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`

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`close()` Relinquishes all resources associated with this cursor, including the cursor itself.
`byte`	`getByte()` Get the signed byte at the current page offset, and then increment the offset by one.
`byte`	`getByte(int offset)` Get the signed byte at the given offset into the page.
`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.
`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.
`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.
`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.
`int`	`getInt()` Get the signed int at the current page offset, and then increment the offset by one.
`int`	`getInt(int offset)` Get the signed int at the given offset into the page.
`long`	`getLong()` Get the signed long at the current page offset, and then increment the offset by one.
`long`	`getLong(int offset)` Get the signed long at the given offset into the page.
`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.
`short`	`getShort()` Get the signed short at the current page offset, and then increment the offset by one.
`short`	`getShort(int offset)` Get the signed short at the given offset into the page.
`long`	`getUnsignedInt()` Get the unsigned int at the current page offset, and then increment the offset by one.
`long`	`getUnsignedInt(int offset)` Get the unsigned int at the given offset into the page.
`boolean`	`next()` Moves the cursor to the next page, if any, and returns true when it is ready to be processed.
`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.
`void`	`putByte(byte value)` Set the signed byte at the current offset into the page, and then increment the offset by one.
`void`	`putByte(int offset, byte value)` Set the signed byte at the given offset into the page.
`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.
`void`	`putInt(int value)` Set the signed int at the current offset into the page, and then increment the offset by one.
`void`	`putInt(int offset, int value)` Set the signed int at the given offset into the page.
`void`	`putLong(int offset, long value)` Set the signed long at the given offset into the page.
`void`	`putLong(long value)` Set the signed long at the current offset into the page, and then increment the offset by one.
`void`	`putShort(int offset, short value)` Set the signed short at the given offset into the page.
`void`	`putShort(short value)` Set the signed short at the current offset into the page, and then increment the offset by one.
`void`	`rewind()` Rewinds the cursor to its initial condition, as if freshly returned from an equivalent io() call.
`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.
`boolean`	`shouldRetry()` Returns true if the page has entered an inconsistent state since the last call to next() or shouldRetry().

- Field Detail
  - UNBOUND_PAGE_ID
```
static final long UNBOUND_PAGE_ID
```
    See Also:
    Constant Field Values
  - UNBOUND_PAGE_SIZE
```
static final int UNBOUND_PAGE_SIZE
```
    See Also:
    Constant Field Values
- Method Detail
  - getByte
```
byte getByte()
```
    Get the signed byte at the current page offset, and then increment the offset by one.
    
    Throws:
    
    IndexOutOfBoundsException - if the current offset is not within the page bounds.
  - getByte
```
byte getByte(int offset)
```
    Get the signed byte at the given offset into the page. Leaves the current page offset unchanged.
    
    Throws:
    
    IndexOutOfBoundsException - if the given offset is not within the page bounds.
  - putByte
```
void putByte(byte value)
```
    Set the signed byte at the current offset into the page, and then increment the offset by one.
    
    Throws:
    
    IndexOutOfBoundsException - if the current offset is not within the page bounds.
  - putByte
```
void putByte(int offset,
           byte value)
```
    Set the signed byte at the given offset into the page. Leaves the current page offset unchanged.
    
    Throws:
    
    IndexOutOfBoundsException - if the given offset is not within the page bounds.
  - getLong
```
long getLong()
```
    Get the signed long at the current page offset, and then increment the offset by one.
    
    Throws:
    
    IndexOutOfBoundsException - if the current offset is not within the page bounds.
  - getLong
```
long getLong(int offset)
```
    Get the signed long at the given offset into the page. Leaves the current page offset unchanged.
    
    Throws:
    
    IndexOutOfBoundsException - if the given offset is not within the page bounds.
  - putLong
```
void putLong(long value)
```
    Set the signed long at the current offset into the page, and then increment the offset by one.
    
    Throws:
    
    IndexOutOfBoundsException - if the current offset is not within the page bounds.
  - putLong
```
void putLong(int offset,
           long value)
```
    Set the signed long at the given offset into the page. Leaves the current page offset unchanged.
    
    Throws:
    
    IndexOutOfBoundsException - if the given offset is not within the page bounds.
  - getInt
```
int getInt()
```
    Get the signed int at the current page offset, and then increment the offset by one.
    
    Throws:
    
    IndexOutOfBoundsException - if the current offset is not within the page bounds.
  - getInt
```
int getInt(int offset)
```
    Get the signed int at the given offset into the page. Leaves the current page offset unchanged.
    
    Throws:
    
    IndexOutOfBoundsException - if the given offset is not within the page bounds.
  - putInt
```
void putInt(int value)
```
    Set the signed int at the current offset into the page, and then increment the offset by one.
    
    Throws:
    
    IndexOutOfBoundsException - if the current offset is not within the page bounds.
  - putInt
```
void putInt(int offset,
          int value)
```
    Set the signed int at the given offset into the page. Leaves the current page offset unchanged.
    
    Throws:
    
    IndexOutOfBoundsException - if the given offset is not within the page bounds.
  - getUnsignedInt
```
long getUnsignedInt()
```
    Get the unsigned int at the current page offset, and then increment the offset by one.
    
    Throws:
    
    IndexOutOfBoundsException - if the current offset is not within the page bounds.
  - getUnsignedInt
```
long getUnsignedInt(int offset)
```
    Get the unsigned int at the given offset into the page. Leaves the current page offset unchanged.
    
    Throws:
    
    IndexOutOfBoundsException - if the given offset is not within the page bounds.
  - getBytes
```
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.
    
    Throws:
    
    IndexOutOfBoundsException - if the current offset plus the length of the array reaches beyond the end of the page.
  - putBytes
```
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.
    
    Throws:
    
    IndexOutOfBoundsException - if the current offset plus the length of the array reaches beyond the end of the page.
  - getShort
```
short getShort()
```
    Get the signed short at the current page offset, and then increment the offset by one.
    
    Throws:
    
    IndexOutOfBoundsException - if the current offset is not within the page bounds.
  - getShort
```
short getShort(int offset)
```
    Get the signed short at the given offset into the page. Leaves the current page offset unchanged.
    
    Throws:
    
    IndexOutOfBoundsException - if the given offset is not within the page bounds.
  - putShort
```
void putShort(short value)
```
    Set the signed short at the current offset into the page, and then increment the offset by one.
    
    Throws:
    
    IndexOutOfBoundsException - if the current offset is not within the page bounds.
  - putShort
```
void putShort(int offset,
            short value)
```
    Set the signed short at the given offset into the page. Leaves the current page offset unchanged.
    
    Throws:
    
    IndexOutOfBoundsException - if the given offset is not within the page bounds.
  - setOffset
```
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
```
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
```
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
```
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
```
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
```
void rewind()
            throws IOException
```
    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.
    
    Throws:
    
    IOException
  - next
```
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.
    
    Throws:
    
    IOException
  - next
```
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.
    
    Throws:
    
    IOException
  - close
```
void close()
```
    Relinquishes all resources associated with this cursor, including the cursor itself. The cursor cannot be used after this call.
    
    Specified by:
    
    close in interface AutoCloseable
    
    See Also:
    AutoCloseable.close()
  - shouldRetry
```
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.

Interface PageCursor

Field Summary

Method Summary

Field Detail

UNBOUND_PAGE_ID

UNBOUND_PAGE_SIZE

Method Detail

getByte

getByte

putByte

putByte

getLong

getLong

putLong

putLong

getInt

getInt

putInt

putInt

getUnsignedInt

getUnsignedInt

getBytes

putBytes

getShort

getShort

putShort

putShort

setOffset

getOffset

getCurrentPageId

getCurrentPageSize

getCurrentFile

rewind

next

next

close

shouldRetry