Top Description Fields Constructors Methods
org.eclipse.persistence.queries

public abstract Class ReadQuery

extends DatabaseQuery
Class Inheritance
Known Direct Subclasses
org.eclipse.persistence.queries.DataReadQuery, org.eclipse.persistence.queries.ObjectBuildingQuery
Imports
java.util.List, .Vector, org.eclipse.persistence.internal.databaseaccess.DatabasePlatform, .DatabaseCall, org.eclipse.persistence.internal.helper.NonSynchronizedVector, org.eclipse.persistence.internal.sessions.AbstractRecord, .AbstractSession, org.eclipse.persistence.sessions.DatabaseRecord, org.eclipse.persistence.exceptions.*

Purpose: Abstract class for all read queries.

Responsibilities:

Author
Yvon Lavoie
Since
TOPLink/Java 1.0

Field Summary

Modifier and TypeField and Description
protected boolean
allowQueryResultsCacheValidation

Flag that allows query result cache validation or not.

protected int
fetchSize

Used to set statement fetch size

protected int
firstResult

Used to start query results at a specific result

protected int
maxResults

Stores the JPA maxResult settings for a NamedQuery

protected int
maxRows

Used for retrieve limited rows through the query.

protected long
queryId

protected QueryResultsCachePolicy
queryResultCachingPolicy

Used to specify how query results are cached

protected transient Object
temporaryCachedQueryResults

Optimization: temporarily stores cached query results while they are being built in a cloned query

Inherited from org.eclipse.persistence.queries.DatabaseQuery:
accessorsallowNativeSQLQueryargumentFieldsargumentParameterTypesargumentsargumentTypeNamesargumentTypesargumentValuesBATCH_FETCH_PROPERTYCascadeAggregateDeleteCascadeAllPartsCascadeByMappingCascadeDependentPartscascadePolicyCascadePrivatePartsdescriptordescriptorsdoNotRedirectexecutionSessionflushOnExecutehintStringisCustomQueryUsedisExecutionCloneisNativeConnectionRequiredisPreparedisUserDefinedisUserDefinedSQLCallmonitorNamenameNoCascadingnullableArgumentsparameterDelimiterpartitioningPolicypropertiesqueryMechanismqueryTimeoutqueryTimeoutUnitredirectorsessionsessionNameshouldBindAllParametersshouldCacheStatementshouldCloneCallshouldMaintainCacheshouldPrepareshouldRetrieveBypassCacheshouldReturnGeneratedKeysshouldStoreBypassCacheshouldUseWrapperPolicyshouldValidateUpdateCallCacheUsesourceMappingtranslationRow

Constructor Summary

AccessConstructor and Description
protected
ReadQuery()

PUBLIC: Initialize the state of the query

Method Summary

Modifier and TypeMethod and Description
public Object
buildObject(AbstractRecord row)

INTERNAL: By default return the row.

public void
cacheQueryResults()

ADVANCED:

This method will instruct the query to cache the results returned by its next execution.

public abstract void
cacheResult(Object object)

INTERNAL:

This method is called by the object builder when building an original.

public void
clearQueryResults(AbstractSession session)

PUBLIC: Clears the current cached results, the next execution with read from the database.

protected void
clonedQueryExecutionComplete(DatabaseQuery query, AbstractSession session)

Overrides org.eclipse.persistence.queries.DatabaseQuery.clonedQueryExecutionComplete.

INTERNAL Used to give the subclasses opportunity to copy aspects of the cloned query to the original query.
public void
copyFromQuery(DatabaseQuery query)

Overrides org.eclipse.persistence.queries.DatabaseQuery.copyFromQuery.

INTERNAL: Copy all setting from the query.
public void
doNotCacheQueryResults()

ADVANCED:

This method will instruct the query not to cache results.

public int
getFetchSize()

PUBLIC: Return the fetchSize setting that this query will set on the JDBC Statement NB - a value of zero means that no call to statement.setFetchSize() will be made.

public int
getFirstResult()

PUBLIC: Return the value that will be set for the firstResult in the returned result set

public int

Returns:

the maxResults
getInternalMax()

INTERNAL: returns the JPA max results that may have been set on a NamedQuery

public int
getMaxRows()

PUBLIC: Return the limit for the maximum number of rows that any ResultSet can contain to the given number.

