org.xcmis.search.query
Class QueryBuilder

java.lang.Object
  org.xcmis.search.query.QueryBuilder

public class QueryBuilder
extends Object

A component that can be used to programmatically create QueryCommand objects. Simply call methods to build the selector clause, from clause, join criteria, where criteria, limits, and ordering, and then obtain the query. This builder should be adequate for most queries; however, any query that cannot be expressed by this builder can always be constructed by directly creating the Abstract Query Model classes.

This builder is stateful and therefore should only be used by one thread at a time. However, once a query has been built, the builder can be cleared and used to create another query.

The order in which the methods are called are (for the most part) important. Simply call the methods in the same order that would be most natural in a normal SQL query. For example, the following code creates a Query object that is equivalent to " SELECT * FROM table":

 QueryCommand query = builder.selectStar().from("table").query();
 

Here are a few other examples:

SQL Statement	QueryBuilder code
SELECT * FROM table1 INNER JOIN table2 ON table2.c0 = table1.c0	query = builder.selectStar().from("table1").join("table2").on("table2.c0=table1.c0").query();
SELECT * FROM table1 AS t1 INNER JOIN table2 AS t2 ON t1.c0 = t2.c0	query = builder.selectStar().from("table1 AS t1").join("table2 AS t2").on("t1.c0=t2.c0").query();
SELECT * FROM table1 AS t1 INNER JOIN table2 AS t2 ON t1.c0 = t2.c0 INNER JOIN table3 AS t3 ON t1.c1 = t3.c1	query = builder.selectStar() .from("table1 AS t1") .innerJoin("table2 AS t2") .on("t1.c0=t2.c0") .innerJoin("table3 AS t3") .on("t1.c1=t3.c1") .query();

Nested Class Summary

class	QueryBuilder.AndBuilder<T>
class	QueryBuilder.CastAs<ReturnType>
class	QueryBuilder.CastAsRightHandSide
class	QueryBuilder.ComparisonBuilder An interface used to set the right-hand side of a constraint.
class	QueryBuilder.ConstraintBuilder
static interface	QueryBuilder.DynamicOperandBuilder Interface that defines a dynamic operand portion of a criteria.
class	QueryBuilder.JoinClause Class used to specify a join clause of a query.
protected class	QueryBuilder.LowerCaser A specialized form of the QueryBuilder.ConstraintBuilder that always wraps the generated constraint in a LowerCase instance.
class	QueryBuilder.OrderByBuilder The component used to build the order-by clause.
static interface	QueryBuilder.OrderByOperandBuilder
class	QueryBuilder.RightHandSide
protected class	QueryBuilder.SingleOrderByOperandBuilder
protected class	QueryBuilder.UpperCaser A specialized form of the QueryBuilder.ConstraintBuilder that always wraps the generated constraint in a UpperCase instance.

Field Summary

protected CastSystem	castSystem
protected List<org.xcmis.search.model.column.Column>	columns
protected org.xcmis.search.model.constraint.Constraint	constraint
protected boolean	distinct
protected org.xcmis.search.model.Query	firstQuery
protected boolean	firstQueryAll
protected org.xcmis.search.model.Limit	limit
protected List<org.xcmis.search.model.ordering.Ordering>	orderings
protected org.xcmis.search.model.source.Source	source

Constructor Summary

QueryBuilder(CastSystem castSystem)
Create a new builder that uses the supplied execution context.

Method Summary

