oracle.toplink.descriptors
Class ClassDescriptor

java.lang.Object
  oracle.toplink.publicinterface.Descriptor
      oracle.toplink.internal.descriptors.RootDescriptor
          oracle.toplink.descriptors.ClassDescriptor

All Implemented Interfaces:

java.lang.Cloneable, java.io.Serializable

Direct Known Subclasses:

EISDescriptor, RelationalDescriptor, XMLDescriptor

public class ClassDescriptor

extends oracle.toplink.internal.descriptors.RootDescriptor

Purpose: Abstract descriptor class for defining persistence information on a class. This class provides the data independent behavior and is subclassed, for relational, object-relational, EIS, XML, etc.

See Also:

RelationalDescriptor, ObjectRelationalDescriptor, EISDescriptor, XMLDescriptor, Serialized Form

Field Summary

Fields inherited from class oracle.toplink.publicinterface.Descriptor

DO_NOT_SEND_CHANGES, INVALIDATE_CHANGED_OBJECTS, SEND_NEW_OBJECTS_WITH_CHANGES, SEND_OBJECT_CHANGES, UNDEFINED_OBJECT_CHANGE_BEHAVIOR

Constructor Summary

ClassDescriptor()
PUBLIC: Return a new descriptor.

Method Summary

void	addAbstractQueryKey(java.lang.String queryKeyName) PUBLIC: This method should only be used for interface descriptors.
void	addConstraintDependencies(java.lang.Class dependencies) ADVANCED: TopLink automatically orders database access through the foreign key information provided in 1:1 and 1:m mappings.
DatabaseMapping	addDirectMapping(java.lang.String attributeName, java.lang.String fieldName) PUBLIC: Add a direct mapping to the receiver.
DatabaseMapping	addDirectMapping(java.lang.String attributeName, java.lang.String getMethodName, java.lang.String setMethodName, java.lang.String fieldName) PUBLIC: Add a direct mapping to the receiver.
void	addDirectQueryKey(java.lang.String queryKeyName, java.lang.String fieldName) PUBLIC: Add a query key to the descriptor.
DatabaseMapping	addMapping(DatabaseMapping mapping) PUBLIC: Add a database mapping to the receiver.
void	addMultipleTableForeignKeyFieldName(java.lang.String fieldNameInSourceTable, java.lang.String fieldNameInTargetTable) PUBLIC: This protocol can be used to associate multiple tables with foreign key information.
void	addMultipleTablePrimaryKeyFieldName(java.lang.String fieldNameInSourceTable, java.lang.String fieldNameInTargetTable) PUBLIC: This protocol can be used to map the primary key field names in a multiple table descriptor.
void	addPrimaryKeyField(oracle.toplink.internal.helper.DatabaseField field) ADVANCED: Specify the primary key field of the descriptors table.
void	addPrimaryKeyFieldName(java.lang.String fieldName) PUBLIC: Specify the primary key field of the descriptors table.
void	addQueryKey(QueryKey queryKey) PUBLIC: Add a query key to the descriptor.
void	alwaysConformResultsInUnitOfWork() PUBLIC: Used to set the descriptor to always conform in any unit of work query.
void	alwaysRefreshCache() PUBLIC: This method is the equivalent of calling setShouldAlwaysRefreshCache(boolean) with an argument of true: it configures a Descriptor to always refresh the cache if data is received from the database by any query.
void	alwaysRefreshCacheOnRemote() PUBLIC: This method is the equivalent of calling setShouldAlwaysRefreshCacheOnRemote(boolean) with an argument of true: it configures a Descriptor to always remotely refresh the cache if data is received from the database by any query in a RemoteSession.
void	applyAmendmentMethod() ADVANCED: Call the descriptor amendment method.
void	createCopyPolicy(java.lang.String policyType) PUBLIC: Create a copy policy of the type passed in as a string.
void	createInstantiationPolicy(java.lang.String policyType) PUBLIC: Create a instantiation policy of the type passed in as a string.
void	descriptorIsAggregate() PUBLIC: Sets the descriptor to be an aggregate.
void	descriptorIsAggregateCollection() PUBLIC: Sets the descriptor to be part of an aggregate collection.
void	descriptorIsForInterface() PUBLIC: Sets the descriptor to be for an interface.
void	descriptorIsNormal() PUBLIC: Sets the descriptor to be normal.
void	disableCacheHits() PUBLIC: Allow for cache hits on primary key read object queries to be disabled.
void	disableCacheHitsOnRemote() PUBLIC: Allow for remote session cache hits on primary key read object queries to be disabled.
void	dontAlwaysConformResultsInUnitOfWork() PUBLIC: The descriptor is defined to not conform the results in unit of work in read query.
void	dontAlwaysRefreshCache() PUBLIC: This method is the equivalent of calling setShouldAlwaysRefreshCache(boolean) with an argument of false: it ensures that a Descriptor is not configured to always refresh the cache if data is received from the database by any query.
void	dontAlwaysRefreshCacheOnRemote() PUBLIC: This method is the equivalent of calling setShouldAlwaysRefreshCacheOnRemote(boolean) with an argument of false: it ensures that a Descriptor is not configured to always remotely refresh the cache if data is received from the database by any query in a RemoteSession.
void	dontDisableCacheHits() PUBLIC: Allow for cache hits on primary key read object queries.
void	dontDisableCacheHitsOnRemote() PUBLIC: Allow for remote session cache hits on primary key read object queries.
void	dontOnlyRefreshCacheIfNewerVersion() PUBLIC: This method is the equivalent of calling setShouldOnlyRefreshCacheIfNewerVersion(boolean) with an argument of false: it ensures that a Descriptor is not configured to only refresh the cache if the data received from the database by a query is newer than the data in the cache (as determined by the optimistic locking field).
java.lang.String	getAlias() PUBLIC: Get the alias
java.lang.Class	getAmendmentClass() PUBLIC: Return the amendment class.
java.lang.String	getAmendmentMethodName() PUBLIC: Return the amendment method.
CacheInvalidationPolicy	getCacheInvalidationPolicy() PUBLIC: Return the CacheInvalidationPolicy for this descriptor For uninitialized cache invalidation policies, this will return a NoExpiryCacheInvalidationPolicy
int	getCacheSynchronizationType() PUBLIC: Get a value indicating the type of cache synchronization that will be used on objects of this type.
CMPPolicy	getCMPPolicy() ADVANCED: Return the cmp descriptor that holds EJB CMP specific information.
java.util.Vector	getConstraintDependencies() ADVANCED: TopLink automatically orders database access through the foreign key information provided in 1:1 and 1:m mappings.
DescriptorEventManager	getDescriptorEventManager() PUBLIC: Get the event manager for the descriptor.
InheritancePolicy	getDescriptorInheritancePolicy() PUBLIC: The inheritance policy is used to define how a descriptor takes part in inheritance.
DescriptorQueryManager	getDescriptorQueryManager() PUBLIC: Return the queryManager.
int	getDescriptorType() ADVANCED: return the descriptor type (NORMAL by default, others include INTERFACE, AGGREGATE, AGGREGATE COLLECTION)
FetchGroupManager	getFetchGroupManager() PUBLIC: Get the fetch group manager for the descriptor.
HistoryPolicy	getHistoryPolicy() PUBLIC: Return this descriptors HistoryPolicy.
int	getIdentityMapSize() PUBLIC: Return the size of the identity map.
InterfacePolicy	getInterfacePolicy() PUBLIC: Returns the InterfacePolicy.
java.lang.Class	getJavaClass() PUBLIC: Return the java class.
DatabaseMapping	getMappingForAttributeName(java.lang.String attributeName) PUBLIC: Returns the mapping associated with a given attribute name.
java.util.Vector	getMappings() PUBLIC: Returns mappings
oracle.toplink.descriptors.changetracking.ObjectChangePolicy	getObjectChangePolicy() PUBLIC: Return this objects ObjectChangePolicy.
oracle.toplink.internal.descriptors.OptimisticLockingPolicy	getOptimisticLockingPolicy() PUBLIC: Returns the OptimisticLockingPolicy.
java.util.Vector	getPrimaryKeyFieldNames() PUBLIC: Return the names of all the primary keys.
java.util.Hashtable	getProperties() PUBLIC: Returns the user defined properties.
java.lang.Object	getProperty(java.lang.String name) PUBLIC: Returns the descriptor property associated the given String.
java.util.Hashtable	getQueryKeys() PUBLIC: Return the query keys.
int	getRemoteIdentityMapSize() PUBLIC: Return the size of the remote identity map.
ReturningPolicy	getReturningPolicy() PUBLIC: Return returning policy.
java.lang.String	getSequenceNumberFieldName() PUBLIC: Get sequence number field name
java.lang.String	getSequenceNumberName() PUBLIC: Get sequence number name
WrapperPolicy	getWrapperPolicy() ADVANCED: Return the WrapperPolicy for this descriptor.
boolean	isAggregateCollectionDescriptor() PUBLIC: Return true if this descriptor is an aggregate collection descriptor
boolean	isAggregateDescriptor() PUBLIC: Return true if this descriptor is an aggregate descriptor
boolean	isChildDescriptor() PUBLIC: Return if the descriptor defines inheritence and is a child.
boolean	isDescriptorForInterface() PUBLIC: Return if the java class is interface
boolean	isIsolated() PUBLIC: Returns true if the descriptor represents an isolated class
void	onlyRefreshCacheIfNewerVersion() PUBLIC: This method is the equivalent of calling setShouldOnlyRefreshCacheIfNewerVersion(boolean) with an argument of true: it configures a Descriptor to only refresh the cache if the data received from the database by a query is newer than the data in the cache (as determined by the optimistic locking field) and as long as one of the following is true: the Descriptor was configured by calling alwaysRefreshCache() or alwaysRefreshCacheOnRemote(), the query was configured by calling ObjectLevelReadQuery.refreshIdentityMapResult(), or the query was a call to Session.refreshObject(java.lang.Object) However, if a query hits the cache, data is not refreshed regardless of how this setting is configured.
void	removeProperty(java.lang.String property) PUBLIC: Remove the user defined property.
void	setAlias(java.lang.String alias) PUBLIC: Set the alias
void	setAmendmentClass(java.lang.Class amendmentClass) PUBLIC: Set the amendment class.
void	setAmendmentMethodName(java.lang.String amendmentMethodName) PUBLIC: Set the amendment method.
void	setCacheInvalidationPolicy(CacheInvalidationPolicy policy) PUBLIC: Set the Cache Invalidation Policy for this descriptor
void	setCacheSynchronizationType(int type) PUBLIC: Set the type of cache synchonization that will be used on objects of this type.
void	setCMPPolicy(CMPPolicy newCMPPolicy) ADVANCED: Set the cmp descriptor that holds EJB CMP specific information.
void	setDescriptorType(int descriptorType) ADVANCED: set the descriptor type (NORMAL by default, others include INTERFACE, AGGREGATE, AGGREGATE COLLECTION)
void	setFetchGroupManager(FetchGroupManager fetchGroupManager) PUBLIC: Set the fetch group manager for the descriptor.
void	setHistoryPolicy(HistoryPolicy policy) PUBLIC: Set the HistoryPolicy for this descriptor.
void	setIdentityMapClass(java.lang.Class theIdentityMapClass) PUBLIC: Set the class of identity map to be used by this descriptor.
void	setIdentityMapSize(int identityMapSize) PUBLIC: Set the size of the identity map to be used by this descriptor.
void	setIsIsolated(boolean isIsolated) PUBLIC: Used to set if the class that this descriptor represents should be isolated from the shared cache.
void	setJavaClass(java.lang.Class theJavaClass) PUBLIC: Set the Java class that this descriptor maps.
void	setJavaInterface(java.lang.Class theJavaInterface) PUBLIC: Sets the descriptor to be for an interface.
void	setObjectChangePolicy(oracle.toplink.descriptors.changetracking.ObjectChangePolicy policy) PUBLIC: Set the ObjectChangePolicy for this descriptor.
void	setOptimisticLockingPolicy(oracle.toplink.internal.descriptors.OptimisticLockingPolicy optimisticLockingPolicy) PUBLIC: Set the OptimisticLockingPolicy.
void	setPrimaryKeyFieldName(java.lang.String fieldName) PUBLIC: Specify the primary key field of the descriptors table.
void	setPrimaryKeyFieldNames(java.util.Vector primaryKeyFieldsName) PUBLIC: User can specify a vector of all the primary key field names if primary key is composite.
void	setProperty(java.lang.String name, java.lang.Object value) PUBLIC: Set the user defined property.
void	setReadOnly() PUBLIC: Set the descriptor to be read-only.
void	setRemoteIdentityMapClass(java.lang.Class theIdentityMapClass) PUBLIC: Set the class of identity map to be used by this descriptor.
void	setRemoteIdentityMapSize(int identityMapSize) PUBLIC: Set the size of the identity map to be used by this descriptor.
void	setReturningPolicy(ReturningPolicy returningPolicy) PUBLIC: Sets the returning policy.
void	setSequenceNumberFieldName(java.lang.String fieldName) PUBLIC: Set the sequence number field name.
void	setSequenceNumberName(java.lang.String name) PUBLIC: Set the sequence number name.
void	setShouldAlwaysConformResultsInUnitOfWork(boolean shouldAlwaysConformResultsInUnitOfWork) PUBLIC: set if the descriptor is defined to always conform the results in unit of work in read query.
void	setShouldAlwaysRefreshCache(boolean shouldAlwaysRefreshCache) PUBLIC: When the shouldAlwaysRefreshCache argument passed into this method is true, this method configures a Descriptor to always refresh the cache if data is received from the database by any query.
void	setShouldAlwaysRefreshCacheOnRemote(boolean shouldAlwaysRefreshCacheOnRemote) PUBLIC: When the shouldAlwaysRefreshCacheOnRemote argument passed into this method is true, this method configures a Descriptor to always remotely refresh the cache if data is received from the database by any query in a RemoteSession.
void	setShouldBeReadOnly(boolean shouldBeReadOnly) PUBLIC: Define if the descriptor reference class is read-only
void	setShouldDisableCacheHits(boolean shouldDisableCacheHits) PUBLIC: Set if cache hits on primary key read object queries should be disabled.
void	setShouldDisableCacheHitsOnRemote(boolean shouldDisableCacheHitsOnRemote) PUBLIC: Set if the remote session cache hits on primary key read object queries is allowed or not.
void	setShouldOnlyRefreshCacheIfNewerVersion(boolean shouldOnlyRefreshCacheIfNewerVersion) PUBLIC: When the shouldOnlyRefreshCacheIfNewerVersion argument passed into this method is true, this method configures a Descriptor to only refresh the cache if the data received from the database by a query is newer than the data in the cache (as determined by the optimistic locking field) and as long as one of the following is true: the Descriptor was configured by calling alwaysRefreshCache() or alwaysRefreshCacheOnRemote(), the query was configured by calling ObjectLevelReadQuery.refreshIdentityMapResult(), or the query was a call to Session.refreshObject(java.lang.Object) However, if a query hits the cache, data is not refreshed regardless of how this setting is configured.
void	setShouldOrderMappings(boolean shouldOrderMappings) PUBLIC: This is set to turn off the ordering of mappings.
void	setWrapperPolicy(WrapperPolicy wrapperPolicy) ADVANCED: Sets the WrapperPolicy for this descriptor.
boolean	shouldAlwaysConformResultsInUnitOfWork() PUBLIC: Return if the descriptor is defined to always conform the results in unit of work in read query.
boolean	shouldAlwaysRefreshCache() PUBLIC: This method returns true if the Descriptor is configured to always refresh the cache if data is received from the database by any query.
boolean	shouldAlwaysRefreshCacheOnRemote() PUBLIC: This method returns true if the Descriptor is configured to always remotely refresh the cache if data is received from the database by any query in a RemoteSession.
boolean	shouldBeReadOnly() PUBLIC: Return if the descriptor reference class is defined as read-only
boolean	shouldDisableCacheHits() PUBLIC: Return if for cache hits on primary key read object queries to be disabled.
boolean	shouldDisableCacheHitsOnRemote() PUBLIC: Return if the remote server session cache hits on primary key read object queries is aloowed or not.
boolean	shouldOnlyRefreshCacheIfNewerVersion() PUBLIC: This method returns true if the Descriptor is configured to only refresh the cache if the data received from the database by a query is newer than the data in the cache (as determined by the optimistic locking field).
boolean	shouldUseCacheIdentityMap() PUBLIC: Return true if this descriptor is using CacheIdentityMap
boolean	shouldUseFullIdentityMap() PUBLIC: Return true if this descriptor is using FullIdentityMap
boolean	shouldUseHardCacheWeakIdentityMap() PUBLIC: Return true if this descriptor is using HardCacheWeakIdentityMap.
boolean	shouldUseNoIdentityMap() PUBLIC: Return true if this descriptor is using NoIdentityMap
boolean	shouldUseRemoteCacheIdentityMap() PUBLIC: Return true if this descriptor is using CacheIdentityMap
boolean	shouldUseRemoteFullIdentityMap() PUBLIC: Return true if this descriptor is using FullIdentityMap
boolean	shouldUseRemoteHardCacheWeakIdentityMap() PUBLIC: Return true if this descriptor is using HardCacheWeakIdentityMap
boolean	shouldUseRemoteNoIdentityMap() PUBLIC: Return true if this descriptor is using NoIdentityMap
boolean	shouldUseRemoteSoftCacheWeakIdentityMap() PUBLIC: Return true if this descriptor is using SoftCacheWeakIdentityMap
boolean	shouldUseRemoteWeakIdentityMap() PUBLIC: Return true if this descriptor is using WeakIdentityMap
boolean	shouldUseSoftCacheWeakIdentityMap() PUBLIC: Return true if this descriptor is using SoftCacheWeakIdentityMap.
boolean	shouldUseWeakIdentityMap() PUBLIC: Return true if this descriptor is using WeakIdentityMap
void	useAllFieldsLocking() PUBLIC: Set the locking policy an all fields locking policy.
void	useCacheIdentityMap() PUBLIC: Set the class of identity map to be the cache identity map.
void	useChangedFieldsLocking() PUBLIC: Set the locking policy a changed fields locking policy.
void	useCloneCopyPolicy() PUBLIC: Specifies that the creation of clones within a unit of work is done by sending the #clone() method to the original object.
void	useCloneCopyPolicy(java.lang.String cloneMethodName) PUBLIC: Specifies that the creation of clones within a unit of work is done by sending the cloneMethodName method to the original object.
void	useDefaultConstructorInstantiationPolicy() PUBLIC: Use the default constructor to create new instances of objects built from the database.
void	useFactoryInstantiationPolicy(java.lang.Class factoryClass, java.lang.String methodName) PUBLIC: Use an object factory to create new instances of objects built from the database.
void	useFactoryInstantiationPolicy(java.lang.Class factoryClass, java.lang.String methodName, java.lang.String factoryMethodName) PUBLIC: Use an object factory to create new instances of objects built from the database.
void	useFactoryInstantiationPolicy(java.lang.Object factory, java.lang.String methodName) PUBLIC: Use an object factory to create new instances of objects built from the database.
void	useFullIdentityMap() PUBLIC: Set the class of identity map to be the full identity map.
void	useHardCacheWeakIdentityMap() PUBLIC: Set the class of identity map to be the hard cache weak identity map.
void	useInstantiationCopyPolicy() PUBLIC: Specifies that the creation of clones within a unit of work is done by building a new instance using the technique indicated by the descriptor's instantiation policy (which by default is to use the the default constructor).
void	useMethodInstantiationPolicy(java.lang.String staticMethodName) PUBLIC: Use the specified static method to create new instances of objects built from the database.
void	useNoIdentityMap() PUBLIC: Set the class of identity map to be the no identity map.
void	useRemoteCacheIdentityMap() PUBLIC: Set the class of identity map to be the cache identity map.
void	useRemoteFullIdentityMap() PUBLIC: Set the class of identity map to be the full identity map.
void	useRemoteHardCacheWeakIdentityMap() PUBLIC: Set the class of identity map to be the hard cache weak identity map.
void	useRemoteNoIdentityMap() PUBLIC: Set the class of identity map to be the no identity map.
void	useRemoteSoftCacheWeakIdentityMap() PUBLIC: Set the class of identity map to be the soft cache weak identity map.
void	useRemoteWeakIdentityMap() PUBLIC: Set the class of identity map to be the weak identity map.
void	useSelectedFieldsLocking(java.util.Vector fieldNames) PUBLIC: Set the locking policy a selected fields locking policy.
void	useSoftCacheWeakIdentityMap() PUBLIC: Set the class of identity map to be the soft cache weak identity map.
boolean	usesOptimisticLocking() PUBLIC: Return true if the receiver uses write (optimistic) locking.
boolean	usesSequenceNumbers() PUBLIC: Return true if the receiver uses sequence numbers.
void	useTimestampLocking(java.lang.String writeLockFieldName) PUBLIC: Use the Timestamps locking policy and storing the value in the cache key #see useVersionLocking(String)
void	useTimestampLocking(java.lang.String writeLockFieldName, boolean shouldStoreInCache) PUBLIC: Set the locking policy to use timestamp version locking.
void	useVersionLocking(java.lang.String writeLockFieldName) PUBLIC: Default to use the version locking policy and storing the value in the cache key #see useVersionLocking(String)
void	useVersionLocking(java.lang.String writeLockFieldName, boolean shouldStoreInCache) PUBLIC: Set the locking policy to use numeric version locking.
void	useWeakIdentityMap() PUBLIC: Set the class of identity map to be the weak identity map.

