com.triactive.jdo.store.sql.expr
Class QueryStatement

java.lang.Object
  com.triactive.jdo.store.sql.expr.QueryStatement

All Implemented Interfaces:

StatementTextGenerator

public class QueryStatement

extends java.lang.Object

implements StatementTextGenerator

An SQL SELECT statement that can be constructed programmatically.

This class allows the components parts of a SELECT statement (the columns to be selected, the expression making up the WHERE clause, etc.) to be successively built up. The toStatementText() method then produces the resulting statement text.

Once the text is generated the statement can no longer be modified. Primarily this prevents the statement from inadvertently modifying itself as its text is being produced.

QueryStatement objects should not be constructed directly. Instead, DatabaseAdapter.newQueryStatement(StoreManager,Table) should be called so that an appropriate adapter subclass can be substituted if necessary.

Author:

Mike Martin

Nested Class Summary

static class

QueryStatement.QueryColumn Represents a column in one of the table expressions in a query statement.

Field Summary

protected CorrelationName	defaultRangeVar The range variable for the default table expression, ie "THIS".
protected boolean	distinct true if results must be DISTINCT.
protected StatementText	groupByList The content of the GROUP BY clause, if any.
protected BooleanExpression	havingExpr The content of the HAVING clause, if any.
protected TableExpression	initialTableExpr The initial table expression, ie the first one in the FROM clause.
protected java.util.List	joins A list containing all the additional table expression joins to be added to the FROM clause, in the order in which they should be joined.
protected StatementText	orderByList The content of the ORDER BY clause, if any.
protected java.util.List	selected A list of StatementText objects representing the result expressions that have been selected.
protected StoreManager	storeMgr The associated store manager.
protected QueryStatement	superquery The surrounding statement if this is a subquery, otherwise null.
protected java.util.Map	tableExprsByRangeVar A map of CorrelationName to TableExpression containing all table expressions in the statement.
protected BooleanExpression	whereExpr The content of the WHERE clause, if any.

Constructor Summary

QueryStatement(StoreManager storeMgr, Table initialTable, CorrelationName initialRangeVar, QueryStatement superquery)
Constructs a new query statement.

Method Summary

void	andHavingCondition(BooleanExpression condition) ANDs the given condition into the HAVING clause for this statement.
void	andWhereCondition(BooleanExpression condition) ANDs the given condition into the WHERE clause for this statement.
protected void	assertNotFrozen() Asserts that the statement text has not yet been generated.
boolean	contains(QueryStatement qs) Tests whether the given statement is a subquery of this statement.
void	embedIn(QueryStatement superquery) Establishes the query statement to which this statement belongs.
QueryStatement.QueryColumn	getColumn(Column col) Returns a query column object for the specified column in the default table expression.
QueryStatement.QueryColumn	getColumn(CorrelationName rangeVar, Column col) Returns a query column object for the specified column in the specified table expression.
java.util.Set	getCorrelatedColumns() Returns a set containing all the correlated (ie superquery) columns referenced in this statement.
DatabaseAdapter	getDatabaseAdapter() Convenience method to return the associated store manager's database adapter.
TableExpression	getDefaultTableExpression() Returns the "default" table expression in the statement.
protected BooleanExpression	getJoinConditions() Returns the join conditions to be prefixed on the WHERE clause.
QueryStatement	getQueryStatement() Returns the query statement to which this statement belongs, if any.
StoreManager	getStoreManager() Returns the associated store manager.
TableExpression	getTableExpression(CorrelationName rangeVar) Returns the table expression associated with the range variable rangeVar.
java.util.Collection	getTableExpressions() Returns all the table expressions in the statement.
QueryStatement.QueryColumn[]	join(JoinType type, Table table, CorrelationName rangeVar, QueryStatement.QueryColumn[] from, Column[] to) Performs a join on the equality of two lists of columns.
QueryStatement.QueryColumn	join(JoinType type, Table table, CorrelationName rangeVar, QueryStatement.QueryColumn from, Column to) Performs a join on the equality of two columns.
protected Join	newJoin(JoinType type, TableExpression tableExpr, QueryStatement.QueryColumn[] from, Column[] to) Constructs a new Join object for this statement.
QueryStatement	newSubqueryStatement(Table table, CorrelationName rangeVar) Produces a new subquery of this query, such as might be used in an SQL EXISTS() function, etc.
int	numResultColumns() Returns the number of result columns SELECTed in this statement.
int	select(QueryStatement.QueryColumn qsc) SELECTs the given query column.
int	select(SqlExpression expr) SELECTs the given SQL expression as a result column.
void	setDistinct(boolean distinct) Sets the distinct mode flag, indicating whether or not results must be DISTINCT (unique).
void	setGrouping(java.util.List groupExprs) Establishes the GROUP BY clause for this statement.
void	setOrdering(java.util.List orderingSpecs) Establishes the ORDER BY clause for this statement.
StatementText	toStatementText() Generates and returns the statement text for this query statement.
java.lang.String	toString() Returns the text of this statement.

