rowutil.java

derby database source code.good for you.

/*

   Derby - Class org.apache.derby.iapi.store.access.RowUtil

   Copyright 1998, 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.iapi.store.access;

import org.apache.derby.iapi.services.monitor.Monitor;

import org.apache.derby.iapi.services.sanity.SanityManager;

import org.apache.derby.iapi.error.StandardException; 
import org.apache.derby.iapi.services.io.Storable;
import org.apache.derby.iapi.types.DataValueDescriptor;
import org.apache.derby.iapi.services.io.FormatableBitSet;
import org.apache.derby.iapi.services.loader.InstanceGetter;

import org.apache.derby.iapi.store.raw.FetchDescriptor;

import java.lang.reflect.InvocationTargetException;

import java.util.Enumeration;
import java.util.Hashtable;
import java.util.Vector;

/**
  A set of static utility methods to work with rows.
  <P>
  A row or partial row is described by two or three parameters.
  <OL>
  <LI>DataValueDescriptor[] row - an array of objects, one per column.
  <LI>FormatableBitSet validColumns - 
      an indication of which objects in row map to which columns
  </OL>
  These objects can describe a complete row or a partial row. A partial row is 
  one where a sub-set (e.g. columns 0, 4 and 7) of the columns are supplied 
  for update, or requested to be fetched on a read.  Here's an example
  of code to set up a partial column list to fetch the 0th (type FOO), 
  4th (type BAR), and 7th (type MMM) columns from a row with 10 columns, note
  that the format for a partial row changed from a "packed" representation
  in the 3.0 release to a "sparse" representation in later releases:

  <blockquote><pre>

  // allocate/initialize the row 
  DataValueDescriptor row = new DataValueDescriptor[10]
  row[0] = new FOO();
  row[4] = new BAR();
  row[7] = new MMM();
  
  // allocate/initialize the bit set 
  FormatableBitSet FormatableBitSet = new FormatableBitSet(10);
  
  FormatableBitSet.set(0);
  FormatableBitSet.set(4);
  FormatableBitSet.set(7);
  </blockquote></pre>


  <BR><B>Column mapping<B><BR>
  When validColumns is null:
  <UL>
  <LI> The number of columns is given by row.length
  <LI> Column N maps to row[N], where column numbers start at zero.
  </UL>
  <BR>
  When validColumns is not null, then
  <UL>
  <LI> The number of requested columns is given by the number of bits set in 
       validColumns.
  <LI> Column N is not in the partial row if validColumns.isSet(N) 
       returns false.
  <LI> Column N is in the partial row if validColumns.isSet(N) returns true.
  <LI> If column N is in the partial row then it maps to row[N].
	   If N >= row.length then the column is taken as non existent for an
	   insert or update, and not fetched on a fetch.
  </UL>
  If row.length is greater than the number of columns indicated by validColumns
  the extra entries are ignored.

**/
public class RowUtil
{
	private RowUtil() {}

	/**
		An object that can be used on a fetch to indicate no fields
		need to be fetched.
	*/
	public static final DataValueDescriptor[] EMPTY_ROW = 
        new DataValueDescriptor[0];

	/**
		An object that can be used on a fetch as a FormatableBitSet to indicate no fields
		need to be fetched.
	*/
	public static final FormatableBitSet EMPTY_ROW_BITSET  = 
        new FormatableBitSet(0);

	/**
		An object that can be used on a fetch as a FormatableBitSet to indicate no fields
		need to be fetched.
	*/
	public static final FetchDescriptor EMPTY_ROW_FETCH_DESCRIPTOR  = 
        new FetchDescriptor(0);

	public static final FetchDescriptor[] ROWUTIL_FETCH_DESCRIPTOR_CONSTANTS  =
        {EMPTY_ROW_FETCH_DESCRIPTOR,
         new FetchDescriptor(1, 1),
         new FetchDescriptor(2, 2),
         new FetchDescriptor(3, 3),
         new FetchDescriptor(4, 4),
         new FetchDescriptor(5, 5),
         new FetchDescriptor(6, 6),
         new FetchDescriptor(7, 7)};


	/**
		Get the object for a column identifer (0 based) from a complete or 
        partial row.

		@param row the row
		@param columnList valid columns in the row
		@param columnId which column to return (0 based)

		@return the obejct for the column, or null if the column is not represented.
	*/
	public static DataValueDescriptor getColumn(
    DataValueDescriptor[]   row, 
    FormatableBitSet                 columnList, 
    int                     columnId) 
    {

		if (columnList == null)
			return columnId < row.length ? row[columnId] : null;


		if (!(columnList.getLength() > columnId && columnList.isSet(columnId)))
			return null;

        return columnId < row.length ? row[columnId] : null;

	}

