Module org.cojen.tupl

Package org.cojen.tupl.io

Class PageArray

java.lang.Object

org.cojen.tupl.io.PageArray

All Implemented Interfaces:

Closeable, AutoCloseable, CauseCloseable

Direct Known Subclasses:

FilePageArray, JoinedPageArray, MappedPageArray, StripedPageArray

public abstract class PageArray
extends Object
implements CauseCloseable

Defines a persistent, array of fixed sized pages. Each page is uniquely identified by a 64-bit index, starting at zero.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	PageArray(int pageSize)

Method Summary

Modifier and Type	Method	Description
void	close()
abstract void	close(Throwable cause)
long	copyPage(long srcIndex, long dstIndex)
long	copyPageFromPointer(long srcPointer, long dstIndex)
long	directPagePointer(long index)
int	directPageSize()	Returns a positive page size if not using direct I/O, else negate to get the page size to allocate for direct I/O.
long	dirtyPage(long index)	Indicate that the contents of the given page will be modified.
byte[]	evictPage(long index, byte[] buf)	Same as writePage, except that the given buffer might be altered and a replacement might be returned.
long	evictPage(long index, long bufPtr)	Same as writePage, except that the given buffer might be altered and a replacement might be returned.
abstract void	expandPageCount(long count)	Attempt to expand the total count of pages.
final boolean	isDirectIO()
abstract boolean	isEmpty()
boolean	isFullyMapped()
abstract boolean	isReadOnly()
PageArray	open()	Attempt to open or reopen the page array.
abstract long	pageCount()	Returns the total count of pages in the array, or Long.MAX_VALUE if not applicable.
long	pageCountLimit()	Return maximum allowed page count, or -1 if not applicable.
final int	pageSize()	Returns the fixed size of all pages in the array, in bytes.
void	readPage(long index, byte[] dst)
abstract void	readPage(long index, byte[] dst, int offset, int length)
void	readPage(long index, byte[] dst, int offset, int length, ByteBuffer tail)
void	readPage(long index, long dstPtr)
void	readPage(long index, long dstPtr, int offset, int length)
void	readPage(long index, long dstPtr, int offset, int length, ByteBuffer tail)
abstract void	sync(boolean metadata)	Durably flushes all writes to the underlying device.
void	syncPage(long index)	Durably flushes the page at the given index, but implementation might flush more pages.
abstract void	truncatePageCount(long count)	Attempt to truncate the total count of pages.
void	writePage(long index, byte[] src)	Writes a page, which is lazily flushed.
abstract void	writePage(long index, byte[] src, int offset)	Writes a page, which is lazily flushed.
abstract void	writePage(long index, byte[] src, int offset, ByteBuffer tail)
void	writePage(long index, long srcPtr)	Writes a page, which is lazily flushed.
void	writePage(long index, long srcPtr, int offset)	Writes a page, which is lazily flushed.
void	writePage(long index, long srcPtr, int offset, ByteBuffer tail)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

PageArray

protected PageArray(int pageSize)

Method Details

isDirectIO

public final boolean isDirectIO()

pageSize

public final int pageSize()

Returns the fixed size of all pages in the array, in bytes.

directPageSize

public int directPageSize()

Returns a positive page size if not using direct I/O, else negate to get the page size to allocate for direct I/O.

isFullyMapped

public boolean isFullyMapped()

isReadOnly

public abstract boolean isReadOnly()

isEmpty

public abstract boolean isEmpty()
                         throws IOException

Throws:

IOException

pageCount

public abstract long pageCount()
                        throws IOException

Returns the total count of pages in the array, or Long.MAX_VALUE if not applicable.

Throws:

IOException

truncatePageCount

public abstract void truncatePageCount(long count)
                                throws IOException

Attempt to truncate the total count of pages. Array implementation might not support truncating the page count, in which case this method does nothing.

Throws:

IllegalArgumentException - if count is negative

IOException

expandPageCount

public abstract void expandPageCount(long count)
                              throws IOException

Attempt to expand the total count of pages. Array implementation might not support expanding the page count, in which case this method does nothing.

Throws:

IllegalArgumentException - if count is negative

IOException

pageCountLimit

public long pageCountLimit()
                    throws IOException

Return maximum allowed page count, or -1 if not applicable.

Throws:

IOException

readPage

public void readPage(long index,
 byte[] dst)
              throws IOException

Parameters:

index - zero-based page index to read

dst - receives read data

Throws:

IndexOutOfBoundsException - if index is negative

IOException - if index is greater than or equal to page count

readPage

public abstract void readPage(long index,
 byte[] dst,
 int offset,
 int length)
                       throws IOException

Parameters:

index - zero-based page index to read

dst - receives read data

offset - offset into data buffer

Throws:

IndexOutOfBoundsException - if index is negative

IOException - if index is greater than or equal to page count

readPage

public void readPage(long index,
 byte[] dst,
 int offset,
 int length,
 ByteBuffer tail)
              throws IOException

