|
Oracle Fusion Middleware Java API Reference for Oracle TopLink 11g Release 1 (11.1.1) B32476-03 |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object oracle.toplink.queryframework.DatabaseQuery oracle.toplink.queryframework.ReadQuery oracle.toplink.queryframework.ObjectBuildingQuery oracle.toplink.queryframework.ObjectLevelReadQuery
public abstract class ObjectLevelReadQuery
Purpose: Abstract class for all read queries using objects.
Description: Contains common behavior for all read queries using objects.
Field Summary | |
---|---|
static int |
CheckCacheByExactPrimaryKey
|
static int |
CheckCacheByPrimaryKey
|
static int |
CheckCacheOnly
|
static int |
CheckCacheThenDatabase
|
static int |
ConformResultsInUnitOfWork
|
static int |
DoNotCheckCache
|
static short |
DONT_USE_DISTINCT
|
static short |
UNCOMPUTED_DISTINCT
|
static short |
USE_DISTINCT
|
static int |
UseDescriptorSetting
|
Fields inherited from class oracle.toplink.queryframework.ObjectBuildingQuery |
---|
DEFAULT_LOCK_MODE, LOCK, LOCK_NOWAIT, NO_LOCK |
Fields inherited from class oracle.toplink.queryframework.DatabaseQuery |
---|
CascadeAggregateDelete, CascadeAllParts, CascadeByMapping, CascadeDependentParts, CascadePrivateParts, NoCascading |
Method Summary | |
---|---|
void |
acquireLocks()
Set the query to lock, this will also turn refreshCache on. |
void |
acquireLocksWithoutWaiting()
Set the query to lock without waiting (blocking), this will also turn refreshCache on. |
void |
addJoinedAttribute(Expression attributeExpression)
Specify the attribute to be join fetched in this query. |
void |
addJoinedAttribute(java.lang.String attributeName)
Specify the one-to-one mapped attribute to be join fetched in this query. |
void |
addNonFetchJoinedAttribute(Expression attributeExpression)
Specify the one-to-one mapped attribute to be optimized in this query. |
void |
addNonFetchJoinedAttribute(java.lang.String attributeName)
Specify the one-to-one mapped attribute to be optimized in this query. |
void |
addPartialAttribute(Expression attributeExpression)
Specify that only a subset of the class' attributes be selected in this query. |
void |
addPartialAttribute(java.lang.String attributeName)
Specify that only a subset of the class' attributes be selected in this query. |
void |
checkCacheOnly()
The cache will checked completely, if the object is not found null will be returned or an error if the query is too complex. |
void |
conformResultsInUnitOfWork()
The cache will checked completely, if the object is not found the database will be queried, and the database result will be verified with what is in the cache and/or unit of work including new objects. |
void |
dontAcquireLocks()
Set the query not to lock. |
void |
dontCheckCache()
This can be used to explicitly disable the cache hit. |
void |
dontRefreshIdentityMapResult()
When unset means perform read normally and dont do refresh. |
void |
dontRefreshRemoteIdentityMapResult()
When unset means perform read normally and dont do refresh. |
void |
dontUseDistinct()
ADVANCED: If a distinct has been set the DISTINCT clause will be printed. |
AsOfClause |
getAsOfClause()
ADVANCED: Answers the past time this query is as of. |
int |
getCacheUsage()
Return the cache usage. |
short |
getDistinctState()
ADVANCED: If a distinct has been set the DISTINCT clause will be printed. |
java.lang.Object |
getExampleObject()
This method returns the current example object. |
ExpressionBuilder |
getExpressionBuilder()
REQUIRED: Get the expression builder which should be used for this query. |
FetchGroup |
getFetchGroup()
Return the fetch group set in the query. |
java.lang.String |
getFetchGroupName()
Return the fetch group name set in the query. |
InMemoryQueryIndirectionPolicy |
getInMemoryQueryIndirectionPolicy()
Returns the InMemoryQueryIndirectionPolicy for this query |
int |
getInMemoryQueryIndirectionPolicyState()
Returns the InMemoryQueryIndirectionPolicy for this query |
short |
getLockMode()
Return the current locking mode. |
QueryByExamplePolicy |
getQueryByExamplePolicy()
When using Query By Example, an instance of QueryByExamplePolicy is used to customize the query. |
java.lang.Class |
getReferenceClass()
Return the reference class of the query. |
boolean |
hasAsOfClause()
Answers if the domain objects are to be read as of a past time. |
boolean |
hasFetchGroup()
Return if a fetch group is set in the query. |
boolean |
isLockQuery()
Answers if the query lock mode is known to be LOCK or LOCK_NOWAIT. |
boolean |
isLockQuery(Session session)
ADVANCED: Answers if this query will issue any pessimistic locks. |
boolean |
isObjectLevelReadQuery()
Return if this is an object level read query. |
boolean |
isReadOnly()
Return if the query is read-only. |
boolean |
isResultSetOptimizedQuery()
ADVANCED: Return if the query should be optimized to build directly from the result set. |
void |
refreshIdentityMapResult()
Refresh the attributes of the object(s) resulting from the query. |
void |
refreshRemoteIdentityMapResult()
Refresh the attributes of the object(s) resulting from the query. |
void |
resetDistinct()
ADVANCED: If a distinct has been set the DISTINCT clause will be printed. |
void |
setAsOfClause(AsOfClause pastTime)
ADVANCED: Sets the query to execute as of the past time. |
void |
setCacheUsage(int cacheUsage)
Set the cache usage. |
void |
setDistinctState(short distinctState)
ADVANCED: If a distinct has been set the DISTINCT clause will be printed. |
void |
setEJBQLString(java.lang.String ejbqlString)
Set the EJBQL string of the query. |
void |
setExampleObject(java.lang.Object newExampleObject)
Set the example object of the query to be the newExampleObject. |
void |
setFetchGroup(FetchGroup newFetchGroup)
Set a dynamic (use case) fetch group to the query. |
void |
setFetchGroupName(java.lang.String groupName)
Set a descriptor-level pre-defined named fetch group to the query. |
void |
setInMemoryQueryIndirectionPolicy(InMemoryQueryIndirectionPolicy inMemoryQueryIndirectionPolicy)
Set the InMemoryQueryIndirectionPolicy for this query. |
void |
setInMemoryQueryIndirectionPolicyState(int inMemoryQueryIndirectionPolicy)
Set the InMemoryQueryIndirectionPolicy for this query. |
void |
setIsReadOnly(boolean isReadOnly)
Set the query to be read-only. |
void |
setIsResultSetOptimizedQuery(boolean isResultSetOptimizedQuery)
ADVANCED: Set if the query should be optimized to build directly from the result set. |
void |
setLockMode(short lockMode)
Sets whether this is a pessimistically locking query. |
void |
setQueryByExamplePolicy(QueryByExamplePolicy queryByExamplePolicy)
The QueryByExamplePolicy, is a useful to customize the query when Query By Example is used. |
void |
setReferenceClass(java.lang.Class aClass)
REQUIRED: Set the reference class for the query. |
void |
setSelectionCriteria(Expression expression)
To any user of this object. |
void |
setShouldFilterDuplicates(boolean shouldFilterDuplicates)
Set if duplicate rows should be filter when using 1-m joining. |
void |
setShouldOuterJoinSubclasses(boolean shouldOuterJoinSubclasses)
Set if an outer join should be used to read subclasses. |
void |
setShouldProcessResultsInUnitOfWork(boolean processResultsInUnitOfWork)
ADVANCED: Used for CMP only. |
void |
setShouldRefreshIdentityMapResult(boolean shouldRefreshIdentityMapResult)
Set if the attributes of the object(s) resulting from the query should be refreshed. |
void |
setShouldRefreshRemoteIdentityMapResult(boolean shouldRefreshIdentityMapResult)
Set if the attributes of the object(s) resulting from the query should be refreshed. |
void |
setShouldUseDefaultFetchGroup(boolean shouldUseDefaultFetchGroup)
Set false if the user does not want to use the default fetch group defined in the descriptor level. |
boolean |
shouldCheckCacheOnly()
Return if cache should be checked. |
boolean |
shouldCheckDescriptorForCacheUsage()
Return whether the descriptor's disableCacheHits setting should be checked prior to querying the cache. |
boolean |
shouldConformResultsInUnitOfWork()
Should the results will be checked against the changes within the unit of work and object no longer matching or deleted will be remove, matching new objects will also be added.. |
boolean |
shouldFilterDuplicates()
Return if duplicate rows should be filter when using 1-m joining. |
boolean |
shouldOuterJoinSubclasses()
Return if an outer join should be used to read subclasses. |
boolean |
shouldProcessResultsInUnitOfWork()
ADVANCED: Used for CMP only. |
boolean |
shouldRefreshIdentityMapResult()
Set to a boolean. |
boolean |
shouldRefreshRemoteIdentityMapResult()
Set to a boolean. |
boolean |
shouldUseDefaultFetchGroup()
Return false if the query does not use the default fetch group defined in the descriptor level. |
java.lang.String |
toString()
|
void |
useDistinct()
ADVANCED: If a distinct has been set the DISTINCT clause will be printed. |
Methods inherited from class oracle.toplink.queryframework.ObjectBuildingQuery |
---|
isObjectBuildingQuery, setShouldUseExclusiveConnection, shouldUseExclusiveConnection |
Methods inherited from class oracle.toplink.queryframework.ReadQuery |
---|
cacheQueryResults, clearQueryResults, clearQueryResults, doNotCacheQueryResults, getFetchSize, getFirstResult, getMaxRows, getQueryResultsCachePolicy, isReadQuery, setFetchSize, setFirstResult, setMaxRows, setQueryResultsCachePolicy, setShouldCacheQueryResults, shouldCacheQueryResults |
Methods inherited from class java.lang.Object |
---|
getClass, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public static final int UseDescriptorSetting
public static final int DoNotCheckCache
public static final int CheckCacheByExactPrimaryKey
public static final int CheckCacheByPrimaryKey
public static final int CheckCacheThenDatabase
public static final int CheckCacheOnly
public static final int ConformResultsInUnitOfWork
public static final short UNCOMPUTED_DISTINCT
public static final short USE_DISTINCT
public static final short DONT_USE_DISTINCT
Method Detail |
---|
public boolean isReadOnly()
public void setIsReadOnly(boolean isReadOnly)
public void acquireLocks()
public void acquireLocksWithoutWaiting()
public void addJoinedAttribute(java.lang.String attributeName)
Note: This cannot be used for objects where it is possible not to have a part, as these objects will be ommited from the result set, unless an outer join is used through passing and expression using "getAllowingNull". To join fetch collection relationships use the addJoinedAttribute(Expression) using "anyOf" ot "anyOfAllowingNone".
Example: query.addJoinedAttribute("address")
addJoinedAttribute(Expression)
,
ReadAllQuery.addBatchReadAttribute(Expression)
public void addJoinedAttribute(Expression attributeExpression)
Note: This cannot be used for objects where it is possible not to have a part, as these objects will be ommited from the result set, unless an outer join is used through passing and expression using "getAllowingNull".
Example: The following will fetch along with Employee(s) "Jones" all projects they participate in along with teamLeaders and their addresses, teamMembers and their phones. query.setSelectionCriteria(query.getExpressionBuilder().get("lastName").equal("Jones")); Expression projects = query.getExpressionBuilder().anyOf("projects"); query.addJoinedAttribute(projects); Expression teamLeader = projects.get("teamLeader"); query.addJoinedAttribute(teamLeader); Expression teamLeaderAddress = teamLeader.getAllowingNull("address"); query.addJoinedAttribute(teamLeaderAddress); Expression teamMembers = projects.anyOf("teamMembers"); query.addJoinedAttribute(teamMembers); Expression teamMembersPhones = teamMembers.anyOfAllowingNone("phoneNumbers"); query.addJoinedAttribute(teamMembersPhones); Note that: the order is essential: an expression should be added before any expression derived from it; the object is built once - it won't be rebuilt if it to be read again as a joined attribute: in the example the query won't get phones for "Jones" - even though they are among teamMembers (for whom phones are read).
public void addNonFetchJoinedAttribute(java.lang.String attributeName)
Note: This cannot be used for objects where it is possible not to have a part, as these objects will be ommited from the result set, unless an outer join is used through passing and expression using "getAllowingNull".
Example: query.addNonFetchJoinedAttribute("address")
addNonFetchJoinedAttribute(Expression)
public void addNonFetchJoinedAttribute(Expression attributeExpression)
Note: This cannot be used for objects where it is possible not to have a part, as these objects will be ommited from the result set, unless an outer join is used through passing and expression using "getAllowingNull".
Example: query.addNonFetchJoinedAttribute(query.getExpressionBuilder().get("teamLeader").get("address"))
addNonFetchJoinedAttribute(Expression)
public void addPartialAttribute(java.lang.String attributeName)
This allows for the query to be optimized through selecting less data.
Partial objects will be returned from the query, where the unspecified attributes will be left null
.
The primary key will always be selected to allow re-querying of the whole object.
Note: Because the object is not fully initialized it cannot be cached, and cannot be edited.
Note: You cannot have 2 partial attributes of the same type. You also cannot add a partial attribute which is of the same type as the class being queried.
Example: query.addPartialAttribute("firstName")
addPartialAttribute(Expression)
public void setAsOfClause(AsOfClause pastTime)
Equivalent to query.getSelectionCriteria().asOf(pastTime) called immediately before query execution.
An as of clause at the query level will override any clauses set at the expression level. Useful in cases where the selection criteria is not known in advance, such as for query by example or primary key (selection object), or where you do not need to cache the result (report query).
Ideally an as of clause at the session level is superior as query
results can then be cached. You must set
setShouldMaintainCache(false)
To query all joined/batched attributes as of the same time set
this.cascadeAllParts()
.
QueryException
- (at execution time) unless
setShouldMaintainCache(false)
is set. If some more recent
data were in the cache, this would be returned instead, and both the
cache and query result would become inconsistent.hasAsOfClause()
,
Session.acquireHistoricalSession(oracle.toplink.history.AsOfClause)
,
Expression.asOf(oracle.toplink.history.AsOfClause)
public void addPartialAttribute(Expression attributeExpression)
This allows for the query to be optimized through selecting less data.
Partial objects will be returned from the query, where the unspecified attributes will be left null
.
The primary key will always be selected to allow re-querying of the whole object.
Note: Because the object is not fully initialized it cannot be cached, and cannot be edited.
Note: You cannot have 2 partial attributes of the same type. You also cannot add a partial attribute which is of the same type as the class being queried.
Example: query.addPartialAttribute(query.getExpressionBuilder().get("address").get("city"))
public void checkCacheOnly()
setCacheUsage(int)
public void conformResultsInUnitOfWork()
setCacheUsage(int)
public void dontAcquireLocks()
public void dontCheckCache()
public void dontRefreshIdentityMapResult()
dontRefreshIdentityMapResult
in class ObjectBuildingQuery
public void dontRefreshRemoteIdentityMapResult()
dontRefreshRemoteIdentityMapResult
in class ObjectBuildingQuery
public void dontUseDistinct()
public AsOfClause getAsOfClause()
null
if no clause set, AsOfClause.NO_CLAUSE
if
clause explicitly set to null
.AsOfClause
,
setAsOfClause(oracle.toplink.history.AsOfClause)
,
hasAsOfClause()
public int getCacheUsage()
Valid values are:
public short getDistinctState()
public java.lang.Object getExampleObject()
public ExpressionBuilder getExpressionBuilder()
public int getInMemoryQueryIndirectionPolicyState()
public InMemoryQueryIndirectionPolicy getInMemoryQueryIndirectionPolicy()
public boolean shouldFilterDuplicates()
public void setShouldFilterDuplicates(boolean shouldFilterDuplicates)
public short getLockMode()
getLockMode
in class ObjectBuildingQuery
public QueryByExamplePolicy getQueryByExamplePolicy()
public java.lang.Class getReferenceClass()
getReferenceClass
in class ObjectBuildingQuery
public boolean hasAsOfClause()
getAsOfClause()
public boolean isLockQuery()
If a single joined attribute was configured for pessimistic locking then this will return true (after first execution) as the SQL contained a FOR UPDATE OF clause.
isLockQuery
in class ObjectBuildingQuery
public boolean isLockQuery(Session session)
If the lock mode is not known (DEFAULT_LOCK_MODE / descriptor specified fine-grained locking) the lock mode will be determined now, to be either LOCK, LOCK_NOWAIT, or NO_LOCK.
isLockQuery()
public boolean isObjectLevelReadQuery()
isObjectLevelReadQuery
in class DatabaseQuery
public void refreshIdentityMapResult()
refreshIdentityMapResult
in class ObjectBuildingQuery
public void refreshRemoteIdentityMapResult()
refreshRemoteIdentityMapResult
in class ObjectBuildingQuery
public void resetDistinct()
public void setCacheUsage(int cacheUsage)
Valid values are:
public void setDistinctState(short distinctState)
public void setExampleObject(java.lang.Object newExampleObject)
If a query already has a selection criteria this criteria and the generated query by example criteria will be conjuncted.
Once a query is executed you must make an explicit call to setExampleObject if the example object is changed, so the query will know to prepare itself again.
There is a caution to setting both a selection criteria and an example object: Only in this case if you set the example object again after execution you must then also reset the selection criteria. (This is because after execution the original criteria and Query By Example criteria were fused together, and the former cannot be easily recovered from the now invalid result).
public void setInMemoryQueryIndirectionPolicy(InMemoryQueryIndirectionPolicy inMemoryQueryIndirectionPolicy)
public void setInMemoryQueryIndirectionPolicyState(int inMemoryQueryIndirectionPolicy)
public void setLockMode(short lockMode)
Fine Grained Locking: On execution the reference class and those of all joined attributes will be checked. If any of these have a PessimisticLockingPolicy set on their descriptor, they will be locked in a SELECT ... FOR UPDATE OF ... {NO WAIT}. Issues fewer locks and avoids setting the lock mode on each query.
Example:readAllQuery.setSelectionCriteria(employee.get("address").equal("Ottawa"));
setLockMode
in class ObjectBuildingQuery
PessimisticLockingPolicy
public void setEJBQLString(java.lang.String ejbqlString)
setEJBQLString
in class DatabaseQuery
public void setQueryByExamplePolicy(QueryByExamplePolicy queryByExamplePolicy)
Once a query is executed you must make an explicit call to setQueryByExamplePolicy when changing the policy, so the query will know to prepare itself again.
There is a caution to setting both a selection criteria and an example object: If you set the policy after execution you must also reset the selection criteria. (This is because after execution the original criteria and Query By Example criteria are fused together, and the former cannot be easily recovered).
public void setReferenceClass(java.lang.Class aClass)
setReferenceClass
in class ObjectBuildingQuery
public void setSelectionCriteria(Expression expression)
setSelectionCriteria
in class DatabaseQuery
public void setShouldRefreshIdentityMapResult(boolean shouldRefreshIdentityMapResult)
setShouldRefreshIdentityMapResult
in class ObjectBuildingQuery
public void setShouldRefreshRemoteIdentityMapResult(boolean shouldRefreshIdentityMapResult)
setShouldRefreshRemoteIdentityMapResult
in class ObjectBuildingQuery
public boolean shouldCheckCacheOnly()
public boolean shouldCheckDescriptorForCacheUsage()
public boolean shouldConformResultsInUnitOfWork()
public boolean shouldOuterJoinSubclasses()
public void setShouldOuterJoinSubclasses(boolean shouldOuterJoinSubclasses)
public boolean shouldRefreshIdentityMapResult()
shouldRefreshIdentityMapResult
in class ObjectBuildingQuery
public boolean shouldRefreshRemoteIdentityMapResult()
shouldRefreshRemoteIdentityMapResult
in class ObjectBuildingQuery
public java.lang.String toString()
toString
in class ObjectBuildingQuery
public void setShouldProcessResultsInUnitOfWork(boolean processResultsInUnitOfWork)
If set to false, then UnitOfWork allocation will be deferred until a business method (including creates/removes) or finder with shouldProcessResultsInUnitOfWork == true is invoked. Any finder executed before such a time, will do so against the underlying ServerSession. Forcing finder execution to always go through a UnitOfWork means the results will be cloned and cached in the UnitOfWork up front. This is desired when the results will be accessed in the same transaction.
Note that finders executed with an unspecified transaction context will never be executed against a UnitOfWork, even if this setting is true. This case may happen with the NotSupported, Never, and Supports attributes.
setShouldProcessResultsInUnitOfWork
in class ObjectBuildingQuery
public boolean shouldProcessResultsInUnitOfWork()
If set to false, then UnitOfWork allocation will be deferred until a business method (including creates/removes) or finder with shouldProcessResultsInUnitOfWork == true is invoked. Any finder executed before such a time, will do so against the underlying ServerSession. Forcing finder execution to always go through a UnitOfWork means the results will be cloned and cached in the UnitOfWork up front. This is desired when the results will be accessed in the same transaction.
Note that finders executed with an unspecified transaction context will never be executed against a UnitOfWork, even if this setting is true. This case may happen with the NotSupported, Never, and Supports attributes.
shouldProcessResultsInUnitOfWork
in class ObjectBuildingQuery
public void useDistinct()
public boolean isResultSetOptimizedQuery()
public void setIsResultSetOptimizedQuery(boolean isResultSetOptimizedQuery)
public boolean hasFetchGroup()
public FetchGroup getFetchGroup()
getFetchGroup
in class ObjectBuildingQuery
public void setFetchGroup(FetchGroup newFetchGroup)
public void setFetchGroupName(java.lang.String groupName)
public java.lang.String getFetchGroupName()
public boolean shouldUseDefaultFetchGroup()
public void setShouldUseDefaultFetchGroup(boolean shouldUseDefaultFetchGroup)
|
|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |