Documentation of 'org.apache.derby.impl.store.raw.data.StoredPage' Java class
StoredPage
Skip navigation links
org.apache.derby.impl.store.raw.data

Class StoredPage

  • All Implemented Interfaces:
    java.util.Observer, Cacheable, TypedFormat, Page
    Direct Known Subclasses:
    AllocPage

    public class StoredPage
extends CachedPage
    StoredPage is a sub class of CachedPage that stores page data in a fixed size byte array and is designed to be written out to a file through a DataInput/DataOutput interface. A StoredPage can exist in its clean or dirty state without the FileContainer it was created from being in memory.

    Page Format
    The page is broken into five sections 

      +----------+-------------+-------------------+-------------------+----------+
  | formatId | page header | records           | slot offset table | checksum |
  +----------+-------------+-------------------+-------------------+----------+

    FormatId
    The formatId is a 4 bytes array, it contains the format Id of this page.
    Page Header
    The page header is a fixed size, 56 bytes 
      1 byte  boolean           is page an overflow page
  1 byte  byte              page status (a field maintained in base page)
  8 bytes long              pageVersion (a field maintained in base page)
  2 bytes unsigned short    number of slots in slot offset table
  4 bytes integer           next record identifier
  4 bytes integer           generation number of this page (Future Use)
  4 bytes integer           previous generation of this page (Future Use)
  8 bytes bipLocation       the location of the beforeimage page (Future Use)
  2 bytes unsigned short    number of deleted rows on page. (new release 2.0)
  2 bytes unsigned short    % of the page to keep free for updates
  2 bytes short             spare for future use
  4 bytes long              spare for future use (encryption uses to write 
                                                  random bytes here).
  8 bytes long              spare for future use
  8 bytes long              spare for future use
    Note that spare space has been guaranteed to be writen with "0", so that future use of field should not either not use "0" as a valid data item or pick 0 as a valid default value so that on the fly upgrade can assume that 0 means field was never assigned.
    Records The records section contains zero or more records, the format of each record follows. minimumRecordSize is the minimum user record size, excluding the space we use for the record header and field headers. When a record is inserted, it is stored in a space at least as large as the sum of the minimumRecordSize and total header size. For example, If minimumRecordSize is 10 bytes, the user record is 7 bytes, we used 5 bytes for record and field headers, this record will take (10 + 5) bytes of space, extra 3 bytes is put into reserve. If minimumRecordSize is 10 bytes, user record is 17 bytes, we used 5 bytes for record and field headers, this record will take (17 + 5) bytes of space, no reserve space here. minimumRecordSize is defined by user on per container basis. The default for minimumRecordSize is set to 1. This implementation always keeps occupied bytes at the low end of the record section. Thus removing (purging) a record moves all other records down, and their slots are also moved down. A page has no empty slot (an empty page has no slot)
    Record & Field Format Record Header format is defined in the StoredRecordHeader class. 
       
  
    Fields

  1 byte    Boolean - is null, if true no more data follows.
  4 bytes   Integer - length of field that follows (excludes these four bytes).

  StoredPage will use the static method provided by StoredFieldHeader
  to read/write field status and field data length.

  Field Header format is defined in the StoredFieldHeader class.

    Slot Offset Table
    The slot offset table is a table of 6 or 12 bytes per record, depending on the pageSize being less or greater than 64K: 2 bytes (unsigned short) or 4 bytes (int) page offset for the record that is assigned to the slot, and 2 bytes (unsigned short) or 4 bytes (int) for the length of the record on this page. 2 bytes (unsigned short) or 4 bytes (int) for the length of the reserved number of bytes for this record on this page. First slot is slot 0. The slot table grows backwards. Slots are never left empty.
    Checksum
    8 bytes of a java.util.zip.CRC32 checksum of the entire's page contents without the 8 bytes representing the checksum.

    Page Access The page data is accessed in this class by one of three methods.

    1. As a byte array using pageData (field in cachedPage). This is the fastest.
    2. As an ArrayInputStream (rawDataIn) and ArrayOutputStream (rawDataOut), this is used to set limits on any one reading the page logically.
    3. Logically through rawDataIn (ArrayInputStream) and logicalDataOut (FormatIdOutputStream), this provides the methods to write logical data (e.g. booleans and integers etc.) and the ObjectInput and ObjectOutput interfaces for DataValueDescriptor's. These logical streams are constructed using the array streams.
    See Also:
    CRC32, ArrayInputStream, ArrayOutputStream

    • Field Detail

      • FORMAT_NUMBER

        public static final int FORMAT_NUMBER
        static final Fields of the class
        See Also:
        Constant Field Values

      • VALID_PAGE

        public static final byte VALID_PAGE
        Values for pageStatus flag page goes thru the following transition: VALID_PAGE <-> deallocated page -> free page <-> VALID_PAGE deallocated and free page are both INVALID_PAGE as far as BasePage is concerned. When a page is deallocated, it transitioned from VALID to INVALID. When a page is allocated, it trnasitioned from INVALID to VALID.
        See Also:
        Constant Field Values

      • INIT_PAGE_REUSE

        public static final int INIT_PAGE_REUSE
        Init page flag. INIT_PAGE_REUSE - set if page is being initialized for reuse INIT_PAGE_OVERFLOW - set if page will be an overflow page INIT_PAGE_REUSE_RECORDID - set if page is being reused and its record id can be reset to RecordHandle.FIRST_RECORD_ID, rather to 1+ next recordId on the page
        See Also:
        Constant Field Values

      • INIT_PAGE_REUSE_RECORDID

        public static final int INIT_PAGE_REUSE_RECORDID
        See Also:
        Constant Field Values

      • LOG_RECORD_DEFAULT

        public static final int LOG_RECORD_DEFAULT
        Log Record flag. Why the before image of this record is being logged LOG_RECORD_FOR_UPDATE - set if the record is being logged for update. LOG_RECORD_DEFAULT - for non update. LOG_RECORD_FOR_PURGE - set if the record is being logged for purges and no data required to ve logged. The other cases (copy, purge, delete), we don't need to distinguish, leave no bit set.
        See Also:
        Constant Field Values

    • Constructor Detail

      • StoredPage

        public StoredPage()
        Simple no-arg constructor for StoredPage.

    • Method Detail

      • getTypeFormatId

        public int getTypeFormatId()
        Return my format identifier.
        Returns:
        The identifier. (A UUID stuffed in an array of 16 bytes).

      • getTotalSpace

        public int getTotalSpace(int slot)
                  throws StandardException
        Return the total number of bytes used, reserved, or wasted by the record at this slot.

        The amount of space the record on this slot is currently taking on the page. If there is any reserve space or wasted space, count that in also Do NOT count the slot entry size

        Parameters:
        slot - look at row at this slot.
        Returns:
        The number of bytes used by the row at slot "slot".
        Throws:
        StandardException - Standard exception policy.

      • spaceForInsert

        public boolean spaceForInsert()
                       throws StandardException
        Is there minimal space for insert?

        Does quick calculation to see if average size row on this page could be inserted on the page. This is done because the actual row size being inserted isn't known until we actually copy the columns from their object form into their on disk form which is expensive. So we use this calculation so that in the normal case we only do one copy of the row directly onto the page.

        Returns:
        true if we think the page will allow an insert, false otherwise.
        Throws:
        StandardException - Standard exception policy.

      • spaceForInsert

        public boolean spaceForInsert(java.lang.Object[] row,
                              FormatableBitSet validColumns,
                              int overflowThreshold)
                       throws StandardException
        Is row guaranteed to be inserted successfully on this page?

        Return true if this record is guaranteed to be inserted successfully using insert() or insertAtSlot(). This guarantee is only valid while the row remains unchanged and the page latch is held.

        Parameters:
        row - The row to check for insert.
        validColumns - bit map to interpret valid columns in row.
        overflowThreshold - The percentage of the page to use for the insert. 100 means use 100% of the page, 50 means use 50% of page (ie. make sure 2 rows fit per page).
        Returns:
        bolean indicating if row can be inserted on this page.
        Throws:
        StandardException - Standard exception policy.

      • unfilled

        public boolean unfilled()
        Is this page unfilled?

        Returns true if page is relatively unfilled, which means the page is < 1/2 full and has enough space to insert an "average" sized row onto the page.

        Returns:
        true if page is relatively unfilled.

      • allowInsert

        public boolean allowInsert()
        Is there enough space on the page to insert a minimum size row?

        Calculate whether there is enough space on the page to insert a minimum size row. The calculation includes maintaining the required reserved space on the page for existing rows to grow on the page.

        Returns:
        boolean indicating if a minimum sized row can be inserted.

      • spaceForCopy

        public boolean spaceForCopy(int num_rows,
                            int[] spaceNeeded)
        Does this page have enough space to insert the input rows?

        Can the rows with lengths spaceNeeded[0..num_rows-1] be copied onto this page?

        Parameters:
        num_rows - number of rows to check for.
        spaceNeeded - array of lengths of the rows to insert.
        Returns:
        true if the sum of the lengths will fit on the page.

      • newRecordId

        public int newRecordId()
        Create a new record handle.

        Return the next record id for allocation. Callers of this interface expect the next id to get bumped some where else - probably by storeRecordForInsert().

        Returns:
        The next id to assing to a row.

      • newRecordIdAndBump

        public int newRecordIdAndBump()
        Create a new record handle, and bump the id.

        Create a new record handle, and bump the id while holding the latch so that no other user can ever see this record id. This will lead to unused record id's in the case where an insert fails because there is not enough space on the page.

        Returns:
        The next id to assing to a row.

      • isOverflowPage

        public boolean isOverflowPage()
        Return true if the page is an overflow page, false if not. For implementation that don't have overflow pages, return false.

      • getPageSize

        public final int getPageSize()
        Get the full size of the page.

      • getReservedCount

        public int getReservedCount(int slot)
                     throws java.io.IOException
        Return reserved length of row on this page.

        Return the reserved length of this record. This length is stored as the third "field" of the slot table entry.

        Parameters:
        slot - the slot of the row to look up the length of.
        Returns:
        The reserved length of the row on this page.
        Throws:
        java.io.IOException - Thrown by InputStream methods potential I/O errors

      • recordHeaderOnDemand

        public StoredRecordHeader recordHeaderOnDemand(int slot)
        create the record header for the specific slot.

        Create a new record header object, initialize it, and add it to the array of cache'd record headers on this page. Finally return reference to the initialized record header.

        Parameters:
        slot - return record header of this slot.
        Returns:
        The record header for the specific slot.

      • entireRecordOnPage

        public boolean entireRecordOnPage(int slot)
                           throws StandardException
        Is entire record on the page?

        Parameters:
        slot - Check record at this slot.
        Returns:
        true if the entire record at slot is on this page, i.e, no overflow row or long columns.
        Throws:
        StandardException - Standard exception policy.

      • getRecordLength

        public int getRecordLength(int slot)
                    throws java.io.IOException
        Get the stored length of a record. This must match the amount of data written by logColumn and logField.
        MT - latched - page latch must be held
        Throws:
        java.io.IOException

      • logRow

        public int logRow(int slot,
                  boolean forInsert,
                  int recordId,
                  java.lang.Object[] row,
                  FormatableBitSet validColumns,
                  DynamicByteArrayOutputStream out,
                  int startColumn,
                  byte insertFlag,
                  int realStartColumn,
                  int realSpaceOnPage,
                  int overflowThreshold)
           throws StandardException,
                  java.io.IOException
        Log a row into the StoreOuput stream.

        Write the row in its record format to the stream. Record format is a record header followed by each field with its field header. See this class's description for the specifics of these headers. startColumn is used to specified which column for this logRow to start logging. When realStartColumn is specified, that means part of the row has already been logged. startColumn here indicates that the first column was logged in the logBuffer, need to continue log the rest of the row starting at realStartColumn. This is used when a longColumn is encountered during a long row. After done logging the long column, we need to continue logging the rest of the row. A -1 value for realStartColumn, means that it is not significant. logRow will not throw an noSpaceOnPage exception, if it is an overflow page, and the record we are inserting is the only record on the page. We are supporting rows expanding multiple pages through this mechanism. logRow expects row to be a sparse row.

        Parameters:
        slot - the slot of the row being logged.
        forInsert - this is logging an insert (not update/delete).
        recordId - record id of the row being logged.
        row - actual data of row in object form. If row is null then we are logging an overflow pointer.
        validColumns - bit map describing valid columns in row.
        out - stream to log to.
        startColumn - what column to start with (see above for detail)
        insertFlag - flag indicating mode we are in, INSERT_DEFAULT - default insert INSERT_SPLIT - splitting a row/column across pages.
        realStartColumn - If -1 ignore variable, else part of row has already been logged, and should continue with this column.
        realSpaceOnPage - Use this as space on page if realStartColumn is not -1.
        overflowThreshold - How much of the page to use before deciding to overflow a row.
        Returns:
        the "realStartColumn" value, -1 if not a long row.
        Throws:
        java.io.IOException - RESOLVE
        StandardException - Standard exception policy.
        See Also:
        BasePage.logRow(int, boolean, int, java.lang.Object[], org.apache.derby.iapi.services.io.FormatableBitSet, org.apache.derby.iapi.services.io.DynamicByteArrayOutputStream, int, byte, int, int, int)

      • restoreRecordFromStream

        public void restoreRecordFromStream(LimitObjectInput in,
                                    java.lang.Object[] row)
                             throws StandardException,
                                    java.io.IOException
        Restore a storable row from a LimitInputStream.

        Restore a storable row from an LimitInputStream - user must supply two streams on top of the same data, one implements ObjectInput interface that knows how to restore the object, the other one implements LimitInputStream.

        Parameters:
        in - the limit input stream
        row - (IN/OUT) row that is to be restored (sparse representation)
        Throws:
        StandardException - Standard exception policy.
        java.io.IOException - object exceeds the available data in the stream.

      • restorePortionLongColumn

        public void restorePortionLongColumn(OverflowInputStream fetchStream)
                              throws StandardException,
                                     java.io.IOException
        Restore a portion of a long column.

        Restore a portion of a long column - user must supply two streams on top of the same data, one implements ObjectInput interface that knows how to restore the object, the other one implements LimitInputStream.

        Parameters:
        fetchStream - the stream to read the next portion of long col from
        Throws:
        StandardException - Standard exception policy.
        java.io.IOException

      • logColumn

        public void logColumn(int slot,
                      int fieldId,
                      java.lang.Object column,
                      DynamicByteArrayOutputStream out,
                      int overflowThreshold)
               throws StandardException,
                      java.io.IOException
        Log a Storable to a stream.

        Log a Storable into a stream. This is used by update field operations

        Write the column in its field format to the stream. Field format is a field header followed the data of the column as defined by the data itself. See this class's description for the specifics of the header.

        Parameters:
        slot - slot of the current record
        fieldId - field number of the column being updated
        column - column version of the field.
        out - Where to write the logged form.
        Throws:
        StandardException - Standard Derby error policy
        java.io.IOException - RESOLVE

      • logLongColumn

        public int logLongColumn(int slot,
                         int recordId,
                         java.lang.Object column,
                         DynamicByteArrayOutputStream out)
                  throws StandardException,
                         java.io.IOException
        Log a long column into a DataOuput.

        Log a long column into a DataOuput. This is used by insert operations

        Write the column in its field format to the stream. Field format is a field header followed the data of the column as defined by the data itself. See this class's description for the specifics of the header.

        Parameters:
        slot - slot of the row with the column
        recordId - record id of the
        column - the object form of the column to log
        out - where to log to the column to.
        Throws:
        StandardException - Standard Derby error policy
        java.io.IOException - I/O exception from writing to an array.
        See Also:
        BasePage.logColumn(int, int, java.lang.Object, org.apache.derby.iapi.services.io.DynamicByteArrayOutputStream, int)

      • logRecord

        public void logRecord(int slot,
                      int flag,
                      int recordId,
                      FormatableBitSet validColumns,
                      java.io.OutputStream out,
                      RecordHandle headRowHandle)
               throws StandardException,
                      java.io.IOException
        Log a record to the ObjectOutput stream.

        Write out the complete on-page record to the store stream. Data is preceeded by a compressed int that gives the length of the following data.

        Parameters:
        slot - Slot number the record is stored in.
        flag - LOG_RECORD_*, the reason for logging the record.
        recordId - Record identifier of the record.
        validColumns - which columns needs to be logged
        out - Where to write the logged form.
        headRowHandle - the recordHandle of the head row piece, used for post commit cleanup for update.
        Throws:
        StandardException - Standard Derby error policy
        java.io.IOException - on error writing to log stream.
        See Also:
        BasePage.logRecord(int, int, int, org.apache.derby.iapi.services.io.FormatableBitSet, java.io.OutputStream, org.apache.derby.iapi.store.raw.RecordHandle)

      • logField

        public void logField(int slot,
                     int fieldNumber,
                     java.io.OutputStream out)
              throws StandardException,
                     java.io.IOException
        Log a field to the ObjectOutput stream.

        Find the field in the record and then write out the complete field, i.e. header and data.

        Parameters:
        slot - Slot number the record is stored in.
        fieldNumber - Number of the field (starts at 0).
        out - Where to write the logged form.
        Throws:
        StandardException - Standard Derby error policy
        java.io.IOException - RESOLVE
        See Also:
        BasePage.logField(int, int, java.io.OutputStream)

      • moveRecordForCompressAtSlot

        public int moveRecordForCompressAtSlot(int slot,
                                       java.lang.Object[] row,
                                       RecordHandle[] old_handle,
                                       RecordHandle[] new_handle)
                                throws StandardException
        Move record to a page toward the beginning of the file.

        As part of compressing the table records need to be moved from the end of the file toward the beginning of the file. Only the contiguous set of free pages at the very end of the file can be given back to the OS. This call is used to purge the row from the current page, insert it into a previous page, and return the new row location Mark the record identified by position as deleted. The record may be undeleted sometime later using undelete() by any transaction that sees the record.

        The interface is optimized to work on a number of rows at a time, optimally processing all rows on the page at once. The call will process either all rows on the page, or the number of slots in the input arrays - whichever is smaller. Locking Policy

        MUST be called with table locked, no locks are requested. Because it is called with table locks the call will go ahead and purge any row which is marked deleted. It will also use purge rather than delete to remove the old row after it moves it to a new page. This is ok since the table lock insures that no other transaction will use space on the table before this transaction commits.
        A page latch on the new page will be requested and released.

        Parameters:
        slot - slot of original row to move.
        row - a row template to hold all columns of row.
        old_handle - An array to be filled in by the call with the old handles of all rows moved.
        new_handle - An array to be filled in by the call with the new handles of all rows moved.
        Returns:
        the number of rows processed.
        Throws:
        StandardException - Standard Derby error policy
        See Also:
        LockingPolicy

      • initPage

        public void initPage(LogInstant instant,
                     byte status,
                     int recordId,
                     boolean overflow,
                     boolean reuse)
              throws StandardException
        Initialize the page. If reuse, then Clean up any in memory or on disk structure to ready the page for reuse. This is not only reusing the page buffer, but reusing a free page which may or may not be cleaned up the the client of raw store when it was deallocated.
        Throws:
        StandardException - Derby Standard Error Policy

      • setPageStatus

        public void setPageStatus(LogInstant instant,
                          byte status)
                   throws StandardException
        Set page status
        Parameters:
        instant - the log instant of the log record
        status - the page status
        Throws:
        StandardException - Derby Standard Error Policy

      • setReservedSpace

        public void setReservedSpace(LogInstant instant,
                             int slot,
                             int value)
                      throws StandardException,
                             java.io.IOException
        Set the row reserved space.
        Throws:
        StandardException - Derby Standard Error Policy
        java.io.IOException

      • storeRecord

        public void storeRecord(LogInstant instant,
                        int slot,
                        boolean insert,
                        java.io.ObjectInput in)
                 throws StandardException,
                        java.io.IOException
        Store a record at the given slot.
        Throws:
        StandardException - Standard Derby error policy
        java.io.IOException - RESOLVE

      • storeField

        public void storeField(LogInstant instant,
                       int slot,
                       int fieldNumber,
                       java.io.ObjectInput in)
                throws StandardException,
                       java.io.IOException
        storeField
        Throws:
        StandardException - Standard Derby error policy
        java.io.IOException - RESOLVE

      • reserveSpaceForSlot

        public void reserveSpaceForSlot(LogInstant instant,
                                int slot,
                                int spaceToReserve)
                         throws StandardException,
                                java.io.IOException
        reserveSpaceForSlot This method will reserve at least specified "spaceToReserve" bytes for the record in the slot.
        Throws:
        StandardException - Standard Derby error policy
        java.io.IOException - RESOLVE

      • skipField

        public void skipField(java.io.ObjectInput in)
               throws java.io.IOException
        Skip a field header and its data on the given stream.
        Throws:
        java.io.IOException - corrupt stream

      • skipRecord

        public void skipRecord(java.io.ObjectInput in)
                throws java.io.IOException
        Throws:
        java.io.IOException

      • setDeleteStatus

        public void setDeleteStatus(LogInstant instant,
                            int slot,
                            boolean delete)
                     throws StandardException,
                            java.io.IOException
        Set the deleted status
        slot - the slot to delete or undelete
        delete - set delete status to this value
        Throws:
        StandardException - Standard Derby error policy
        java.io.IOException - RESOLVE
        See Also:
        BasePage.setDeleteStatus(int, boolean)

      • purgeRecord

        public void purgeRecord(LogInstant instant,
                        int slot,
                        int recordId)
                 throws StandardException,
                        java.io.IOException
        purgeRecord from page. Move following slots up by one.
        slot - the slot to purge
        recordId - the id of the record that is to be purged
        Throws:
        StandardException - Standard Derby error policy
        java.io.IOException - RESOLVE

      • currentTimeStamp

        public PageTimeStamp currentTimeStamp()
        Get a time stamp for this page
        Returns:
        page time stamp

      • setTimeStamp

        public void setTimeStamp(PageTimeStamp ts)
                  throws StandardException
        Set given pageVersion to be the as what is on this page
        Throws:
        StandardException - given time stamp is null or is not a time stamp implementation this page knows how to deal with

      • equalTimeStamp

        public boolean equalTimeStamp(PageTimeStamp ts)
                       throws StandardException
        compare given PageVersion with pageVersion on page
        Parameters:
        ts - the page version gotton from this page via a currentTimeStamp or setTimeStamp call earlier
        Returns:
        true if the same
        Throws:
        StandardException - given time stamp not gotton from this page
        See Also:
        PageTimeStamp

      • toString

        public java.lang.String toString()
        debugging, print this page
        Overrides:
        toString in class java.lang.Object

      • toUncheckedString

        public java.lang.String toUncheckedString()

      • getOverflowPageForInsert

        public org.apache.derby.impl.store.raw.data.BasePage getOverflowPageForInsert(int currentSlot,
                                                                              java.lang.Object[] row,
                                                                              FormatableBitSet validColumns)
                                                                       throws StandardException
        Get a overflow page that potentially can handle a new overflowed record.
        Throws:
        StandardException - Standard Derby error policy

      • getOverflowPageForInsert

        public org.apache.derby.impl.store.raw.data.BasePage getOverflowPageForInsert(int currentSlot,
                                                                              java.lang.Object[] row,
                                                                              FormatableBitSet validColumns,
                                                                              int startColumn)
                                                                       throws StandardException
        Throws:
        StandardException - Standard Derby error policy

      • updateOverflowDetails

        public void updateOverflowDetails(RecordHandle handle,
                                  RecordHandle overflowHandle)
                           throws StandardException
        Update a record handle to point to an overflowed record portion. Note that the record handle need not be the current page.
        Parameters:
        handle - handle of the record for long row
        overflowHandle - the overflow (continuation) pointer for the long row
        Throws:
        StandardException - Standard Derby error policy

      • updateFieldOverflowDetails

        public void updateFieldOverflowDetails(RecordHandle handle,
                                       RecordHandle overflowHandle)
                                throws StandardException
        Update the overflow pointer for a long column
        MT - latched - page latch must be held
        Parameters:
        handle - handle of the record for long row
        overflowHandle - the overflow (continuation) pointer for the long row
        Throws:
        StandardException - Standard Derby error policy

      • appendOverflowFieldHeader

        public int appendOverflowFieldHeader(DynamicByteArrayOutputStream logBuffer,
                                     RecordHandle overflowHandle)
                              throws StandardException,
                                     java.io.IOException
        Append an overflow pointer to a partly logged row, to point to a long column that just been logged.
        MT - latched - page latch must be held
        Parameters:
        logBuffer - The buffer that contains the partially logged row.
        overflowHandle - the overflow (continuation) pointer to the beginning of the long column
        Throws:
        StandardException - Standard Derby error policy
        java.io.IOException

      • getIdentity

        public java.lang.Object getIdentity()
        OK to hand object outside to cache..

      • getInvalidRecordHandle

        public final RecordHandle getInvalidRecordHandle()
        Description copied from interface: Page
        Return an invalid record handle.

        Specified by:
        getInvalidRecordHandle in interface Page
        Returns:
        an invalid record handle.

      • makeRecordHandle

        public final RecordHandle makeRecordHandle(int recordHandleConstant)
                                    throws StandardException
        Description copied from interface: Page
        Return a record handle for the given constant record id.

        Return a record handle that doesn't represent a record but rather has a special meaning. Used for special cases like creating a key specific to the page, but not specific to a row on the page.

        See RecordHandle interface for a list of "special record handles."

        Specified by:
        makeRecordHandle in interface Page
        Parameters:
        recordHandleConstant - the special recordId
        Returns:
        The created record handle.
        Throws:
        StandardException - if input is not a special record identifier.
        See Also:
        RecordHandle

      • getPageNumber

        public final long getPageNumber()
        Description copied from interface: Page
        Return the page number of this page.

        Page numbers are unique within a container and start at ContainerHandle.FIRST_PAGE_NUMBER and increment by 1 regardless of the page size.


        MT - Latched

        Specified by:
        getPageNumber in interface Page
        Returns:
        The page number of this page.
        See Also:
        Page.getPageNumber()

      • getRecordHandle

        public final RecordHandle getRecordHandle(int recordId)
        Description copied from interface: Page
        Get a record handle from a previously stored record id.

        Get a record handle from a previously stored record identifier that was obtained from a RecordHandle.


        MT - Latched

        Specified by:
        getRecordHandle in interface Page
        Parameters:
        recordId - previously stored recordId.
        Returns:
        A valid record handle or null if the record no longer exists.
        See Also:
        RecordHandle.getId()

      • getRecordHandleAtSlot

        public final RecordHandle getRecordHandleAtSlot(int slot)
        Description copied from interface: Page
        Get the record handle of row at slot.

        Get the record handle of a record on a latched page using its slot number.
        MT - latched

        Specified by:
        getRecordHandleAtSlot in interface Page
        Parameters:
        slot - the slot number
        Returns:
        the record handle.

      • recordExists

        public final boolean recordExists(RecordHandle handle,
                                  boolean ignoreDelete)
                           throws StandardException
        Description copied from interface: Page
        does the record still exist on the page?

        If "ignoreDelete" is true and the record handle represents a record on the page (either marked deleted or not) return true. If "ignoreDelete" is false return true if the record handle represents a record on the page and the record is not marked as deleted. Return false otherwise.
        MT - Latched

        Specified by:
        recordExists in interface Page
        Parameters:
        handle - handle of the record to look for.
        ignoreDelete - if true, then routine will return true even if the row is marked deleted.
        Returns:
        boolean indicating if the record still exists on the page.
        Throws:
        StandardException - recordHandle is not a valid record handle
        See Also:
        Page.recordExists(org.apache.derby.iapi.store.raw.RecordHandle, boolean)

      • fetchFromSlot

        public RecordHandle fetchFromSlot(RecordHandle rh,
                                  int slot,
                                  java.lang.Object[] row,
                                  FetchDescriptor fetchDesc,
                                  boolean ignoreDelete)
                           throws StandardException
        Description copied from interface: Page
        Fetch a record located in the passed in slot.

        Fetch a record located in the passed in slot and fill-in the passed in StorebleRow and the Object columns contained within. If row is null then the record is locked but is not fetched.
        This interface allows the caller to either return a deleted row or not. If "ignoreDelete" is set to true, fetch the record regardless of whether it is deleted or not (same as above fetchFromSlot). However, if "ignoreDelete" is set to false and the and the slot correspond to a deleted row, null is returned.
        If a non-null Qualifier list is provided then the qualifier array will be applied to the row and the row will only be returned if the row qualifies, otherwise null will be returned. Values in the columns of row may or may not be altered while trying to apply the qualifiers, if null is returned the state of the columns is undefined. If a null Qualifier list is provided then no qualification is applied.
        If a non-null record handle is passed in, it is assumed that the record handle corresponds to the record in the slot. If record handle is null, a record handle will be manufactured and returned if the record is not deleted or if "ignoreDelete" is true. This parameter is here for the case where the caller have already manufactured the record handle for locking or other purposes so it would make sense for the page to avoid creating a new record handle object if possible.

        Specified by:
        fetchFromSlot in interface Page
        Parameters:
        rh - the record handle of the row. If non-null it must refer to the same record as the slot.
        slot - the slot number
        row - Row to be filled in with information from record.
        fetchDesc - A structure to efficiently carry a set of parameters needed to describe the fetch, these include: validColumns - A bit map of which columns in the row to be fetched. ValidColumns will not be changed by RawStore. qualifier_list - A list of Qualifiers to apply to the row to see if the row should be returned. An array of qualifiers which restrict whether or not the row should be returned by the fetch. Rows for which any one of the qualifiers returns false are not returned by the fetch. If null, no qualification is done and the requested columns of the rows are returned. Qualifiers can only reference columns which are included in the scanColumnList. The column id that a qualifier returns is the column id the table, not the column id in the partial row being returned. qualifier_scratch_space - An array of int's that matches the size of the row[] array. Used to process qualifiers, if no qualifiers are input then array need not be input. Passed in rather than allocated so that space can be allocated a single time in a scan. If not passed in then raw store will allocate and deallocate per call.
        ignoreDelete - if true, return row regardless of whether it is deleted or not. If false, only return non-deleted row.
        Returns:
        A handle to the record.
        Throws:
        StandardException - Standard Derby error policy
        See Also:
        LockingPolicy

      • fetchFieldFromSlot

        public final RecordHandle fetchFieldFromSlot(int slot,
                                             int fieldId,
                                             java.lang.Object column)
                                      throws StandardException
        Description copied from interface: Page
        Fetch a single field from a deleted or non-deleted record. Fills in the passed in Object column with the field identified by fieldid if column is not null, otherwise the record is locked but not fetched.
        The fieldId of the first field is 0. If the fieldId is >= the number of fields on the record, column is restored to null

        Locking Policy
        No locks are obtained. It is up to the caller to obtain the correct locks.
        It is guaranteed that the page latch is not released by this method

        Specified by:
        fetchFieldFromSlot in interface Page
        Parameters:
        slot - is the slot number
        fieldId - is the column id
        column - is to be filled in with information from the record.
        Returns:
        the Handle to the record that is locked
        Throws:
        StandardException - Standard Derby error policy
        See Also:
        Page.fetchFieldFromSlot(int, int, java.lang.Object)

      • getNextSlotNumber

        public final int getNextSlotNumber(RecordHandle handle)
                            throws StandardException
        Description copied from interface: Page
        Find slot for record with an id greater than the passed in identifier.

        Find the slot for the first record on the page with an id greater than the passed in identifier.
        Returns the slot of the first record on the page with an id greater than the one passed in. Usefulness of this functionality depends on the client's use of the raw store interfaces. If all "new" records are always inserted at the end of the page, and the raw store continues to guarantee that all record id's will be allocated in increasing order on a given page (assuming a PAGE_REUSABLE_RECORD_ID container), then a page is always sorted in record id order. For instance current heap tables function this way. If the client ever inserts at a particular slot number, rather than at the "end" then the record id's will not be sorted.
        In the case where all record id's are always sorted on a page, then this routine can be used by scan's which "lose" their position because the row they have as a position was purged. They can reposition their scan at the "next" row after the row that is now missing from the table.
        This method returns the record regardless of its deleted status.
        MT - latched

        Specified by:
        getNextSlotNumber in interface Page
        Parameters:
        handle - record handle to find the next higher id.
        Returns:
        record id of the first record on the page with a record id higher than the one passed in. If no such record exists, -1 is returned.
        Throws:
        StandardException - Record does not exist on this page.
        See Also:
        Page.getNextSlotNumber(org.apache.derby.iapi.store.raw.RecordHandle)

      • insert

        public final RecordHandle insert(java.lang.Object[] row,
                                 FormatableBitSet validColumns,
                                 byte insertFlag,
                                 int overflowThreshold)
                          throws StandardException
        Description copied from interface: Page
        Insert a record anywhere on the page.

        Locking Policy
        Calls the lockRecordForWrite() method of the LockingPolicy object passed to the openContainer() call before the record is inserted.
        MT - latched

        Specified by:
        insert in interface Page
        Parameters:
        row - The row version of the data
        validColumns - a bit map of which columns in the row is valid. ValidColumns will not be changed by RawStore.
        insertFlag - see values for insertFlag below.
        Returns:
        A RecordHandle representing the new record.
        Throws:
        StandardException - Standard Derby error policy
        See Also:
        Page.insert(java.lang.Object[], org.apache.derby.iapi.services.io.FormatableBitSet, byte, int)

      • insertAllowOverflow

        public RecordHandle insertAllowOverflow(int slot,
                                        java.lang.Object[] row,
                                        FormatableBitSet validColumns,
                                        int startColumn,
                                        byte insertFlag,
                                        int overflowThreshold,
                                        RecordHandle nextPortionHandle)
                                 throws StandardException
        Insert a row allowing overflow. If handle is supplied then the record at that hanlde will be updated to indicate it is a partial row and it has an overflow portion.
        Throws:
        StandardException - Standard Derby error policy

      • updateAtSlot

        public final RecordHandle updateAtSlot(int slot,
                                       java.lang.Object[] row,
                                       FormatableBitSet validColumns)
                                throws StandardException
        Description copied from interface: Page
        Update the complete record identified by the slot.

        Locking Policy

        Calls the lockRecordForWrite() method of the LockingPolicy object passed to the openContainer() call before the record is undeleted. If record already deleted, an exception is thrown.
        It is guaranteed that the page latch is not released by this method

        Specified by:
        updateAtSlot in interface Page
        Parameters:
        slot - is the slot number
        validColumns - a bit map of which columns in the row is valid. ValidColumns will not be changed by RawStore.
        Returns:
        a Handle to the updated record.
        Throws:
        StandardException - Standard Derby error policy
        StandardException - StandardException.newException(SQLState.UPDATE_DELETED_RECORD if the record is already deleted
        StandardException - StandardException.newException(SQLState.CONTAINER_READ_ONLY if the container is read only
        See Also:
        Page.updateAtSlot(int, java.lang.Object[], org.apache.derby.iapi.services.io.FormatableBitSet)

      • deleteAtSlot

        public RecordHandle deleteAtSlot(int slot,
                                 boolean delete,
                                 LogicalUndo undo)
                          throws StandardException
        Description copied from interface: Page
        Mark the record at slot as deleted or undeleted according to delete flag.

        Locking Policy

        Calls the lockRecordForWrite() method of the LockingPolicy object passed to the openContainer() call before the record is deleted. If record already deleted, and an attempt is made to delete it, an exception is thrown. If record not deleted, and an attempt is made to undelete it, an exception is thrown.
        MT - latched

        Specified by:
        deleteAtSlot in interface Page
        Parameters:
        slot - the slot number
        delete - true if this record is to be deleted, false if this deleted record is to be marked undeleted
        undo - logical undo logic if necessary
        Returns:
        a Handle to the deleted/undeleted record.
        Throws:
        StandardException - Standard exception policy.
        StandardException - StandardException.newException(SQLState.UPDATE_DELETED_RECORD if an attempt to delete a record that is already deleted
        StandardException - StandardException.newException(SQLState.UNDELETE_RECORD if an attempt to undelete a record that is not deleted
        See Also:
        Page.deleteAtSlot(int, boolean, org.apache.derby.iapi.store.access.conglomerate.LogicalUndo)

      • purgeAtSlot

        public void purgeAtSlot(int slot,
                        int numpurges,
                        boolean needDataLogged)
                 throws StandardException
        Purge one or more rows on a non-overflow page.
        Specified by:
        purgeAtSlot in interface Page
        Parameters:
        slot - the starting slot number
        numpurges - number of slots to purge. If <= 0, just returns as a no-op.
        needDataLogged - if set to true data is logged for purges else only headers.
        Throws:
        StandardException - Standard exception policy.
        See Also:
        Page.purgeAtSlot(int, int, boolean)

      • copyAndPurge

        public void copyAndPurge(Page destPage,
                         int src_slot,
                         int num_rows,
                         int dest_slot)
                  throws StandardException
        Description copied from interface: Page
        move rows from one page to another, purging in the process.

        Move from this page slot[src_slot] to slot[src_slot+num_rows-1] to destPage slot[dest_slot] to slot[dest_slot + num_rows - 1], in that order. Both this page and destPage must be latched and from the same container with the same page and record format.
        Slot[src_slot] to slot[src_slot+numrows-1] will be purged from this page. RecordId on the dest page will be brand new and not in any particular order or range. RecordId of the purged rows in this page is never reused. Deleted and undeleted rows are copied over just the same. Exception will be thrown if this page does not have all the rows in the moved over range.
        RESOLVE: reserve space now not copied over because in btree, a row never shrinks. When this routine is called by heap or by some page which will have shrunken row, then we need to add that
        DestPage must have at least dest_slot row occupying slot[0] to slot[dest_slot-1]. DestPage must have enough space to take the copied over data. Rows that occupied slot number > dest_slot will be moved up the slot (I.e., slot[dest_slot] -> slot[dest_slot + num_rows]).
        If this operation rolls back, this page (the src page) will get the rows back and the dest page will purge the rows that were copied - this is as if the rows were inserted into the dest page with INSERT_UNDO_WITH_PURGE.

        Locking Policy

        Calls the lockRecordForWrite() method of the LockingPolicy object passed to the openContainer() call before the rows are copied over and bore the records are purged. I.e, for num_rows moved, there will be 2*num_rows calls to lockRecordForWrite.

        Use with caution
        As with a normal purge, no space is reserved on this page for rollback of the purge, so you must commit before inserting any rows onto this page - unless those inserts are INSERT_UNDO_WITH_PURGE.

        Specified by:
        copyAndPurge in interface Page
        Parameters:
        destPage - the page to copy to
        src_slot - start copying from this slot
        num_rows - copy and purge this many rows from this page
        dest_slot - copying into this slot of destPage
        Throws:
        StandardException - Standard exception policy.
        See Also:
        Page.copyAndPurge(org.apache.derby.iapi.store.raw.Page, int, int, int)

      • isLatched

        public final boolean isLatched()
        Check whether the page is latched.
        Specified by:
        isLatched in interface Page
        Returns:
        true if the page is latched, false otherwise
        See Also:
        Page.isLatched()

      • recordCount

        public final int recordCount()
        Description copied from interface: Page
        Return the number of records on the page. The returned count includes rows that are deleted, i.e. it is the same as the number of slots on the page.
        MT - latched
        Specified by:
        recordCount in interface Page
        See Also:
        Page.recordCount()

      • shouldReclaimSpace

        public boolean shouldReclaimSpace(int num_non_deleted_rows,
                                  int slot_just_deleted)
                           throws StandardException
        Is this page/deleted row a candidate for immediate reclaim space.

        Used by access methods after executing a delete on "slot_just_deleted" to ask whether a post commit should be queued to try to reclaim space after the delete commits.

        Will return true if the number of non-deleted rows on the page is <= "num_non_deleted_rows". For instance 0 means schedule reclaim only if all rows are deleted, 1 if all rows but one are deleted.

        Will return true if the row just deleted is either a long row or long column. In this case doing a reclaim space on the single row may reclaim multiple pages of free space, so better to do it now rather than wait for all rows on page to be deleted. This case is to address the worst case scenario of all rows with long columns, but very short rows otherwise. In this case there could be 1000's of rows on the main page with many gigabytes of data on overflow pages in deleted space that would not be reclaimed until all rows on the page were deleted.

        Specified by:
        shouldReclaimSpace in interface Page
        Parameters:
        num_non_deleted_rows - threshold number of non-deleted rows to schedule reclaim space.
        slot_just_deleted - row on page to check for long row/long column
        Returns:
        true if a reclaim space should be scheduled post commit on this page, false otherwise.
        Throws:
        StandardException - Standard exception policy.

      • isDeletedAtSlot

        public boolean isDeletedAtSlot(int slot)
                        throws StandardException
        Description copied from interface: Page
        Test if a record is deleted.

        Locking Policy
        No locks are obtained.
        It is guaranteed that the page latch is not released by this method

        Specified by:
        isDeletedAtSlot in interface Page
        Parameters:
        slot - slot of record to be tested.
        Throws:
        StandardException - Standard exception policy.
        See Also:
        Page.isDeletedAtSlot(int)

      • setAuxObject

        public void setAuxObject(AuxObject obj)
        Set the aux object.
        MT - single thread required. Calls via the Page interface will have the page latched, thus providing single threadedness. Otherwise calls via this class are only made when the class has no-identity, thus only a single thread can see the object.
        Specified by:
        setAuxObject in interface Page
        See Also:
        Page.setAuxObject(org.apache.derby.iapi.store.raw.AuxObject)

      • getAuxObject

        public AuxObject getAuxObject()
        Get the aux object.
        MT - latched - It is required the caller throws away the returned reference when the page is unlatched.
        Specified by:
        getAuxObject in interface Page
        See Also:
        Page.getAuxObject()

      • setRepositionNeeded

        public void setRepositionNeeded()
        Set a hint in this page to make B-tree scans positioned on it reposition before they continue. This method is typically called when rows are removed from a B-tree leaf page (for instance in a page split).
        Specified by:
        setRepositionNeeded in interface Page

      • isRepositionNeeded

        public boolean isRepositionNeeded(long version)
        Check if a B-tree scan positioned on this page needs to reposition.
        Specified by:
        isRepositionNeeded in interface Page
        Parameters:
        version - the last version on which the B-tree scan had a valid position on this page
        Returns:
        true if a repositioning is needed because the row on the current position may have been removed from this page after the specified version; false otherwise

      • update

        public void update(java.util.Observable obj,
                   java.lang.Object arg)
        This object is set to observe the BaseContainerHandle it was obtained by, that handle will notify its observers when it is being closed. In that case we will release the latch on the page held by that container.
        MT - latched
        Specified by:
        update in interface java.util.Observer
        See Also:
        Observer.update(java.util.Observable, java.lang.Object)

      • getPageId

        public final PageKey getPageId()
        Get the Page identifer
        MT - RESOLVE

      • setDeleteStatus

        public int setDeleteStatus(int slot,
                           boolean delete)
                    throws StandardException,
                           java.io.IOException
        Mark the record at the passed in slot as deleted. return code comes from StoredRecordHeader class: return 1, if delete status from not deleted to deleted return -1, if delete status from deleted to not deleted return 0, if status unchanged.
        Any sub-class must call this method when deleting a record.
        MT - latched
        Throws:
        StandardException - Standard Derby error policy
        java.io.IOException - IO error accessing page

      • initPage

        public void initPage(int initFlag,
                     long pageOffset)
              throws StandardException
        Mark this page as being allocated and initialize it to a pristine page
        Throws:
        StandardException - Derby Standard error policy

      • findRecordById

        public int findRecordById(int recordId,
                          int slotHint)
        Find the slot for the record with the passed in identifier.
        This method returns the record regardless of its deleted status.
        The "slotHint" argument is a hint about what slot the record id might be in. Callers may save the last slot where the record was across latch/unlatches to the page, and then pass that slot back as a hint - if the page has not shuffled slots since the last reference then the hint will succeed and a linear search is saved. If the caller has no idea where it may be, then FIRST_SLOT_NUMBER is passed in and a linear search is performed.
        MT - latched
        Parameters:
        recordId - record id of the record to search for.
        slotHint - "hint" about which slot the record might be in.

      • compactRecord

        public void compactRecord(RecordHandle handle)
                   throws StandardException
        Try to compact this record. Deleted record are treated the same way as nondeleted record. This page must not be an overflow page. The record may already have been purged from the page.

        Locking Policy

        No locks are obtained.
        MT - latched

        NOTE : CAVEAT
        This operation will physically get rid of any reserved space this record may have, or it may compact the record by merging strung out row pieces together. Since the freed reserved space is immediately usable by other transactions which latched the page, it is only safe to use this operation if the caller knows that it has exclusive access to the page for the duration of the transaction, i.e., effectively holding a page lock on the page, AND that the record has no uncommitted updates.

        Parameters:
        handle - Handle to deleted or non-deleted record
        Throws:
        StandardException - Standard Derby error policy
        See Also:
        ContainerHandle.compactRecord(org.apache.derby.iapi.store.raw.RecordHandle)

      • getLastLogInstant

        public final LogInstant getLastLogInstant()

      • getPageVersion

        public final long getPageVersion()
        Return the current page version.
        Specified by:
        getPageVersion in interface Page
        Returns:
        page version number

      • setPageVersion

        public final void setPageVersion(long v)
        set it when the page is read from disk.
        MT - single thread required - Only called while the page has no identity which requires that only a single caller can be accessing it.

      • getPageStatus

        public byte getPageStatus()
        Get the page status, one of the values in the above page status flag
Skip navigation links

DataMelt 3.0 © DataMelt by jWork.ORG

You see the box below because you did not login.