org.neo4j.io.pagecache

Interface PageCursor

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

Method Summary

Modifier and Type	Method and Description
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.
void	close() Relinquishes all resources associated with this cursor, including the cursor itself, and any linked cursors opened through it.
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.
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.
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.
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.
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.
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.
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	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.
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	raiseOutOfBounds() Explicitly raise the out-of-bounds flag.
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.

getByte

byte getByte(int offset)

Get the signed byte at the given offset into the page. Leaves the current page offset unchanged.

putByte

void putByte(byte value)

Set the signed byte at the current offset into the page, and then increment the offset by one.

putByte

void putByte(int offset,
             byte value)

Set the signed byte at the given offset into the page. Leaves the current page offset unchanged.

getLong

long getLong()

Get the signed long at the current page offset, and then increment the offset by one.

getLong

long getLong(int offset)

Get the signed long at the given offset into the page. Leaves the current page offset unchanged.

putLong

void putLong(long value)

Set the signed long at the current offset into the page, and then increment the offset by one.

putLong

void putLong(int offset,
             long value)

Set the signed long at the given offset into the page. Leaves the current page offset unchanged.

getInt

int getInt()

Get the signed int at the current page offset, and then increment the offset by one.

getInt

int getInt(int offset)

Get the signed int at the given offset into the page. Leaves the current page offset unchanged.

putInt

void putInt(int value)

Set the signed int at the current offset into the page, and then increment the offset by one.

putInt

void putInt(int offset,
            int value)

Set the signed int at the given offset into the page. Leaves the current page offset unchanged.

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.

getBytes

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.

Throws:

IndexOutOfBoundsException - if the current offset plus the length 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.

putBytes

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.

Throws:

IndexOutOfBoundsException - if the current offset plus the length 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()

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

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, 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

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

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

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.

raiseOutOfBounds

void raiseOutOfBounds()

Explicitly raise the out-of-bounds flag.

See Also:

checkAndClearBoundsFlag()

openLinkedCursor

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.