EclipseLink1.0 - 20080707 API Reference

org.eclipse.persistence.queries
Class ReadQuery

java.lang.Object
  extended by org.eclipse.persistence.queries.DatabaseQuery
      extended by org.eclipse.persistence.queries.ReadQuery
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable
Direct Known Subclasses:
DataReadQuery, ObjectBuildingQuery

public abstract class ReadQuery
extends DatabaseQuery

Purpose: Abstract class for all read queries.

Responsibilities:

See Also:
Serialized Form
Author:
Yvon Lavoie
Since:
TOPLink/Java 1.0

Field Summary
protected  int fetchSize
          Used to set statement fetch size
protected  int firstResult
          Used to start query results at a specific result
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  java.lang.Object temporaryCachedQueryResults
          Optimization: temporarily stores cached query results while they are being built in a cloned query
 
Fields inherited from class org.eclipse.persistence.queries.DatabaseQuery
accessor, arguments, argumentTypeNames, argumentTypes, argumentValues, CascadeAggregateDelete, CascadeAllParts, CascadeByMapping, CascadeDependentParts, cascadePolicy, CascadePrivateParts, descriptor, doNotRedirect, executionSession, flushOnExecute, hintString, isCustomQueryUsed, isExecutionClone, isFromParseCache, isNativeConnectionRequired, isPrepared, isUserDefined, name, NoCascading, properties, queryMechanism, queryTimeout, redirector, session, sessionName, shouldBindAllParameters, shouldCacheStatement, shouldCloneCall, shouldMaintainCache, shouldPrepare, shouldUseWrapperPolicy, translationRow
 
Constructor Summary
ReadQuery()
          PUBLIC: Initialize the state of the query
 
Method Summary
 java.lang.Object buildObject(org.eclipse.persistence.internal.sessions.AbstractRecord row)
          INTERNAL: By default return the row.
 void cacheQueryResults()
          ADVANCED: This method will instruct the query to cache the results returned by its next execution.
abstract  void cacheResult(java.lang.Object object)
          INTERNAL: This method is called by the object builder when building an original.
 void clearQueryResults(org.eclipse.persistence.internal.sessions.AbstractSession session)
          PUBLIC: Clears the current cached results, the next execution with read from the database.
