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

java.lang.Object
  extended bycom.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


Copyright 2001-2007 The TJDO Project All Rights Reserved.