Package edu.caltech.nanodb.storage

Class PageTuple

  • All Implemented Interfaces:
    Tuple, Pinnable
    Direct Known Subclasses:
    HeapFilePageTuple
    public abstract class PageTuple
extends java.lang.Object
implements Tuple

    This class is a partial implementation of the Tuple interface that handles reading and writing tuple data against a DBPage object. This can be used to read and write tuples in a table file, keys in an index file, etc. It could also be used to store and manage tuples in memory, although it's generally much faster and simpler to use an optimized in-memory representation for tuples in memory.

    Each tuple is stored in a layout like this:

    • The first one or more bytes are dedicated to a NULL-bitmap, which records columns that are currently NULL.
    • The remaining bytes are dedicated to storing the non-NULL values for the columns in the tuple.

    In order to make this class' functionality generic, certain operations must be implemented by subclasses: specifically, any operation that changes a tuple's size (e.g. writing a non-NULL value to a previously NULL column or vice versa, or changing the size of a variable-size column). The issue with these operations is that they require page-level data management, which is beyond the scope of what this class can provide. Thus, concrete subclasses of this class can provide page-level data management as needed.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private DBPage dbPage
      The database page that contains the tuple's data.
      private int endOffset
      The offset in the page where the tuple's data ends.
      static int NULL_OFFSET
      This value is used in valueOffsets when a column value is set to NULL.
      private int pageOffset
      The offset in the page of the tuple's start.
      private int pinCount
      The pin-count of this tuple.
      private Schema schema
      The schema of the tuple.
      private int[] valueOffsets
      This array contains the cached offsets of each value in this tuple.

    • Constructor Summary

      Constructors 
      Constructor Description
      PageTuple​(DBPage dbPage, int pageOffset, Schema schema)
      Construct a new tuple object that is backed by the data in the database page.

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      private void checkColumnIndex​(int colIndex)
      This helper method checks the column index for being in the proper range of values.
      private void computeValueOffsets()
      This helper function computes and caches the offset of each column value in the tuple.
      protected abstract void deleteTupleDataRange​(int off, int len)  
      int getColumnCount()
      Returns the number of attributes in the tuple.
      java.lang.Object getColumnValue​(int colIndex)
      Returns the specified column's value as an Object reference.
      private int getColumnValueSize​(ColumnType colType, int valueOffset)
      Returns the number of bytes used by the column-value at the specified offset, with the specified type.
      private int getDataStartOffset()
      Returns the offset where the tuple's data actually starts.
      DBPage getDBPage()  
      int getEndOffset()  
      FilePointer getExternalReference()
      This method returns an external reference to the tuple, which can be stored and used to look up this tuple.
      private boolean getNullFlag​(int colIndex)
      This is a helper function to find out the current value of a column's NULL flag.
      static int getNullFlagsSize​(int numCols)
      This method computes and returns the number of bytes that are used to store the null-flags in each tuple.
      int getOffset()  
      int getPinCount()
      Returns the total number of times the object has been pinned.
      Schema getSchema()  
      int getSize()
      Returns the storage-size of the tuple in bytes.
      static int getStorageSize​(ColumnType colType, int dataLength)
      Returns the storage size of a particular column's (non-NULL) value, in bytes.
      static int getTupleStorageSize​(Schema schema, Tuple tuple)
      This helper function takes a tuple (from an arbitrary source) and computes how much space it would require to be stored in a heap table file with the specified schema.
      protected abstract void insertTupleDataRange​(int off, int len)  
      boolean isDiskBacked()
      Page tuples are backed by data pages managed by the Buffer Manager, so this method always returns true.
      boolean isNullValue​(int colIndex)
      Returns true if the specified column is currently set to the SQL NULL value.
      boolean isPinned()
      Returns true if the object is currently pinned, false otherwise.
      void pin()
      Increase the pin-count on the object by one.
      void setColumnValue​(int colIndex, java.lang.Object value)
      Sets the column to the specified value, or NULL if the value is the Java null value.
      private void setNonNullColumnValue​(int iCol, java.lang.Object value)
      This helper function is used by the setColumnValue(int, java.lang.Object) method in the specific case when a column is being set to a non-NULL value.
      private void setNullColumnValue​(int iCol)
      This helper function is used by the setColumnValue(int, java.lang.Object) method in the specific case when a column is being set to the SQL NULL value.
      private void setNullFlag​(int colIndex, boolean value)
      This is a helper function to set or clear the value of a column's NULL flag.
      static void setNullFlag​(DBPage dbPage, int tupleStart, int colIndex, boolean value)
      This is a helper function to set or clear the value of a column's NULL flag.
      static int storeTuple​(DBPage dbPage, int pageOffset, Schema schema, Tuple tuple)  
      java.lang.String toString()  
      void unpin()
      Decrease the pin-count on the object by one.
      static int writeNonNullValue​(DBPage dbPage, int offset, ColumnType colType, java.lang.Object value)
      This helper function is used by the setColumnValue(int, java.lang.Object) method in the specific case when a column is being set to a non-NULL value.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • pinCount

        private int pinCount
        The pin-count of this tuple. Note that this tuple's pin-count will likely be different from the backing DBPage's pin-count, particularly if multiple tuples from the DBPage are in use.

      • dbPage

        private DBPage dbPage
        The database page that contains the tuple's data.

      • pageOffset

        private int pageOffset
        The offset in the page of the tuple's start.

      • schema

        private Schema schema
        The schema of the tuple.

      • valueOffsets

        private int[] valueOffsets
        This array contains the cached offsets of each value in this tuple. The array is populated when a tuple is constructed. For columns with a value of NULL, the offset will be 0.
        See Also:
        NULL_OFFSET

      • endOffset

        private int endOffset
        The offset in the page where the tuple's data ends. Note that this value is one byte past the end of the tuple's data; as with most Java sequences, the starting offset is inclusive and the ending offset is exclusive. Also, as a consequence, this value could be past the end of the byte-array that the tuple resides in, if the tuple is at the end of the byte-array.

    • Constructor Detail

      • PageTuple

        public PageTuple​(DBPage dbPage,
                 int pageOffset,
                 Schema schema)
        Construct a new tuple object that is backed by the data in the database page. This tuple is able to be read from or written to.
        Parameters:
        dbPage - the specific database page that holds the tuple
        pageOffset - the offset of the tuple's actual data in the page
        schema - the details of the columns that appear within the tuple

    • Method Detail

      • isDiskBacked

        public boolean isDiskBacked()
        Page tuples are backed by data pages managed by the Buffer Manager, so this method always returns true.
        Specified by:
        isDiskBacked in interface Tuple
        Returns:
        true since page tuples are backed by disk pages.

      • pin

        public void pin()
        Description copied from interface: Pinnable
        Increase the pin-count on the object by one. An object with a nonzero pin-count cannot be released because it is in use.
        Specified by:
        pin in interface Pinnable

      • unpin

        public void unpin()
        Description copied from interface: Pinnable
        Decrease the pin-count on the object by one. When the pin-count reaches zero, the object can be released.
        Specified by:
        unpin in interface Pinnable

      • getPinCount

        public int getPinCount()
        Description copied from interface: Pinnable
        Returns the total number of times the object has been pinned.
        Specified by:
        getPinCount in interface Pinnable
        Returns:
        the total number of times the object has been pinned.

      • isPinned

        public boolean isPinned()
        Description copied from interface: Pinnable
        Returns true if the object is currently pinned, false otherwise.
        Specified by:
        isPinned in interface Pinnable

      • getExternalReference

        public FilePointer getExternalReference()
        This method returns an external reference to the tuple, which can be stored and used to look up this tuple. The external reference is represented as a file-pointer. The default implementation simply returns a file-pointer to the tuple-data itself, but specific storage formats may introduce a level of indirection into external references.
        Specified by:
        getExternalReference in interface Tuple
        Returns:
        a file-pointer that can be used to look up this tuple

      • getDBPage

        public DBPage getDBPage()

      • getOffset

        public int getOffset()

      • getEndOffset

        public int getEndOffset()

      • getSize

        public int getSize()
        Returns the storage-size of the tuple in bytes.
        Returns:
        the storage-size of the tuple in bytes.

      • getSchema

        public Schema getSchema()

      • checkColumnIndex

        private void checkColumnIndex​(int colIndex)
        This helper method checks the column index for being in the proper range of values.
        Parameters:
        colIndex - the column index to check
        Throws:
        java.lang.IllegalArgumentException - if the specified column index is out of range.

      • getColumnCount

        public int getColumnCount()
        Returns the number of attributes in the tuple. Note that this value may be zero.
        Specified by:
        getColumnCount in interface Tuple
        Returns:
        a count of the number of columns in the tuple.

      • getNullFlag

        private boolean getNullFlag​(int colIndex)
        This is a helper function to find out the current value of a column's NULL flag. It is not intended to be used to determine if a column's value is NULL since the method does a lot of work; instead, use the isNullValue(int) method which relies on cached column information.
        Parameters:
        colIndex - the index of the column to retrieve the null-flag for
        Returns:
        true if the column is null, or false otherwise

      • setNullFlag

        private void setNullFlag​(int colIndex,
                         boolean value)
        This is a helper function to set or clear the value of a column's NULL flag.
        Parameters:
        colIndex - the index of the column to retrieve the null-flag for
        value - true if the column is null, or false otherwise

      • getDataStartOffset

        private int getDataStartOffset()
        Returns the offset where the tuple's data actually starts. This is past the bytes used to store NULL-flags.
        Returns:
        the starting index of the tuple's data

      • computeValueOffsets

        private void computeValueOffsets()
        This helper function computes and caches the offset of each column value in the tuple. If a column has a NULL value then NULL_OFFSET is used for the offset.

      • getColumnValueSize

        private int getColumnValueSize​(ColumnType colType,
                               int valueOffset)
        Returns the number of bytes used by the column-value at the specified offset, with the specified type.
        Parameters:
        colType - the column type, which includes both the basic SQL data type (e.g. VARCHAR) and the size/length of the column's type.
        valueOffset - the offset in the data where the column's value actually starts
        Returns:
        the total number of bytes used by the column-value

      • isNullValue

        public boolean isNullValue​(int colIndex)
        Returns true if the specified column is currently set to the SQL NULL value.
        Specified by:
        isNullValue in interface Tuple
        Parameters:
        colIndex - the index of the column to check for NULLness.
        Returns:
        true if the specified column is currently set to NULL, or false otherwise.

      • getColumnValue

        public java.lang.Object getColumnValue​(int colIndex)
        Returns the specified column's value as an Object reference. The actual type of the object depends on the column type, and follows this mapping:
        • INTEGER produces Integer
        • SMALLINT produces Short
        • BIGINT produces Long
        • TINYINT produces Byte
        • FLOAT produces Float
        • DOUBLE produces Double
        • CHAR(n) produces String
        • VARCHAR(n) produces String
        • FILE_POINTER (internal) produces FilePointer
        Specified by:
        getColumnValue in interface Tuple
        Parameters:
        colIndex - the index of the column to retrieve the value for
        Returns:
        the value of the column, or null if the column is NULL.

      • setColumnValue

        public void setColumnValue​(int colIndex,
                           java.lang.Object value)
        Sets the column to the specified value, or NULL if the value is the Java null value.
        Specified by:
        setColumnValue in interface Tuple
        Parameters:
        colIndex - The index of the column to set.
        value - the value to set the column to, or null if the column should be set to the SQL NULL value.

      • setNullColumnValue

        private void setNullColumnValue​(int iCol)
        This helper function is used by the setColumnValue(int, java.lang.Object) method in the specific case when a column is being set to the SQL NULL value.
        Parameters:
        iCol - the index of the column to set to NULL

      • setNonNullColumnValue

        private void setNonNullColumnValue​(int iCol,
                                   java.lang.Object value)
        This helper function is used by the setColumnValue(int, java.lang.Object) method in the specific case when a column is being set to a non-NULL value.
        Parameters:
        iCol - The index of the column to set.
        value - the value to set the column to.
        Throws:
        java.lang.IllegalArgumentException - if the specified value is null

      • getNullFlagsSize

        public static int getNullFlagsSize​(int numCols)
        This method computes and returns the number of bytes that are used to store the null-flags in each tuple.
        Parameters:
        numCols - the total number of columns in the table
        Returns:
        the number of bytes used for the null-bitmap.
        Code Review:
        (donnie) This is really a table-file-level computation, not a tuple-level computation.

      • getStorageSize

        public static int getStorageSize​(ColumnType colType,
                                 int dataLength)
        Returns the storage size of a particular column's (non-NULL) value, in bytes. The length of the value is required in cases where the column value can be variable size, such as if the type is a VARCHAR. Note that the data-length is actually not required when the type is CHAR, since CHAR fields always have a specific size.
        Parameters:
        colType - the column's data type
        dataLength - for column-types that specify a length, this is the length value.
        Returns:
        the storage size of the data in bytes

      • getTupleStorageSize

        public static int getTupleStorageSize​(Schema schema,
                                      Tuple tuple)
        This helper function takes a tuple (from an arbitrary source) and computes how much space it would require to be stored in a heap table file with the specified schema. This is used to insert new tuples into a table file by computing how much space will be needed, so that an appropriate page can be found.
        Parameters:
        schema - the schema of the tuple
        tuple - the tuple to compute the storage size for
        Returns:
        the total size for storing the tuple's data in bytes
        Code Review:
        (donnie) It doesn't make sense to have this be a non-static method, since a page-tuple references a specific tuple, not a data page. However, having this as a static method on this class doesn't seem too bad.

      • storeTuple

        public static int storeTuple​(DBPage dbPage,
                             int pageOffset,
                             Schema schema,
                             Tuple tuple)

      • setNullFlag

        public static void setNullFlag​(DBPage dbPage,
                               int tupleStart,
                               int colIndex,
                               boolean value)
        This is a helper function to set or clear the value of a column's NULL flag.
        Parameters:
        dbPage - the file-page that the value will be written into
        tupleStart - the byte-offset in the page where the tuple starts
        colIndex - the index of the column to set the null-flag for
        value - the new value for the null-flag

      • writeNonNullValue

        public static int writeNonNullValue​(DBPage dbPage,
                                    int offset,
                                    ColumnType colType,
                                    java.lang.Object value)
        This helper function is used by the setColumnValue(int, java.lang.Object) method in the specific case when a column is being set to a non-NULL value.
        Parameters:
        dbPage - the file-page that the value will be written into
        offset - the actual byte-offset in the page where the value is written to
        colType - the type of the column that the value is being written for
        value - the non-null value to store
        Returns:
        The number of bytes written for the specified value.
        Throws:
        java.lang.NullPointerException - if dbPage is null, or if value is null.

      • insertTupleDataRange

        protected abstract void insertTupleDataRange​(int off,
                                             int len)

      • deleteTupleDataRange

        protected abstract void deleteTupleDataRange​(int off,
                                             int len)

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object