Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| ModeShape Distribution 3.0.0.Beta3
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.modeshape.jcr.query
Class QueryBuilder

    java.lang.Object
      org.modeshape.jcr.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()`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| ModeShape Distribution 3.0.0.Beta3
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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