Methods inherited from class oracle.toplink.publicinterface.Descriptor

addTableName, getEventManager, getInheritancePolicy, getJavaClassName, getQueryManager, getTableName, getTableNames, removeMappingForAttributeName, setConstraintDependencies, setDefaultTableName, setMultipleTableInsertOrder, setTableName, setTableNames, setTableQualifier, toString

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ClassDescriptor

public ClassDescriptor()

PUBLIC: Return a new descriptor.

Method Detail

addAbstractQueryKey

public void addAbstractQueryKey(java.lang.String queryKeyName)

PUBLIC: This method should only be used for interface descriptors. It adds an abstract query key to the interface descriptor. Any implementors of that interface must define the query key defined by this abstract query key.

Overrides:

addAbstractQueryKey in class Descriptor

addConstraintDependencies

public void addConstraintDependencies(java.lang.Class dependencies)

ADVANCED: TopLink automatically orders database access through the foreign key information provided in 1:1 and 1:m mappings. In some case when 1:1 are not defined it may be required to tell the descriptor about a constraint, this defines that this descriptor has a foreign key constraint to another class and must be inserted after instances of the other class.

Overrides:

addConstraintDependencies in class Descriptor

addDirectMapping

public DatabaseMapping addDirectMapping(java.lang.String attributeName,
                                        java.lang.String fieldName)

