org.modeshape.graph.query
Class QueryBuilder

java.lang.Object
  extended by org.modeshape.graph.query.QueryBuilder

@NotThreadSafe
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();
 
 SELECT * FROM table1
 UNION
 SELECT * FROM table2
 
 query = builder.selectStar().from("table1").union().selectStar().from("table2").query();
 
 SELECT t1.c1,t1.c2,t2.c3 FROM table1 AS t1
    INNER JOIN table2 AS t2
            ON t1.c0 = t2.c0
 UNION ALL
 SELECT t3.c1,t3.c2,t4.c3 FROM table3 AS t3
    INNER JOIN table4 AS t4
            ON t3.c0 = t4.c0
 
 query = builder.select("t1.c1","t1.c2","t2.c3",)
                .from("table1 AS t1")
                .innerJoin("table2 AS t2")
                .on("t1.c0=t2.c0")
                .union()
                .select("t3.c1","t3.c2","t4.c3",)
                .from("table3 AS t3")
                .innerJoin("table4 AS t4")
                .on("t3.c0=t4.c0")
                .query();
 


Nested Class Summary
 class QueryBuilder.AndBuilder<T>
           
 class QueryBuilder.ArithmeticBuilder
           
 class QueryBuilder.CastAs<ReturnType>
           
 class QueryBuilder.CastAsLowerBoundary
           
 class QueryBuilder.CastAsRightHandSide
           
 class QueryBuilder.CastAsUpperBoundary
           
 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.
 class QueryBuilder.LowerBoundary
           
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
           
 class QueryBuilder.UpperBoundary
           
protected  class QueryBuilder.UpperCaser
          A specialized form of the QueryBuilder.ConstraintBuilder that always wraps the generated constraint in a UpperCase instance.
 
Field Summary
protected  List<Column> columns
           
protected  Constraint constraint
           
protected  boolean distinct
           
protected  QueryCommand firstQuery
           
protected  boolean firstQueryAll
           
protected  SetQuery.Operation firstQuerySetOperation
           
protected  Limit limit
           
protected  List<Ordering> orderings
           
protected  Source source
           
protected  TypeSystem typeSystem
           
 
Constructor Summary
QueryBuilder(TypeSystem context)
          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  Column column(String nameExpression)
          Create a Column given the supplied expression.
 QueryBuilder.JoinClause crossJoin(String tableName)
          Perform a cross join between the already defined source with the supplied table.
 QueryBuilder.JoinClause crossJoinAllNodesAs(String alias)
          Perform a cross join between the already defined source with the "__ALL_NODES" table using the supplied alias.
 QueryBuilder except()
          Perform an EXCEPT between the query as defined prior to this method and the query that will be defined following this method.
 QueryBuilder exceptAll()
          Perform an EXCEPT ALL between the query as defined prior to this method and the query that will be defined following this method.
 QueryBuilder from(String tableNameWithOptionalAlias)
          Specify the name of the table from which tuples should be selected.
 QueryBuilder fromAllNodes()
          Specify that the query should select from the "__ALLNODES__" built-in table.
 QueryBuilder fromAllNodesAs(String alias)
          Specify that the query should select from the "__ALLNODES__" built-in table using the supplied alias.
 QueryBuilder.JoinClause fullOuterJoin(String tableName)
          Perform a full outer join between the already defined source with the supplied table.
 QueryBuilder.JoinClause fullOuterJoinAllNodesAs(String alias)
          Perform a full outer join between the already defined source with the "__ALL_NODES" table using the supplied alias.
 QueryBuilder.JoinClause innerJoin(String tableName)
          Perform an inner join between the already defined source with the supplied table.
 QueryBuilder.JoinClause innerJoinAllNodesAs(String alias)
          Perform an inner join between the already defined source with the "__ALL_NODES" table using the supplied alias.
 QueryBuilder intersect()
          Perform an INTERSECT between the query as defined prior to this method and the query that will be defined following this method.
 QueryBuilder intersectAll()
          Perform an INTERSECT ALL between the query as defined prior to this method and the query that will be defined following this method.
 QueryBuilder.JoinClause join(String tableName)
          Perform an inner join between the already defined source with the supplied table.
 QueryBuilder.JoinClause joinAllNodesAs(String alias)
          Perform an inner join between the already defined source with the "__ALLNODES__" table using the supplied alias.
 QueryBuilder.JoinClause leftOuterJoin(String tableName)
          Perform a left outer join between the already defined source with the supplied table.
 QueryBuilder.JoinClause leftOuterJoinAllNodesAs(String alias)
          Perform a left outer join between the already defined source with the "__ALL_NODES" table using the supplied alias.
 QueryBuilder limit(int rowLimit)
          Specify the maximum number of rows that are to be returned in the results.
protected  NamedSelector namedSelector(String nameWithOptionalAlias)
          Convenience method that creates a NamedSelector 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.
 QueryCommand 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.JoinClause rightOuterJoinAllNodesAs(String alias)
          Perform a right outer join between the already defined source with the "__ALL_NODES" table using the supplied alias.
 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  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 union()
          Perform a UNION between the query as defined prior to this method and the query that will be defined following this method.
 QueryBuilder unionAll()
          Perform a UNION ALL between the query as defined prior to this method and the query that will be defined following this method.
 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

