Purpose:
Abstract class for all database query objects.
DatabaseQuery is a visible class to the TopLink user. Users create an appropriate
query by creating an instance of a concrete subclasses of DatabaseQuery.

CascadeAggregateDelete

CascadeByMapping

DatabaseQuery

public DatabaseQuery()

Initialize the state of the query

Method Detail

addArgument

public void addArgument(java.lang.String argumentName)

Add the argument named argumentName.
This will cause the translation of references of argumentName in the receiver's expression,
with the value of the argument as supplied to the query in order from executeQuery()

addArgument

Add the argument named argumentName and its class type.
This will cause the translation of references of argumentName in the receiver's expression,
with the value of the argument as supplied to the query in order from executeQuery().
Specifying the class type is important if identically named queries are used but with
different argument lists.

addArgument

Add the argument named argumentName and its class type.
This will cause the translation of references of argumentName in the receiver's expression,
with the value of the argument as supplied to the query in order from executeQuery().
Specifying the class type is important if identically named queries are used but with
different argument lists.

addArgumentValue

public void addArgumentValue(java.lang.Object argumentValue)

Add the argumentValue.
Argument values must be added in the same order the arguments are defined.

addArgumentValues

public void addArgumentValues(java.util.Vector theArgumentValues)

Add the argumentValues to the query.
Argument values must be added in the same order the arguments are defined.

addStatement

Used to define a statement level query.
This may be used for multiple SQL executions to be mapped to a single query.
This cannot be used for cursored selects, delete alls or does exists.

bindAllParameters

public void bindAllParameters()

Bind all arguments to any SQL statement.

cacheStatement

public void cacheStatement()

Cache the prepared statements, this requires full parameter binding as well.

cascadeAllParts

public void cascadeAllParts()

Cascade the query and its properties on the queries object(s) and all objects related to the queries object(s).
This includes private and independent relationships, but not read-only relationships.
This will still stop on uninstantiated indirection objects except for deletion.
Great caution should be used in using the property as the query may effect a large number of objects.
This policy is used by the unit of work to ensure persistence by reachability.

cascadeByMapping

public void cascadeByMapping()

Cascade the query and its properties on the queries object(s) and all related objects where the mapping has
been set to cascade the merge.

cascadePrivateParts

public void cascadePrivateParts()

Cascade the query and its properties on the queries object(s)
and all privately owned objects related to the queries object(s).
This is the default for write and delete queries.
This policy should normally be used for refreshing, otherwise you could refresh half of any object.

dontBindAllParameters

public void dontBindAllParameters()

Do not Bind all arguments to any SQL statement.

dontCacheStatement

public void dontCacheStatement()

Dont cache the prepared statements, this requires full parameter binding as well.

dontCascadeParts

public void dontCascadeParts()

Do not cascade the query and its properties on the queries object(s) relationships.
This does not effect the queries private parts but only the object(s) direct row-level attributes.
This is the default for read queries and can be used in writting if it is known that only
row-level attributes changed, or to resolve circular foreign key dependencies.

dontMaintainCache

public void dontMaintainCache()

Set for the identity map (cache) to be ignored completely.
The cache check will be skipped and the result will not be put into the identity map.
This can be used to retreive the exact state of an object on the database.
By default the identity map is always maintained.

getCall

public DatabaseCall getCall()

OBSOLETE:
Return the call for this query.
This call contains the SQL and argument list.

getRedirector

Return the query redirector.
A redirector can be used in a query to replace its execution with the execution of code.
This can be used for named or parameterized queries to allow dynamic configuration of the query base on the query arguments.

getSQLStrings

public java.util.List getSQLStrings()

ADVANCED:
Return the SQL strings of the query. Used for queries with multiple calls
This can be used for SQL queries.
This can also be used for normal queries if they have been prepared, (i.e. query.prepareCall()).

getTranslatedSQLString

public java.lang.String getTranslatedSQLString(Session session,
Record translationRow)

ADVANCED:
This can be used to access a queries translated SQL if they have been prepared, (i.e. query.prepareCall()).
The Record argument is one of (Record, XMLRecord) that contains the query arguments.

maintainCache

prepareCall

ADVANCED:
Pre-generate the call/SQL for the query.
This method takes a Session and an implementor of Record (DatebaseRow or XMLRecord).
This can be used to access the SQL for a query without executing it.
To access the call use, query.getCall(), or query.getSQLString() for the SQL.
Note the SQL will have argument markers in it (i.e. "?").
To translate these use query.getTranslatedSQLString(session, translationRow).

setCall

setJPQLString

Set the JPQL string of the query.
If arguments are required in the string they will be preceeded by ":" then the argument name.
The JPQL arguments must also be added as argument to the query.

