com.goldencode.p2j.persist

Class FQLBundle

java.lang.Object

com.goldencode.p2j.persist.FQLBundle

public final class FQLBundle
extends java.lang.Object

An assemblage of the various FQL statements, corresponding, reflective methods, and an index of the runtime query substitution parameters, which are necessary to satisfy a specific record retrieval request for a random access query.

Each bundle contains a list of one or more FQL statements which are executed in sequence by a RandomAccessQuery instance to obtain a result for a specific record retrieval (e.g., first, last, next, etc.) request. These statements include as their restriction criteria (i.e., where clause), the query's original, base where clause (if any), augmented with sequentially less-specific restriction criteria composed using the query's sort criteria. If any parameterized substitutions are necessary to supply these statements with data extracted from the current record, the appropriate list of "getter" methods is supplied by the bundle as well.

To satisfy the random access query's single-record retrieval semantic, each statement is executed in turn, until a non-null result is returned. For each statement, as many of the getter methods are executed against the current record DMO, as are necessary to provided the substitutions required for that statement (for the augmented portion only). These values are added to the existing parameter array (if any) for the base where clause, at the time the statement is executed.

For example, given the following query criteria and a request to retrieve the "next" record...

    DMO:        Customer
    alias:      customer
    where:      customer.number = ? and customer.creditLimit = ?
    order by:   customer.name asc
 

...the FQL bundle might contain the following list of FQL statements...

 1) from Customer as customer
    where (customer.number = ? and customer.creditLimit = ?)
      and (customer.name = ? and customer.recid > ?)

 2) from Customer as customer
    where (customer.number = ? and customer.creditLimit = ?)
      and (customer.name > ?)
 

...and the following list of DMO "getter" methods...

 1) Customer.getName()
 2) Customer.primaryKey()
 

The methods are only used to satisfy the customer.name and customer.id substitutions; the customer.number and customer.creditLimit parameter substitution values must be provided by the client code which creates the query.

A bundle is unaware of the navigation/retrieval mode with which it has been tasked (e.g., first, last, next, etc.); it is simply a container for the information described above.

See Also:

FQLHelper

Field Summary

Fields

Modifier and Type	Field and Description
private java.util.List<java.lang.String>	dirtyStatements Parallel set of FQL statements for dirty database use
private java.util.List<java.lang.reflect.Method>	getters DMO getter methods used to get sort criteria parameter values
private ParameterIndices	paramIndices Mapping of indices in the array of query substitution parameters
private java.util.List<java.lang.String>	statements FQL statements to be executed to satisfy a record retrieval request

Constructor Summary

Constructors

Constructor and Description
FQLBundle() Default constructor.

Method Summary

Modifier and Type	Method and Description
(package private) void	addGetter(java.lang.reflect.Method getter) Add a DMO getter method to the end of the list of methods stored in this bundle.
(package private) void	addStatement(java.lang.String statement, boolean dirty) Add an FQL statement to the end of the list of primary or dirty statements stored in this bundle.
(package private) void	freeze() Freeze this bundle so that its internal data structures can no longer be modified.
java.util.List<java.lang.String>	getDirtyStatements() Get an unmodifiable view on the list of FQL statements in this bundle, which are for dirty database use.
(package private) ParameterIndices	getParameterIndices() Get the ParameterIndices object associated with this bundle.
(package private) java.lang.String	getStatement(int index, boolean dirty) Retrieve the FQL statement at a particular index in the list.
(package private) java.util.Iterator<java.lang.reflect.Method>	getters() Get an iterator on the DMO getter methods, if any, stored in this bundle.
(package private) int	gettersSize() Return the number of DMO getter methods stored in this bundle.
(package private) void	setParameterIndices(ParameterIndices paramIndices) Set the ParameterIndices object associated with this bundle.
(package private) void	setStatement(int index, java.lang.String statement, boolean dirty) Replace the FQL statement at the specified index with a new statement.
(package private) java.util.Iterator<java.lang.String>	statements() Get an iterator on the list of FQL statements in this bundle.
(package private) int	statementsSize() Get the number of FQL statements stored in this bundle.
java.lang.String	toString() Get a string representation of the internal state of this object, primarily for debugging purposes.