PUBLIC: Add a direct mapping to the receiver. The new mapping specifies that an instance variable of the class of objects which the receiver describes maps in the default manner for its type to the indicated database field.

Overrides:

addDirectMapping in class Descriptor

Returns:

The newly created DatabaseMapping is returned.

addDirectMapping

public DatabaseMapping addDirectMapping(java.lang.String attributeName,
                                        java.lang.String getMethodName,
                                        java.lang.String setMethodName,
                                        java.lang.String fieldName)

PUBLIC: Add a direct mapping to the receiver. The new mapping specifies that a variable accessed by the get and set methods of the class of objects which the receiver describes maps in the default manner for its type to the indicated database field.

Overrides:

addDirectMapping in class Descriptor

addDirectQueryKey

public void addDirectQueryKey(java.lang.String queryKeyName,
                              java.lang.String fieldName)

PUBLIC: Add a query key to the descriptor. Query keys define Java aliases to database fields.

Overrides:

addDirectQueryKey in class Descriptor

addMapping

public DatabaseMapping addMapping(DatabaseMapping mapping)

PUBLIC: Add a database mapping to the receiver. Perform any required initialization of both the mapping and the receiving descriptor as a result of adding the new mapping.

Overrides:

addMapping in class Descriptor

addMultipleTableForeignKeyFieldName

public void addMultipleTableForeignKeyFieldName(java.lang.String fieldNameInSourceTable,
                                                java.lang.String fieldNameInTargetTable)
                                         throws DescriptorException

PUBLIC: This protocol can be used to associate multiple tables with foreign key information. The join criteria will be generated based on the fields provided. By default TopLink associates multiple tables using a primary key join where the primary keys fields are named the same.

Overrides:

addMultipleTableForeignKeyFieldName in class Descriptor

Throws:

DescriptorException

addMultipleTablePrimaryKeyFieldName

public void addMultipleTablePrimaryKeyFieldName(java.lang.String fieldNameInSourceTable,
                                                java.lang.String fieldNameInTargetTable)
                                         throws DescriptorException

PUBLIC: This protocol can be used to map the primary key field names in a multiple table descriptor. By default TopLink assumes that all of the primary key fields are named the same.

Overrides:

addMultipleTablePrimaryKeyFieldName in class Descriptor

Throws:

DescriptorException

addPrimaryKeyFieldName

public void addPrimaryKeyFieldName(java.lang.String fieldName)

PUBLIC: Specify the primary key field of the descriptors table. This should be called for each field that makes up the primary key of the table. If the descriptor has many tables, this must be the primary key in the first table, if the other tables have the same primary key nothing else is required, otherwise a primary key/foreign key field mapping must be provided for each of the other tables.

Overrides:

addPrimaryKeyFieldName in class Descriptor

See Also:

#addMultipleTableForeignKeyFieldName(String, String);

addPrimaryKeyField

public void addPrimaryKeyField(oracle.toplink.internal.helper.DatabaseField field)

ADVANCED: Specify the primary key field of the descriptors table. This should be called for each field that makes up the primary key of the table. This can be used for advanced field types, such as XML nodes, or to set the field type.

Overrides:

addPrimaryKeyField in class Descriptor

addQueryKey

public void addQueryKey(QueryKey queryKey)

PUBLIC: Add a query key to the descriptor. Query keys define Java aliases to database fields.

Overrides:

addQueryKey in class Descriptor

alwaysConformResultsInUnitOfWork

public void alwaysConformResultsInUnitOfWork()

PUBLIC: Used to set the descriptor to always conform in any unit of work query.

Overrides:

alwaysConformResultsInUnitOfWork in class Descriptor

alwaysRefreshCache

public void alwaysRefreshCache()

PUBLIC: This method is the equivalent of calling setShouldAlwaysRefreshCache(boolean) with an argument of true: it configures a Descriptor to always refresh the cache if data is received from the database by any query.

However, if a query hits the cache, data is not refreshed regardless of how this setting is configured. For example, by default, when a query for a single object based on its primary key is executed, OracleAS TopLink will first look in the cache for the object. If the object is in the cache, the cached object is returned and data is not refreshed. To avoid cache hits, use the disableCacheHits() method.

Also note that the UnitOfWork will not refresh its registered objects.

Use this property with caution because it can lead to poor performance and may refresh on queries when it is not desired. Normally, if you require fresh data, it is better to configure a query with ObjectLevelReadQuery.refreshIdentityMapResult(). To ensure that refreshes are only done when required, use this method in conjunction with onlyRefreshCacheIfNewerVersion().

Overrides:

alwaysRefreshCache in class Descriptor

See Also:

dontAlwaysRefreshCache()

alwaysRefreshCacheOnRemote

public void alwaysRefreshCacheOnRemote()

PUBLIC: This method is the equivalent of calling setShouldAlwaysRefreshCacheOnRemote(boolean) with an argument of true: it configures a Descriptor to always remotely refresh the cache if data is received from the database by any query in a RemoteSession.

However, if a query hits the cache, data is not refreshed regardless of how this setting is configured. For example, by default, when a query for a single object based on its primary key is executed, OracleAS TopLink will first look in the cache for the object. If the object is in the cache, the cached object is returned and data is not refreshed. To avoid cache hits, use the disableCacheHitsOnRemote() method.