setEJBQLString

public void setEJBQLString(java.lang.String ejbqlString)

Set the EJBQL string of the query.
If arguments are required in the string they will be preceeded by "?" then the argument number.

setFlushOnExecute

public void setFlushOnExecute(java.lang.Boolean flushMode)

If executed against a RepeatableWriteUnitOfWork if this attribute is true
TopLink will write changes to the database before executing the query.

setHintString

public void setHintString(java.lang.String newHintString)

Used to set the database hint string on the query.
This should be the full hint string including the comment delimiters.
This method will cause a query to re-prepare if it has already been executed.

Parameters:

newHintString - the hint string to be added into the SQL call.

setName

public void setName(java.lang.String queryName)

Set the query's name.
Queries can be named and added to a descriptor or the session and then referenced by name.

setQueryTimeout

public void setQueryTimeout(int queryTimeout)

Set the number of seconds the driver will wait for a Statement to execute to the given number of seconds.
If the limit is exceeded, a DatabaseException is thrown.
queryTimeout - the new query timeout limit in seconds; DefaultTimeout is the default, which
redirects to DescriptorQueryManager's queryTimeout.

setRedirector

Set the query redirector.
A redirector can be used in a query to replace its execution with the execution of code.
This can be used for named or parameterized queries to allow dynamic configuration of the query base on the query arguments.

setShouldBindAllParameters

setShouldCacheStatement

Cache the prepared statements, this requires full parameter binding as well.

setShouldMaintainCache

public void setShouldMaintainCache(boolean shouldMaintainCache)

Set if the identity map (cache) should be used or not.
If not the cache check will be skipped and the result will not be put into the identity map.
By default the identity map is always maintained.

setShouldPrepare

public void setShouldPrepare(boolean shouldPrepare)

Set if the query should be prepared.
TopLink automatically prepares queries to generate their SQL only once,
one each execution of the query the SQL does not need to be generated again only the arguments need to be translated.
This option is provide to disable this optimization as in can cause problems with certain types of queries that require dynamic SQL basd on their arguments.

These queries include:

Expressions that make use of 'equal' where the argument value has the potential to be null, this can cause problems on databases that require IS NULL, instead of = NULL.

Expressions that make use of 'in' and that use parameter binding, this will cause problems as the in values must be bound individually.

setSQLStatement

To any user of this object. Set the SQL statement of the query.
This method should only be used when dealing with statement objects.

setSQLString

public void setSQLString(java.lang.String sqlString)

To any user of this object. Set the SQL string of the query.
This method should only be used when dealing with user defined SQL strings.
If arguments are required in the string they will be preceeded by "#" then the argument name.
Warning: Allowing an unverified SQL string to be passed into this
method makes your application vulnerable to SQL injection attacks.

shouldBindAllParameters

public boolean shouldBindAllParameters()

Bind all arguments to any SQL statement.

shouldCacheStatement

public boolean shouldCacheStatement()

Cache the prepared statements, this requires full parameter binding as well.

shouldCascadeAllParts

public boolean shouldCascadeAllParts()

Flag used to determine if all parts should be cascaded

shouldCascadeByMapping

public boolean shouldCascadeByMapping()

Mappings should be checked to determined if the current operation should be
cascaded to the objects referenced.

shouldCascadeParts

public boolean shouldCascadeParts()

Flag used to determine if any parts should be cascaded

shouldCascadePrivateParts

public boolean shouldCascadePrivateParts()

Flag used to determine if any private parts should be cascaded

shouldIgnoreBindAllParameters

public boolean shouldIgnoreBindAllParameters()

Local shouldBindAllParameters() should be ignored,
Session's shouldBindAllParameters() should be used.

shouldIgnoreCacheStatement

public boolean shouldIgnoreCacheStatement()

Local shouldCacheStatement() should be ignored,
Session's shouldCacheAllStatements() should be used.

shouldMaintainCache

public boolean shouldMaintainCache()

Return if the identity map (cache) should be used or not.
If not the cache check will be skipped and the result will not be put into the identity map.
By default the identity map is always maintained.

shouldPrepare

public boolean shouldPrepare()

Return if the query should be prepared.
TopLink automatically prepares queries to generate their SQL only once,
one each execution of the query the SQL does not need to be generated again only the arguments need to be translated.
This option is provide to disable this optimization as in can cause problems with certain types of queries that require dynamic SQL basd on their arguments.

These queries include:

Expressions that make use of 'equal' where the argument value has the potential to be null, this can cause problems on databases that require IS NULL, instead of = NULL.

Expressions that make use of 'in' and that use parameter binding, this will cause problems as the in values must be bound individually.