Methods inherited from class java.lang.Object

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

Field Detail

getters

private java.util.List<java.lang.reflect.Method> getters

DMO getter methods used to get sort criteria parameter values

statements

private java.util.List<java.lang.String> statements

FQL statements to be executed to satisfy a record retrieval request

dirtyStatements

private java.util.List<java.lang.String> dirtyStatements

Parallel set of FQL statements for dirty database use

paramIndices

private ParameterIndices paramIndices

Mapping of indices in the array of query substitution parameters

Constructor Detail

FQLBundle

FQLBundle()

Default constructor.

Method Detail

getDirtyStatements

public java.util.List<java.lang.String> getDirtyStatements()

Get an unmodifiable view on the list of FQL statements in this bundle, which are for dirty database use. If no dirty statements have been stored in this bundle, the list of primary database FQL statements is returned.

Returns:

Unmodifiable list of FQL statements using dirty database's dialect.

toString

public java.lang.String toString()

Get a string representation of the internal state of this object, primarily for debugging purposes.

Overrides:

toString in class java.lang.Object

Returns:

String representing this object's state.

statements

java.util.Iterator<java.lang.String> statements()

Get an iterator on the list of FQL statements in this bundle.

Returns:

Iterator of FQL statements.

statementsSize

int statementsSize()

Get the number of FQL statements stored in this bundle.

Returns:

Statement list size.

getStatement

java.lang.String getStatement(int index,
                              boolean dirty)

Retrieve the FQL statement at a particular index in the list.

Parameters:

index - Index of the required statement.

dirty - true to retrieve statement for dirty database dialect; false to get primary statement.

Returns:

FQL statement at the specified index.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if index is invalid.

setStatement

void setStatement(int index,
                  java.lang.String statement,
                  boolean dirty)

Replace the FQL statement at the specified index with a new statement.

Parameters:

index - Index at which to replace statement.

statement - New FQL statement.

dirty - true to set statement for dirty database dialect; false to set primary statement.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if index is invalid.

addStatement

void addStatement(java.lang.String statement,
                  boolean dirty)

Add an FQL statement to the end of the list of primary or dirty statements stored in this bundle.

Parameters:

statement - FQL statement to add.

dirty - true to add statement for dirty database dialect; false to add primary statement.

gettersSize

int gettersSize()

Return the number of DMO getter methods stored in this bundle.

Returns:

A nonnegative number.

getters

java.util.Iterator<java.lang.reflect.Method> getters()

Get an iterator on the DMO getter methods, if any, stored in this bundle.

Returns:

Iterator of getter method objects.

addGetter

void addGetter(java.lang.reflect.Method getter)

Add a DMO getter method to the end of the list of methods stored in this bundle.

Parameters:

getter - Accessor method.

getParameterIndices

ParameterIndices getParameterIndices()

Get the ParameterIndices object associated with this bundle. This object maintains an array of zero-based indices into the array of query substitution arguments for the base (i.e., unaugmented) where clause, as it exists after preprocessing is complete. This additional level of indirection is necessary because the query substitution placeholders may have been reordered within the FQL where clause expression during the FQL preprocessing rewrite step, and some parameters may have been inlined into the where clause.

Returns:

An object which provides a mapping of indices into the query substitution parameter list.

setParameterIndices

void setParameterIndices(ParameterIndices paramIndices)

Set the ParameterIndices object associated with this bundle. This object maintains an array of zero-based indices into the array of query substitution arguments for the base (i.e., unaugmented) where clause, as it exists after preprocessing is complete. This additional level of indirection is necessary because the query substitution placeholders may have been reordered within the FQL where clause expression during the FQL preprocessing rewrite step, and some parameters may have been inlined into the where clause.

Parameters:

paramIndices - An object which provides a mapping of indices into the query substitution parameter list.

freeze

void freeze()

Freeze this bundle so that its internal data structures can no longer be modified.