RowUtil


/*

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

   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to you 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.error.StandardException; 
import org.apache.derby.iapi.services.io.FormatableBitSet;
import org.apache.derby.iapi.services.io.Storable;
import org.apache.derby.shared.common.sanity.SanityManager;

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

import org.apache.derby.iapi.types.DataValueDescriptor;
import org.apache.derby.iapi.types.DataValueFactory;

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

/**
  A set of static utility methods to work with rows.
  
  A row or partial row is described by two or three parameters.
  

  DataValueDescriptor[] row - an array of objects, one per column.
  
FormatableBitSet validColumns - 
      an indication of which objects in row map to which columns
  
  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:

  
  // 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);




  
Column mapping

  When validColumns is null:
  
   The number of columns is given by row.length
  
 Column N maps to row[N], where column numbers start at zero.
  
  

  When validColumns is not null, then
  
   The number of requested columns is given by the number of bits set in 
       validColumns.
  
 Column N is not in the partial row if validColumns.isSet(N) 
       returns false.
  
 Column N is in the partial row if validColumns.isSet(N) returns true.
  
 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.
  
  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);

	private 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.
     * 
     * This is simply a count of the number of bits set in the FormatableBitSet.
     * 

     *
     * @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 or row.length is zero.

		@return true if row is empty.
	*/
	public static boolean isRowEmpty(
    DataValueDescriptor[]   row) 
    {

		if (row == null)
			return true;

		if (row.length == 0)
			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.
     * 

     * 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 template row of DataValueDescriptor's
     * 

     * Generate an array of DataValueDescriptor objects which will be used to 
     * make 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.
     * 

     *
	 * @return The new row.
     *
     * @param column_list A bit set indicating which columns to include in row.
     * @param format_ids  an array of format id's, one per column in row.
     *
	 * @exception  StandardException  Standard exception policy.
     **/
    public static DataValueDescriptor[] newTemplate(
    DataValueFactory    dvf,
    FormatableBitSet    column_list,
    int[]               format_ids,
    int[]               collation_ids) 
        throws StandardException
    {
        int                   num_cols = format_ids.length;
        DataValueDescriptor[] ret_row  = new DataValueDescriptor[num_cols];

		int column_listSize = 
            (column_list == null) ? 0 : column_list.getLength();

        for (int i = 0; i < num_cols; i++)
        {
            // does caller want this column?
            if ((column_list != null)   && 
                !((column_listSize > i) && 
                (column_list.isSet(i))))
            {
                // no - column should be skipped.
            }
            else
            {
                // yes - create the column 

                // get empty instance of object identified by the format id.

                ret_row[i] = dvf.getNull(format_ids[i], collation_ids[i]);
            }
        }

        return(ret_row);
    }

    /**
     * Generate an "empty" row from an array of DataValueDescriptor objects.
     * 

     * Generate an array of new'd objects by using the getNewNull()
     * method on each of the DataValueDescriptor objects.  
     * 

     *
	 * @return The new row.
     *
     * @param  template            An array of DataValueDescriptor objects 
     *                             each of which can be used to create a new 
     *                             instance of the appropriate type to build a 
     *                             new empty template row.
     *
	 * @exception  StandardException  Standard exception policy.
     **/
    public static DataValueDescriptor[] newRowFromTemplate(
    DataValueDescriptor[]    template) 
        throws StandardException
    {

        DataValueDescriptor[] columns = 
            new DataValueDescriptor[template.length];

        
        for (int column_index = template.length; column_index-- > 0;)
        {
            if (template[column_index] != null)
            {
                // get empty instance of DataValueDescriptor identified by 
                // the format id.
                columns[column_index] = template[column_index].getNewNull();
            }
        }

		return columns;
    }


    /**
     * return string version of row.
     * 

     * For debugging only. 
     *
	 * @return The string version of row.
     *
     * @param row The row.
     *
     **/
    public static String toString(Object[] row)
    {
        if (SanityManager.DEBUG)
        {

            String str = "";

            if (row != null)
            {
                if (row.length == 0)
                {
                    str = "empty row";
                }
                else
                {
                    for (int i = 0; i < row.length; i++)
                        str += "col[" + i + "]=" + row[i];
                }
            }
            else
            {
                str = "row is null";
            }

            return(str);
        }
        else
        {
            return(null);
        }
    }

    /**
     * return string version of a HashTable returned from a FetchSet.
     * 

     *
	 * @return The string version of row.
     *
     *
     **/

    // For debugging only. 
    public static String toString(Hashtable hash_table)
    {
        if (SanityManager.DEBUG)
        {
            String str = "";

            Object  row_or_vector;

            for (Enumeration e = hash_table.elements(); e.hasMoreElements();)
            {
                row_or_vector = e.nextElement();

                if (row_or_vector instanceof Object[])
                {
                    // it's a row
                    str += RowUtil.toString((Object[]) row_or_vector);
                    str += "\n";
                }
                else if (row_or_vector instanceof Vector)
                {
                    // it's a vector
                    Vector vec = (Vector) row_or_vector;

                    for (int i = 0; i < vec.size(); i++)
                    {
                        str += 
                            "vec[" + i + "]:" + 
                            RowUtil.toString((Object[]) vec.get(i));

                        str += "\n";
                    }
                }
                else
                {
                    str += "BAD ENTRY\n";
                }
            }
            return(str);
        }
        else
        {
            return(null);
        }
    }

    /**
     * Process the qualifier list on the row, return true if it qualifies.
     *

* A two dimensional array is to be used to pass around a AND's and OR's in * conjunctive normal form. The top slot of the 2 dimensional array is * optimized for the more frequent where no OR's are present. The first * array slot is always a list of AND's to be treated as described above * for single dimensional AND qualifier arrays. The subsequent slots are * to be treated as AND'd arrays or OR's. Thus the 2 dimensional array * qual[][] argument is to be treated as the following, note if * qual.length = 1 then only the first array is valid and it is and an * array of and clauses: * * (qual[0][0] and qual[0][0] ... and qual[0][qual[0].length - 1]) * and * (qual[1][0] or qual[1][1] ... or qual[1][qual[1].length - 1]) * and * (qual[2][0] or qual[2][1] ... or qual[2][qual[2].length - 1]) * ... * and * (qual[qual.length - 1][0] or qual[1][1] ... or qual[1][2]) * * * @return true if the row qualifies. * * @param row The row being qualified. * @param qual_list 2 dimensional array representing conjunctive * normal form of simple qualifiers. * * @exception StandardException Standard exception policy. **/ public static final boolean qualifyRow( DataValueDescriptor[] row, Qualifier[][] qual_list) throws StandardException { boolean row_qualifies = true; if (SanityManager.DEBUG) { SanityManager.ASSERT(row != null); } // First do the qual[0] which is an array of qualifer terms. if (SanityManager.DEBUG) { // routine should not be called if there is no qualifier SanityManager.ASSERT(qual_list != null); SanityManager.ASSERT(qual_list.length > 0); } for (int i = 0; i < qual_list[0].length; i++) { // process each AND clause row_qualifies = false; // process each OR clause. Qualifier q = qual_list[0][i]; // Get the column from the possibly partial row, of the // q.getColumnId()'th column in the full row. DataValueDescriptor columnValue = row[q.getColumnId()]; row_qualifies = columnValue.compare( q.getOperator(), q.getOrderable(), q.getOrderedNulls(), q.getUnknownRV()); if (q.negateCompareResult()) row_qualifies = !row_qualifies; // Once an AND fails the whole Qualification fails - do a return! if (!row_qualifies) return(false); } // all the qual[0] and terms passed, now process the OR clauses for (int and_idx = 1; and_idx < qual_list.length; and_idx++) { // loop through each of the "and" clause. row_qualifies = false; if (SanityManager.DEBUG) { // Each OR clause must be non-empty. SanityManager.ASSERT(qual_list[and_idx].length > 0); } for (int or_idx = 0; or_idx < qual_list[and_idx].length; or_idx++) { // Apply one qualifier to the row. Qualifier q = qual_list[and_idx][or_idx]; int col_id = q.getColumnId(); if (SanityManager.DEBUG) { SanityManager.ASSERT( (col_id < row.length), "Qualifier is referencing a column not in the row."); } // Get the column from the possibly partial row, of the // q.getColumnId()'th column in the full row. DataValueDescriptor columnValue = row[q.getColumnId()]; if (SanityManager.DEBUG) { if (columnValue == null) SanityManager.THROWASSERT( "1:row = " + RowUtil.toString(row) + "row.length = " + row.length + ";q.getColumnId() = " + q.getColumnId()); } // do the compare between the column value and value in the // qualifier. row_qualifies = columnValue.compare( q.getOperator(), q.getOrderable(), q.getOrderedNulls(), q.getUnknownRV()); if (q.negateCompareResult()) row_qualifies = !row_qualifies; // SanityManager.DEBUG_PRINT("StoredPage.qual", "processing qual[" + and_idx + "][" + or_idx + "] = " + qual_list[and_idx][or_idx] ); // SanityManager.DEBUG_PRINT("StoredPage.qual", "value = " + row_qualifies); // processing "OR" clauses, so as soon as one is true, break // to go and process next AND clause. if (row_qualifies) break; } // The qualifier list represented a set of "AND'd" // qualifications so as soon as one is false processing is done. if (!row_qualifies) break; } return(row_qualifies); } }

Ads help maintain this website.

© 2013-2026 Powered by Doc2SQL Page generated in 0.0033540725708008 seconds and 445 kB