Also note that the UnitOfWork will not refresh its registered objects.

Use this property with caution because it can lead to poor performance and may refresh on queries when it is not desired. Normally, if you require fresh data, it is better to configure a query with ObjectLevelReadQuery.refreshIdentityMapResult(). To ensure that refreshes are only done when required, use this method in conjunction with #refreshOnlyIfNewerVersion.

Overrides:

alwaysRefreshCacheOnRemote in class Descriptor

See Also:

dontAlwaysRefreshCacheOnRemote()

applyAmendmentMethod

public void applyAmendmentMethod()

ADVANCED: Call the descriptor amendment method. This is called while loading or creating a descriptor that has an amendment method defined.

Overrides:

applyAmendmentMethod in class Descriptor

createCopyPolicy

public void createCopyPolicy(java.lang.String policyType)

PUBLIC: Create a copy policy of the type passed in as a string.

Overrides:

createCopyPolicy in class Descriptor

createInstantiationPolicy

public void createInstantiationPolicy(java.lang.String policyType)

PUBLIC: Create a instantiation policy of the type passed in as a string.

Overrides:

createInstantiationPolicy in class Descriptor

descriptorIsAggregate

public void descriptorIsAggregate()

PUBLIC: Sets the descriptor to be an aggregate. An aggregate descriptor is contained within another descriptor's table. Aggregate descriptors are insert/updated/deleted with their owner and cannot exist without their owner as they share the same row. Aggregates are not cached (they are cached as part of their owner) and cannot be read/written/deleted/registered. All aggregate descriptors must call this.

Overrides:

descriptorIsAggregate in class Descriptor

descriptorIsAggregateCollection

public void descriptorIsAggregateCollection()

PUBLIC: Sets the descriptor to be part of an aggregate collection. An aggregate collection descriptor stored in a seperate table but some of the fields (the primary key) comes from its owner. Aggregate collection descriptors are insert/updated/deleted with their owner and cannot exist without their owner as they share the primary key. Aggregate collections are not cached (they are cached as part of their owner) and cannot be read/written/deleted/registered. All aggregate collection descriptors must call this.

Overrides:

descriptorIsAggregateCollection in class Descriptor

descriptorIsForInterface

public void descriptorIsForInterface()

PUBLIC: Sets the descriptor to be for an interface. An interface descriptor allows for other classes to reference an interface or one of serveral other classes. The implementor classes can be completely unrelated in term of the database stored in distinct tables. Queries can also be done for the interface which will query each of the implementor classes. An interface descriptor cannot define any mappings as an interface is just API and not state, a interface descriptor should define the common query key of its implementors to allow querying. An interface descriptor also does not define a primary key or table or other settings. If an interface only has a single implementor (i.e. a classes public interface or remote) then an interface descriptor should not be defined for it and relationships should be to the implementor class not the interface, in this case the implementor class can add the interface through its interface policy to map queries on the interface to it.

Overrides:

descriptorIsForInterface in class Descriptor

descriptorIsNormal

public void descriptorIsNormal()

PUBLIC: Sets the descriptor to be normal. This is the default and means the descriptor is not aggregate or for an interface.

Overrides:

descriptorIsNormal in class Descriptor

disableCacheHits

public void disableCacheHits()

PUBLIC: Allow for cache hits on primary key read object queries to be disabled. This can be used with alwaysRefreshCache() or alwaysRefreshCacheOnRemote() to ensure queries always go to the database.

Overrides:

disableCacheHits in class Descriptor

disableCacheHitsOnRemote

public void disableCacheHitsOnRemote()

PUBLIC: Allow for remote session cache hits on primary key read object queries to be disabled. This can be used with alwaysRefreshCacheOnRemote() to ensure queries always go to the server sesion cache.

Overrides:

disableCacheHitsOnRemote in class Descriptor

See Also:

alwaysRefreshCacheOnRemote()

dontAlwaysConformResultsInUnitOfWork

public void dontAlwaysConformResultsInUnitOfWork()

PUBLIC: The descriptor is defined to not conform the results in unit of work in read query. Default.

Overrides:

dontAlwaysConformResultsInUnitOfWork in class Descriptor

dontAlwaysRefreshCache

public void dontAlwaysRefreshCache()

PUBLIC: This method is the equivalent of calling setShouldAlwaysRefreshCache(boolean) with an argument of false: it ensures that a Descriptor is not configured to always refresh the cache if data is received from the database by any query.

Overrides:

dontAlwaysRefreshCache in class Descriptor

See Also:

alwaysRefreshCache()

dontAlwaysRefreshCacheOnRemote

public void dontAlwaysRefreshCacheOnRemote()

PUBLIC: This method is the equivalent of calling setShouldAlwaysRefreshCacheOnRemote(boolean) with an argument of false: it ensures that a Descriptor is not configured to always remotely refresh the cache if data is received from the database by any query in a RemoteSession.

Overrides:

dontAlwaysRefreshCacheOnRemote in class Descriptor

See Also:

alwaysRefreshCacheOnRemote()

dontDisableCacheHits

public void dontDisableCacheHits()

PUBLIC: Allow for cache hits on primary key read object queries.

Overrides:

dontDisableCacheHits in class Descriptor

See Also:

disableCacheHits()

dontDisableCacheHitsOnRemote

public void dontDisableCacheHitsOnRemote()

PUBLIC: Allow for remote session cache hits on primary key read object queries.

Overrides:

dontDisableCacheHitsOnRemote in class Descriptor

See Also:

disableCacheHitsOnRemote()

dontOnlyRefreshCacheIfNewerVersion

public void dontOnlyRefreshCacheIfNewerVersion()

PUBLIC: This method is the equivalent of calling setShouldOnlyRefreshCacheIfNewerVersion(boolean) with an argument of false: it ensures that a Descriptor is not configured to only refresh the cache if the data received from the database by a query is newer than the data in the cache (as determined by the optimistic locking field).

Overrides:

dontOnlyRefreshCacheIfNewerVersion in class Descriptor

See Also:

onlyRefreshCacheIfNewerVersion()

getAlias

public java.lang.String getAlias()

PUBLIC: Get the alias

Overrides:

getAlias in class Descriptor

getAmendmentClass

public java.lang.Class getAmendmentClass()

PUBLIC: Return the amendment class. The amendment method will be called on the class before initialization to allow for it to initialize the descriptor. The method must be a public static method on the class.

Overrides:

getAmendmentClass in class Descriptor

getAmendmentMethodName

public java.lang.String getAmendmentMethodName()

PUBLIC: Return the amendment method. This will be called on the amendment class before initialization to allow for it to initialize the descriptor. The method must be a public static method on the class.

Overrides:

getAmendmentMethodName in class Descriptor

getObjectChangePolicy

public oracle.toplink.descriptors.changetracking.ObjectChangePolicy getObjectChangePolicy()

PUBLIC: Return this objects ObjectChangePolicy.

Overrides:

getObjectChangePolicy in class Descriptor

getHistoryPolicy

public HistoryPolicy getHistoryPolicy()

PUBLIC: Return this descriptors HistoryPolicy.

Overrides:

getHistoryPolicy in class Descriptor

getCacheInvalidationPolicy

public CacheInvalidationPolicy getCacheInvalidationPolicy()

PUBLIC: Return the CacheInvalidationPolicy for this descriptor For uninitialized cache invalidation policies, this will return a NoExpiryCacheInvalidationPolicy

Overrides:

getCacheInvalidationPolicy in class Descriptor

Returns:

CacheInvalidationPolicy

See Also:

CacheInvalidationPolicy

getCacheSynchronizationType

public int getCacheSynchronizationType()

PUBLIC: Get a value indicating the type of cache synchronization that will be used on objects of this type. Possible values are: SEND_OBJECT_CHANGES INVALIDATE_CHANGED_OBJECTS SEND_NEW_OBJECTS+WITH_CHANGES DO_NOT_SEND_CHANGES

Overrides:

getCacheSynchronizationType in class Descriptor

Returns:

int

getConstraintDependencies

public java.util.Vector getConstraintDependencies()

ADVANCED: TopLink automatically orders database access through the foreign key information provided in 1:1 and 1:m mappings. In some case when 1:1 are not defined it may be required to tell the descriptor about a constraint, this defines that this descriptor has a foreign key constraint to another class and must be inserted after instances of the other class.

Overrides:

getConstraintDependencies in class Descriptor

getDescriptorType

public int getDescriptorType()

ADVANCED: return the descriptor type (NORMAL by default, others include INTERFACE, AGGREGATE, AGGREGATE COLLECTION)

Overrides:

getDescriptorType in class Descriptor

getDescriptorEventManager

public DescriptorEventManager getDescriptorEventManager()

PUBLIC: Get the event manager for the descriptor. The event manager is responsible for managing the pre/post selectors.

getIdentityMapSize

public int getIdentityMapSize()

PUBLIC: Return the size of the identity map.

Overrides:

getIdentityMapSize in class Descriptor

getDescriptorInheritancePolicy

public InheritancePolicy getDescriptorInheritancePolicy()

PUBLIC: The inheritance policy is used to define how a descriptor takes part in inheritance. All inheritance properties for both child and parent classes is configured in inheritance policy. Caution must be used in using this method as it lazy initializes an inheritance policy. Calling this on a descriptor that does not use inheritance will cause problems, #hasInheritance() must always first be called.

