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

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:

Query API documentation, AbstractQuery

Last modified

$Date: 2009-04-06 14:52:39 +0200 (Mon, 06 Apr 2009) $

Method Summary

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	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	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 Detail

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