Package net.sf.basedb.core.query

Interface Query

All Known Subinterfaces:
EntityQuery, HqlQuery, SqlQuery
All Known Implementing Classes:
AbstractEntityQuery, AbstractHqlQuery, AbstractQuery, AbstractSqlQuery, DataCube.RawMappingQuery, DataQuery, DynamicExtraValueQuery, DynamicPositionQuery, DynamicQuery, DynamicRawDataQuery, DynamicReporterQuery, DynamicSpotQuery, ItemQuery, ReporterScoreQuery, SpecialQuery
public interface Query
This defines the simplest form of a relational query. A relational query can be written in the form: 
SELECT [DISTINCT] <selection-list>
FROM <root-entity>
[JOIN <joined-entity>]
[WHERE <restrictions>]
[GROUP BY <groupby-list]
[HAVING <restrictions>]
[ORDER BY <orderby-list>]
Only the SELECT and FROM query elements are needed, everything else is optional. The methods in this interface are used to build the query by adding QueryElement:s to the query.

All query elements can be either permanent or non-permanent. The difference is that permanent options are not cleared by the reset() method.

Query implementations are not required to support all options. If that is the case a UnsupportedOperationException should be thrown.

This interface doesn't define any execution methods, because the type of return object depends on the data that is returned. It is up to the implementors to define appropriate execution methods. For example: ItemQuery.list(DbControl).

Version:
2.0
Author:
Nicklas
See Also:
Developer documentation: The Query API
Last modified
$Date: 2015-05-12 09:25:48 +0200 (ti, 12 maj 2015) $

  • Method Summary

    Modifier and Type Method Description
    void addAutoJoiner​(AutoJoiner<?,​?> joiner)  
    long count​(DbControl dc)
    Count the number of items/rows that are returned by the query.
    int getFirstResult()
    The number of the row the query should start returning.
    int getMaxResults()
    The maximum number of rows returned by the query.
    Set<String> getParameterNames()
    Get a set with the names for all parameters in this query.
    QueryParameter getQueryParameter​(String name)
    Get parameter information for the parameter with given name.
    QuerySection getQuerySection()
    Get the current section of the query that is beeing built.
    QueryType getQueryType()
    Get the type of query.
    String getRootAlias()
    The alias of the root-entity in the FROM part.
    void group​(Expression e)
    Add an expression query element to the group list.
    void groupPermanent​(Expression e)
    Permanently add an expression query element to the group list.
    boolean hasParameterValue​(String name)
    Check if a value for the specified parameter has been set or not.
    void having​(Restriction r)
    Add a restriction query element to the having list.
    void havingPermanent​(Restriction r)
    Permanently add a restriction query element to the having list.
    boolean isCounting()
    Check if the query is executing the count(DbControl) method or not
    boolean isDistinct()
    If this query returns distinct results of not.
    boolean isFailSafe()
    Check if a failure of this query should still allow the current transaction to continue.
    boolean isReadonly()
    If this query is readonly and cannot be structurally modified.
    boolean isReturningTotalCount()
    If this query returns the total count or not.
    void join​(Join j)
    Add a join query element to the join list.
    void joinPermanent​(Join j)
    Permanently add a join query element to the join list.
    void order​(Order o)
    Add an ordering query element to the orderby list.
    void orderPermanent​(Order o)
    Permanently add an ordering query element to the orderby list.
    void reset()
    Reset the query, removing all non-permanent query elements and parameter values.
    void restrict​(Restriction r)
    Add a restriction query element to the restriction list.
    void restrictPermanent​(Restriction r)
    Permanently add a restriction query element to the restriction list.
    void select​(Select s)
    Add a selection query element to the selection list.
    void selectPermanent​(Select s)
    Permanently add a selection query element to the selection list.
    void setDistinct​(boolean flag)
    Specify if the query should only return distinct rows.
    void setFailSafe​(boolean failSafe)
    Set this flag to ensure that the transaction used to execute the query is allowed to continue even after a failure at the SQL level of this query.
    void setFirstResult​(int firstResult)
    Specify that the query should start returning rows from the specified row number. 0 = start returning from the first row.
    void setMaxResults​(int maxResults)
    Specify that the query should at most return the specified number of rows.
    void setParameter​(String name, Object value, Type valueType)
    Set the value of a query parameter.
    void setPermanentParameter​(String name, Object value, Type valueType)
    Permanently set the value of a query parameter.
    void setReturnTotalCount​(boolean flag)
    Specify if the query should return a count for the total number of items that would have been returned if the setFirstResult(int) and setMaxResults(int) had been disabled, or if the results are loaded by an iterator where the number of rows not are known beforehand.
    String toQl​(DbControl dc)
    Generate the query string that is going to be sent to the underlying query system (eg.

  • Method Details

    • getQueryType

      QueryType getQueryType()
      Get the type of query. Ie. The query language.
      Returns:
      A value from the QueryType enumeration

    • addAutoJoiner

      void addAutoJoiner​(AutoJoiner<?,​?> joiner)

    • select

      void select​(Select s)
      Add a selection query element to the selection list.
      Parameters:
      s - The query element to add
      Throws:
      UnsupportedOperationException - If this operation isn't supported by the implementation
      See Also:
      selectPermanent(Select)

    • selectPermanent

      void selectPermanent​(Select s)
      Permanently add a selection query element to the selection list. The query element is not cleared by the reset() method.
      Parameters:
      s - The query element to add
      Throws:
      UnsupportedOperationException - If this operation isn't supported by the implementation
      See Also:
      select(Select)

    • join

      void join​(Join j)
      Add a join query element to the join list.
      Parameters:
      j - The query element to add
      Throws:
      UnsupportedOperationException - If this operation isn't supported by the implementation
      See Also:
      joinPermanent(Join)

    • joinPermanent

      void joinPermanent​(Join j)
      Permanently add a join query element to the join list. The query element is not cleared by the reset() method.
      Parameters:
      j - The query element to add
      Throws:
      UnsupportedOperationException - If this operation isn't supported by the implementation
      See Also:
      join(Join)

    • restrict

      void restrict​(Restriction r)
      Add a restriction query element to the restriction list.
      Parameters:
      r - The query element to add
      Throws:
      UnsupportedOperationException - If this operation isn't supported by the implementation
      See Also:
      restrictPermanent(Restriction)

    • restrictPermanent

      void restrictPermanent​(Restriction r)
      Permanently add a restriction query element to the restriction list. The query element is not cleared by the reset() method.
      Parameters:
      r - The query element to add
      Throws:
      UnsupportedOperationException - If this operation isn't supported by the implementation
      See Also:
      restrict(Restriction)

    • group

      void group​(Expression e)
      Add an expression query element to the group list.
      Parameters:
      e - The query element to add
      Throws:
      UnsupportedOperationException - If this operation isn't supported by the implementation
      See Also:
      groupPermanent(Expression)

    • groupPermanent

      void groupPermanent​(Expression e)
      Permanently add an expression query element to the group list. The query element is not cleared by the reset() method.
      Parameters:
      e - The query element to add
      Throws:
      UnsupportedOperationException - If this operation isn't supported by the implementation
      See Also:
      group(Expression)

    • having

      void having​(Restriction r)
      Add a restriction query element to the having list.
      Parameters:
      r - The query element to add
      Throws:
      UnsupportedOperationException - If this operation isn't supported by the implementation
      See Also:
      havingPermanent(Restriction)

    • havingPermanent

      void havingPermanent​(Restriction r)
      Permanently add a restriction query element to the having list. The query element is not cleared by the reset() method.
      Parameters:
      r - The query element to add
      Throws:
      UnsupportedOperationException - If this operation isn't supported by the implementation
      See Also:
      having(Restriction)

    • order

      void order​(Order o)
      Add an ordering query element to the orderby list.
      Parameters:
      o - The query element to add
      Throws:
      UnsupportedOperationException - If this operation isn't supported by the implementation
      See Also:
      orderPermanent(Order)

    • orderPermanent

      void orderPermanent​(Order o)
      Permanently add an ordering query element to the orderby list. The query element is not cleared by the reset() method.
      Parameters:
      o - The query element to add
      Throws:
      UnsupportedOperationException - If this operation isn't supported by the implementation
      See Also:
      order(Order)

    • setParameter

      void setParameter​(String name, Object value, Type valueType)
      Set the value of a query parameter. If the value of this parameter has already been set by a call to the setPermanentParameter(String, Object, Type) method, an InvalidDataException is thrown.
      Parameters:
      name - The name of the parameter
      value - The value of the parameter
      valueType - The type of the value, or null if not needed
      Throws:
      UnsupportedOperationException - If this operation isn't supported by the implementation
      InvalidDataException - If the value of the parameter has already been permanently set
      See Also:
      setPermanentParameter(String, Object, Type)

    • setPermanentParameter

      void setPermanentParameter​(String name, Object value, Type valueType)
      Permanently set the value of a query parameter. If the value of this parameter has already been set by a call to this method, an InvalidDataException is thrown.
      Parameters:
      name - The name of the parameter
      value - The value of the parameter
      valueType - The type of the value, or null if not needed
      Throws:
      UnsupportedOperationException - If this operation isn't supported by the implementation
      InvalidDataException - If the value of the parameter has already been permanently set
      See Also:
      setParameter(String, Object, Type)

    • hasParameterValue

      boolean hasParameterValue​(String name)
      Check if a value for the specified parameter has been set or not. The method should check both permanent and non-permanent parameters.
      Returns:
      TRUE if a value (including null) has been set, FALSE otherwise

    • getParameterNames

      Set<String> getParameterNames()
      Get a set with the names for all parameters in this query.
      Returns:
      A set (empty if no parameters exists)
      Since:
      2.9

    • getQueryParameter

      QueryParameter getQueryParameter​(String name)
      Get parameter information for the parameter with given name.
      Parameters:
      name - The name of the parameter
      Returns:
      A QueryParameter object or null if no parameter with that name exists
      Since:
      2.9

    • setFirstResult

      void setFirstResult​(int firstResult)
      Specify that the query should start returning rows from the specified row number. 0 = start returning from the first row. If the value is higher than the total number of rows, no rows are returned. This option is best combined with the setMaxResults(int) option.
      Parameters:
      firstResult - The number of the first row starting at 0
      Throws:
      UnsupportedOperationException - If this operation isn't supported by the implementation
      See Also:
      setMaxResults(int)

    • getFirstResult

      int getFirstResult()
      The number of the row the query should start returning.
      See Also:
      setFirstResult(int)

    • setMaxResults

      void setMaxResults​(int maxResults)
      Specify that the query should at most return the specified number of rows. If the matching number of rows is less than this value only the matching rows are returned. A value of 0 disabled this option. This option is best combined with the setFirstResult(int) option.
      Parameters:
      maxResults - The maximum number of rows to return
      Throws:
      UnsupportedOperationException - If this operation isn't supported by the implementation
      See Also:
      setFirstResult(int)

    • getMaxResults

      int getMaxResults()
      The maximum number of rows returned by the query. A value of 0 indicates no limit.
      See Also:
      setMaxResults(int)

    • setReturnTotalCount

      void setReturnTotalCount​(boolean flag)
      Specify if the query should return a count for the total number of items that would have been returned if the setFirstResult(int) and setMaxResults(int) had been disabled, or if the results are loaded by an iterator where the number of rows not are known beforehand.
      Parameters:
      flag - TRUE if the query should return the total count, FALSE otherwise
      Throws:
      UnsupportedOperationException - If this operation isn't supported by the implementation

    • isReturningTotalCount

      boolean isReturningTotalCount()
      If this query returns the total count or not.
      See Also:
      setReturnTotalCount(boolean)

    • setDistinct

      void setDistinct​(boolean flag)
      Specify if the query should only return distinct rows. Exctly what this means depends on what is selected by the query. For example, if we are selecting items no item would be returned more than once, if we are selecting numbers the same number wouldn't be returned more than once.
      Parameters:
      flag - TRUE if the query should return distinct results, FALSE otherwise

    • isDistinct

      boolean isDistinct()
      If this query returns distinct results of not.
      See Also:
      setDistinct(boolean)

    • isReadonly

      boolean isReadonly()
      If this query is readonly and cannot be structurally modified. Ie. no more query elements can be added. It is still possible to set parameter values. A call to reset() would unlock the query and allow it to be modified again.
      Returns:
      TRUE if the query is readonly, FALSE otherwise

    • reset

      void reset()
      Reset the query, removing all non-permanent query elements and parameter values.

    • getRootAlias

      String getRootAlias()
      The alias of the root-entity in the FROM part. This value is used by the query elements to let a client application skip specifying the root alias all the time.
      See Also:
      Hql.property(String, String)

    • count

      long count​(DbControl dc) throws BaseException
      Count the number of items/rows that are returned by the query. The method ignores the getFirstResult() and getMaxResults() settings.
      Returns:
      The number of rows/items returned by the query
      Throws:
      BaseException - If there is an error

    • isCounting

      boolean isCounting()
      Check if the query is executing the count(DbControl) method or not
      Returns:
      TRUE if the query is currently executing the count method, FALSE otherwise

    • getQuerySection

      QuerySection getQuerySection()
      Get the current section of the query that is beeing built. This method can be used by QueryElement:s if they need different syntax in different sections.
      Returns:
      A QuerySection

    • toQl

      String toQl​(DbControl dc)
      Generate the query string that is going to be sent to the underlying query system (eg. HQL/Hibernate or SQL/JDBC).
      Parameters:
      dc - The DbControl that is going to be used for executing the query
      Returns:
      The query string
      Since:
      2.9

    • setFailSafe

      void setFailSafe​(boolean failSafe)
      Set this flag to ensure that the transaction used to execute the query is allowed to continue even after a failure at the SQL level of this query. Setting this flag to TRUE should allow the transaction to continue, setting it to FALSE may or may not allow it to continue. The default setting is FALSE.
      Parameters:
      failSafe - TRUE to ensure that the transaction is allowed to continue, FALSE if it doesn't matter
      Since:
      3.1

    • isFailSafe

      boolean isFailSafe()
      Check if a failure of this query should still allow the current transaction to continue.
      Returns:
      TRUE if the transaction should be allowed to continue, FALSE if it doesn't matter
      Since:
      3.1