getInterfacePolicy

public InterfacePolicy getInterfacePolicy()

PUBLIC: Returns the InterfacePolicy. The interface policy allows for a descriptor's public and variable interfaces to be defined. Caution must be used in using this method as it lazy initializes an interface policy. Calling this on a descriptor that does not use interfaces will cause problems, #hasInterfacePolicy() must always first be called.

Overrides:

getInterfacePolicy in class Descriptor

getJavaClass

public java.lang.Class getJavaClass()

PUBLIC: Return the java class.

Overrides:

getJavaClass in class Descriptor

getMappingForAttributeName

public DatabaseMapping getMappingForAttributeName(java.lang.String attributeName)

PUBLIC: Returns the mapping associated with a given attribute name. This can be used to find a descriptors mapping in a amendment method before the descriptor has been initialized.

Overrides:

getMappingForAttributeName in class Descriptor

getMappings

public java.util.Vector getMappings()

PUBLIC: Returns mappings

Overrides:

getMappings in class Descriptor

getOptimisticLockingPolicy

public oracle.toplink.internal.descriptors.OptimisticLockingPolicy getOptimisticLockingPolicy()

PUBLIC: Returns the OptimisticLockingPolicy. By default this is an instance of VersionLockingPolicy.

Overrides:

getOptimisticLockingPolicy in class Descriptor

getPrimaryKeyFieldNames

public java.util.Vector getPrimaryKeyFieldNames()

PUBLIC: Return the names of all the primary keys.

Overrides:

getPrimaryKeyFieldNames in class Descriptor

getProperties

public java.util.Hashtable getProperties()

PUBLIC: Returns the user defined properties.

Overrides:

getProperties in class Descriptor

getProperty

public java.lang.Object getProperty(java.lang.String name)

PUBLIC: Returns the descriptor property associated the given String.

Overrides:

getProperty in class Descriptor

getQueryKeys

public java.util.Hashtable getQueryKeys()

PUBLIC: Return the query keys.

Overrides:

getQueryKeys in class Descriptor

getDescriptorQueryManager

public DescriptorQueryManager getDescriptorQueryManager()

PUBLIC: Return the queryManager. The query manager can be used to specify customization of the SQL that TopLink generates for this descriptor.

getRemoteIdentityMapSize

public int getRemoteIdentityMapSize()

PUBLIC: Return the size of the remote identity map.

Overrides:

getRemoteIdentityMapSize in class Descriptor

getReturningPolicy

public ReturningPolicy getReturningPolicy()

PUBLIC: Return returning policy.

Overrides:

getReturningPolicy in class Descriptor

getSequenceNumberFieldName

public java.lang.String getSequenceNumberFieldName()

PUBLIC: Get sequence number field name

Overrides:

getSequenceNumberFieldName in class Descriptor

getSequenceNumberName

public java.lang.String getSequenceNumberName()

PUBLIC: Get sequence number name

Overrides:

getSequenceNumberName in class Descriptor

getWrapperPolicy

public WrapperPolicy getWrapperPolicy()

ADVANCED: Return the WrapperPolicy for this descriptor. This advacned feature can be used to wrap objects with other classes such as CORBA TIE objects or EJBs.

Overrides:

getWrapperPolicy in class Descriptor

isAggregateCollectionDescriptor

public boolean isAggregateCollectionDescriptor()

PUBLIC: Return true if this descriptor is an aggregate collection descriptor

Overrides:

isAggregateCollectionDescriptor in class Descriptor

isAggregateDescriptor

public boolean isAggregateDescriptor()

PUBLIC: Return true if this descriptor is an aggregate descriptor

Overrides:

isAggregateDescriptor in class Descriptor

isChildDescriptor

public boolean isChildDescriptor()

PUBLIC: Return if the descriptor defines inheritence and is a child.

Overrides:

isChildDescriptor in class Descriptor

isDescriptorForInterface

public boolean isDescriptorForInterface()

PUBLIC: Return if the java class is interface

Overrides:

isDescriptorForInterface in class Descriptor

isIsolated

public boolean isIsolated()

PUBLIC: Returns true if the descriptor represents an isolated class

Overrides:

isIsolated in class Descriptor

onlyRefreshCacheIfNewerVersion

public void onlyRefreshCacheIfNewerVersion()

PUBLIC: This method is the equivalent of calling setShouldOnlyRefreshCacheIfNewerVersion(boolean) with an argument of true: it configures a Descriptor to only refresh the cache if the data received from the database by a query is newer than the data in the cache (as determined by the optimistic locking field) and as long as one of the following is true:

• the Descriptor was configured by calling alwaysRefreshCache() or alwaysRefreshCacheOnRemote(),
• the query was configured by calling ObjectLevelReadQuery.refreshIdentityMapResult(), or
• the query was a call to Session.refreshObject(java.lang.Object)

However, if a query hits the cache, data is not refreshed regardless of how this setting is configured. For example, by default, when a query for a single object based on its primary key is executed, OracleAS TopLink will first look in the cache for the object. If the object is in the cache, the cached object is returned and data is not refreshed. To avoid cache hits, use the disableCacheHits() method.

Also note that the UnitOfWork will not refresh its registered objects.

Overrides:

onlyRefreshCacheIfNewerVersion in class Descriptor

See Also:

dontOnlyRefreshCacheIfNewerVersion()

removeProperty

public void removeProperty(java.lang.String property)

PUBLIC: Remove the user defined property.

Overrides:

removeProperty in class Descriptor

setAlias

public void setAlias(java.lang.String alias)

PUBLIC: Set the alias

Overrides:

setAlias in class Descriptor

setAmendmentClass

public void setAmendmentClass(java.lang.Class amendmentClass)

PUBLIC: Set the amendment class. The amendment method will be called on the class before initialization to allow for it to initialize the descriptor. The method must be a public static method on the class.

Overrides:

setAmendmentClass in class Descriptor

setAmendmentMethodName

public void setAmendmentMethodName(java.lang.String amendmentMethodName)

PUBLIC: Set the amendment method. This will be called on the amendment class before initialization to allow for it to initialize the descriptor. The method must be a public static method on the class.

Overrides:

setAmendmentMethodName in class Descriptor

setCacheSynchronizationType

public void setCacheSynchronizationType(int type)

PUBLIC: Set the type of cache synchonization that will be used on objects of this type. Possible values are: SEND_OBJECT_CHANGES INVALIDATE_CHANGED_OBJECTS SEND_NEW_OBJECTS+WITH_CHANGES DO_NOT_SEND_CHANGES Note: Cache Synchronization type cannot be altered for descriptors that are set as isolated using the setIsIsolated method.

Overrides:

setCacheSynchronizationType in class Descriptor

Parameters:

type - int The synchronization type for this descriptor

setObjectChangePolicy

public void setObjectChangePolicy(oracle.toplink.descriptors.changetracking.ObjectChangePolicy policy)

PUBLIC: Set the ObjectChangePolicy for this descriptor.

Overrides:

setObjectChangePolicy in class Descriptor

setHistoryPolicy

public void setHistoryPolicy(HistoryPolicy policy)

PUBLIC: Set the HistoryPolicy for this descriptor.

Overrides:

setHistoryPolicy in class Descriptor

setCacheInvalidationPolicy

public void setCacheInvalidationPolicy(CacheInvalidationPolicy policy)

PUBLIC: Set the Cache Invalidation Policy for this descriptor

Overrides:

setCacheInvalidationPolicy in class Descriptor

See Also:

CacheInvalidationPolicy

setDescriptorType

public void setDescriptorType(int descriptorType)

ADVANCED: set the descriptor type (NORMAL by default, others include INTERFACE, AGGREGATE, AGGREGATE COLLECTION)

Overrides:

setDescriptorType in class Descriptor

setIdentityMapClass

public void setIdentityMapClass(java.lang.Class theIdentityMapClass)

PUBLIC: Set the class of identity map to be used by this descriptor. The default is the "FullIdentityMap".

Overrides:

setIdentityMapClass in class Descriptor

setIdentityMapSize

public void setIdentityMapSize(int identityMapSize)

PUBLIC: Set the size of the identity map to be used by this descriptor. The default is the 100.

Overrides:

setIdentityMapSize in class Descriptor

setReturningPolicy

public void setReturningPolicy(ReturningPolicy returningPolicy)

PUBLIC: Sets the returning policy.

Overrides:

setReturningPolicy in class Descriptor

setIsIsolated

public void setIsIsolated(boolean isIsolated)

PUBLIC: Used to set if the class that this descriptor represents should be isolated from the shared cache. Note: Calling this method with true will also set the cacheSynchronizationType to DO_NOT_SEND_CHANGES since isolated objects cannot be sent by TopLink cache synchronization.

Overrides:

setIsIsolated in class Descriptor

setJavaClass

public void setJavaClass(java.lang.Class theJavaClass)

PUBLIC: Set the Java class that this descriptor maps. Every descriptor maps one and only one class.

Overrides:

setJavaClass in class Descriptor

setJavaInterface

public void setJavaInterface(java.lang.Class theJavaInterface)

PUBLIC: Sets the descriptor to be for an interface. An interface descriptor allows for other classes to reference an interface or one of serveral other classes. The implementor classes can be completely unrelated in term of the database stored in distinct tables. Queries can also be done for the interface which will query each of the implementor classes. An interface descriptor cannot define any mappings as an interface is just API and not state, a interface descriptor should define the common query key of its implementors to allow querying. An interface descriptor also does not define a primary key or table or other settings. If an interface only has a single implementor (i.e. a classes public interface or remote) then an interface descriptor should not be defined for it and relationships should be to the implementor class not the interface, in this case the implementor class can add the interface through its interface policy to map queries on the interface to it.

Overrides:

setJavaInterface in class Descriptor

setOptimisticLockingPolicy

public void setOptimisticLockingPolicy(oracle.toplink.internal.descriptors.OptimisticLockingPolicy optimisticLockingPolicy)

PUBLIC: Set the OptimisticLockingPolicy. This can be one of the provided locking policies or a user defined policy.

Overrides:

setOptimisticLockingPolicy in class Descriptor

See Also:

VersionLockingPolicy, TimestampLockingPolicy, FieldsLockingPolicy

setPrimaryKeyFieldName

public void setPrimaryKeyFieldName(java.lang.String fieldName)

PUBLIC: Specify the primary key field of the descriptors table. This should only be called if it is a singlton primary key field, otherwise addPrimaryKeyFieldName should be called. If the descriptor has many tables, this must be the primary key in all of the tables.

Overrides:

setPrimaryKeyFieldName in class Descriptor

See Also:

addPrimaryKeyFieldName(String)

setPrimaryKeyFieldNames

public void setPrimaryKeyFieldNames(java.util.Vector primaryKeyFieldsName)

PUBLIC: User can specify a vector of all the primary key field names if primary key is composite.

Overrides:

setPrimaryKeyFieldNames in class Descriptor

See Also:

addPrimaryKeyFieldName(String)

setProperty

public void setProperty(java.lang.String name,
                        java.lang.Object value)

PUBLIC: Set the user defined property.

Overrides:

setProperty in class Descriptor

setRemoteIdentityMapClass

public void setRemoteIdentityMapClass(java.lang.Class theIdentityMapClass)

PUBLIC: Set the class of identity map to be used by this descriptor. The default is the "FullIdentityMap".

Overrides:

setRemoteIdentityMapClass in class Descriptor

setRemoteIdentityMapSize

public void setRemoteIdentityMapSize(int identityMapSize)

PUBLIC: Set the size of the identity map to be used by this descriptor. The default is the 100.

Overrides:

setRemoteIdentityMapSize in class Descriptor

setSequenceNumberFieldName

public void setSequenceNumberFieldName(java.lang.String fieldName)

PUBLIC: Set the sequence number field name. This is the field in the descriptors table that needs its value to be generated. This is normally the primary key field of the descriptor.

Overrides:

setSequenceNumberFieldName in class Descriptor

setSequenceNumberName

public void setSequenceNumberName(java.lang.String name)

PUBLIC: Set the sequence number name. This is the seq_name part of the row stored in the sequence table for this descriptor. If using Oracle native sequencing this is the name of the Oracle sequence object. If using Sybase native sequencing this name has no meaning, but should still be set for compatibility. The name does not have to be unique among descriptors, as having descriptors share sequences can improve pre-allocation performance.

Overrides:

setSequenceNumberName in class Descriptor

setShouldAlwaysConformResultsInUnitOfWork

public void setShouldAlwaysConformResultsInUnitOfWork(boolean shouldAlwaysConformResultsInUnitOfWork)

PUBLIC: set if the descriptor is defined to always conform the results in unit of work in read query.

Overrides:

setShouldAlwaysConformResultsInUnitOfWork in class Descriptor

setShouldAlwaysRefreshCache

public void setShouldAlwaysRefreshCache(boolean shouldAlwaysRefreshCache)

PUBLIC: When the shouldAlwaysRefreshCache argument passed into this method is true, this method configures a Descriptor to always refresh the cache if data is received from the database by any query.

However, if a query hits the cache, data is not refreshed regardless of how this setting is configured. For example, by default, when a query for a single object based on its primary key is executed, OracleAS TopLink will first look in the cache for the object. If the object is in the cache, the cached object is returned and data is not refreshed. To avoid cache hits, use the disableCacheHits() method.

Also note that the UnitOfWork will not refresh its registered objects.

Use this property with caution because it can lead to poor performance and may refresh on queries when it is not desired. Normally, if you require fresh data, it is better to configure a query with ObjectLevelReadQuery.refreshIdentityMapResult(). To ensure that refreshes are only done when required, use this method in conjunction with onlyRefreshCacheIfNewerVersion().

When the shouldAlwaysRefreshCache argument passed into this method is false, this method ensures that a Descriptor is not configured to always refresh the cache if data is received from the database by any query.

Overrides:

setShouldAlwaysRefreshCache in class Descriptor

See Also:

alwaysRefreshCache(), dontAlwaysRefreshCache()

setShouldAlwaysRefreshCacheOnRemote

public void setShouldAlwaysRefreshCacheOnRemote(boolean shouldAlwaysRefreshCacheOnRemote)

PUBLIC: When the shouldAlwaysRefreshCacheOnRemote argument passed into this method is true, this method configures a Descriptor to always remotely refresh the cache if data is received from the database by any query in a RemoteSession. However, if a query hits the cache, data is not refreshed regardless of how this setting is configured. For example, by default, when a query for a single object based on its primary key is executed, OracleAS TopLink will first look in the cache for the object. If the object is in the cache, the cached object is returned and data is not refreshed. To avoid cache hits, use the disableCacheHitsOnRemote() method.

Also note that the UnitOfWork will not refresh its registered objects.

Use this property with caution because it can lead to poor performance and may refresh on queries when it is not desired. Normally, if you require fresh data, it is better to configure a query with ObjectLevelReadQuery.refreshIdentityMapResult(). To ensure that refreshes are only done when required, use this method in conjunction with #refreshOnlyIfNewerVersion.

When the shouldAlwaysRefreshCacheOnRemote argument passed into this method is false, this method ensures that a Descriptor is not configured to always remotely refresh the cache if data is received from the database by any query in a RemoteSession.

Overrides:

setShouldAlwaysRefreshCacheOnRemote in class Descriptor

See Also:

alwaysRefreshCacheOnRemote(), dontAlwaysRefreshCacheOnRemote()

setShouldBeReadOnly

public void setShouldBeReadOnly(boolean shouldBeReadOnly)

PUBLIC: Define if the descriptor reference class is read-only

Overrides:

setShouldBeReadOnly in class Descriptor

setReadOnly

public void setReadOnly()

PUBLIC: Set the descriptor to be read-only. Declaring a descriptor is read-only means that instances of the reference class will never be modified. Read-only descriptor is usually used in the unit of work to gain performance as there is no need for the registration, clone and merge for the read-only classes.

Overrides:

setReadOnly in class Descriptor

setShouldDisableCacheHits

public void setShouldDisableCacheHits(boolean shouldDisableCacheHits)

PUBLIC: Set if cache hits on primary key read object queries should be disabled.

Overrides:

setShouldDisableCacheHits in class Descriptor

See Also:

alwaysRefreshCache()

setShouldDisableCacheHitsOnRemote

public void setShouldDisableCacheHitsOnRemote(boolean shouldDisableCacheHitsOnRemote)

PUBLIC: Set if the remote session cache hits on primary key read object queries is allowed or not.

Overrides:

setShouldDisableCacheHitsOnRemote in class Descriptor

See Also:

disableCacheHitsOnRemote()

setShouldOnlyRefreshCacheIfNewerVersion

public void setShouldOnlyRefreshCacheIfNewerVersion(boolean shouldOnlyRefreshCacheIfNewerVersion)

PUBLIC: When the shouldOnlyRefreshCacheIfNewerVersion argument passed into this method is true, this method configures a Descriptor to only refresh the cache if the data received from the database by a query is newer than the data in the cache (as determined by the optimistic locking field) and as long as one of the following is true:

• the Descriptor was configured by calling alwaysRefreshCache() or alwaysRefreshCacheOnRemote(),
• the query was configured by calling ObjectLevelReadQuery.refreshIdentityMapResult(), or
• the query was a call to Session.refreshObject(java.lang.Object)

However, if a query hits the cache, data is not refreshed regardless of how this setting is configured. For example, by default, when a query for a single object based on its primary key is executed, OracleAS TopLink will first look in the cache for the object. If the object is in the cache, the cached object is returned and data is not refreshed. To avoid cache hits, use the disableCacheHits() method.

Also note that the UnitOfWork will not refresh its registered objects.

When the shouldOnlyRefreshCacheIfNewerVersion argument passed into this method is false, this method ensures that a Descriptor is not configured to only refresh the cache if the data received from the database by a query is newer than the data in the cache (as determined by the optimistic locking field).

Overrides:

setShouldOnlyRefreshCacheIfNewerVersion in class Descriptor

See Also:

onlyRefreshCacheIfNewerVersion(), dontOnlyRefreshCacheIfNewerVersion()

setShouldOrderMappings

public void setShouldOrderMappings(boolean shouldOrderMappings)

PUBLIC: This is set to turn off the ordering of mappings. By Default this is set to true. By ordering the mappings TopLink insures that object are merged in the right order. If the order of the mappings needs to be specified by the developer then set this to false and TopLink will use the order that the mappings were added to the descriptor

Overrides:

setShouldOrderMappings in class Descriptor

setWrapperPolicy

public void setWrapperPolicy(WrapperPolicy wrapperPolicy)

ADVANCED: Sets the WrapperPolicy for this descriptor. This advacned feature can be used to wrap objects with other classes such as CORBA TIE objects or EJBs.