Methods inherited from class java.lang.Object

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

Field Detail

storeMgr

protected final StoreManager storeMgr

The associated store manager.

defaultRangeVar

protected final CorrelationName defaultRangeVar

The range variable for the default table expression, ie "THIS".

initialTableExpr

protected final TableExpression initialTableExpr

The initial table expression, ie the first one in the FROM clause.

superquery

protected QueryStatement superquery

The surrounding statement if this is a subquery, otherwise null.

tableExprsByRangeVar

protected java.util.Map tableExprsByRangeVar

A map of CorrelationName to TableExpression containing all table expressions in the statement.

distinct

protected boolean distinct

true if results must be DISTINCT.

selected

protected java.util.List selected

A list of StatementText objects representing the result expressions that have been selected.

joins

protected java.util.List joins

A list containing all the additional table expression joins to be added to the FROM clause, in the order in which they should be joined. Each Join * object's toString() value will be added.

whereExpr

protected BooleanExpression whereExpr

The content of the WHERE clause, if any.

groupByList

protected StatementText groupByList

The content of the GROUP BY clause, if any.

havingExpr

protected BooleanExpression havingExpr

The content of the HAVING clause, if any.

orderByList

protected StatementText orderByList

The content of the ORDER BY clause, if any.

Constructor Detail

QueryStatement

public QueryStatement(StoreManager storeMgr,
                      Table initialTable,
                      CorrelationName initialRangeVar,
                      QueryStatement superquery)

Constructs a new query statement. Should be called only by a DatabaseAdapter object.

Parameters:

storeMgr - The store manager

initialTable - The initial table from which the query will select.

initialRangeVar - The range variable to use for the initial table. If null the SQL identifier THIS will be used.

superquery - If this is a subquery, the surrounding query; otherwise null

Method Detail

assertNotFrozen

protected void assertNotFrozen()

Asserts that the statement text has not yet been generated.

Throws:

java.lang.IllegalStateException - If the statement text has already been generated.

getStoreManager

public StoreManager getStoreManager()

Returns the associated store manager.

getDatabaseAdapter

public DatabaseAdapter getDatabaseAdapter()

Convenience method to return the associated store manager's database adapter.

getQueryStatement

public QueryStatement getQueryStatement()

Returns the query statement to which this statement belongs, if any. Returns null if this is not a subquery.

embedIn

public void embedIn(QueryStatement superquery)

Establishes the query statement to which this statement belongs. It cannot be set to null, nor can it be changed once it is set.

Parameters:

superquery - the query statement to which this statement belongs

newSubqueryStatement

public QueryStatement newSubqueryStatement(Table table,
                                           CorrelationName rangeVar)

Produces a new subquery of this query, such as might be used in an SQL EXISTS() function, etc.

Parameters:

table - The initial table from which the query will select.

rangeVar - The range variable to use for the initial table. If null the SQL identifier THIS will be used.

contains

public boolean contains(QueryStatement qs)

Tests whether the given statement is a subquery of this statement.

Returns:

true if the given statement is a subquery of this statement, or is this statement itself; false otherwise.

getCorrelatedColumns

public java.util.Set getCorrelatedColumns()

Returns a set containing all the correlated (ie superquery) columns referenced in this statement. For the present this includes only those correlated columns listed in the WHERE or HAVING clause, although that might suffice for all cases.

Returns:

A set of QueryStatement.QueryColumn objects.

getDefaultTableExpression

public TableExpression getDefaultTableExpression()

Returns the "default" table expression in the statement. The default expression is the one that uses the range variable "THIS". Its rows are supposed to represent the contents of the primary JDO objects over which this statement is querying.

getTableExpression

public TableExpression getTableExpression(CorrelationName rangeVar)

Returns the table expression associated with the range variable rangeVar. Returns null if no such range variable is in-use in the statement.

getTableExpressions

public java.util.Collection getTableExpressions()

Returns all the table expressions in the statement.

setDistinct

public void setDistinct(boolean distinct)

Sets the distinct mode flag, indicating whether or not results must be DISTINCT (unique).

Parameters:

distinct - true if results must be distinct, false to allow duplicates.

select

public int select(QueryStatement.QueryColumn qsc)

SELECTs the given query column.

Parameters:

qsc - The query column to SELECT. The QueryColumn object indicates both the TableExpression and the Column within that expression.

Returns:

The resulting index, left-to-right, of the selected column in the statement. The first selected column is index 1.

Throws:

java.lang.IllegalArgumentException - If the given query column belongs to a different query statement.

java.lang.IllegalStateException - If the statement text has already been generated.

select

public int select(SqlExpression expr)

SELECTs the given SQL expression as a result column.

Parameters:

expr - The expression to SELECT.

Returns:

The resulting column index, left-to-right, of the expression result in the query statement. The first result column is index 1.