public long
getQueryId()

INTERNAL: This method is used to get the time in millis that this query is being executed at.

protected Object
getQueryResults(AbstractSession session)

INTERNAL: To any user of this object with some knowledge of what the query's results may contain.

protected Object
getQueryResults(AbstractSession session, boolean checkExpiry)

INTERNAL: To any user of this object with some knowledge of what the query's results may contain.

protected Object
getQueryResults(AbstractSession session, AbstractRecord row, boolean checkExpiry)

INTERNAL: To any user of this object with some knowledge of what the query's results may contain.

public QueryResultsCachePolicy
getQueryResultsCachePolicy()

PUBLIC: Return the QueryResultsCachePolicy for this query.

public Object
getTemporaryCachedQueryResults()

INTERNAL: Get results from the remporary cache.

public boolean
isDefaultPropertiesQuery()

Overrides org.eclipse.persistence.queries.DatabaseQuery.isDefaultPropertiesQuery.

INTERNAL: Return true if the query uses default properties.
public boolean
isReadQuery()

Overrides org.eclipse.persistence.queries.DatabaseQuery.isReadQuery.

PUBLIC: Return if this is a read query.
protected void
prepare()

Overrides org.eclipse.persistence.queries.DatabaseQuery.prepare.

INTERNAL: This is different from 'prepareForExecution' in that this is called on the original query, and the other is called on the copy of the query.
public void
prepareForExecution()

Overrides org.eclipse.persistence.queries.DatabaseQuery.prepareForExecution.

INTERNAL: Prepare the receiver for execution in a session.
public Object
remoteExecute(AbstractSession session)

Overrides org.eclipse.persistence.queries.DatabaseQuery.remoteExecute.

INTERNAL: Return if this is a read query.
public void
setAllowQueryResultsCacheValidation(boolean allowQueryResultsCacheValidation)

public void
setFetchSize(int fetchSize)

PUBLIC: Set the fetchSize setting that this query will set on the JDBC Statement NB - a value of zero means that no call to statement.setFetchSize() will be made.

public void
setFirstResult(int firstResult)

PUBLIC: Used to set the first result in any result set that is returned for this query.

public void
setInternalMax(int max)

INTERNAL: sets the JPA max results that may have been set on a NamedQuery

public void
setMaxRows(int maxRows)

PUBLIC: Used to set the limit for the maximum number of rows that any ResultSet can contain to the given number.

public void
setQueryId(long id)

INTERNAL: This method is used to set the current system time in millis that this query is being executed at.

protected void
setQueryResults(Object resultFromQuery, AbstractRecord row, AbstractSession session)

INTERNAL: Set the cached results of the query.

public void
setQueryResultsCachePolicy(QueryResultsCachePolicy policy)

Set the QueryResultsCachePolicy.

public void
setTemporaryCachedQueryResults(Object queryResults)

INTERNAL: Put results in the temporary cache.

public boolean
shouldAllowQueryResultsCacheValidation()

public boolean
shouldCacheQueryResults()

PUBLIC: Return if the query should cache the results of the next execution or not.