Overrides:

setWrapperPolicy in class Descriptor

shouldAlwaysConformResultsInUnitOfWork

public boolean shouldAlwaysConformResultsInUnitOfWork()

PUBLIC: Return if the descriptor is defined to always conform the results in unit of work in read query.

Overrides:

shouldAlwaysConformResultsInUnitOfWork in class Descriptor

shouldAlwaysRefreshCache

public boolean shouldAlwaysRefreshCache()

PUBLIC: This method returns true if the Descriptor is configured to always refresh the cache if data is received from the database by any query. Otherwise, it returns false.

Overrides:

shouldAlwaysRefreshCache in class Descriptor

See Also:

setShouldAlwaysRefreshCache(boolean)

shouldAlwaysRefreshCacheOnRemote

public boolean shouldAlwaysRefreshCacheOnRemote()

PUBLIC: This method returns true if the Descriptor is configured to always remotely refresh the cache if data is received from the database by any query in a RemoteSession. Otherwise, it returns false.

Overrides:

shouldAlwaysRefreshCacheOnRemote in class Descriptor

See Also:

setShouldAlwaysRefreshCacheOnRemote(boolean)

shouldBeReadOnly

public boolean shouldBeReadOnly()

PUBLIC: Return if the descriptor reference class is defined as read-only

Overrides:

shouldBeReadOnly in class Descriptor

shouldDisableCacheHits

public boolean shouldDisableCacheHits()

PUBLIC: Return if for cache hits on primary key read object queries to be disabled.

Overrides:

shouldDisableCacheHits in class Descriptor

See Also:

disableCacheHits()

shouldDisableCacheHitsOnRemote

public boolean shouldDisableCacheHitsOnRemote()

PUBLIC: Return if the remote server session cache hits on primary key read object queries is aloowed or not.

Overrides:

shouldDisableCacheHitsOnRemote in class Descriptor

See Also:

disableCacheHitsOnRemote()

shouldOnlyRefreshCacheIfNewerVersion

public boolean shouldOnlyRefreshCacheIfNewerVersion()

PUBLIC: This method returns true if the Descriptor is configured to only refresh the cache if the data received from the database by a query is newer than the data in the cache (as determined by the optimistic locking field). Otherwise, it returns false.

Overrides:

shouldOnlyRefreshCacheIfNewerVersion in class Descriptor

See Also:

setShouldOnlyRefreshCacheIfNewerVersion(boolean)

shouldUseCacheIdentityMap

public boolean shouldUseCacheIdentityMap()

PUBLIC: Return true if this descriptor is using CacheIdentityMap

Overrides:

shouldUseCacheIdentityMap in class Descriptor

shouldUseFullIdentityMap

public boolean shouldUseFullIdentityMap()

PUBLIC: Return true if this descriptor is using FullIdentityMap

Overrides:

shouldUseFullIdentityMap in class Descriptor

shouldUseHardCacheWeakIdentityMap

public boolean shouldUseHardCacheWeakIdentityMap()

PUBLIC: Return true if this descriptor is using HardCacheWeakIdentityMap.

Overrides:

shouldUseHardCacheWeakIdentityMap in class Descriptor

shouldUseNoIdentityMap

public boolean shouldUseNoIdentityMap()

PUBLIC: Return true if this descriptor is using NoIdentityMap

Overrides:

shouldUseNoIdentityMap in class Descriptor

shouldUseRemoteCacheIdentityMap

public boolean shouldUseRemoteCacheIdentityMap()

PUBLIC: Return true if this descriptor is using CacheIdentityMap

Overrides:

shouldUseRemoteCacheIdentityMap in class Descriptor

shouldUseRemoteFullIdentityMap

public boolean shouldUseRemoteFullIdentityMap()

PUBLIC: Return true if this descriptor is using FullIdentityMap

Overrides:

shouldUseRemoteFullIdentityMap in class Descriptor

shouldUseRemoteHardCacheWeakIdentityMap

public boolean shouldUseRemoteHardCacheWeakIdentityMap()

PUBLIC: Return true if this descriptor is using HardCacheWeakIdentityMap

Overrides:

shouldUseRemoteHardCacheWeakIdentityMap in class Descriptor

shouldUseRemoteNoIdentityMap

public boolean shouldUseRemoteNoIdentityMap()

PUBLIC: Return true if this descriptor is using NoIdentityMap

Overrides:

shouldUseRemoteNoIdentityMap in class Descriptor

shouldUseRemoteSoftCacheWeakIdentityMap

public boolean shouldUseRemoteSoftCacheWeakIdentityMap()

PUBLIC: Return true if this descriptor is using SoftCacheWeakIdentityMap

Overrides:

shouldUseRemoteSoftCacheWeakIdentityMap in class Descriptor

shouldUseRemoteWeakIdentityMap

public boolean shouldUseRemoteWeakIdentityMap()

PUBLIC: Return true if this descriptor is using WeakIdentityMap

Overrides:

shouldUseRemoteWeakIdentityMap in class Descriptor

shouldUseSoftCacheWeakIdentityMap

public boolean shouldUseSoftCacheWeakIdentityMap()

PUBLIC: Return true if this descriptor is using SoftCacheWeakIdentityMap.

Overrides:

shouldUseSoftCacheWeakIdentityMap in class Descriptor

shouldUseWeakIdentityMap

public boolean shouldUseWeakIdentityMap()

PUBLIC: Return true if this descriptor is using WeakIdentityMap

Overrides:

shouldUseWeakIdentityMap in class Descriptor

useAllFieldsLocking

public void useAllFieldsLocking()

PUBLIC: Set the locking policy an all fields locking policy. A field locking policy is base on locking on all fields by comparing with their previous values to detect field-level collisions. Note: the unit of work must be used for all updates when using field locking.

Overrides:

useAllFieldsLocking in class Descriptor

See Also:

AllFieldsLockingPolicy

useCacheIdentityMap

public void useCacheIdentityMap()

PUBLIC: Set the class of identity map to be the cache identity map. This map caches the LRU instances read from the database. The default is the "SoftCacheWeakIdentityMap".

Overrides:

useCacheIdentityMap in class Descriptor

useChangedFieldsLocking

public void useChangedFieldsLocking()

PUBLIC: Set the locking policy a changed fields locking policy. A field locking policy is base on locking on all changed fields by comparing with their previous values to detect field-level collisions. Note: the unit of work must be used for all updates when using field locking.

Overrides:

useChangedFieldsLocking in class Descriptor

See Also:

ChangedFieldsLockingPolicy

useCloneCopyPolicy

public void useCloneCopyPolicy()

PUBLIC: Specifies that the creation of clones within a unit of work is done by sending the #clone() method to the original object. The #clone() method must return a logical shallow copy of the original object. This can be used if the default mechanism of creating a new instance does not handle the object's non-persistent attributes correctly.

Overrides:

useCloneCopyPolicy in class Descriptor

See Also:

useCloneCopyPolicy(String)

useCloneCopyPolicy

public void useCloneCopyPolicy(java.lang.String cloneMethodName)

PUBLIC: Specifies that the creation of clones within a unit of work is done by sending the cloneMethodName method to the original object. This method must return a logical shallow copy of the original object. This can be used if the default mechanism of creating a new instance does not handle the object's non-persistent attributes correctly.

Overrides:

useCloneCopyPolicy in class Descriptor

See Also:

useCloneCopyPolicy()

useInstantiationCopyPolicy

public void useInstantiationCopyPolicy()

PUBLIC: Specifies that the creation of clones within a unit of work is done by building a new instance using the technique indicated by the descriptor's instantiation policy (which by default is to use the the default constructor). This new instance is then populated by using the descriptor's mappings to copy attributes from the original to the clone. This is the default. If another mechanism is desired the copy policy allows for a clone method to be called.

Overrides:

useInstantiationCopyPolicy in class Descriptor

See Also:

useCloneCopyPolicy(), useCloneCopyPolicy(String), useDefaultConstructorInstantiationPolicy(), useMethodInstantiationPolicy(String), useFactoryInstantiationPolicy(Class, String), useFactoryInstantiationPolicy(Class, String, String), useFactoryInstantiationPolicy(Object, String)

useDefaultConstructorInstantiationPolicy

public void useDefaultConstructorInstantiationPolicy()

PUBLIC: Use the default constructor to create new instances of objects built from the database. This is the default. The descriptor's class must either define a default constructor or define no constructors at all.

Overrides:

useDefaultConstructorInstantiationPolicy in class Descriptor

See Also:

useMethodInstantiationPolicy(String), useFactoryInstantiationPolicy(Class, String), useFactoryInstantiationPolicy(Class, String, String), useFactoryInstantiationPolicy(Object, String)

useFactoryInstantiationPolicy

public void useFactoryInstantiationPolicy(java.lang.Class factoryClass,
                                          java.lang.String methodName)

PUBLIC: Use an object factory to create new instances of objects built from the database. The methodName is the name of the method that will be invoked on the factory. When invoked, it must return a new instance of the descriptor's class. The factory will be created by invoking the factoryClass's default constructor.

Overrides:

useFactoryInstantiationPolicy in class Descriptor

See Also:

useDefaultConstructorInstantiationPolicy(), useMethodInstantiationPolicy(String), useFactoryInstantiationPolicy(Class, String, String), useFactoryInstantiationPolicy(Object, String)

useFactoryInstantiationPolicy

public void useFactoryInstantiationPolicy(java.lang.Class factoryClass,
                                          java.lang.String methodName,
                                          java.lang.String factoryMethodName)