protected  void clonedQueryExecutionComplete(DatabaseQuery query, org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL Used to give the subclasses oportunity to copy aspects of the cloned query to the original query.
 void copyFromQuery(DatabaseQuery query)
          INTERNAL: Copy all setting from the query.
 void doNotCacheQueryResults()
          ADVANCED: This method will instruct the query not to cache results.
 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.
 int getFirstResult()
          PUBLIC: Return the value that will be set for the firstResult in the returned result set
 int getMaxRows()
          PUBLIC: Return the limit for the maximum number of rows that any ResultSet can contain to the given number.
 long getQueryId()
          INTERNAL: This method is used to get the time in millis that this query is being executed at.
protected  java.lang.Object getQueryResults(org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: To any user of this object with some knowledge of what the query's results may contain.
protected  java.lang.Object getQueryResults(org.eclipse.persistence.internal.sessions.AbstractSession session, org.eclipse.persistence.internal.sessions.AbstractRecord row, boolean checkExpiry)
          INTERNAL: To any user of this object with some knowledge of what the query's results may contain.
protected  java.lang.Object getQueryResults(org.eclipse.persistence.internal.sessions.AbstractSession session, boolean checkExpiry)
          INTERNAL: To any user of this object with some knowledge of what the query's results may contain.
 QueryResultsCachePolicy getQueryResultsCachePolicy()
          PUBLIC: Return the QueryResultsCachePolicy for this query.
 java.lang.Object getTemporaryCachedQueryResults()
          INTERNAL: Get results from the remporary cache.
 boolean isDefaultPropertiesQuery()
          INTERNAL: Return true if the query uses default properties.
 boolean isReadQuery()
          PUBLIC: Return if this is a read query.
protected  void 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.
 void prepareForExecution()
          INTERNAL: Prepare the receiver for execution in a session.
 java.lang.Object remoteExecute(org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: Return if this is a read query.
 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.
 void setFirstResult(int firstResult)
          PUBLIC: Used to set the first result in any result set that is returned for this query.
 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.
 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(java.lang.Object resultFromQuery, org.eclipse.persistence.internal.sessions.AbstractRecord row, org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: Set the cached results of the query.
protected  void setQueryResults(java.lang.Object resultFromQuery, org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: Set the cached results of the query.
 void setQueryResultsCachePolicy(QueryResultsCachePolicy policy)
          Set the QueryResultsCachePolicy.
 void setTemporaryCachedQueryResults(java.lang.Object queryResults)
          INTERNAL: Put results in the temporary cache.
 boolean shouldCacheQueryResults()
          PUBLIC: Return if the query should cache the results of the next execution or not.
 
Methods inherited from class org.eclipse.persistence.queries.DatabaseQuery
addArgument, addArgument, addArgument, addArgumentByTypeName, addArgumentValue, addArgumentValues, addCall, addStatement, bindAllParameters, buildSelectionCriteria, cacheStatement, cascadeAllParts, cascadeByMapping, cascadeOnlyDependentParts, cascadePrivateParts, checkDescriptor, checkEarlyReturn, checkForCustomQuery, checkPrepare, checkPrepare, clone, convertClassNamesToClasses, dontBindAllParameters, dontCacheStatement, dontCascadeParts, dontMaintainCache, execute, executeDatabaseQuery, executeInUnitOfWork, extractRemoteResult, getAccessor, getArguments, getArgumentTypeNames, getArgumentTypes, getArgumentValues, getCall, getCascadePolicy, getDatasourceCall, getDatasourceCalls, getDefaultRedirector, getDescriptor, getDomainClassNounName, getDoNotRedirect, getEJBQLString, getExecutionSession, getFlushOnExecute, getHintString, getJPQLString, getName, getProperties, getProperty, getQueryMechanism, getQueryNounName, getQueryTimeout, getRedirector, getReferenceClass, getReferenceClassName, getSelectionCriteria, getSensorName, getSession, getSessionName, getShouldBindAllParameters, getSQLStatement, getSQLString, getSQLStrings, getTranslatedSQLString, getTranslatedSQLStrings, getTranslationRow, hasAccessor, hasArguments, hasProperties, hasQueryMechanism, hasSessionName, ignoreBindAllParameters, ignoreCacheStatement, isCallQuery, isCascadeOfAggregateDelete, isCustomQueryUsed, isCustomSelectionQuery, isDataModifyQuery, isDataReadQuery, isDeleteAllQuery, isDeleteObjectQuery, isDirectReadQuery, isExecutionClone, isExpressionQuery, isFromParseCache, isInsertObjectQuery, isModifyAllQuery, isModifyQuery, isNativeConnectionRequired, isObjectBuildingQuery, isObjectLevelModifyQuery, isObjectLevelReadQuery, isPrepared, isReadAllQuery, isReadObjectQuery, isReportQuery, isSQLCallQuery, isUpdateAllQuery, isUpdateObjectQuery, isUserDefined, isValueReadQuery, isWriteObjectQuery, maintainCache, prepareCall, prepareCustomQuery, prepareForRemoteExecution, prepareFromQuery, redirectQuery, remoteExecute, removeProperty, replaceValueHoldersIn, rowFromArguments, setAccessor, setArguments, setArgumentTypeNames, setArgumentTypes, setArgumentValues, setCall, setCascadePolicy, setDatasourceCall, setDescriptor, setDoNotRedirect, setEJBQLString, setExecutionSession, setFlushOnExecute, setHintString, setIsCustomQueryUsed, setIsExecutionClone, setIsFromParseCache, setIsNativeConnectionRequired, setIsPrepared, setIsUserDefined, setJPQLString, setName, setProperties, setProperty, setQueryMechanism, setQueryTimeout, setRedirector, setSelectionCriteria, setSession, setSessionName, setShouldBindAllParameters, setShouldBindAllParameters, setShouldCacheStatement, setShouldMaintainCache, setShouldPrepare, setShouldUseWrapperPolicy, setSQLStatement, setSQLString, setTranslationRow, shouldBindAllParameters, shouldCacheStatement, shouldCascadeAllParts, shouldCascadeByMapping, shouldCascadeOnlyDependentParts, shouldCascadeParts, shouldCascadePrivateParts, shouldCloneCall, shouldIgnoreBindAllParameters, shouldIgnoreCacheStatement, shouldMaintainCache, shouldPrepare, shouldUseWrapperPolicy, toString
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

maxRows

protected int maxRows
Used for retrieve limited rows through the query.


firstResult

protected int firstResult
Used to start query results at a specific result


queryId

protected long queryId

fetchSize

protected int fetchSize
Used to set statement fetch size


queryResultCachingPolicy

protected QueryResultsCachePolicy queryResultCachingPolicy
Used to specify how query results are cached


temporaryCachedQueryResults

protected transient java.lang.Object temporaryCachedQueryResults
Optimization: temporarily stores cached query results while they are being built in a cloned query

Constructor Detail

ReadQuery

public ReadQuery()
PUBLIC: Initialize the state of the query

Method Detail

buildObject

public java.lang.Object buildObject(org.eclipse.persistence.internal.sessions.AbstractRecord row)
INTERNAL: By default return the row. Used by cursored stream.


cacheQueryResults

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(org.eclipse.persistence.queries.QueryResultsCachePolicy) passing in null.


cacheResult

public abstract void cacheResult(java.lang.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.


clonedQueryExecutionComplete

protected void clonedQueryExecutionComplete(DatabaseQuery query,
                                            org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL Used to give the subclasses oportunity to copy aspects of the cloned query to the original query.

Overrides:
clonedQueryExecutionComplete in class DatabaseQuery

clearQueryResults

public void clearQueryResults(org.eclipse.persistence.internal.sessions.AbstractSession session)
PUBLIC: Clears the current cached results, the next execution with read from the database.


doNotCacheQueryResults

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(org.eclipse.persistence.queries.QueryResultsCachePolicy) 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


getQueryResultsCachePolicy

public QueryResultsCachePolicy getQueryResultsCachePolicy()
PUBLIC: Return the QueryResultsCachePolicy for this query.

See Also:
QueryResultsCachePolicy

getFirstResult

public int getFirstResult()
PUBLIC: Return the value that will be set for the firstResult in the returned result set


getQueryId

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.


getMaxRows

public int getMaxRows()
PUBLIC: Return the limit for the maximum number of rows that any ResultSet can contain to the given number.


getFetchSize

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.


getQueryResults

protected java.lang.Object getQueryResults(org.eclipse.persistence.internal.sessions.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.


getQueryResults

protected java.lang.Object getQueryResults(org.eclipse.persistence.internal.sessions.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.


getQueryResults

protected java.lang.Object getQueryResults(org.eclipse.persistence.internal.sessions.AbstractSession session,
                                           org.eclipse.persistence.internal.sessions.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.


getTemporaryCachedQueryResults

public java.lang.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


isDefaultPropertiesQuery

public boolean 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.

Overrides:
isDefaultPropertiesQuery in class DatabaseQuery

isReadQuery

public boolean isReadQuery()
PUBLIC: Return if this is a read query.

Overrides:
isReadQuery in class DatabaseQuery

copyFromQuery

public void copyFromQuery(DatabaseQuery query)
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.

Overrides:
copyFromQuery in class DatabaseQuery

prepare

protected void prepare()
                throws QueryException
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.

Overrides:
prepare in class DatabaseQuery
Throws:
QueryException

prepareForExecution

public void prepareForExecution()
                         throws QueryException
INTERNAL: Prepare the receiver for execution in a session.

Overrides:
prepareForExecution in class DatabaseQuery
Throws:
QueryException

remoteExecute

public java.lang.Object remoteExecute(org.eclipse.persistence.internal.sessions.AbstractSession session)
                               throws DatabaseException
INTERNAL: Return if this is a read query.

Overrides:
remoteExecute in class DatabaseQuery
Throws:
DatabaseException

setQueryResultsCachePolicy

public void setQueryResultsCachePolicy(QueryResultsCachePolicy policy)
Set the QueryResultsCachePolicy.

See Also:
QueryResultsCachePolicy

setFirstResult

public void setFirstResult(int firstResult)
PUBLIC: Used to set the first result in any result set that is returned for this query. This method should only be set once per query. To change the firstReslt use another query. This method will call the absolute method on the JDBC result set to move the initial row used by TopLink. Note: The set of results returned from the database will still include the results before the first result. TopLink will just not use them for object building.


setQueryId

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.


setMaxRows

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


setFetchSize

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.


setQueryResults

protected void setQueryResults(java.lang.Object resultFromQuery,
                               org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL: Set the cached results of the query. This will only be set if the query caches results.


setQueryResults

protected void setQueryResults(java.lang.Object resultFromQuery,
                               org.eclipse.persistence.internal.sessions.AbstractRecord row,
                               org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL: Set the cached results of the query. This will only be set if the query caches results.


shouldCacheQueryResults

public boolean shouldCacheQueryResults()
PUBLIC: Return if the query should cache the results of the next execution or not.


setTemporaryCachedQueryResults

public void setTemporaryCachedQueryResults(java.lang.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


EclipseLink1.0 - 20080707 API Reference