	public static Object getColumn(
    Object[]   row, 
    FormatableBitSet                 columnList, 
    int                     columnId) 
    {

		if (columnList == null)
			return columnId < row.length ? row[columnId] : null;


		if (!(columnList.getLength() > columnId && columnList.isSet(columnId)))
			return null;

        return columnId < row.length ? row[columnId] : null;

	}

	/**
		Get a FormatableBitSet representing all the columns represented in
		a qualifier list.

		@return a FormatableBitSet describing the valid columns.
	*/
	public static FormatableBitSet getQualifierBitSet(Qualifier[][] qualifiers) 
    {
		FormatableBitSet qualifierColumnList = new FormatableBitSet();

		if (qualifiers != null) 
        {
			for (int i = 0; i < qualifiers.length; i++)
			{
                for (int j = 0; j < qualifiers[i].length; j++)
                {
                    int colId = qualifiers[i][j].getColumnId();

                    // we are about to set bit colId, need length to be colId+1
                    qualifierColumnList.grow(colId+1);
                    qualifierColumnList.set(colId);
                }
			}
		}

		return qualifierColumnList;
	}

    /**
     * Get the number of columns represented by a FormatableBitSet.
     * <p>
     * This is simply a count of the number of bits set in the FormatableBitSet.
     * <p>
     *
     * @param maxColumnNumber Because the FormatableBitSet.size() can't be used as
     *                        the number of columns, allow caller to tell
     *                        the maximum column number if it knows.  
     *                        -1  means caller does not know.
     *                        >=0 number is the largest column number.
     *                           
     * @param columnList valid columns in the row
     *
	 * @return The number of columns represented in the FormatableBitSet.
     **/
    public static int getNumberOfColumns(
    int     maxColumnNumber,
    FormatableBitSet  columnList)
    {
        if (SanityManager.DEBUG)
            SanityManager.ASSERT(columnList != null);

        int max_col_number = columnList.getLength();

		if (maxColumnNumber > 0 && maxColumnNumber < max_col_number)
			max_col_number = maxColumnNumber;

        int ret_num_cols = 0;

        for (int i = 0; i < max_col_number; i++)
        {
            if (columnList.isSet(i))
                ret_num_cols++;
        }

        return(ret_num_cols);
    }

	/**
		See if a row actually contains no columns.
		Returns true if row is null, row.length is null,
		or columnList is not null but has not bits set.

		@return true if no columns are selected in this row.
	*/
	public static boolean isRowEmpty(
    DataValueDescriptor[]   row, 
    FormatableBitSet                 columnList) 
    {

		if (row == null)
			return true;

		if (row.length == 0)
			return true;

		if (columnList == null)
			return false;

		int size = columnList.getLength();
		for (int i = 0; i < size; i--) {
			if (columnList.isSet(i))
				return true;
		}
		return false;
	}

	/**
		Return the column number of the first column out of range, or a number
        less than zero if all columns are in range.
	*/
	public static int columnOutOfRange(
    DataValueDescriptor[]   row, 
    FormatableBitSet                 columnList, 
    int                     maxColumns) 
    {

		if (columnList == null) {
			if (row.length > maxColumns)
				return maxColumns;

			return -1;
		}

		int size = columnList.getLength();
		for (int i = maxColumns; i < size; i++) {
			if (columnList.isSet(i))
				return i;
		}

		return -1;
	}

	/**
		Get the next valid column after or including start column.
		Returns -1 if no valid columns exist after startColumn
	*/
	public static int nextColumn(
    Object[]   row, 
    FormatableBitSet                 columnList, 
    int                     startColumn) 
    {

		if (columnList != null) {

			int size = columnList.getLength();

			for (; startColumn < size; startColumn++) {
				if (columnList.isSet(startColumn)) {
					return startColumn;
				}
			}

			return -1;
		}

		if (row == null)
			return -1;

		return startColumn < row.length ? startColumn : -1;
	}

    /**
     * Return a FetchDescriptor which describes a single column set.
     * <p>
     * This routine returns one of a set of constant FetchDescriptor's, and
     * should not be altered by the caller.
     **/
    public static final FetchDescriptor getFetchDescriptorConstant(
    int     single_column_number)
    {
        if (single_column_number < ROWUTIL_FETCH_DESCRIPTOR_CONSTANTS.length)
        {
            return(ROWUTIL_FETCH_DESCRIPTOR_CONSTANTS[single_column_number]);
        }
        else
        {
            return(
                new FetchDescriptor(
                    single_column_number, single_column_number));
        }
    }

    /**************************************************************************
     * Public Methods dealing with cloning and row copying util functions
     **************************************************************************
     */

    /**
     * Generate a row of InstanceGetter objects to be used to generate  "empty" rows.
     * <p>
     * Generate an array of InstanceGetter objects which will be used to make
     * repeated calls to newRowFromClassInfoTemplate(), to repeatedly and
     * efficiently generate new rows.  This is important for certain 
     * applications like the sorter and fetchSet which generate large numbers
     * of "new" empty rows.