Inherited from org.eclipse.persistence.queries.DatabaseQuery:
addArgumentaddArgumentaddArgumentaddArgumentaddArgumentaddArgumentaddArgumentByTypeNameaddArgumentValueaddArgumentValuesaddCalladdStatementbindAllParametersbuildArgumentFieldsbuildSelectionCriteriacacheStatementcascadeAllPartscascadeByMappingcascadeOnlyDependentPartscascadePrivatePartscheckDescriptorcheckEarlyReturncheckForCustomQuerycheckPreparecheckPreparecloneconvertClassNamesToClassesdontBindAllParametersdontCacheStatementdontCascadePartsdontMaintainCacheexecuteexecuteDatabaseQueryexecuteInUnitOfWorkextractRemoteResultgetAccessorgetAccessorsgetArgumentParameterTypesgetArgumentsgetArgumentTypeNamesgetArgumentTypesgetArgumentValuesgetBatchObjectsgetCallgetCascadePolicygetDatasourceCallgetDatasourceCallsgetDefaultRedirectorgetDescriptorgetDescriptorsgetDomainClassNounNamegetDoNotRedirectgetEJBQLStringgetExecutionSessiongetFlushOnExecutegetHintStringgetJPQLStringgetMonitorNamegetNamegetNullableArgumentsgetParameterDelimitergetParameterDelimiterChargetPartitioningPolicygetPropertiesgetPropertygetQueryMechanismgetQueryNounNamegetQueryTimeoutgetQueryTimeoutUnitgetRedirectorgetRedirectorForQuerygetReferenceClassgetReferenceClassNamegetSelectionCriteriagetSensorNamegetSessiongetSessionNamegetShouldBindAllParametersgetSourceMappinggetSQLStatementgetSQLStringgetSQLStringsgetTranslatedSQLStringgetTranslatedSQLStringsgetTranslationRowhasAccessorhasArgumentshasNullableArgumentshasPropertieshasQueryMechanismhasSessionNameignoreBindAllParametersignoreCacheStatementisCallQueryisCascadeOfAggregateDeleteisCustomQueryUsedisCustomSelectionQueryisDataModifyQueryisDataReadQueryisDeleteAllQueryisDeleteObjectQueryisDirectReadQueryisExecutionCloneisExpressionQueryisInsertObjectQueryisJPQLCallQueryisModifyAllQueryisModifyQueryisNativeConnectionRequiredisObjectBuildingQueryisObjectLevelModifyQueryisObjectLevelReadQueryisPreparedisReadAllQueryisReadObjectQueryisReportQueryisResultSetMappingQueryisSQLCallQueryisUpdateAllQueryisUpdateObjectQueryisUserDefinedisUserDefinedSQLCallisValueReadQueryisWriteObjectQuerymaintainCacheprepareCallprepareCustomQueryprepareForRemoteExecutionprepareFromQueryprepareInternalredirectQueryremoteExecuteremovePropertyreplaceValueHoldersInresetMonitorNameretrieveBypassCacherowFromArgumentssetAccessorsetAccessorssetAllowNativeSQLQuerysetArgumentssetArgumentTypeNamessetArgumentTypessetArgumentValuessetBatchObjectssetCallsetCascadePolicysetDatasourceCallsetDescriptorsetDoNotRedirectsetEJBQLStringsetExecutionSessionsetFlushOnExecutesetHintStringsetIsCustomQueryUsedsetIsExecutionClonesetIsNativeConnectionRequiredsetIsPreparedsetIsUserDefinedsetIsUserDefinedSQLCallsetJPQLStringsetNamesetNullableArgumentssetParameterDelimitersetPartitioningPolicysetPropertiessetPropertysetQueryMechanismsetQueryTimeoutsetQueryTimeoutUnitsetRedirectorsetSelectionCriteriasetSessionsetSessionNamesetShouldBindAllParameterssetShouldBindAllParameterssetShouldCacheStatementsetShouldMaintainCachesetShouldPreparesetShouldRetrieveBypassCachesetShouldReturnGeneratedKeyssetShouldStoreBypassCachesetShouldUseWrapperPolicysetShouldValidateUpdateCallCacheUsesetSourceMappingsetSQLStatementsetSQLStringsetTranslationRowshouldAllowNativeSQLQueryshouldBindAllParametersshouldCacheStatementshouldCascadeAllPartsshouldCascadeByMappingshouldCascadeOnlyDependentPartsshouldCascadePartsshouldCascadePrivatePartsshouldCloneCallshouldIgnoreBindAllParametersshouldIgnoreCacheStatementshouldMaintainCacheshouldPrepareshouldPrepareshouldRetrieveBypassCacheshouldReturnGeneratedKeysshouldStoreBypassCacheshouldUseWrapperPolicyshouldValidateUpdateCallCacheUsestoreBypassCachetoString

Field Detail

allowQueryResultsCacheValidationback to summary
protected boolean allowQueryResultsCacheValidation

Flag that allows query result cache validation or not.

fetchSizeback to summary
protected int fetchSize

Used to set statement fetch size

firstResultback to summary
protected int firstResult

Used to start query results at a specific result

maxResultsback to summary
protected int maxResults

Stores the JPA maxResult settings for a NamedQuery

maxRowsback to summary
protected int maxRows

Used for retrieve limited rows through the query.

queryIdback to summary
protected long queryId
queryResultCachingPolicyback to summary
protected QueryResultsCachePolicy queryResultCachingPolicy