PUBLIC: Use an object factory to create new instances of objects built from the database. The factoryMethodName is a static method declared by the factoryClass. When invoked, it must return an instance of the factory. The methodName is the name of the method that will be invoked on the factory. When invoked, it must return a new instance of the descriptor's class.

Overrides:

useFactoryInstantiationPolicy in class Descriptor

See Also:

useDefaultConstructorInstantiationPolicy(), useFactoryInstantiationPolicy(Class, String), useFactoryInstantiationPolicy(Object, String), useMethodInstantiationPolicy(String)

useFactoryInstantiationPolicy

public void useFactoryInstantiationPolicy(java.lang.Object factory,
                                          java.lang.String methodName)

PUBLIC: Use an object factory to create new instances of objects built from the database. The methodName is the name of the method that will be invoked on the factory. When invoked, it must return a new instance of the descriptor's class.

Overrides:

useFactoryInstantiationPolicy in class Descriptor

See Also:

useDefaultConstructorInstantiationPolicy(), useMethodInstantiationPolicy(String), useFactoryInstantiationPolicy(Class, String), useFactoryInstantiationPolicy(Class, String, String)

useFullIdentityMap

public void useFullIdentityMap()

PUBLIC: Set the class of identity map to be the full identity map. This map caches all instances read and grows to accomodate them. The default is the "SoftCacheWeakIdentityMap".

Overrides:

useFullIdentityMap in class Descriptor

useHardCacheWeakIdentityMap

public void useHardCacheWeakIdentityMap()

PUBLIC: Set the class of identity map to be the hard cache weak identity map. This map uses weak references to only cache object in-memory. It also includes a secondary fixed sized soft cache to improve caching performance. This is provided because some Java VM's do not implement soft references correctly. The default is the "SoftCacheWeakIdentityMap".

Overrides:

useHardCacheWeakIdentityMap in class Descriptor

useMethodInstantiationPolicy

public void useMethodInstantiationPolicy(java.lang.String staticMethodName)

PUBLIC: Use the specified static method to create new instances of objects built from the database. This method must be statically declared by the descriptor's class, and it must return a new instance of the descriptor's class.

Overrides:

useMethodInstantiationPolicy in class Descriptor

See Also:

useDefaultConstructorInstantiationPolicy(), useFactoryInstantiationPolicy(Class, String), useFactoryInstantiationPolicy(Class, String, String), useFactoryInstantiationPolicy(Object, String)

useNoIdentityMap

public void useNoIdentityMap()

PUBLIC: Set the class of identity map to be the no identity map. This map does no caching. The default is the "SoftCacheWeakIdentityMap".

Overrides:

useNoIdentityMap in class Descriptor

useRemoteCacheIdentityMap

public void useRemoteCacheIdentityMap()

PUBLIC: Set the class of identity map to be the cache identity map. This map caches the LRU instances read from the database. The default is the "SoftCacheWeakIdentityMap".

Overrides:

useRemoteCacheIdentityMap in class Descriptor

useRemoteFullIdentityMap

public void useRemoteFullIdentityMap()

PUBLIC: Set the class of identity map to be the full identity map. This map caches all instances read and grows to accomodate them. The default is the "SoftCacheWeakIdentityMap".

Overrides:

useRemoteFullIdentityMap in class Descriptor

useRemoteHardCacheWeakIdentityMap

public void useRemoteHardCacheWeakIdentityMap()

PUBLIC: Set the class of identity map to be the hard cache weak identity map. This map uses weak references to only cache object in-memory. It also includes a secondary fixed sized soft cache to improve caching performance. This is provided because some Java VM's do not implement soft references correctly. The default is the "SoftCacheWeakIdentityMap".

Overrides:

useRemoteHardCacheWeakIdentityMap in class Descriptor

useRemoteNoIdentityMap

public void useRemoteNoIdentityMap()

PUBLIC: Set the class of identity map to be the no identity map. This map does no caching. The default is the "SoftCacheWeakIdentityMap".

Overrides:

useRemoteNoIdentityMap in class Descriptor

useRemoteSoftCacheWeakIdentityMap

public void useRemoteSoftCacheWeakIdentityMap()

PUBLIC: Set the class of identity map to be the soft cache weak identity map. The SoftCacheIdentityMap holds a fixed number of objects is memory (using SoftReferences) to improve caching. The default is the "SoftCacheWeakIdentityMap".

Overrides:

useRemoteSoftCacheWeakIdentityMap in class Descriptor

useRemoteWeakIdentityMap

public void useRemoteWeakIdentityMap()

PUBLIC: Set the class of identity map to be the weak identity map. The default is the "SoftCacheWeakIdentityMap".

Overrides:

useRemoteWeakIdentityMap in class Descriptor

useSelectedFieldsLocking

public void useSelectedFieldsLocking(java.util.Vector fieldNames)

PUBLIC: Set the locking policy a selected fields locking policy. A field locking policy is base on locking on the specified fields by comparing with their previous values to detect field-level collisions. Note: the unit of work must be used for all updates when using field locking.

Overrides:

useSelectedFieldsLocking in class Descriptor

See Also:

SelectedFieldsLockingPolicy

useSoftCacheWeakIdentityMap

public void useSoftCacheWeakIdentityMap()

PUBLIC: Set the class of identity map to be the soft cache weak identity map. The SoftCacheIdentityMap holds a fixed number of objects is memory (using SoftReferences) to improve caching. The default is the "SoftCacheWeakIdentityMap".

Overrides:

useSoftCacheWeakIdentityMap in class Descriptor

usesOptimisticLocking

public boolean usesOptimisticLocking()

PUBLIC: Return true if the receiver uses write (optimistic) locking.

Overrides:

usesOptimisticLocking in class Descriptor

usesSequenceNumbers

public boolean usesSequenceNumbers()

PUBLIC: Return true if the receiver uses sequence numbers.

Overrides:

usesSequenceNumbers in class Descriptor

useTimestampLocking

public void useTimestampLocking(java.lang.String writeLockFieldName)

PUBLIC: Use the Timestamps locking policy and storing the value in the cache key #see useVersionLocking(String)

Overrides:

useTimestampLocking in class Descriptor

useTimestampLocking

public void useTimestampLocking(java.lang.String writeLockFieldName,
                                boolean shouldStoreInCache)

PUBLIC: Set the locking policy to use timestamp version locking. This updates the timestamp field on all updates, first comparing that the field has not changed to detect locking conflicts. Note: many database have limited precision of timestamps which can be an issue is highly concurrent systems. The parameter 'shouldStoreInCache' configures the version lock value to be stored in the cache or in the object. Note: if using a stateless model where the object can be passed to a client and then later updated in a different transaction context, then the version lock value should not be stored in the cache, but in the object to ensure it is the correct value for that object.

Overrides:

useTimestampLocking in class Descriptor

See Also:

VersionLockingPolicy

useVersionLocking

public void useVersionLocking(java.lang.String writeLockFieldName)

PUBLIC: Default to use the version locking policy and storing the value in the cache key #see useVersionLocking(String)

Overrides:

useVersionLocking in class Descriptor

useVersionLocking

public void useVersionLocking(java.lang.String writeLockFieldName,
                              boolean shouldStoreInCache)

PUBLIC: Set the locking policy to use numeric version locking. This updates the version field on all updates, first comparing that the field has not changed to detect locking conflicts. The parameter 'shouldStoreInCache' configures the version lock value to be stored in the cache or in the object. Note: if using a stateless model where the object can be passed to a client and then later updated in a different transaction context, then the version lock value should not be stored in the cache, but in the object to ensure it is the correct value for that object.

Overrides:

useVersionLocking in class Descriptor

See Also:

TimestampLockingPolicy

useWeakIdentityMap

public void useWeakIdentityMap()

PUBLIC: Set the class of identity map to be the weak identity map. The default is the "SoftCacheWeakIdentityMap".

Overrides:

useWeakIdentityMap in class Descriptor

getCMPPolicy

public CMPPolicy getCMPPolicy()

ADVANCED: Return the cmp descriptor that holds EJB CMP specific information. This will be null unless explicitly set, or after CMP deoloyment. This can only be specified when using CMP for bean class descriptors. This must be set explicitly if any setting need to be configured and before calling getCMPPolicy().

Overrides:

getCMPPolicy in class Descriptor

setCMPPolicy

public void setCMPPolicy(CMPPolicy newCMPPolicy)

ADVANCED: Set the cmp descriptor that holds EJB CMP specific information. This can only be specified when using CMP for bean class descriptors. This must be set explicitly if any setting need to be configured and before calling getCMPPolicy().

Overrides:

setCMPPolicy in class Descriptor

getFetchGroupManager

public FetchGroupManager getFetchGroupManager()

PUBLIC: Get the fetch group manager for the descriptor. The fetch group manager is responsible for managing the fetch group behaviors and operations. To use the fetch group, the domain object must implement FetchGroupTracker interface. Otherwise, a descriptor validation exception would throw during initialization. NOTE: It's for CMP project only.

Overrides:

getFetchGroupManager in class Descriptor

See Also:

FetchGroupTracker

setFetchGroupManager

public void setFetchGroupManager(FetchGroupManager fetchGroupManager)

PUBLIC: Set the fetch group manager for the descriptor. The fetch group manager is responsible for managing the fetch group behaviors and operations.

Overrides:

setFetchGroupManager in class Descriptor