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

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `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

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `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

    Constructors
    Constructor and Description
    `QueryBuilder(TypeSystem context)` Create a new builder that uses the supplied execution context.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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-2014 JBoss, a division of Red Hat. All Rights Reserved.