Used to specify how query results are cached

temporaryCachedQueryResultsback to summary
protected transient Object temporaryCachedQueryResults

Optimization: temporarily stores cached query results while they are being built in a cloned query

Constructor Detail

ReadQueryback to summary
protected ReadQuery()

PUBLIC: Initialize the state of the query

Method Detail

buildObjectback to summary
public Object buildObject(AbstractRecord row)

INTERNAL: By default return the row. Used by cursored stream.

cacheQueryResultsback to summary
public void cacheQueryResults()

ADVANCED:

This method will instruct the query to cache the results returned by its next execution. All subsequent executions of this query will return this cached result set even if new query parameters are specified. This method provides a performance enhancement for queries known to always return the same result set. Oracle recommends that you use this method only for such queries.

To disable this behavior, call doNotCacheQueryResults or setQueryResultsCachePolicy passing in null.

cacheResultback to summary
public abstract void cacheResult(Object object)

INTERNAL:

This method is called by the object builder when building an original. It will cause the original to be cached in the query results if the query is set to do so.

clearQueryResultsback to summary
public void clearQueryResults(AbstractSession session)

PUBLIC: Clears the current cached results, the next execution with read from the database.

clonedQueryExecutionCompleteback to summary
protected void clonedQueryExecutionComplete(DatabaseQuery query, AbstractSession session)

Overrides org.eclipse.persistence.queries.DatabaseQuery.clonedQueryExecutionComplete.

INTERNAL Used to give the subclasses opportunity to copy aspects of the cloned query to the original query.

Annotations
@Override
copyFromQueryback to summary
public void copyFromQuery(DatabaseQuery query)

Overrides org.eclipse.persistence.queries.DatabaseQuery.copyFromQuery.

INTERNAL: Copy all setting from the query. This is used to morph queries from one type to the other. By default this calls prepareFromQuery, but additional properties may be required to be copied as prepareFromQuery only copies properties that affect the SQL.

Annotations
@Override
doNotCacheQueryResultsback to summary
public void doNotCacheQueryResults()

ADVANCED:

This method will instruct the query not to cache results. All subsequent executions return result sets according to the current configuration of query parameters. After calling this method, any previously cached result set will be discarded the next time the query is executed.

To enable this behavior, call cacheQueryResults or setQueryResultsCachePolicy passing in a valid QueryResultsCachePolicy.

Note

If this method is called on a query that initially cached query results, clearQueryResults(Session) should also be called. Otherwise, the results of this query will remain in the cache and cause extra memory use

getFetchSizeback to summary
public int getFetchSize()

PUBLIC: Return the fetchSize setting that this query will set on the JDBC Statement NB - a value of zero means that no call to statement.setFetchSize() will be made.

getFirstResultback to summary
public int getFirstResult()

PUBLIC: Return the value that will be set for the firstResult in the returned result set

getInternalMaxback to summary
public int getInternalMax()

INTERNAL: returns the JPA max results that may have been set on a NamedQuery

Returns:int

the maxResults

getMaxRowsback to summary
public int getMaxRows()

PUBLIC: Return the limit for the maximum number of rows that any ResultSet can contain to the given number.

getQueryIdback to summary
public long getQueryId()

INTERNAL: This method is used to get the time in millis that this query is being executed at. it is set just prior to executing the SQL and will be used to determine which objects should be refreshed. CR #4365 CR #2698903 ... instead of using millis we will now use id's instead. Method renamed appropriately.

getQueryResultsback to summary
protected Object getQueryResults(AbstractSession session)

INTERNAL: To any user of this object with some knowledge of what the query's results may contain. Return the results of the query. If the query has never been executed, or does not cache results, the results will be null.

getQueryResultsback to summary
protected Object getQueryResults(AbstractSession session, boolean checkExpiry)

INTERNAL: To any user of this object with some knowledge of what the query's results may contain. Return the results of the query. If the query has never been executed, or does not cache results, the results will be null.

getQueryResultsback to summary
protected Object getQueryResults(AbstractSession session, AbstractRecord row, boolean checkExpiry)

INTERNAL: To any user of this object with some knowledge of what the query's results may contain. Return the results of the query. If the query has never been executed, or does not cache results, the results will be null.