QueryBuilder	clear() Clear this builder completely to start building a new query.
protected QueryBuilder	clear(boolean clearFirstQuery) Utility method that does all the work of the clear, but with a flag that defines whether to clear the first query.
protected org.xcmis.search.model.column.Column	column(String nameExpression) Create a Column given the supplied expression.
QueryBuilder	from(String tableNameWithOptionalAlias) Specify the name of the table from which tuples should be selected.
QueryBuilder.JoinClause	innerJoin(String tableName) Perform an inner join between the already defined source with the supplied table.
QueryBuilder.JoinClause	join(String tableName) Perform an inner join between the already defined source with the supplied table.
QueryBuilder.JoinClause	leftOuterJoin(String tableName) Perform a left outer join between the already defined source with the supplied table.
QueryBuilder	limit(int rowLimit) Specify the maximum number of rows that are to be returned in the results.
protected org.xcmis.search.model.source.Selector	namedSelector(String nameWithOptionalAlias) Convenience method that creates a Selector object given a string that contains the selector name and optionally an alias.
QueryBuilder	offset(int offset) Specify the number of rows that results are to skip.
QueryBuilder.OrderByBuilder	orderBy() Obtain a builder that will create the order-by clause (with one or more Ordering statements) for the query.
org.xcmis.search.model.Query	query() Return a QueryCommand representing the currently-built query.
QueryBuilder.JoinClause	rightOuterJoin(String tableName) Perform a right outer join between the already defined source with the supplied table.
QueryBuilder	select(String... columnNames) Add to the select clause the columns with the supplied names.
QueryBuilder	selectDistinct(String... columnNames) Select the distinct values from the columns with the supplied names.
QueryBuilder	selectDistinctStar() Select all of the distinct values from the single-valued columns.
protected org.xcmis.search.model.source.SelectorName	selector(String name) Convenience method that creates a selector name object using the supplied string.
QueryBuilder	selectStar() Select all of the single-valued columns.
QueryBuilder.ConstraintBuilder	where() Begin the WHERE clause for this query by obtaining the constraint builder.

Methods inherited from class java.lang.Object

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

Field Detail

castSystem

protected final CastSystem castSystem

source

protected org.xcmis.search.model.source.Source source

constraint

protected org.xcmis.search.model.constraint.Constraint constraint

columns

protected List<org.xcmis.search.model.column.Column> columns

orderings

protected List<org.xcmis.search.model.ordering.Ordering> orderings

limit

protected org.xcmis.search.model.Limit limit

distinct

protected boolean distinct

firstQuery

protected org.xcmis.search.model.Query firstQuery

firstQueryAll

protected boolean firstQueryAll

Constructor Detail

QueryBuilder

public QueryBuilder(CastSystem castSystem)

Create a new builder that uses the supplied execution context.

Parameters:

context - the execution context

Throws:

IllegalArgumentException - if the context is null

Method Detail

clear

public QueryBuilder clear()

Clear this builder completely to start building a new query.

Returns:

this builder object, for convenience in method chaining

clear

protected QueryBuilder clear(boolean clearFirstQuery)

Utility method that does all the work of the clear, but with a flag that defines whether to clear the first query. This method is used by clear() as well as the many set operations.

Parameters:

clearFirstQuery - true if the first query should be cleared, or false if the first query should be retained

Returns:

this builder object, for convenience in method chaining

selector

protected org.xcmis.search.model.source.SelectorName selector(String name)

Convenience method that creates a selector name object using the supplied string.

Parameters:

name - the name of the selector; may not be null

Returns:

the selector name; never null

namedSelector

protected org.xcmis.search.model.source.Selector namedSelector(String nameWithOptionalAlias)

Convenience method that creates a Selector object given a string that contains the selector name and optionally an alias. The format of the string parameter is name [AS alias]. Leading and trailing whitespace are trimmed.

Parameters:

nameWithOptionalAlias - the name and optional alias; may not be null

Returns:

the named selector object; never null

column

protected org.xcmis.search.model.column.Column column(String nameExpression)

Create a Column given the supplied expression. The expression has the form "[tableName.]columnName", where " tableName" must be a valid table name or alias. If the table name/alias is not specified, then there is expected to be a single FROM clause with a single named selector.

Parameters:

nameExpression - the expression specifying the columm name and (optionally) the table's name or alias; may not be null

Returns:

the column; never null

Throws:

IllegalArgumentException - if the table's name/alias is not specified, but the query has more than one named source

selectStar

public QueryBuilder selectStar()

Select all of the single-valued columns.

Returns:

this builder object, for convenience in method chaining

select

public QueryBuilder select(String... columnNames)

Add to the select clause the columns with the supplied names. Each column name has the form " [tableName.]columnName", where " tableName" must be a valid table name or alias. If the table name/alias is not specified, then there is expected to be a single FROM clause with a single named selector.

Parameters:

columnNames - the column expressions; may not be null

Returns:

this builder object, for convenience in method chaining

Throws:

IllegalArgumentException - if the table's name/alias is not specified, but the query has more than one named source

selectDistinctStar

public QueryBuilder selectDistinctStar()

Select all of the distinct values from the single-valued columns.

Returns:

this builder object, for convenience in method chaining

selectDistinct

public QueryBuilder selectDistinct(String... columnNames)

Select the distinct values from the columns with the supplied names. Each column name has the form " [tableName.]columnName", where " tableName" must be a valid table name or alias. If the table name/alias is not specified, then there is expected to be a single FROM clause with a single named selector.

Parameters:

columnNames - the column expressions; may not be null

Returns:

this builder object, for convenience in method chaining

Throws:

IllegalArgumentException - if the table's name/alias is not specified, but the query has more than one named source

from

public QueryBuilder from(String tableNameWithOptionalAlias)

Specify the name of the table from which tuples should be selected. The supplied string is of the form " tableName [AS alias]".

Parameters:

tableNameWithOptionalAlias - the name of the table, optionally including the alias

Returns:

this builder object, for convenience in method chaining

where

public QueryBuilder.ConstraintBuilder where()

Begin the WHERE clause for this query by obtaining the constraint builder. When completed, be sure to call end() on the resulting constraint builder, or else the constraint will not be applied to the current query.

Returns:

the constraint builder that can be used to specify the criteria; never null

join

public QueryBuilder.JoinClause join(String tableName)

Perform an inner join between the already defined source with the supplied table. The supplied string is of the form " tableName [AS alias]".

Parameters:

tableName - the name of the table, optionally including the alias

Returns:

the component that must be used to complete the join specification; never null

innerJoin

public QueryBuilder.JoinClause innerJoin(String tableName)

Perform an inner join between the already defined source with the supplied table. The supplied string is of the form " tableName [AS alias]".

Parameters:

tableName - the name of the table, optionally including the alias

Returns:

the component that must be used to complete the join specification; never null

leftOuterJoin

public QueryBuilder.JoinClause leftOuterJoin(String tableName)

Perform a left outer join between the already defined source with the supplied table. The supplied string is of the form " tableName [AS alias]".

Parameters:

tableName - the name of the table, optionally including the alias

Returns:

the component that must be used to complete the join specification; never null

rightOuterJoin

public QueryBuilder.JoinClause rightOuterJoin(String tableName)

Perform a right outer join between the already defined source with the supplied table. The supplied string is of the form " tableName [AS alias]".

Parameters:

tableName - the name of the table, optionally including the alias

Returns:

the component that must be used to complete the join specification; never null

limit

public QueryBuilder limit(int rowLimit)

Specify the maximum number of rows that are to be returned in the results. By default there is no limit.

Parameters:

rowLimit - the maximum number of rows

Returns:

this builder object, for convenience in method chaining

Throws:

IllegalArgumentException - if the row limit is not a positive integer

offset

public QueryBuilder offset(int offset)

Specify the number of rows that results are to skip. The default offset is '0'.

Parameters:

offset - the number of rows before the results are to begin

Returns:

this builder object, for convenience in method chaining

Throws:

IllegalArgumentException - if the row limit is a negative integer

orderBy

public QueryBuilder.OrderByBuilder orderBy()

Obtain a builder that will create the order-by clause (with one or more Ordering statements) for the query. This method need be called only once to build the order-by clause, but can be called multiple times (it merely adds additional Ordering statements).

Returns:

the order-by builder; never null

query

public org.xcmis.search.model.Query query()

Return a QueryCommand representing the currently-built query.

Returns:

the resulting query command; never null

See Also:

clear()