Throws:

IOException

readPage

public void readPage(long index,
 long dstPtr)
              throws IOException

Parameters:

index - zero-based page index to read

dstPtr - receives read data

Throws:

IndexOutOfBoundsException - if index is negative

IOException - if index is greater than or equal to page count

readPage

public void readPage(long index,
 long dstPtr,
 int offset,
 int length)
              throws IOException

Parameters:

index - zero-based page index to read

dstPtr - receives read data

offset - offset into data buffer

Throws:

IndexOutOfBoundsException - if index is negative

IOException - if index is greater than or equal to page count

readPage

public void readPage(long index,
 long dstPtr,
 int offset,
 int length,
 ByteBuffer tail)
              throws IOException

Throws:

IOException

writePage

public void writePage(long index,
 byte[] src)
               throws IOException

Writes a page, which is lazily flushed. The array grows automatically if the index is greater than or equal to the current page count. If array supports caching, page must be immediately copied into it.

Parameters:

index - zero-based page index to write

src - data to write

Throws:

IndexOutOfBoundsException - if index is negative

IOException

writePage

public abstract void writePage(long index,
 byte[] src,
 int offset)
                        throws IOException

Writes a page, which is lazily flushed. The array grows automatically if the index is greater than or equal to the current page count. If array supports caching, page must be immediately copied into it.

Parameters:

index - zero-based page index to write

src - data to write

offset - offset into data buffer

Throws:

IndexOutOfBoundsException - if index is negative

IOException

writePage

public abstract void writePage(long index,
 byte[] src,
 int offset,
 ByteBuffer tail)
                        throws IOException

Throws:

IOException

writePage

public void writePage(long index,
 long srcPtr)
               throws IOException

Writes a page, which is lazily flushed. The array grows automatically if the index is greater than or equal to the current page count. If array supports caching, page must be immediately copied into it.

Parameters:

index - zero-based page index to write

srcPtr - data to write

Throws:

IndexOutOfBoundsException - if index is negative

IOException

writePage

public void writePage(long index,
 long srcPtr,
 int offset)
               throws IOException

Writes a page, which is lazily flushed. The array grows automatically if the index is greater than or equal to the current page count. If array supports caching, page must be immediately copied into it.

Parameters:

index - zero-based page index to write

srcPtr - data to write

offset - offset into data buffer

Throws:

IndexOutOfBoundsException - if index is negative

IOException

writePage

public void writePage(long index,
 long srcPtr,
 int offset,
 ByteBuffer tail)
               throws IOException

Throws:

IOException

evictPage

public byte[] evictPage(long index,
 byte[] buf)
                 throws IOException

Same as writePage, except that the given buffer might be altered and a replacement might be returned. Caller must not alter the original buffer if a replacement was provided, and the contents of the replacement are undefined.

Parameters:

index - zero-based page index to write

buf - data to write; implementation might alter the contents

Returns:

replacement buffer, or same instance if replacement was not performed

Throws:

IndexOutOfBoundsException - if index is negative

IOException

evictPage

public long evictPage(long index,
 long bufPtr)
               throws IOException

Same as writePage, except that the given buffer might be altered and a replacement might be returned. Caller must not alter the original buffer if a replacement was provided, and the contents of the replacement are undefined.

Parameters:

index - zero-based page index to write

bufPtr - data to write; implementation might alter the contents

Returns:

replacement buffer, or same instance if replacement was not performed

Throws:

IndexOutOfBoundsException - if index is negative

IOException

directPagePointer

public long directPagePointer(long index)
                       throws IOException

Throws:

IOException

dirtyPage

public long dirtyPage(long index)
               throws IOException

Indicate that the contents of the given page will be modified. Permits the implementation to make a copy of the existing page contents, if it supports snapshotting.

Returns:

direct pointer to destination

Throws:

IOException

copyPage

public long copyPage(long srcIndex,
 long dstIndex)
              throws IOException

Returns:

direct pointer to destination

Throws:

IOException

copyPageFromPointer

public long copyPageFromPointer(long srcPointer,
 long dstIndex)
                         throws IOException

Returns:

direct pointer to destination

Throws:

IOException

sync

public abstract void sync(boolean metadata)
                   throws IOException

Durably flushes all writes to the underlying device.

Parameters:

metadata - pass true to flush all file metadata

Throws:

IOException

syncPage

public void syncPage(long index)
              throws IOException

Durably flushes the page at the given index, but implementation might flush more pages. File metadata is not flushed.

Throws:

IOException

close

public void close()
           throws IOException

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException

close

public abstract void close(Throwable cause)
                    throws IOException

Specified by:

close in interface CauseCloseable

Parameters:

cause - null if close is not caused by a failure

Throws:

IOException

open

public PageArray open()
               throws IOException

Attempt to open or reopen the page array.

Returns:

existing or new page array

Throws:

IOException