Throws:

java.lang.IllegalArgumentException - If the given expression belongs to a different query statement.

java.lang.IllegalStateException - If the statement text has already been generated.

numResultColumns

public int numResultColumns()

Returns the number of result columns SELECTed in this statement.

getColumn

public QueryStatement.QueryColumn getColumn(Column col)

Returns a query column object for the specified column in the default table expression.

Parameters:

col - The column, which must belong to a table in the default table expression.

Returns:

A new query column object.

getColumn

public QueryStatement.QueryColumn getColumn(CorrelationName rangeVar,
                                            Column col)

Returns a query column object for the specified column in the specified table expression.

Parameters:

rangeVar - The range variable of the table expression.

col - The column, which must belong to a table in the specified table expression.

Returns:

A new query column object.

Throws:

java.lang.IllegalArgumentException - If no such range variable exists in the statement.

join

public QueryStatement.QueryColumn join(JoinType type,
                                       Table table,
                                       CorrelationName rangeVar,
                                       QueryStatement.QueryColumn from,
                                       Column to)

Performs a join on the equality of two columns.

Parameters:

type - The type of join to perform.

table - The table to be joined.

rangeVar - The range variable (i.e. alias) to use for the table expression.

from - The source (left) query column. Must be null for JoinType.CROSS.

to - The target column in the table being joined. Must be null for JoinType.CROSS.

Returns:

The target (right) query column in the joined table, or null for JoinType.CROSS.

Throws:

java.lang.IllegalArgumentException - If the to is not a column in table, or if rangeVar is already in use.

java.lang.IllegalStateException - If the statement text has already been generated.

join

public QueryStatement.QueryColumn[] join(JoinType type,
                                         Table table,
                                         CorrelationName rangeVar,
                                         QueryStatement.QueryColumn[] from,
                                         Column[] to)

Performs a join on the equality of two lists of columns.

Parameters:

type - The type of join to perform.

table - The table to be joined.

rangeVar - The range variable (i.e. alias) to use for the table expression.

from - The source (left) query columns. Must be zero-length for JoinType.CROSS.

to - The target columns in the table being joined. Must be zero-length for JoinType.CROSS.

Returns:

The target (right) query columns in the joined table, or an empty array for JoinType.CROSS.

Throws:

java.lang.IllegalArgumentException - If a to column is not a column in table, or if rangeVar is already in use, or if the two column lists are not the same size.

java.lang.IllegalStateException - If the statement text has already been generated.

newJoin

protected Join newJoin(JoinType type,
                       TableExpression tableExpr,
                       QueryStatement.QueryColumn[] from,
                       Column[] to)

Constructs a new Join object for this statement. The implementation in this class returns a StandardJoin object. Vendor-specific subclasses could override it and return a customized join object.

getJoinConditions

protected BooleanExpression getJoinConditions()

Returns the join conditions to be prefixed on the WHERE clause. Used only for Oracle-style joins.

andWhereCondition

public void andWhereCondition(BooleanExpression condition)

ANDs the given condition into the WHERE clause for this statement. If the statement has no WHERE clause yet the condition becomes its WHERE clause.

Parameters:

condition - A boolean SQL expression representing the test condition to be ANDed.

Throws:

java.lang.IllegalStateException - If the statement text has already been generated.

setGrouping

public void setGrouping(java.util.List groupExprs)

Establishes the GROUP BY clause for this statement. Any previous GROUP BY clause is discarded.

If required by the underlying DBMS, any columns referenced in the GROUP BY expression(s) will also be SELECTed in the statement.

Parameters:

groupExprs - A list of SqlExpression objects representing the contents of the GROUP BY clause.

Throws:

java.lang.IllegalStateException - If the statement text has already been generated.

andHavingCondition

public void andHavingCondition(BooleanExpression condition)

ANDs the given condition into the HAVING clause for this statement. If the statement has no HAVING clause yet the condition becomes its HAVING clause.

Parameters:

condition - A boolean SQL expression representing the test condition to be ANDed.

Throws:

java.lang.IllegalStateException - If the statement text has already been generated.

setOrdering

public void setOrdering(java.util.List orderingSpecs)

Establishes the ORDER BY clause for this statement. Any previous ORDER BY clause is discarded.

If required by the underlying DBMS, any columns referenced in the ORDER BY expression(s) will also be SELECTed in the statement.

Parameters:

orderingSpecs - A list of OrderingSpec objects representing the contents of the ORDER BY clause.

Throws:

java.lang.IllegalStateException - If the statement text has already been generated.

toStatementText

public StatementText toStatementText()

Generates and returns the statement text for this query statement. Once this method is called the statement object can no longer be modified.

Specified by:

toStatementText in interface StatementTextGenerator

toString

public java.lang.String toString()

Returns the text of this statement. Calls toStatementText() and returns the resulting string.

Specified by:

toString in interface StatementTextGenerator