storedfieldheader.java

derby database source code.good for you.

/*

   Derby - Class org.apache.derby.impl.store.raw.data.StoredFieldHeader

   Copyright 2002, 2004 The Apache Software Foundation or its licensors, as applicable.

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

 */
package org.apache.derby.impl.store.raw.data;

import org.apache.derby.iapi.store.raw.RecordHandle;
import org.apache.derby.iapi.services.sanity.SanityManager;

import java.io.IOException;
import java.io.EOFException;

import java.io.ObjectInput;
import java.io.OutputStream;

import org.apache.derby.iapi.services.io.ArrayInputStream;
import org.apache.derby.iapi.services.io.CompressedNumber;

import java.io.InputStream;

/**
    A class to provide static methods to manipulate fields in the field header.

	A class StoredPage uses to read/write field status and field data length.
	No attributes exist in this class, this class provides a set of static
	methods for writing field status and field data length, and for reading
	field status and field data length.

	<P><B>Stored Field Header Format</B><BR>
	The field header is broken into two sections.  
    Only the Status byte is required to be there.
	<PRE>
	Field header format:
	+--------+-------------------+
	| status | <fieldDataLength> |
	+--------+-------------------+
	Overflow page and overflow id are stored as field data.
	If the overflow bit in status is set, the field data is the overflow 
    information.  When the overflow bit is not set in status, then,
	fieldData is the actually user data for the field.
	That means, field header consists only field status, and field data length.

	A non-overflow field:
	+--------+-------------------+-------------+
	| status | <fieldDataLength> | <fieldData> |
	+--------+-------------------+-------------+

	An overflow field:
	+--------+-------------------+-----------------+--------------+
	| status | <fieldDataLength> | <overflow page> | <overflowID> |
	+--------+-------------------+-----------------+--------------+

	</PRE>
	<BR><B>status</B><BR>
	The status is 1 byte, it indicates the state of the field.

	A FieldHeader can be in the following states:
	NULL		- if the field is NULL, no field data length is stored
	OVERFLOW	- indicates the field has been overflowed to another page.
				  overflow page and overflow ID is stored at the end of the 
                  user data. field data length must be a number greater or 
                  equal to 0, indicating the length of the field that is stored
                  on the current page.

				  The format looks like this:
				  +--------+-----------------+---------------+------------+
				  |<status>|<fieldDataLength>|<overflow page>|<overflowID>|
				  +--------+-----------------+---------------+------------+

				  overflowPage will be written as compressed long,
				  overflowId will be written as compressed Int

	NONEXISTENT	- the field no longer exists, 
                  e.g. column has been dropped during an alter table

	EXTENSIBLE	- the field is of user defined data type.  
                  The field may be tagged.
                  
	TAGGED		- the field is TAGGED if and only if it is EXTENSIBLE.

	FIXED		- the field is FIXED if and only if it is used in the log 
                  records for version 1.2 and higher.

	<BR><B>fieldDataLength</B><BR>
	The fieldDataLength is only set if the field is not NULL.  It is the length
    of the field that is stored on the current page.
	The fieldDataLength is a variable length CompressedInt.
	<BR><B>overflowPage and overflowID</B><BR>
	The overflowPage is a variable length CompressedLong, overflowID is a 
    variable Length CompressedInt.
	They are only stored when the field state is OVERFLOW.
	And they are not stored in the field header.
	Instead, they are stored at the end of the field data.
	The reason we do that is to save a copy if the field has to overflow.

	<BR> MT - Mutable - Immutable identity - Thread Aware
*/
public final class StoredFieldHeader
{

    /**************************************************************************
     * Constants of the class
     **************************************************************************
     */

    // DO NOT use 0x80, some code reads byte into an int without masking the
    // sign bit, so do not use the high bit in the byte for a field status.
	private		static final int FIELD_INITIAL		= 0x00;
	public		static final int FIELD_NULL			= 0x01;
	public		static final int FIELD_OVERFLOW		= 0x02;
	private		static final int FIELD_NOT_NULLABLE	= 0x04;
	public		static final int FIELD_EXTENSIBLE	= 0x08;
	public		static final int FIELD_TAGGED		= 0x10;
	protected	static final int FIELD_FIXED		= 0x20;

	public		static final int FIELD_NONEXISTENT	= (FIELD_NOT_NULLABLE | FIELD_NULL);


    public static final int    STORED_FIELD_HEADER_STATUS_SIZE = 1;

    /**************************************************************************
     * Get accessors for testing bits in the status field.
     **************************************************************************
     */

	/**
		Get the status of the field

		<BR> MT - single thread required
	*/
	public static final boolean isNull(int status) {
		return ((status & FIELD_NULL) == FIELD_NULL);
	}

	public static final boolean isOverflow(int status) {
		return ((status & FIELD_OVERFLOW) == FIELD_OVERFLOW);
	}

	public static final boolean isNonexistent(int status) {
		return ((status & FIELD_NONEXISTENT) == FIELD_NONEXISTENT);
	}

