org.eclipse.persistence.queries
Class ReadObjectQuery

java.lang.Object
  extended by org.eclipse.persistence.queries.DatabaseQuery
      extended by org.eclipse.persistence.queries.ReadQuery
          extended by org.eclipse.persistence.queries.ObjectBuildingQuery
              extended by org.eclipse.persistence.queries.ObjectLevelReadQuery
                  extended by org.eclipse.persistence.queries.ReadObjectQuery
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable

public class ReadObjectQuery
extends ObjectLevelReadQuery

Purpose: Concrete class for all read queries involving a single object.

Responsibilities: Return a single object for the query. Implements the inheritance feature when dealing with abstract descriptors.

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

Field Summary
 
Fields inherited from class org.eclipse.persistence.queries.ObjectLevelReadQuery
CheckCacheByExactPrimaryKey, CheckCacheByPrimaryKey, CheckCacheOnly, CheckCacheThenDatabase, ConformResultsInUnitOfWork, DoNotCheckCache, DONT_USE_DISTINCT, NONE, OPTIMISTIC, OPTIMISTIC_FORCE_INCREMENT, PESSIMISTIC_, PESSIMISTIC_FORCE_INCREMENT, PESSIMISTIC_READ, PESSIMISTIC_WRITE, READ, UNCOMPUTED_DISTINCT, USE_DISTINCT, UseDescriptorSetting, WRITE
 
Fields inherited from class org.eclipse.persistence.queries.ObjectBuildingQuery
DEFAULT_LOCK_MODE, LOCK, LOCK_NOWAIT, LOCK_RESULT_PROPERTY, NO_LOCK
 
Fields inherited from class org.eclipse.persistence.queries.DatabaseQuery
CascadeAggregateDelete, CascadeAllParts, CascadeByMapping, CascadeDependentParts, CascadePrivateParts, NoCascading
 
Constructor Summary
ReadObjectQuery()
          PUBLIC: Return a new read object query.
ReadObjectQuery(Call call)
          PUBLIC: Return a new read object query.
ReadObjectQuery(java.lang.Class classToRead)
          PUBLIC: Return a new read object query.
ReadObjectQuery(java.lang.Class classToRead, Call call)
          PUBLIC: Return a new read object query.
ReadObjectQuery(java.lang.Class classToRead, Expression selectionCriteria)
          PUBLIC: Return a new read object query for the class and the selection criteria.
ReadObjectQuery(java.lang.Class classToRead, ExpressionBuilder builder)
          PUBLIC: Return a new read object query for the class.
ReadObjectQuery(ExpressionBuilder builder)
          PUBLIC: The expression builder should be provide on creation to ensure only one is used.
ReadObjectQuery(java.lang.Object objectToRead)
          PUBLIC: Return a query to read the object with the same primary key as the provided object.
ReadObjectQuery(java.lang.Object exampleObject, QueryByExamplePolicy policy)
          PUBLIC: Return a query by example query to find an object matching the attributes of the example object.
 
