org.jboss.dna.graph.query
Class QueryBuilder

java.lang.Object
  extended by org.jboss.dna.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
           
 class QueryBuilder.OrderByBuilder
          The component used to build the order-by clause.
static interface QueryBuilder.OrderByOperandBuilder
           
 class QueryBuilder.RightHandSide
           
 class QueryBuilder.UpperBoundary
           
 
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.
 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.
 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.
 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
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

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

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.