	public static final boolean isExtensible(int status) {
		return ((status & FIELD_EXTENSIBLE) == FIELD_EXTENSIBLE);
	}

	public static final boolean isNullorNonExistent(int status) {
        // just need to check whether null bit is set.
        // return ((status & FIELD_NONEXISTENT) == FIELD_NONEXISTENT);
		return ((status & FIELD_NULL) != 0);
	}

	public static final boolean isTagged(int status) {
		//		if (SanityManager.DEBUG)
		//			SanityManager.ASSERT(isExtensible(status), "a field cannot be tagged if it is not extensible");
		return ((status & FIELD_TAGGED) == FIELD_TAGGED);
	}

	public static final boolean isFixed(int status) {
		return ((status & FIELD_FIXED) == FIELD_FIXED);
	}

	public static final boolean isNullable(int status) {
		return ((status & FIELD_NOT_NULLABLE) == 0);
	}

	public static final int size(
    int status, 
    int fieldDataLength, 
    int fieldDataSize) 
    {

        if ((status & (FIELD_NULL | FIELD_FIXED)) == 0)
        {
            // usual case - not-null, not-fixed

            // WARNING - the following code hand inlined from 
            // CompressedNumber for performance.
            //
            // return(CompressedNumber.sizeInt(fieldDataLength) + 1);
            //

            if (fieldDataLength <= 
                        CompressedNumber.MAX_COMPRESSED_INT_ONE_BYTE)
            {
                // compressed form is 1 byte
                return(2);
            }
            else if (fieldDataLength <= 
                        CompressedNumber.MAX_COMPRESSED_INT_TWO_BYTES)
            {
                // compressed form is 2 bytes
                return(3);
            }
            else
            {
                // compressed form is 4 bytes
                return(5);
            }
        }
        else if ((status & FIELD_NULL) != 0)
        {
            // field is null

			return(1);
		} 
        else
        {
            // fixed length field

            return((fieldDataSize > 2) ? 5 : 3);
		}
	}


    /**************************************************************************
     * Set accessors for setting bits in the status field.
     **************************************************************************
     */

	public final static int setInitial() {
		return FIELD_INITIAL;
	}

	public final static int setNull(int status, boolean isNull) {
		if (isNull)
			status |= FIELD_NULL;
		else
			status &= ~FIELD_NULL;
		return status;
	}

	public final static int setOverflow(int status, boolean isOverflow) {
		if (isOverflow)
			status |= FIELD_OVERFLOW;
		else
			status &= ~FIELD_OVERFLOW;
		return status;
	}

	public final static int setNonexistent(int status) {
		status |= FIELD_NONEXISTENT;
		return status;
	}

	public final static int setExtensible(int status, boolean isExtensible) {
		if (isExtensible)
			status |= FIELD_EXTENSIBLE;
		else
			status &= ~FIELD_EXTENSIBLE;
		return status;
	}

	public final static int setTagged(int status, boolean isTagged) {

		if (SanityManager.DEBUG)
			SanityManager.ASSERT(isExtensible(status),
				"a field cannot be set to tagged if it is not extensible");

		if (isTagged)
			status |= FIELD_TAGGED;
		else
			status &= ~FIELD_TAGGED;
		return status;
	}

	public final static int setFixed(int status, boolean isFixed) {
		if (isFixed)
			status |= FIELD_FIXED;
		else
			status &= ~FIELD_FIXED;
		return status;
	}

    /**************************************************************************
     * routines used to write a field header to a OutputStream
     **************************************************************************
     */

	/**
		write out the field status and field data Length

		@exception IOException Thrown by potential I/O errors while writing 
                               field header.
	 */
	public static final int write(
    OutputStream out, 
    int status, 
    int fieldDataLength, 
    int fieldDataSize)
		throws IOException 
    {
		int len = 1;

		out.write(status);

		if (isNull(status))
			return len;

		if (isFixed(status)) 
        {
			// if the field header is for log, we write it in compressed format,
			// then we pad the field, so the total length is fixed.			
  			if (fieldDataSize > 2) 
            {
				int diffLen = 
                    fieldDataSize - 
                    CompressedNumber.writeInt(out, fieldDataLength);

				for (int i = diffLen; i > 0; i--)
					out.write(0);
				len += fieldDataSize;	// size of an int - 4 bytes
			} 
            else 
            {
				// write the int out as a short
				out.write((fieldDataLength >>> 8) & 0xFF);
				out.write((fieldDataLength >>> 0) & 0xFF);
				len += 2;	// size of a short - 2 bytes
			}

			// NOTE: fixed version is used for logs only,
			// the overflow information is stored at the end of the optional 
            // data, not in the field headers.  
            // That's why we are not writing overflow info here.

		} 
        else 
        {
			// if we are writing the fieldHeader for the page, 
            // we write in compressed format

			len += CompressedNumber.writeInt(out, fieldDataLength);
		}

		return len;
	}

    /**************************************************************************
     * routines used to read a field header from an ObjectInput stream, array
     **************************************************************************
     */