Method Summary
 void cacheResult(java.lang.Object unwrappedOriginal)
          INTERNAL:
 void checkCacheByExactPrimaryKey()
          PUBLIC: The cache will be checked only if the query contains exactly the primary key.
 void checkCacheByPrimaryKey()
          PUBLIC: This is the default, the cache will be checked only if the query contains the primary key.
 void checkCacheThenDatabase()
          PUBLIC: The cache will be checked completely, then if the object is not found or the query too complex the database will be queried.
 void checkDescriptor(org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: Ensure that the descriptor has been set.
 void copyFromQuery(DatabaseQuery query)
          INTERNAL: Copy all setting from the query.
 void dontLoadResultIntoSelectionObject()
          PUBLIC: Do not refesh/load into the selection object, this is the default.
 java.lang.Object execute(org.eclipse.persistence.internal.sessions.AbstractSession session, org.eclipse.persistence.internal.sessions.AbstractRecord row)
          INTERNAL: Execute the query.
 java.lang.Object extractRemoteResult(org.eclipse.persistence.internal.sessions.remote.Transporter transporter)
          INTERNAL: Extract the correct query result from the transporter.
 java.util.Vector getSelectionKey()
          PUBLIC: The primary key can be specified if used instead of an expression or selection object.
 java.lang.Object getSelectionObject()
          PUBLIC: Return the selection object of the query.
 boolean isPrimaryKeyQuery()
          INTERNAL: Return if the query is by primary key.
 boolean isReadObjectQuery()
          PUBLIC: Return if this is a read object query.
 void loadResultIntoSelectionObject()
          PUBLIC: Allow for the selection object of the query to be refreshed or put into the EclipseLink cache.
 void prepareForExecution()
          INTERNAL: Prepare the receiver for execution in a session.
 java.lang.Object registerResultInUnitOfWork(java.lang.Object result, org.eclipse.persistence.internal.sessions.UnitOfWorkImpl unitOfWork, org.eclipse.persistence.internal.sessions.AbstractRecord arguments, boolean buildDirectlyFromRows)
          INTERNAL: All objects queried via a UnitOfWork get registered here.
 java.util.Map replaceValueHoldersIn(java.lang.Object object, org.eclipse.persistence.internal.sessions.remote.RemoteSessionController controller)
          INTERNAL: replace the value holders in the specified result object(s)
 void setSelectionKey(java.util.List selectionKey)
          PUBLIC: The primary key can be specified if used instead of an expression or selection object.
 void setSelectionObject(java.lang.Object selectionObject)
          PUBLIC: Used to set the where clause of the query.
 void setShouldLoadResultIntoSelectionObject(boolean shouldLoadResultIntoSelectionObject)
          PUBLIC: Allow for the selection object of the query to be refreshed or put into the EclipseLink cache.
 void setSingletonSelectionKey(java.lang.Object selectionKey)
          PUBLIC: The primary key can be specified if used instead of an expression or selection object.
 boolean shouldCheckCache()
          PUBLIC: Return if the cache should be checked.
 boolean shouldCheckCacheByExactPrimaryKey()
          PUBLIC: Return if cache should be checked.
 boolean shouldCheckCacheByPrimaryKey()
          PUBLIC: Return if cache should be checked.
 boolean shouldCheckCacheThenDatabase()
          PUBLIC: Return if cache should be checked.
 boolean shouldLoadResultIntoSelectionObject()
          PUBLIC: return true if the result should be loaded into the passed in selection Object
 
Methods inherited from class org.eclipse.persistence.queries.ObjectLevelReadQuery
acquireLocks, acquireLocksWithoutWaiting, addAdditionalField, addAdditionalField, addDescendingOrdering, addJoinedAttribute, addJoinedAttribute, addNonFetchJoinedAttribute, addNonFetchJoinedAttribute, addOrdering, addPartialAttribute, addPartialAttribute, buildObject, changeDescriptor, checkCacheOnly, checkEarlyReturn, checkPrepare, clone, conformResultsInUnitOfWork, deepClone, dontAcquireLocks, dontCheckCache, dontRefreshIdentityMapResult, dontRefreshRemoteIdentityMapResult, dontUseDistinct, equals, executeDatabaseQuery, executeInUnitOfWork, extendPessimisticLockScope, getAdditionalFields, getAsOfClause, getCacheUsage, getConcreteSubclassCalls, getDistinctState, getExampleObject, getExecutionTime, getExpressionBuilder, getFetchGroup, getFetchGroupName, getFetchGroupSelectionFields, getInMemoryQueryIndirectionPolicy, getInMemoryQueryIndirectionPolicyState, getJoinedAttributeExpressions, getJoinedAttributeManager, getLeafDescriptorFor, getLeafMappingFor, getLockingClause, getLockMode, getNonFetchJoinAttributeExpressions, getOrderByExpressions, getPartialAttributeExpressions, getPartialAttributeSelectionFields, getQueryByExamplePolicy, getReferenceClass, getReferenceClassName, getSelectionFields, getWaitTimeout, hasAdditionalFields, hasAsOfClause, hasDefaultBuilder, hasFetchGroup, hashCode, hasJoining, hasNonFetchJoinedAttributeExpressions, hasOrderByExpressions, hasPartialAttributeExpressions, initializeFetchGroup, isClonePessimisticLocked, isDefaultLock, isDefaultPropertiesQuery, isDistinctComputed, isFetchGroupAttribute, isLockQuery, isLockQuery, isObjectLevelReadQuery, isPartialAttribute, isReadOnly, isResultSetOptimizedQuery, prepareFromQuery, prepareOutsideUnitOfWork, recordCloneForPessimisticLocking, refreshIdentityMapResult, refreshRemoteIdentityMapResult, resetDistinct, setAdditionalFields, setAsOfClause, setCacheUsage, setDescriptor, setDistinctState, setEJBQLString, setExampleObject, setExecutionTime, setExpressionBuilder, setFetchGroup, setFetchGroupName, setInMemoryQueryIndirectionPolicy, setInMemoryQueryIndirectionPolicyState, setIsPrepared, setIsReadOnly, setIsResultSetOptimizedQuery, setJoinedAttributeExpressions, setJoinedAttributeManager, setLockingClause, setLockMode, setLockModeType, setOrderByExpressions, setPartialAttributeExpressions, setQueryByExamplePolicy, setReferenceClass, setReferenceClassName, setSelectionCriteria, setShouldExtendPessimisticLockScope, setShouldFilterDuplicates, setShouldIncludeData, setShouldOuterJoinSubclasses, setShouldProcessResultsInUnitOfWork, setShouldRefreshIdentityMapResult, setShouldRefreshRemoteIdentityMapResult, setShouldRegisterResultsInUnitOfWork, setShouldUseDefaultFetchGroup, setWaitTimeout, shouldCheckCacheOnly, shouldCheckDescriptorForCacheUsage, shouldConformResultsInUnitOfWork, shouldDistinctBeUsed, shouldExtendPessimisticLockScope, shouldFilterDuplicates, shouldIncludeData, shouldOuterJoinSubclasses, shouldProcessResultsInUnitOfWork, shouldReadAllMappings, shouldReadMapping, shouldRefreshIdentityMapResult, shouldRefreshRemoteIdentityMapResult, shouldRegisterResultsInUnitOfWork, shouldUseDefaultFetchGroup, useDistinct
 
Methods inherited from class org.eclipse.persistence.queries.ObjectBuildingQuery
convertClassNamesToClasses, getDataResults, isAttributeJoined, isObjectBuildingQuery, registerIndividualResult, setShouldBuildNullForNullPk, setShouldUseExclusiveConnection, shouldBuildNullForNullPk, shouldUseExclusiveConnection
 
Methods inherited from class org.eclipse.persistence.queries.ReadQuery
cacheQueryResults, clearQueryResults, doNotCacheQueryResults, getFetchSize, getFirstResult, getMaxRows, getQueryId, getQueryResultsCachePolicy, getTemporaryCachedQueryResults, isReadQuery, remoteExecute, setFetchSize, setFirstResult, setMaxRows, setQueryId, setQueryResultsCachePolicy, setTemporaryCachedQueryResults, shouldCacheQueryResults
 
Methods inherited from class org.eclipse.persistence.queries.DatabaseQuery
addArgument, addArgument, addArgument, addArgumentByTypeName, addArgumentValue, addArgumentValues, addCall, addStatement, bindAllParameters, buildArgumentFields, cacheStatement, cascadeAllParts, cascadeByMapping, cascadeOnlyDependentParts, cascadePrivateParts, checkPrepare, dontBindAllParameters, dontCacheStatement, dontCascadeParts, dontMaintainCache, getAccessor, getArguments, getArgumentTypeNames, getArgumentTypes, getArgumentValues, getCall, getCascadePolicy, getDatasourceCall, getDatasourceCalls, getDescriptor, getDomainClassNounName, getDoNotRedirect, getEJBQLString, getExecutionSession, getFlushOnExecute, getHintString, getJPQLString, getName, getProperties, getProperty, getQueryMechanism, getQueryNounName, getQueryTimeout, getRedirector, getSelectionCriteria, getSensorName, getSession, getSessionName, getShouldBindAllParameters, getSourceMapping, getSQLStatement, getSQLString, getSQLStrings, getTranslatedSQLString, getTranslatedSQLStrings, getTranslationRow, hasAccessor, hasArguments, hasProperties, hasQueryMechanism, hasSessionName, ignoreBindAllParameters, ignoreCacheStatement, isCallQuery, isCascadeOfAggregateDelete, isCustomQueryUsed, isDataModifyQuery, isDataReadQuery, isDeleteAllQuery, isDeleteObjectQuery, isDirectReadQuery, isExecutionClone, isExpressionQuery, isInsertObjectQuery, isJPQLCallQuery, isModifyAllQuery, isModifyQuery, isNativeConnectionRequired, isObjectLevelModifyQuery, isPrepared, isReadAllQuery, isReportQuery, isSQLCallQuery, isUpdateAllQuery, isUpdateObjectQuery, isUserDefined, isValueReadQuery, isWriteObjectQuery, maintainCache, prepareCall, redirectQuery, removeProperty, retrieveBypassCache, rowFromArguments, setAccessor, setArguments, setArgumentTypeNames, setArgumentTypes, setArgumentValues, setCall, setCascadePolicy, setDatasourceCall, setDoNotRedirect, setFlushOnExecute, setHintString, setIsExecutionClone, setIsNativeConnectionRequired, setIsUserDefined, setJPQLString, setName, setProperties, setProperty, setQueryTimeout, setRedirector, setSession, setSessionName, setShouldBindAllParameters, setShouldBindAllParameters, setShouldCacheStatement, setShouldMaintainCache, setShouldPrepare, setShouldRetrieveBypassCache, setShouldStoreBypassCache, setShouldUseWrapperPolicy, setSourceMapping, setSQLStatement, setSQLString, setTranslationRow, shouldBindAllParameters, shouldCacheStatement, shouldCascadeAllParts, shouldCascadeByMapping, shouldCascadeOnlyDependentParts, shouldCascadeParts, shouldCascadePrivateParts, shouldCloneCall, shouldIgnoreBindAllParameters, shouldIgnoreCacheStatement, shouldMaintainCache, shouldPrepare, shouldRetrieveBypassCache, shouldStoreBypassCache, shouldUseWrapperPolicy, storeBypassCache, toString
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ReadObjectQuery

public ReadObjectQuery()
PUBLIC: Return a new read object query. A reference class must be specified before execution. It is better to provide the class and expression builder on construction to esnure a single expression builder is used. If no selection criteria is specified this will reads the first object found in the database.


ReadObjectQuery

public ReadObjectQuery(java.lang.Class classToRead)
PUBLIC: Return a new read object query. By default, the query has no selection criteria. Executing this query without selection criteria will always result in a database access to read the first instance of the specified Class found in the database. This is true no matter how cache usage is configured and even if an instance of the specified Class exists in the cache. Executing a query with selection criteria allows you to avoid a database access if the selected instance is in the cache. For this reason, you may whish to use a ReadObjectQuery constructor that takes selection criteria, such as: ReadObjectQuery(Class, Call), ReadObjectQuery(Class, Expression), ReadObjectQuery(Class, ExpressionBuilder), ReadObjectQuery(ExpressionBuilder), ReadObjectQuery(Object), or ReadObjectQuery(Object, QueryByExamplePolicy).


ReadObjectQuery

public ReadObjectQuery(java.lang.Class classToRead,
                       Expression selectionCriteria)
PUBLIC: Return a new read object query for the class and the selection criteria.


ReadObjectQuery

public ReadObjectQuery(java.lang.Class classToRead,
                       ExpressionBuilder builder)
PUBLIC: Return a new read object query for the class. The expression builder must be used for all associated expressions used with the query.


ReadObjectQuery

public ReadObjectQuery(java.lang.Class classToRead,
                       Call call)
PUBLIC: Return a new read object query. The call represents a database interaction such as SQL, Stored Procedure.


ReadObjectQuery

public ReadObjectQuery(Call call)
PUBLIC: Return a new read object query. The call represents a database interaction such as SQL, Stored Procedure.


ReadObjectQuery

public ReadObjectQuery(java.lang.Object objectToRead)
PUBLIC: Return a query to read the object with the same primary key as the provided object. Note: This is not a query by example object, only the primary key will be used for the selection criteria.


ReadObjectQuery

public ReadObjectQuery(java.lang.Object exampleObject,
                       QueryByExamplePolicy policy)
PUBLIC: Return a query by example query to find an object matching the attributes of the example object.


ReadObjectQuery

public ReadObjectQuery(ExpressionBuilder builder)
PUBLIC: The expression builder should be provide on creation to ensure only one is used.

Method Detail

cacheResult

public void cacheResult(java.lang.Object unwrappedOriginal)
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.

Specified by:
cacheResult in class ReadQuery

checkCacheByExactPrimaryKey

public void checkCacheByExactPrimaryKey()
PUBLIC: The cache will be checked only if the query contains exactly the primary key. Queries can be configured to use the cache at several levels. Other caching option are available.

See Also:
ObjectLevelReadQuery.setCacheUsage(int)

checkCacheByPrimaryKey

public void checkCacheByPrimaryKey()
PUBLIC: This is the default, the cache will be checked only if the query contains the primary key. Queries can be configured to use the cache at several levels. Other caching option are available.

See Also:
ObjectLevelReadQuery.setCacheUsage(int)

checkCacheThenDatabase

public void checkCacheThenDatabase()
PUBLIC: The cache will be checked completely, then if the object is not found or the query too complex the database will be queried. Queries can be configured to use the cache at several levels. Other caching option are available.

See Also:
ObjectLevelReadQuery.setCacheUsage(int)

checkDescriptor

public void checkDescriptor(org.eclipse.persistence.internal.sessions.AbstractSession session)
                     throws QueryException
INTERNAL: Ensure that the descriptor has been set.

Overrides:
checkDescriptor in class ObjectLevelReadQuery
Throws:
QueryException

dontLoadResultIntoSelectionObject

public void dontLoadResultIntoSelectionObject()
PUBLIC: Do not refesh/load into the selection object, this is the default. This property allows for the selection object of the query to be refreshed or put into the TopLink cache. By default on a read or refresh the object in the cache is refreshed and returned or a new object is built from the database, in some cases such as EJB BMP it is desirable to refresh or load into the object passed into the read object query.

Note: This forces the selection object into the cache a replaces any existing object that may already be there, this is a strict violation of object identity and other objects can still be refering to the old object.


execute

public java.lang.Object execute(org.eclipse.persistence.internal.sessions.AbstractSession session,
                                org.eclipse.persistence.internal.sessions.AbstractRecord row)
                         throws DatabaseException
INTERNAL: Execute the query. If there are cached results return those. This must override the super to support result caching.

Overrides:
execute in class ObjectLevelReadQuery
Parameters:
session - the session in which the receiver will be executed.
Returns:
An object or vector, the result of executing the query.
Throws:
DatabaseException - - an error has occurred on the database

extractRemoteResult

public java.lang.Object extractRemoteResult(org.eclipse.persistence.internal.sessions.remote.Transporter transporter)
INTERNAL: Extract the correct query result from the transporter.

Overrides:
extractRemoteResult in class DatabaseQuery

getSelectionKey

public java.util.Vector getSelectionKey()
PUBLIC: The primary key can be specified if used instead of an expression or selection object. If composite the primary must be in the same order as defined in the descriptor.


getSelectionObject

public java.lang.Object getSelectionObject()
PUBLIC: Return the selection object of the query. This can be used instead of a where clause expression for single object primary key queries. The selection object given should have a primary key defined, this primary key will be used to query the database instance of the same object. This is a basic form of query by example where only the primary key is required, it can be used for simple query forms, or testing.


isReadObjectQuery

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

Overrides:
isReadObjectQuery in class DatabaseQuery

isPrimaryKeyQuery

public boolean isPrimaryKeyQuery()
INTERNAL: Return if the query is by primary key.

Overrides:
isPrimaryKeyQuery in class ObjectLevelReadQuery

loadResultIntoSelectionObject

public void loadResultIntoSelectionObject()
PUBLIC: Allow for the selection object of the query to be refreshed or put into the EclipseLink cache. By default on a read or refresh the object in the cache is refreshed and returned or a new object is built from the database, in some cases such as EJB BMP it is desirable to refresh or load into the object passed into the read object query.

Note: This forces the selection object into the cache a replaces any existing object that may already be there, this is a strict violation of object identity and other objects can still be referring to the old object.


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 ObjectLevelReadQuery

prepareForExecution

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

Overrides:
prepareForExecution in class ReadQuery
Throws:
QueryException

registerResultInUnitOfWork

public java.lang.Object registerResultInUnitOfWork(java.lang.Object result,
                                                   org.eclipse.persistence.internal.sessions.UnitOfWorkImpl unitOfWork,
                                                   org.eclipse.persistence.internal.sessions.AbstractRecord arguments,
                                                   boolean buildDirectlyFromRows)
INTERNAL: All objects queried via a UnitOfWork get registered here. If the query went to the database.

Involves registering the query result individually and in totality, and hence refreshing / conforming is done here.

Specified by:
registerResultInUnitOfWork in class ObjectLevelReadQuery
Parameters:
result - may be collection (read all) or an object (read one), or even a cursor. If in transaction the shared cache will be bypassed, meaning the result may not be originals from the parent but raw database rows.
unitOfWork - the unitOfWork the result is being registered in.
arguments - the original arguments/parameters passed to the query execution. Used by conforming
buildDirectlyFromRows - If in transaction must construct a registered result from raw database rows.
Returns:
the final (conformed, refreshed, wrapped) UnitOfWork query result

replaceValueHoldersIn

public java.util.Map replaceValueHoldersIn(java.lang.Object object,
                                           org.eclipse.persistence.internal.sessions.remote.RemoteSessionController controller)
INTERNAL: replace the value holders in the specified result object(s)

Overrides:
replaceValueHoldersIn in class DatabaseQuery

setSelectionKey

public void setSelectionKey(java.util.List selectionKey)
PUBLIC: The primary key can be specified if used instead of an expression or selection object. If composite the primary must be in the same order as defined in the descriptor.


setSelectionObject

public void setSelectionObject(java.lang.Object selectionObject)
PUBLIC: Used to set the where clause of the query. This can be used instead of a where clause expression for single object primary key queries. The selection object given should have a primary key defined, this primary key will be used to query the database instance of the same object. This is a basic form of query by example where only the primary key is required, it can be used for simple query forms, or testing.


setShouldLoadResultIntoSelectionObject

public void setShouldLoadResultIntoSelectionObject(boolean shouldLoadResultIntoSelectionObject)
PUBLIC: Allow for the selection object of the query to be refreshed or put into the EclipseLink cache. By default on a read or refresh the object in the cache is refreshed and returned or a new object is built from the database, in some cases such as EJB BMP it is desirable to refresh or load into the object passed into the read object query.

Note: This forces the selection object into the cache a replaces any existing object that may already be there, this is a strict violation of object identity and other objects can still be referring to the old object.


setSingletonSelectionKey

public void setSingletonSelectionKey(java.lang.Object selectionKey)
PUBLIC: The primary key can be specified if used instead of an expression or selection object.


shouldCheckCache

public boolean shouldCheckCache()
PUBLIC: Return if the cache should be checked.


shouldCheckCacheByExactPrimaryKey

public boolean shouldCheckCacheByExactPrimaryKey()
PUBLIC: Return if cache should be checked.


shouldCheckCacheByPrimaryKey

public boolean shouldCheckCacheByPrimaryKey()
PUBLIC: Return if cache should be checked.


shouldCheckCacheThenDatabase

public boolean shouldCheckCacheThenDatabase()
PUBLIC: Return if cache should be checked.


shouldLoadResultIntoSelectionObject

public boolean shouldLoadResultIntoSelectionObject()
PUBLIC: return true if the result should be loaded into the passed in selection Object