Apache Derby Database Engine and Embedded JDBC Driver 10.17.1.0 · org.apache.derby.iapi.store.access.RowUtil

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.

Field Summary

Modifier and Type	Field and Description
public static final DataValueDescriptor[]	EMPTY_ROW An object that can be used on a fetch to indicate no fields need to be fetched.
public static final FormatableBitSet	EMPTY_ROW_BITSET 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 An object that can be used on a fetch as a FormatableBitSet to indicate no fields need to be fetched.
private static final FetchDescriptor[]	ROWUTIL_FETCH_DESCRIPTOR_CONSTANTS

Access	Constructor and Description
private	RowUtil()

Method Summary

Modifier and Type	Method and Description
public static int	columnOutOfRange(DataValueDescriptor[] row, FormatableBitSet columnList, int maxColumns) 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 DataValueDescriptor	Returns: the obejct for the column, or null if the column is not represented. getColumn(DataValueDescriptor[] the row row, FormatableBitSet valid columns in the row columnList, int which column to return (0 based) columnId) Get the object for a column identifer (0 based) from a complete or partial row.
public static Object	getColumn(Object[] row, FormatableBitSet columnList, int columnId)
public static final FetchDescriptor	getFetchDescriptorConstant(int single_column_number) Return a FetchDescriptor which describes a single column set.
public static int	Returns: The number of columns represented in the FormatableBitSet. getNumberOfColumns(int 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. maxColumnNumber, FormatableBitSet valid columns in the row columnList) Get the number of columns represented by a FormatableBitSet.
public static FormatableBitSet	Returns: a FormatableBitSet describing the valid columns. getQualifierBitSet(Qualifier[][] qualifiers) Get a FormatableBitSet representing all the columns represented in a qualifier list.
public static boolean	Returns: true if row is empty. isRowEmpty(DataValueDescriptor[] row) See if a row actually contains no columns.
public static DataValueDescriptor[]	Returns: The new row. newRowFromTemplate(DataValueDescriptor[] 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. template) Generate an "empty" row from an array of DataValueDescriptor objects.
public static DataValueDescriptor[]	Returns: The new row. newTemplate(DataValueFactory dvf, FormatableBitSet A bit set indicating which columns to include in row. column_list, int[] an array of format id's, one per column in row. format_ids, int[] collation_ids) 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.
public static int	nextColumn(Object[] row, FormatableBitSet columnList, int startColumn) Get the next valid column after or including start column.
public static final boolean	Returns: true if the row qualifies. qualifyRow(DataValueDescriptor[] The row being qualified. row, Qualifier[][] 2 dimensional array representing conjunctive normal form of simple qualifiers. qual_list) Process the qualifier list on the row, return true if it qualifies.
public static String	Returns: The string version of row. toString(Object[] The row. row) return string version of row.
public static String	Returns: The string version of row. toString(Hashtable<K, V> hash_table) return string version of a HashTable returned from a FetchSet.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

EMPTY_ROW	back to summary
public static final DataValueDescriptor[] EMPTY_ROW An object that can be used on a fetch to indicate no fields need to be fetched.

EMPTY_ROW_BITSET	back to summary
public static final FormatableBitSet EMPTY_ROW_BITSET An object that can be used on a fetch as a FormatableBitSet to indicate no fields need to be fetched.

EMPTY_ROW_FETCH_DESCRIPTOR	back to summary
public static final FetchDescriptor EMPTY_ROW_FETCH_DESCRIPTOR An object that can be used on a fetch as a FormatableBitSet to indicate no fields need to be fetched.

ROWUTIL_FETCH_DESCRIPTOR_CONSTANTS	back to summary
private static final FetchDescriptor[] ROWUTIL_FETCH_DESCRIPTOR_CONSTANTS

Constructor Detail

RowUtil	back to summary
private RowUtil()

Method Detail

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

getColumn	back to summary
public static DataValueDescriptor getColumn(DataValueDescriptor[] row, FormatableBitSet columnList, int columnId) Get the object for a column identifer (0 based) from a complete or partial row. Parameters row:DataValueDescriptor[] the row columnList:FormatableBitSet valid columns in the row columnId:int which column to return (0 based) Returns:DataValueDescriptor the obejct for the column, or null if the column is not represented.

getColumn

back to summary

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

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

Parameters

row:DataValueDescriptor[]: the row
columnList:FormatableBitSet: valid columns in the row
columnId:int: which column to return (0 based)

Returns:DataValueDescriptor

the obejct for the column, or null if the column is not represented.

getColumn	back to summary
public static Object getColumn(Object[] row, FormatableBitSet columnList, int columnId)

getFetchDescriptorConstant	back to summary
public static final FetchDescriptor getFetchDescriptorConstant(int single_column_number) 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.

getFetchDescriptorConstant

back to summary

public static final FetchDescriptor getFetchDescriptorConstant(int single_column_number)

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.

getNumberOfColumns	back to summary
public static int getNumberOfColumns(int maxColumnNumber, FormatableBitSet columnList) Get the number of columns represented by a FormatableBitSet. This is simply a count of the number of bits set in the FormatableBitSet. Parameters maxColumnNumber:int 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. columnList:FormatableBitSet valid columns in the row Returns:int The number of columns represented in the FormatableBitSet.

getNumberOfColumns

back to summary

public static int getNumberOfColumns(int maxColumnNumber, FormatableBitSet columnList)

Get the number of columns represented by a FormatableBitSet.

This is simply a count of the number of bits set in the FormatableBitSet.

Parameters

maxColumnNumber:int: 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.
columnList:FormatableBitSet: valid columns in the row

Returns:int

The number of columns represented in the FormatableBitSet.

getQualifierBitSet	back to summary
public static FormatableBitSet getQualifierBitSet(Qualifier[][] qualifiers) Get a FormatableBitSet representing all the columns represented in a qualifier list. Returns:FormatableBitSet a FormatableBitSet describing the valid columns.

getQualifierBitSet

back to summary

public static FormatableBitSet getQualifierBitSet(Qualifier[][] qualifiers)

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

Returns:FormatableBitSet: a FormatableBitSet describing the valid columns.

isRowEmpty	back to summary
public static boolean isRowEmpty(DataValueDescriptor[] row) See if a row actually contains no columns. Returns true if row is null or row.length is zero. Returns:boolean true if row is empty.

isRowEmpty

back to summary

public static boolean isRowEmpty(DataValueDescriptor[] row)

See if a row actually contains no columns. Returns true if row is null or row.length is zero.

Returns:boolean: true if row is empty.

newRowFromTemplate	back to summary
public static DataValueDescriptor[] newRowFromTemplate(DataValueDescriptor[] template) throws StandardException 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. Parameters template:DataValueDescriptor[] 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. Returns:DataValueDescriptor[] The new row. Exceptions StandardException: Standard exception policy.

newRowFromTemplate

back to summary

public static DataValueDescriptor[] newRowFromTemplate(DataValueDescriptor[] template) throws StandardException

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.

Parameters

template:DataValueDescriptor[]: 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.

Returns:DataValueDescriptor[]

The new row.

Exceptions

StandardException:: Standard exception policy.

newTemplate	back to summary
public static DataValueDescriptor[] newTemplate(DataValueFactory dvf, FormatableBitSet column_list, int[] format_ids, int[] collation_ids) throws StandardException 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. Parameters column_list:FormatableBitSet A bit set indicating which columns to include in row. format_ids:int[] an array of format id's, one per column in row. Returns:DataValueDescriptor[] The new row. Exceptions StandardException: Standard exception policy.

newTemplate

back to summary

public static DataValueDescriptor[] newTemplate(DataValueFactory dvf, FormatableBitSet column_list, int[] format_ids, int[] collation_ids) throws StandardException

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.

Parameters

column_list:FormatableBitSet: A bit set indicating which columns to include in row.
format_ids:int[]: an array of format id's, one per column in row.

Returns:DataValueDescriptor[]

The new row.

Exceptions

StandardException:: Standard exception policy.

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

qualifyRow	back to summary
public static final boolean qualifyRow(DataValueDescriptor[] row, Qualifier[][] qual_list) throws StandardException 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]) Parameters row:DataValueDescriptor[] The row being qualified. qual_list:Qualifier[][] 2 dimensional array representing conjunctive normal form of simple qualifiers. Returns:boolean true if the row qualifies. Exceptions StandardException: Standard exception policy.

qualifyRow

back to summary

public static final boolean qualifyRow(DataValueDescriptor[] row, Qualifier[][] qual_list) throws StandardException

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])

Parameters

row:DataValueDescriptor[]: The row being qualified.
qual_list:Qualifier[][]: 2 dimensional array representing conjunctive normal form of simple qualifiers.

Returns:boolean

true if the row qualifies.

Exceptions

StandardException:: Standard exception policy.

toString	back to summary
public static String toString(Object[] row) return string version of row. For debugging only. Parameters row:Object[] The row. Returns:String The string version of row.

toString

back to summary

public static String toString(Object[] row)

return string version of row.

For debugging only.

Parameters

row:Object[]: The row.

Returns:String

The string version of row.

toString	back to summary
public static String toString(Hashtable<K, V> hash_table) return string version of a HashTable returned from a FetchSet. Returns:String The string version of row.

toString

back to summary

public static String toString(Hashtable<K, V> hash_table)

return string version of a HashTable returned from a FetchSet.

Returns:String: The string version of row.

public Class RowUtil

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail