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:
- Last modified
- $Date: 2015-05-12 09:25:48 +0200 (ti, 12 maj 2015) $
-
Method Summary
Modifier and TypeMethodDescriptionvoid
addAutoJoiner
(AutoJoiner<?, ?> joiner) long
Count the number of items/rows that are returned by the query.int
The number of the row the query should start returning.int
The maximum number of rows returned by the query.Get a set with the names for all parameters in this query.getQueryParameter
(String name) Get parameter information for the parameter with given name.Get the current section of the query that is beeing built.Get the type of query.The alias of theroot-entity
in theFROM
part.void
group
(Expression e) Add an expression query element to the group list.void
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
Add a restriction query element to the having list.void
Permanently add a restriction query element to the having list.boolean
Check if the query is executing thecount(DbControl)
method or notboolean
If this query returns distinct results of not.boolean
Check if a failure of this query should still allow the current transaction to continue.boolean
If this query is readonly and cannot be structurally modified.boolean
If this query returns the total count or not.void
Add a join query element to the join list.void
Permanently add a join query element to the join list.void
Add an ordering query element to the orderby list.void
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
Add a restriction query element to the restriction list.void
Permanently add a restriction query element to the restriction list.void
Add a selection query element to the selection list.void
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 thesetFirstResult(int)
andsetMaxResults(int)
had been disabled, or if the results are loaded by an iterator where the number of rows not are known beforehand.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
-
select
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
Permanently add a selection query element to the selection list. The query element is not cleared by thereset()
method.- Parameters:
s
- The query element to add- Throws:
UnsupportedOperationException
- If this operation isn't supported by the implementation- See Also:
-
join
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
Permanently add a join query element to the join list. The query element is not cleared by thereset()
method.- Parameters:
j
- The query element to add- Throws:
UnsupportedOperationException
- If this operation isn't supported by the implementation- See Also:
-
restrict
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
Permanently add a restriction query element to the restriction list. The query element is not cleared by thereset()
method.- Parameters:
r
- The query element to add- Throws:
UnsupportedOperationException
- If this operation isn't supported by the implementation- See Also:
-
group
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
Permanently add an expression query element to the group list. The query element is not cleared by thereset()
method.- Parameters:
e
- The query element to add- Throws:
UnsupportedOperationException
- If this operation isn't supported by the implementation- See Also:
-
having
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
Permanently add a restriction query element to the having list. The query element is not cleared by thereset()
method.- Parameters:
r
- The query element to add- Throws:
UnsupportedOperationException
- If this operation isn't supported by the implementation- See Also:
-
order
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
Permanently add an ordering query element to the orderby list. The query element is not cleared by thereset()
method.- Parameters:
o
- The query element to add- Throws:
UnsupportedOperationException
- If this operation isn't supported by the implementation- See Also:
-
setParameter
Set the value of a query parameter. If the value of this parameter has already been set by a call to thesetPermanentParameter(String, Object, Type)
method, anInvalidDataException
is thrown.- Parameters:
name
- The name of the parametervalue
- The value of the parametervalueType
- The type of the value, or null if not needed- Throws:
UnsupportedOperationException
- If this operation isn't supported by the implementationInvalidDataException
- If the value of the parameter has already been permanently set- See Also:
-
setPermanentParameter
Permanently set the value of a query parameter. If the value of this parameter has already been set by a call to this method, anInvalidDataException
is thrown.- Parameters:
name
- The name of the parametervalue
- The value of the parametervalueType
- The type of the value, or null if not needed- Throws:
UnsupportedOperationException
- If this operation isn't supported by the implementationInvalidDataException
- If the value of the parameter has already been permanently set- See Also:
-
hasParameterValue
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
Get a set with the names for all parameters in this query.- Returns:
- A set (empty if no parameters exists)
- Since:
- 2.9
-
getQueryParameter
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 thesetMaxResults(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:
-
getFirstResult
int getFirstResult()The number of the row the query should start returning.- See Also:
-
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 thesetFirstResult(int)
option.- Parameters:
maxResults
- The maximum number of rows to return- Throws:
UnsupportedOperationException
- If this operation isn't supported by the implementation- See Also:
-
getMaxResults
int getMaxResults()The maximum number of rows returned by the query. A value of 0 indicates no limit.- See Also:
-
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 thesetFirstResult(int)
andsetMaxResults(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:
-
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:
-
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 toreset()
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 theroot-entity
in theFROM
part. This value is used by the query elements to let a client application skip specifying the root alias all the time.- See Also:
-
count
Count the number of items/rows that are returned by the query. The method ignores thegetFirstResult()
andgetMaxResults()
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 thecount(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 byQueryElement
:s if they need different syntax in different sections.- Returns:
- A QuerySection
-
toQl
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
-