de.mguennewig.pobjects
Class Query

java.lang.Object
  de.mguennewig.pobjects.Query

Direct Known Subclasses:

JdbcQuery, PredicateQuery

public abstract class Query
extends java.lang.Object

Describes a simple query to retrieve objects from a database.

This class provides a small subset of the functionality of SQL that is required to gain access to objects based on certain selection criteria. All queries return references to instances of Record.

Author:

Michael Günnewig

Field Summary

static boolean	ASCENDING
static boolean	DESCENDING

Method Summary

void	addArguments(java.lang.Object[] arguments) Adds the arguments for a SELECT expression.
void	addConj(Condition pred) Adds the Condition to the list of boolean expressions, that are AND'ed together to form the WHERE part of the statement.
int	addJoin(int baseColumn, Column refColumn, boolean pullInFields) Add an equi-join on the table referenced by the reference in refColumn.
void	addOrderBy(int baseColumn, Column designator)
void	addOrderBy(int baseColumn, Column[] designator, boolean ascending)
void	addOrderBy(int baseColumn, Column designator, boolean ascending)
void	addOrderBy(Member designator, boolean ascending)
void	addTableExpr(java.lang.Class<? extends Record> tableClass, boolean pullInFields) Adds a new table expression to the query.
void	addTableExpr(TableExpr te, boolean pullInFields) Adds a new table expression to the query.
abstract int	count() Returns the number of rows which will be returned by the query.
abstract EvalContext	evaluate(boolean forCount) Evaluates this query.
Record[][]	execute() Executes this query and returns the result.
abstract PObjResultSet	executeResultSet() Executes this query and returns the result set for row-by-row processing.
Container	getContainer()
int	getNumTableExprs()
TableExpr	getTableExpr(int n) Returns the table expression at index n of this query.
boolean	isDistinct() Returns whether this query will filter out duplicates.
boolean	isOrdered()
void	pullInReference(Member designator) As part of the query, retrieve the complete data of all objects referenced by designator.
void	setDistinct(boolean distinct) Sets whether this query should filter out duplicates.
void	setLimit(int aOffset, int aLimit) Limits the result of this query.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ASCENDING

public static final boolean ASCENDING

See Also:

Constant Field Values

DESCENDING

public static final boolean DESCENDING

See Also:

Constant Field Values

Method Detail

getContainer

public final Container getContainer()

addTableExpr

public final void addTableExpr(TableExpr te,
                               boolean pullInFields)

Adds a new table expression to the query.

Parameters:

te - the table expression to add.

pullInFields - if true all fields of the table will be read, else just the IdField to make a transient object. This parameter will be ignored for SELECT expressions.

See Also:

addTableExprFct(TableExpr,boolean)

addTableExpr

public final void addTableExpr(java.lang.Class<? extends Record> tableClass,
                               boolean pullInFields)

Adds a new table expression to the query.

Parameters:

tableClass - the class of the table expression to add.

pullInFields - if true all fields of the table will be read, else just the IdField to make a transient object. This parameter will be ignored for SELECT expressions.

See Also:

addTableExprFct(TableExpr,boolean)

getTableExpr

public final TableExpr getTableExpr(int n)

Returns the table expression at index n of this query.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if no such table expression exists

getNumTableExprs

public final int getNumTableExprs()

isDistinct

public final boolean isDistinct()

Returns whether this query will filter out duplicates.

There are some limitations with this feature, which are described under setDistinct(boolean).

setDistinct

public void setDistinct(boolean distinct)

Sets whether this query should filter out duplicates.

Even if the query is marked as distinct can it still return duplicates, due to the nature of created query and how DISTINCT works in SQL. To get a real distinct result the following things have to be met:

1. the parameter pullInFields of the addTableExpr methods must be false for every table. Note that for SelectExpr and ViewDecl this parameter is always true, so that the distinctness depends on the distinctness of these expressions.
2. pullInReference(Member) has not to be used.

See Also:

addTableExpr(Class, boolean), addTableExpr(TableExpr, boolean), pullInReference(Member)

addArguments

public final void addArguments(java.lang.Object[] arguments)

Adds the arguments for a SELECT expression.

setLimit

public final void setLimit(int aOffset,
                           int aLimit)

Limits the result of this query.

addConj

public void addConj(Condition pred)

Adds the Condition to the list of boolean expressions, that are AND'ed together to form the WHERE part of the statement.

Throws:

java.lang.IllegalArgumentException - if pred is null.

See Also:

EvalContext.addWhereConj(de.mguennewig.pobjects.Term)

addOrderBy

public final void addOrderBy(int baseColumn,
                             Column designator)

addOrderBy

public final void addOrderBy(int baseColumn,
                             Column designator,
                             boolean ascending)

addOrderBy

public final void addOrderBy(int baseColumn,
                             Column[] designator,
                             boolean ascending)

addOrderBy

public void addOrderBy(Member designator,
                       boolean ascending)

Throws:

java.lang.IllegalArgumentException - if no designator is given, or the designator refers to an unknown table expression.

See Also:

ASCENDING, DESCENDING

isOrdered

public final boolean isOrdered()

pullInReference

public void pullInReference(Member designator)

As part of the query, retrieve the complete data of all objects referenced by designator.

This makes sure that the data of the referenced objects is internalized during the request, preventing individual database lookups for them later on.

Pre-condition:The attribute identified by designator is of type ReferenceToClass. designator must have a selector. The referring field must be pulled in.

Throws:

java.lang.IllegalArgumentException - if the designator does not met a pre-conditions.

java.lang.IllegalStateException - if the reference to pull is from a table whose fields are not pulled in.

See Also:

addTableExpr(Class,boolean), addTableExpr(TableExpr,boolean)

addJoin

public int addJoin(int baseColumn,
                   Column refColumn,
                   boolean pullInFields)

Add an equi-join on the table referenced by the reference in refColumn.

Result is the column index of the new entry in the query's list of result columns.

Pre-condition: The type of refColumn is ReferenceToClass.

evaluate

public abstract EvalContext evaluate(boolean forCount)

Evaluates this query.

execute

public Record[][] execute()

Executes this query and returns the result.

Returns:

Array of array.

       result = new Record[][] {
         new Table_1[] { table_1[row_0], table_1[row_1], ... },
         new Table_2[] { table_2[row_0], table_2[row_1], ... },
         ...
       };
       

Throws:

PObjReadError - if any database error occurs.

See Also:

executeResultSet()

executeResultSet

public abstract PObjResultSet executeResultSet()

Executes this query and returns the result set for row-by-row processing.

Throws:

PObjReadError - if any database error occurs.

See Also:

execute()

count

public abstract int count()

Returns the number of rows which will be returned by the query.

Throws:

PObjReadError