getQueryResultsCachePolicyback to summary
public QueryResultsCachePolicy getQueryResultsCachePolicy()

PUBLIC: Return the QueryResultsCachePolicy for this query.

See Also
org.eclipse.persistence.queries.QueryResultsCachePolicy
getTemporaryCachedQueryResultsback to summary
public Object getTemporaryCachedQueryResults()

INTERNAL: Get results from the remporary cache. Used when caching query results on a clone so they can be copied to the original query

isDefaultPropertiesQueryback to summary
public boolean isDefaultPropertiesQuery()

Overrides org.eclipse.persistence.queries.DatabaseQuery.isDefaultPropertiesQuery.

INTERNAL: Return true if the query uses default properties. This is used to determine if this query is cacheable. i.e. does not use any properties that may conflict with another query with the same EJBQL or selection criteria.

Annotations
@Override
isReadQueryback to summary
public boolean isReadQuery()

Overrides org.eclipse.persistence.queries.DatabaseQuery.isReadQuery.

PUBLIC: Return if this is a read query.

Annotations
@Override
prepareback to summary
protected void prepare() throws QueryException

Overrides org.eclipse.persistence.queries.DatabaseQuery.prepare.

INTERNAL: This is different from 'prepareForExecution' in that this is called on the original query, and the other is called on the copy of the query. This query is copied for concurrency so this prepare can only setup things that will apply to any future execution of this query. Clear the query cache when a query is prepared.

Annotations
@Override
prepareForExecutionback to summary
public void prepareForExecution() throws QueryException

Overrides org.eclipse.persistence.queries.DatabaseQuery.prepareForExecution.

INTERNAL: Prepare the receiver for execution in a session.

Annotations
@Override
remoteExecuteback to summary
public Object remoteExecute(AbstractSession session) throws DatabaseException

Overrides org.eclipse.persistence.queries.DatabaseQuery.remoteExecute.

INTERNAL: Return if this is a read query.

Annotations
@Override
setAllowQueryResultsCacheValidationback to summary
public void setAllowQueryResultsCacheValidation(boolean allowQueryResultsCacheValidation)
setFetchSizeback to summary
public void setFetchSize(int fetchSize)

PUBLIC: Set the fetchSize setting that this query will set on the JDBC Statement NB - a value of zero means that no call to statement.setFetchSize() will be made.

setFirstResultback to summary
public void setFirstResult(int firstResult)

PUBLIC: Used to set the first result in any result set that is returned for this query. On supported database platforms this will cause the query to issue specific SQL that avoids selecting the firstResult number of rows. Otherwise by it will use the JDBC absolute to skip the firstResult number of rows.

setInternalMaxback to summary
public void setInternalMax(int max)

INTERNAL: sets the JPA max results that may have been set on a NamedQuery

setMaxRowsback to summary
public void setMaxRows(int maxRows)

PUBLIC: Used to set the limit for the maximum number of rows that any ResultSet can contain to the given number. This method should only be set once per query. To change the max rows use another query. This method limits the number of candidate results returned to TopLink that can be used to build objects

setQueryIdback to summary
public void setQueryId(long id)

INTERNAL: This method is used to set the current system time in millis that this query is being executed at. it is set just prior to executing the SQL and will be used to determine which objects should be refreshed. CR #4365 CR #2698903 ... instead of using millis we will now use id's instead. Method renamed appropriately.

setQueryResultsback to summary
protected void setQueryResults(Object resultFromQuery, AbstractRecord row, AbstractSession session)

INTERNAL: Set the cached results of the query. This will only be set if the query caches results.

setQueryResultsCachePolicyback to summary
public void setQueryResultsCachePolicy(QueryResultsCachePolicy policy)

Set the QueryResultsCachePolicy.

See Also
org.eclipse.persistence.queries.QueryResultsCachePolicy
setTemporaryCachedQueryResultsback to summary
public void setTemporaryCachedQueryResults(Object queryResults)

INTERNAL: Put results in the temporary cache. Used when caching query results on a clone so they can be copied to the original query

shouldAllowQueryResultsCacheValidationback to summary
public boolean shouldAllowQueryResultsCacheValidation()
shouldCacheQueryResultsback to summary
public boolean shouldCacheQueryResults()

PUBLIC: Return if the query should cache the results of the next execution or not.