typeSystem

protected final TypeSystem typeSystem

source

protected Source source

constraint

protected Constraint constraint

columns

protected List<Column> columns

orderings

protected List<Ordering> orderings

limit

protected Limit limit

distinct

protected boolean distinct

firstQuery

protected QueryCommand firstQuery

firstQuerySetOperation

protected SetQuery.Operation firstQuerySetOperation

firstQueryAll

protected boolean firstQueryAll
Constructor Detail

QueryBuilder

public QueryBuilder(TypeSystem context)
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 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 NamedSelector namedSelector(String nameWithOptionalAlias)
Convenience method that creates a NamedSelector 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 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

fromAllNodes

public QueryBuilder fromAllNodes()
Specify that the query should select from the "__ALLNODES__" built-in table.

Returns:
this builder object, for convenience in method chaining

fromAllNodesAs

public QueryBuilder fromAllNodesAs(String alias)
Specify that the query should select from the "__ALLNODES__" built-in table using the supplied alias.

Parameters:
alias - the alias for the "__ALL_NODES" table; may not be null
Returns:
this builder object, for convenience in method chaining

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

crossJoin

public QueryBuilder.JoinClause crossJoin(String tableName)
Perform a cross join between the already defined source with the supplied table. The supplied string is of the form " tableName [AS alias]". Cross joins have a higher precedent than other join types, so if this is called after another join was defined, the resulting cross join will be between the previous join's right-hand side and the supplied table.

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

fullOuterJoin

public QueryBuilder.JoinClause fullOuterJoin(String tableName)
Perform a full 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

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

joinAllNodesAs

public QueryBuilder.JoinClause joinAllNodesAs(String alias)
Perform an inner join between the already defined source with the "__ALLNODES__" table using the supplied alias.

Parameters:
alias - the alias for the "__ALL_NODES" table; may not be null
Returns:
the component that must be used to complete the join specification; never null

innerJoinAllNodesAs

public QueryBuilder.JoinClause innerJoinAllNodesAs(String alias)
Perform an inner join between the already defined source with the "__ALL_NODES" table using the supplied alias.

Parameters:
alias - the alias for the "__ALL_NODES" table; may not be null
Returns:
the component that must be used to complete the join specification; never null

crossJoinAllNodesAs

public QueryBuilder.JoinClause crossJoinAllNodesAs(String alias)
Perform a cross join between the already defined source with the "__ALL_NODES" table using the supplied alias. Cross joins have a higher precedent than other join types, so if this is called after another join was defined, the resulting cross join will be between the previous join's right-hand side and the supplied table.

Parameters:
alias - the alias for the "__ALL_NODES" table; may not be null
Returns:
the component that must be used to complete the join specification; never null

fullOuterJoinAllNodesAs

public QueryBuilder.JoinClause fullOuterJoinAllNodesAs(String alias)
Perform a full outer join between the already defined source with the "__ALL_NODES" table using the supplied alias.

Parameters:
alias - the alias for the "__ALL_NODES" table; may not be null
Returns:
the component that must be used to complete the join specification; never null

leftOuterJoinAllNodesAs

public QueryBuilder.JoinClause leftOuterJoinAllNodesAs(String alias)
Perform a left outer join between the already defined source with the "__ALL_NODES" table using the supplied alias.

Parameters:
alias - the alias for the "__ALL_NODES" table; may not be null
Returns:
the component that must be used to complete the join specification; never null

rightOuterJoinAllNodesAs

public QueryBuilder.JoinClause rightOuterJoinAllNodesAs(String alias)
Perform a right outer join between the already defined source with the "__ALL_NODES" table using the supplied alias.

Parameters:
alias - the alias for the "__ALL_NODES" table; may not be null
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

union

public QueryBuilder union()
Perform a UNION between the query as defined prior to this method and the query that will be defined following this method.

Returns:
this builder object, for convenience in method chaining

unionAll

public QueryBuilder unionAll()
Perform a UNION ALL between the query as defined prior to this method and the query that will be defined following this method.

Returns:
this builder object, for convenience in method chaining

intersect

public QueryBuilder intersect()
Perform an INTERSECT between the query as defined prior to this method and the query that will be defined following this method.

Returns:
this builder object, for convenience in method chaining

intersectAll

public QueryBuilder intersectAll()
Perform an INTERSECT ALL between the query as defined prior to this method and the query that will be defined following this method.

Returns:
this builder object, for convenience in method chaining

except

public QueryBuilder except()
Perform an EXCEPT between the query as defined prior to this method and the query that will be defined following this method.

Returns:
this builder object, for convenience in method chaining

exceptAll

public QueryBuilder exceptAll()
Perform an EXCEPT ALL between the query as defined prior to this method and the query that will be defined following this method.

Returns:
this builder object, for convenience in method chaining

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 QueryCommand query()
Return a QueryCommand representing the currently-built query.

Returns:
the resulting query command; never null
See Also:
clear()


Copyright © 2008-2010 JBoss, a division of Red Hat. All Rights Reserved.