oracle.toplink.publicinterface
Class Descriptor

java.lang.Object
oracle.toplink.publicinterface.Descriptor

All Implemented Interfaces:

java.lang.Cloneable, java.io.Serializable

Direct Known Subclasses:

ObjectRelationalDescriptor, SDKDescriptor

public class Descriptor

extends java.lang.Object

implements java.lang.Cloneable, java.io.Serializable

Purpose: TopLink has been designed to take advantage of the similarities between relational databases and objects while accommodating for their differences, providing an object oriented wrapper for relational databases. This is accomplished through the use of Descriptors. A descriptor is a pure specification class with all its behaviour deputized to DescriptorEventManager, DescriptorQueryManager and ObjectBuilder. Look at the following variables for the list of specification on the descriptor. A Descriptor is a set of mappings that describe how an objects's data is to be represented in a relational database. It contains mappings from the class instance variables to the table's fields, as well as the transformation routines necessary for storing and retrieving attributes. As such the descriptor acts as the link between the Java object and its database representaiton. Every descripor is initialized with the following information:

• The Java class its describes, and the corresponding table(s) for storing instances of the class.
• The primary key of the table.
• A list of query keys for field names.
• A description of the objects's attributes and relationships. This information is stored in mappings.
• A set of user selectable properties for tailoring the behaviour of the descriptor.

See Also:

DescriptorEventManager, DescriptorQueryManager, InheritancePolicy, InterfacePolicy, OptimisticLockingPolicy, Serialized Form

Constructor Summary

Descriptor()
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 to field 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 to field 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	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	addTableName(java.lang.String tableName) PUBLIC: Specify the table name for the class of objects the receiver describes.
void	adjustMultipleTableInsertOrder() INTERNAL: Adjust the order of the tables in the multipleTableInsertOrder Vector according to the FK relationship if one (or more) were previously specified.
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	applyAmendmentMethod(DescriptorEvent event) INTERNAL: Call the descriptor amendment method.
boolean	arePrimaryKeyFields(java.util.Vector fields) INTERNAL: Used to determine if a foreign key references the primary key.
java.util.Vector	buildDirectValuesFromFieldValue(java.lang.Object fieldValue) INTERNAL: Extract the direct values from the specified field value.
void	buildField(oracle.toplink.internal.helper.DatabaseField field) INTERNAL: The table of the field is ensured to be unique from the descriptor's tables.
oracle.toplink.internal.helper.DatabaseField	buildField(java.lang.String fieldName) INTERNAL: A DatabaseField is built from the given field name.
java.lang.Object	buildFieldValueFromDirectValues(java.util.Vector directValues, java.lang.String elementDataTypeName, oracle.toplink.publicinterface.Session session) INTERNAL: Build the appropriate field value for the specified set of direct values.
java.lang.Object	buildFieldValueFromForeignKeys(java.util.Vector foreignKeys, java.lang.String referenceDataTypeName, oracle.toplink.publicinterface.Session session) INTERNAL: Build and return the appropriate field value for the specified set of foreign keys (i.e. each row has the fields that make up a foreign key).
java.lang.Object	buildFieldValueFromNestedRow(DatabaseRow nestedRow, oracle.toplink.publicinterface.Session session) INTERNAL: Build and return the field value from the specified nested database row.
java.lang.Object	buildFieldValueFromNestedRows(java.util.Vector nestedRows, java.lang.String structureName, oracle.toplink.publicinterface.Session session) INTERNAL: Build and return the appropriate field value for the specified set of nested rows.
DatabaseRow	buildNestedRowFromFieldValue(java.lang.Object fieldValue) INTERNAL: Build and return the nested database row from the specified field value.
java.util.Vector	buildNestedRowsFromFieldValue(java.lang.Object fieldValue, oracle.toplink.publicinterface.Session session) INTERNAL: Build and return the nested rows from the specified field value.
void	checkInheritanceTreeAggregateSettings(oracle.toplink.publicinterface.Session session, AggregateMapping mapping) INTERNAL: Verify that an aggregate descriptor's inheritance tree is full of aggregate descriptors.
java.lang.Object	clone() INTERNAL: Clones the descriptor
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.util.Hashtable	getAdditionalTablePrimaryKeyFields() INTERNAL: This is used to map the primary key field names in a multiple table descriptor.
java.lang.String	getAlias() PUBLIC: Get the alias
java.util.Vector	getAllFields() INTERNAL: Return all the fields.
java.lang.Class	getAmendmentClass() PUBLIC: Return the amendment class.
java.lang.String	getAmendmentMethodName() PUBLIC: Return the amendment method.
java.util.Vector	getConstraintDependencies() ADVANCED: TopLink automatically orders database access through the foreign key information provided in 1:1 and 1:m mappings.
oracle.toplink.internal.descriptors.CopyPolicy	getCopyPolicy() INTERNAL: Returns the copy policy.
oracle.toplink.internal.helper.DatabaseTable	getDefaultTable() INTERNAL: The first table in the tables is always treated as default.
int	getDescriptorType() ADVANCED: return the descriptor type (NORMAL by default, others include INTERFACE, AGGREGATE, AGGREGATE COLLECTION)
java.lang.String	getDescriptorTypeValue() INTERNAL: This method is explicitly used by the XML reader.
DescriptorEventManager	getEventManager() PUBLIC: Get the event manager for the descriptor.
java.util.Vector	getFields() INTERNAL: Return all the fields
java.lang.Class	getIdentityMapClass() INTERNAL: Return the class of identity map to be used by this descriptor.
int	getIdentityMapSize() PUBLIC: Return the size of the identity map.
InheritancePolicy	getInheritancePolicy() PUBLIC: The inheritance policy is used to define how a descriptor takes part in inheritance.
InheritancePolicy	getInheritancePolicyOrNull() INTERNAL: Return the inheritance policy.
oracle.toplink.internal.descriptors.InstantiationPolicy	getInstantiationPolicy() INTERNAL: Returns the instantiation policy.
InterfacePolicy	getInterfacePolicy() PUBLIC: Returns the InterfacePolicy.
InterfacePolicy	getInterfacePolicyOrNull() INTERNAL: 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
java.util.Vector	getMultipleTableForeignKeyAssociations() INTERNAL: Returns the foreign key relationships used for multiple tables which were specified by the user.
java.util.Hashtable	getMultipleTableForeignKeys() INTERNAL: Returns the foreign key relationships used for multiple tables which were specified by the user.
java.util.Vector	getMultipleTableInsertOrder() INTERNAL: Returns the Vector of DatabaseTables in the order which INSERTS should take place.
java.util.Vector	getMultipleTablePrimaryKeyAssociations() INTERNAL: Returns the foreign key relationships used for multiple tables which were specified by the user.
oracle.toplink.internal.descriptors.ObjectBuilder	getObjectBuilder() INTERNAL: Return the object builder
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.Vector	getPrimaryKeyFields() INTERNAL: Return all the primary key fields
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.
QueryKey	getQueryKeyNamed(java.lang.String queryKeyName) INTERNAL: Return the query key with the specified name
java.util.Hashtable	getQueryKeys() PUBLIC: Return the query keys.
DescriptorQueryManager	getQueryManager() PUBLIC: Return the queryManager.
java.lang.Class	getRemoteIdentityMapClass() INTERNAL: Return the class of identity map to be used by this descriptor.
int	getRemoteIdentityMapSize() PUBLIC: Return the size of the remote identity map.
oracle.toplink.internal.helper.DatabaseField	getSequenceNumberField() INTERNAL: Get sequence number field
java.lang.String	getSequenceNumberFieldName() PUBLIC: Get sequence number field name
java.lang.String	getSequenceNumberName() PUBLIC: Get sequence number name
java.lang.String	getSessionName() INTERNAL: Return the name of the session local to this descriptor.
oracle.toplink.internal.helper.DatabaseTable	getTable(java.lang.String tableName) INTERNAL: Checks if table name exists with the current descriptor or not.
java.lang.String	getTableName() PUBLIC: Return the name of the descriptor's first table.
java.util.Vector	getTableNames() PUBLIC: Return the table names.
java.util.Vector	getTables() INTERNAL: Return all the tables.
WrapperPolicy	getWrapperPolicy() ADVANCED: Return the WrapperPolicy for this descriptor.
boolean	hasDependencyOnParts() INTERNAL: Checks if the class has any private owned parts or other dependencies, (i.e.
boolean	hasInheritance() INTERNAL: Return if this descriptor is involved in inheritence, (is child or parent).
boolean	hasInterfacePolicy() INTERNAL: Return if this descriptor is involved in interface, (is child or parent).
boolean	hasMultipleTables() INTERNAL: Check if descriptor has multiple tables
boolean	hasPrivatelyOwnedParts() INTERNAL: Checks if the class has any private owned parts are not
boolean	hasQueryKeyOrMapping(java.lang.String attributeName) INTERNAL: Checks to see if it has a query key or mapping with the specified name or not.
boolean	hasWrapperPolicy() INTERNAL: Return if a wrapper policy is used.
void	initialize(oracle.toplink.publicinterface.Session session) INTERNAL: Initialize the mappings as a seperate step.
void	initializeAggregateInheritancePolicy(oracle.toplink.publicinterface.Session session) INTERNAL: This is needed by regular aggregate descriptors (because they are screwed up); but not by SDK aggregate descriptors.
void	initializeMultipleTablePrimaryKeyFields() INTERNAL: Rebuild the multiple table primary key map.
void	interfaceInitialization(oracle.toplink.publicinterface.Session session) INTERNAL: Allow the descriptor to initialize any dependancies on this session.
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	isFullyInitialized() INTERNAL: Check if the descriptor is finished initialization.
boolean	isInterfaceChildDescriptor() INTERNAL: Return if the descriptor defines inheritence and is a child.
boolean	isMultipleTableDescriptor() INTERNAL: Return if this descriptor has more than one table.
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	postInitialize(oracle.toplink.publicinterface.Session session) INTERNAL: Post initializations after mappings are initialized.
void	preInitialize(oracle.toplink.publicinterface.Session session) INTERNAL: Allow the descriptor to initialize any dependancies on this session.
void	preInterfaceInitialization(oracle.toplink.publicinterface.Session session) INTERNAL: Allow the descriptor to initialize any dependancies on this session.
void	rehashFieldDependancies(oracle.toplink.publicinterface.Session session) INTERNAL: Rehash any hashtables based on fields.
void	remoteInitialization(DistributedSession session) INTERNAL: Used to initialize a remote descriptor.
void	removeProperty(java.lang.String property) PUBLIC: Remove the user defined property.
boolean	requiresInitialization() INTERNAL: Aggregate and Interface descriptors do not require initialization as they are cloned and initialized by each mapping.
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	setConstraintDependencies(java.util.Vector constraintDependencies) ADVANCED: TopLink automatically orders database access through the foreign key information provided in 1:1 and 1:m mappings.
void	setCopyPolicy(oracle.toplink.internal.descriptors.CopyPolicy policy) INTERNAL: Set the copy policy.
void	setDefaultTable(oracle.toplink.internal.helper.DatabaseTable defaultTable) INTERNAL: The descriptors default table can be configured if the first table is not desired.
void	setDefaultTableName(java.lang.String defaultTableName) PUBLIC: The descriptors default table can be configured if the first table is not desired.
void	setDescriptorType(int descriptorType) ADVANCED: set the descriptor type (NORMAL by default, others include INTERFACE, AGGREGATE, AGGREGATE COLLECTION)
void	setDescriptorTypeValue(java.lang.String value) INTERNAL: This method is explicitly used by the XML reader.
void	setEventManager(DescriptorEventManager eventManager) INTERNAL: Set the event manager for the descriptor.
void	setExistenceChecking(java.lang.String token) INTERNAL: OBSOLETE - old reader.
void	setFields(java.util.Vector fields) INTERNAL: Set the fields used by 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	setInheritancePolicy(InheritancePolicy inheritancePolicy) INTERNAL: Sets the inheritance policy.
void	setInstantiationPolicy(oracle.toplink.internal.descriptors.InstantiationPolicy instantiationPolicy) INTERNAL: Sets the instantiation policy.
void	setInterfacePolicy(InterfacePolicy interfacePolicy) INTERNAL: Sets the interface policy.
void	setIsAggregateDescriptor(boolean isAggregateDescriptor) Deprecated.
void	setIsDescriptorForInterface(boolean isDescriptorForInterface) Deprecated.
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	setMappings(java.util.Vector mappings) INTERNAL: Set the mappings.
void	setMultipleTableForeignKeyFieldNames(java.util.Vector associations) INTERNAL: This method is used by the TopLink XML Deployment Descriptor to read and write these mappings
void	setMultipleTableInsertOrder(java.util.Vector newValue) ADVANCED: Sets the Vector of DatabaseTables in the order which INSERTS should take place.
void	setMultipleTablePrimaryKeyFieldNames(java.util.Vector associations) INTERNAL: This method is used by the TopLink XML Deployment Descriptor to read and write these mappings
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	setPrimaryKeyFields(java.util.Vector thePrimaryKeyFields) INTERNAL: Set the primary key fields
void	setProperties(java.util.Hashtable properties) INTERNAL: Set the user defined properties.
void	setProperty(java.lang.String name, java.lang.Object value) PUBLIC: Set the user defined property.
void	setQueryKeys(java.util.Hashtable queryKeys) INTERNAL: Set the query keys.
void	setQueryManager(DescriptorQueryManager queryManager) INTERNAL: Set the query manager.
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	setSequenceNumberField(oracle.toplink.internal.helper.DatabaseField sequenceNumberField) INTERNAL: Set the sequence number field.
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	setTableName(java.lang.String tableName) PUBLIC: Specify the table name for the class of objects the receiver describes.
void	setTableNames(java.util.Vector tableNames) PUBLIC: Specify the all table names for the class of objects the receiver describes.
void	setTableQualifier(java.lang.String tableQualifier) PUBLIC: Set the table Qualifier for this descriptor.
void	setTables(java.util.Vector theTables) INTERNAL: Sets the tables
void	setWrapperPolicy(WrapperPolicy wrapperPolicy) ADVANCED: Sets the WrapperPolicy for this descriptor.
void	setWriteLockFieldName(java.lang.String fieldName) Deprecated.
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	shouldOrderMappings() INTERNAL: Return if mappings should be ordered or not.
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
java.lang.String	toString() PUBLIC: Returns a brief string representation of the receiver.
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	useConstructorCopyPolicy() Deprecated. Replaced by useInstantiationCopyPolicy(), which is more accurately named.
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.
boolean	usesCacheIdentityMap() Deprecated. replaced by shouldUseCacheIdentityMap() This was rename to avoid confusing with useCacheIdentityMap.
void	useSelectedFieldsLocking(java.util.Vector fieldNames) PUBLIC: Set the locking policy a selected fields locking policy.
boolean	usesFieldLocking() INTERNAL: Return true if the receiver uses either all or changed fields for optimistic locking.
boolean	usesFullIdentityMap() Deprecated. replaced by shouldUseFullIdentityMap() This was rename to avoid confusing with useFullIdentityMap.
boolean	usesHardCacheWeakIdentityMap() Deprecated. replaced by shouldUseHardCacheWeakIdentityMap() This was rename to avoid confusing with useHardCacheWeakIdentityMap.
boolean	usesNoIdentityMap() Deprecated. replaced by shouldUseNoIdentityMap() This was rename to avoid confusing with useNoIdentityMap.
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.
boolean	usesSoftCacheWeakIdentityMap() Deprecated. replaced by shouldUseSoftCacheWeakIdentityMap() This was rename to avoid confusing with useSoftCacheWeakIdentityMap.
boolean	usesWeakIdentityMap() Deprecated. replaced by shouldUseWeakIdentityMap() This was rename to avoid confusing with useWeakIdentityMap.
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 java.lang.Object

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

Constructor Detail

Descriptor

public Descriptor()

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.

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.

addDirectMapping

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

PUBLIC: Add a direct to field 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.

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 to field 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.

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.

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.

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.

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.

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 all of the tables.

addQueryKey

public void addQueryKey(QueryKey queryKey)

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

addTableName

public void addTableName(java.lang.String tableName)

PUBLIC: Specify the table name for the class of objects the receiver describes. If the table has a qualifier it should be specified using the dot notation, (i.e. "userid.employee"). This method is used if there is more than one table.

adjustMultipleTableInsertOrder

public void adjustMultipleTableInsertOrder()

INTERNAL: Adjust the order of the tables in the multipleTableInsertOrder Vector according to the FK relationship if one (or more) were previously specified. I.e. target of FK relationship should be inserted before source. If the multipleTableInsertOrder has been specified (presumably by the user) then do not change it.

alwaysConformResultsInUnitOfWork

public void alwaysConformResultsInUnitOfWork()

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

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().

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.

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.

applyAmendmentMethod

public void applyAmendmentMethod(DescriptorEvent event)

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

arePrimaryKeyFields

public boolean arePrimaryKeyFields(java.util.Vector fields)

INTERNAL: Used to determine if a foreign key references the primary key.

buildDirectValuesFromFieldValue

public java.util.Vector buildDirectValuesFromFieldValue(java.lang.Object fieldValue)
                                                 throws DatabaseException

INTERNAL: Extract the direct values from the specified field value. Return them in a vector.

Throws:

DatabaseException

buildField

public oracle.toplink.internal.helper.DatabaseField buildField(java.lang.String fieldName)

INTERNAL: A DatabaseField is built from the given field name.

buildField

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

INTERNAL: The table of the field is ensured to be unique from the descriptor's tables. If the field has no table the default table is assigned. This is used only in initialization.

buildFieldValueFromDirectValues

public java.lang.Object buildFieldValueFromDirectValues(java.util.Vector directValues,
                                                        java.lang.String elementDataTypeName,
                                                        oracle.toplink.publicinterface.Session session)
                                                 throws DatabaseException

INTERNAL: Build the appropriate field value for the specified set of direct values.

Throws:

DatabaseException

buildFieldValueFromForeignKeys

public java.lang.Object buildFieldValueFromForeignKeys(java.util.Vector foreignKeys,
                                                       java.lang.String referenceDataTypeName,
                                                       oracle.toplink.publicinterface.Session session)
                                                throws DatabaseException

INTERNAL: Build and return the appropriate field value for the specified set of foreign keys (i.e. each row has the fields that make up a foreign key).

Throws:

DatabaseException

buildFieldValueFromNestedRow

public java.lang.Object buildFieldValueFromNestedRow(DatabaseRow nestedRow,
                                                     oracle.toplink.publicinterface.Session session)
                                              throws DatabaseException

INTERNAL: Build and return the field value from the specified nested database row.

Throws:

DatabaseException

buildFieldValueFromNestedRows

public java.lang.Object buildFieldValueFromNestedRows(java.util.Vector nestedRows,
                                                      java.lang.String structureName,
                                                      oracle.toplink.publicinterface.Session session)
                                               throws DatabaseException

INTERNAL: Build and return the appropriate field value for the specified set of nested rows.

Throws:

DatabaseException

buildNestedRowFromFieldValue

public DatabaseRow buildNestedRowFromFieldValue(java.lang.Object fieldValue)
                                         throws DatabaseException

INTERNAL: Build and return the nested database row from the specified field value.

Throws:

DatabaseException

buildNestedRowsFromFieldValue

public java.util.Vector buildNestedRowsFromFieldValue(java.lang.Object fieldValue,
                                                      oracle.toplink.publicinterface.Session session)
                                               throws DatabaseException

INTERNAL: Build and return the nested rows from the specified field value.

Throws:

DatabaseException

checkInheritanceTreeAggregateSettings

public void checkInheritanceTreeAggregateSettings(oracle.toplink.publicinterface.Session session,
AggregateMapping mapping)
                                           throws DescriptorException

INTERNAL: Verify that an aggregate descriptor's inheritance tree is full of aggregate descriptors.

Throws:

DescriptorException

clone

public java.lang.Object clone()

INTERNAL: Clones the descriptor

createCopyPolicy

public void createCopyPolicy(java.lang.String policyType)

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

createInstantiationPolicy

public void createInstantiationPolicy(java.lang.String policyType)

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

See Also:

alwaysRefreshCacheOnRemote()

dontDisableCacheHits

public void dontDisableCacheHits()

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

See Also:

disableCacheHits()

dontDisableCacheHitsOnRemote

public void dontDisableCacheHitsOnRemote()

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

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).

See Also:

onlyRefreshCacheIfNewerVersion()

getAdditionalTablePrimaryKeyFields

public java.util.Hashtable getAdditionalTablePrimaryKeyFields()

INTERNAL: This is used to map the primary key field names in a multiple table descriptor.

getAlias

public java.lang.String getAlias()

PUBLIC: Get the alias

getAllFields

public java.util.Vector getAllFields()

INTERNAL: Return all the fields. By default it is initialized to the fields for the current 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.

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.

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.

getCopyPolicy

public oracle.toplink.internal.descriptors.CopyPolicy getCopyPolicy()

INTERNAL: Returns the copy policy.

getDefaultTable

public oracle.toplink.internal.helper.DatabaseTable getDefaultTable()

INTERNAL: The first table in the tables is always treated as default.

getDescriptorType

public int getDescriptorType()

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

getDescriptorTypeValue

public java.lang.String getDescriptorTypeValue()

INTERNAL: This method is explicitly used by the XML reader.

getEventManager

public DescriptorEventManager getEventManager()

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

getFields

public java.util.Vector getFields()

INTERNAL: Return all the fields

getIdentityMapClass

public java.lang.Class getIdentityMapClass()

INTERNAL: Return the class of identity map to be used by this descriptor. The default is the "SoftCacheWeakIdentityMap".

getIdentityMapSize

public int getIdentityMapSize()

PUBLIC: Return the size of the identity map.

getInheritancePolicy

public InheritancePolicy getInheritancePolicy()

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.

getInheritancePolicyOrNull

public InheritancePolicy getInheritancePolicyOrNull()

INTERNAL: Return the inheritance policy.

getInstantiationPolicy

public oracle.toplink.internal.descriptors.InstantiationPolicy getInstantiationPolicy()

INTERNAL: Returns the instantiation policy.

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.

getInterfacePolicyOrNull

public InterfacePolicy getInterfacePolicyOrNull()

INTERNAL: Returns the InterfacePolicy.

getJavaClass

public java.lang.Class getJavaClass()

PUBLIC: Return the java class.

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.

getMappings

public java.util.Vector getMappings()

PUBLIC: Returns mappings

getMultipleTableForeignKeyAssociations

public java.util.Vector getMultipleTableForeignKeyAssociations()

INTERNAL: Returns the foreign key relationships used for multiple tables which were specified by the user. Used by the Project XML writer to outpot these associations

Returns:

java.util.Hashtable

See Also:

adjustMultipleTableInsertOrder()

getMultipleTableForeignKeys

public java.util.Hashtable getMultipleTableForeignKeys()

INTERNAL: Returns the foreign key relationships used for multiple tables which were specified by the user. The key of the Hashtable is the field in the source table of the foreign key relationship. The value is the field name of the target table.

Returns:

java.util.Hashtable

See Also:

adjustMultipleTableInsertOrder()

getMultipleTableInsertOrder

public java.util.Vector getMultipleTableInsertOrder()
                                             throws DescriptorException

INTERNAL: Returns the Vector of DatabaseTables in the order which INSERTS should take place. This order is determined by the foreign key fields which are specified by the user.

Returns:

java.util.Vector

Throws:

DescriptorException

getMultipleTablePrimaryKeyAssociations

public java.util.Vector getMultipleTablePrimaryKeyAssociations()

INTERNAL: Returns the foreign key relationships used for multiple tables which were specified by the user. Used by the Project XML writer to outpot these associations

Returns:

java.util.Hashtable

See Also:

adjustMultipleTableInsertOrder()

getObjectBuilder

public oracle.toplink.internal.descriptors.ObjectBuilder getObjectBuilder()

INTERNAL: Return the object builder

getOptimisticLockingPolicy

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

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

getPrimaryKeyFieldNames

public java.util.Vector getPrimaryKeyFieldNames()

PUBLIC: Return the names of all the primary keys.

getPrimaryKeyFields

public java.util.Vector getPrimaryKeyFields()

INTERNAL: Return all the primary key fields

getProperties

public java.util.Hashtable getProperties()

PUBLIC: Returns the user defined properties.

getProperty

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

PUBLIC: Returns the descriptor property associated the given String.

getQueryKeyNamed

public QueryKey getQueryKeyNamed(java.lang.String queryKeyName)

INTERNAL: Return the query key with the specified name

getQueryKeys

public java.util.Hashtable getQueryKeys()

PUBLIC: Return the query keys.

getQueryManager

public DescriptorQueryManager getQueryManager()

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

getRemoteIdentityMapClass

public java.lang.Class getRemoteIdentityMapClass()

INTERNAL: Return the class of identity map to be used by this descriptor. The default is the "SoftCacheWeakIdentityMap".

getRemoteIdentityMapSize

public int getRemoteIdentityMapSize()

PUBLIC: Return the size of the remote identity map.

getSequenceNumberField

public oracle.toplink.internal.helper.DatabaseField getSequenceNumberField()

INTERNAL: Get sequence number field

getSequenceNumberFieldName

public java.lang.String getSequenceNumberFieldName()

PUBLIC: Get sequence number field name

getSequenceNumberName

public java.lang.String getSequenceNumberName()

PUBLIC: Get sequence number name

getSessionName

public java.lang.String getSessionName()

INTERNAL: Return the name of the session local to this descriptor. This is used by the session broker.

getTable

public oracle.toplink.internal.helper.DatabaseTable getTable(java.lang.String tableName)
                                                      throws DescriptorException

INTERNAL: Checks if table name exists with the current descriptor or not.

Throws:

DescriptorException

getTableName

public java.lang.String getTableName()

PUBLIC: Return the name of the descriptor's first table. This method must only be called on single table descriptors.

getTableNames

public java.util.Vector getTableNames()

PUBLIC: Return the table names.

getTables

public java.util.Vector getTables()

INTERNAL: Return all the tables.

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.

hasDependencyOnParts

public boolean hasDependencyOnParts()

INTERNAL: Checks if the class has any private owned parts or other dependencies, (i.e. M:M join table).

hasInheritance

public boolean hasInheritance()

INTERNAL: Return if this descriptor is involved in inheritence, (is child or parent).

hasInterfacePolicy

public boolean hasInterfacePolicy()

INTERNAL: Return if this descriptor is involved in interface, (is child or parent).

hasMultipleTables

public boolean hasMultipleTables()

INTERNAL: Check if descriptor has multiple tables

hasPrivatelyOwnedParts

public boolean hasPrivatelyOwnedParts()

INTERNAL: Checks if the class has any private owned parts are not

hasQueryKeyOrMapping

public boolean hasQueryKeyOrMapping(java.lang.String attributeName)

INTERNAL: Checks to see if it has a query key or mapping with the specified name or not.

hasWrapperPolicy

public boolean hasWrapperPolicy()

INTERNAL: Return if a wrapper policy is used.

initialize

public void initialize(oracle.toplink.publicinterface.Session session)
                throws DescriptorException

INTERNAL: Initialize the mappings as a seperate step. This is done as a seperate step to ensure that inheritence has been first resolved.

Throws:

DescriptorException

initializeAggregateInheritancePolicy

public void initializeAggregateInheritancePolicy(oracle.toplink.publicinterface.Session session)

INTERNAL: This is needed by regular aggregate descriptors (because they are screwed up); but not by SDK aggregate descriptors.

initializeMultipleTablePrimaryKeyFields

public void initializeMultipleTablePrimaryKeyFields()

INTERNAL: Rebuild the multiple table primary key map.

interfaceInitialization

public void interfaceInitialization(oracle.toplink.publicinterface.Session session)
                             throws DescriptorException

INTERNAL: Allow the descriptor to initialize any dependancies on this session.

Throws:

DescriptorException

isAggregateCollectionDescriptor

public boolean isAggregateCollectionDescriptor()

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

isAggregateDescriptor

public boolean isAggregateDescriptor()

PUBLIC: Return true if this descriptor is an aggregate descriptor

isChildDescriptor

public boolean isChildDescriptor()

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

isDescriptorForInterface

public boolean isDescriptorForInterface()

PUBLIC: Return if the java class is interface

isFullyInitialized

public boolean isFullyInitialized()

INTERNAL: Check if the descriptor is finished initialization.

isInterfaceChildDescriptor

public boolean isInterfaceChildDescriptor()

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

isMultipleTableDescriptor

public boolean isMultipleTableDescriptor()

INTERNAL: Return if this descriptor has more than one table.

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.

See Also:

dontOnlyRefreshCacheIfNewerVersion()

postInitialize

public void postInitialize(oracle.toplink.publicinterface.Session session)
                    throws DescriptorException

INTERNAL: Post initializations after mappings are initialized.

Throws:

DescriptorException

preInitialize

public void preInitialize(oracle.toplink.publicinterface.Session session)
                   throws DescriptorException

INTERNAL: Allow the descriptor to initialize any dependancies on this session.

Throws:

DescriptorException

preInterfaceInitialization

public void preInterfaceInitialization(oracle.toplink.publicinterface.Session session)
                                throws DescriptorException

INTERNAL: Allow the descriptor to initialize any dependancies on this session.

Throws:

DescriptorException

rehashFieldDependancies

public void rehashFieldDependancies(oracle.toplink.publicinterface.Session session)

INTERNAL: Rehash any hashtables based on fields. This is used to clone descriptors for aggregates, which hammer field names, it is probably better not to hammer the field name and this should be refactored.

remoteInitialization

public void remoteInitialization(DistributedSession session)

INTERNAL: Used to initialize a remote descriptor.

removeProperty

public void removeProperty(java.lang.String property)

PUBLIC: Remove the user defined property.

requiresInitialization

public boolean requiresInitialization()

INTERNAL: Aggregate and Interface descriptors do not require initialization as they are cloned and initialized by each mapping.

setAlias

public void setAlias(java.lang.String alias)

PUBLIC: Set the alias

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.

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.

setConstraintDependencies

public void setConstraintDependencies(java.util.Vector constraintDependencies)

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.

setCopyPolicy

public void setCopyPolicy(oracle.toplink.internal.descriptors.CopyPolicy policy)

INTERNAL: Set the copy policy. This would be 'protected' but the EJB stuff in another package needs it to be public

setDefaultTable

public void setDefaultTable(oracle.toplink.internal.helper.DatabaseTable defaultTable)

INTERNAL: The descriptors default table can be configured if the first table is not desired.

setDefaultTableName

public void setDefaultTableName(java.lang.String defaultTableName)

PUBLIC: The descriptors default table can be configured if the first table is not desired.

setDescriptorType

public void setDescriptorType(int descriptorType)

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

setDescriptorTypeValue

public void setDescriptorTypeValue(java.lang.String value)

INTERNAL: This method is explicitly used by the XML reader.

setEventManager

public void setEventManager(DescriptorEventManager eventManager)

INTERNAL: Set the event manager for the descriptor. The event manager is responsible for managing the pre/post selectors.

setExistenceChecking

public void setExistenceChecking(java.lang.String token)
                          throws DescriptorException

INTERNAL: OBSOLETE - old reader. This method is explicitly used by the Builder only.

Throws:

DescriptorException

setFields

public void setFields(java.util.Vector fields)

INTERNAL: Set the fields used by this 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".

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.

setInheritancePolicy

public void setInheritancePolicy(InheritancePolicy inheritancePolicy)

INTERNAL: Sets the inheritance policy.

setInstantiationPolicy

public void setInstantiationPolicy(oracle.toplink.internal.descriptors.InstantiationPolicy instantiationPolicy)

INTERNAL: Sets the instantiation policy.

setInterfacePolicy

public void setInterfacePolicy(InterfacePolicy interfacePolicy)

INTERNAL: Sets the interface policy.

setIsAggregateDescriptor

public void setIsAggregateDescriptor(boolean isAggregateDescriptor)

Deprecated.

OBSOLETE:

See Also:

descriptorIsAggregate()

setIsDescriptorForInterface

public void setIsDescriptorForInterface(boolean isDescriptorForInterface)

Deprecated.

OBSOLETE:

See Also:

#descriptorIsInterface()

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.

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.

setMappings

public void setMappings(java.util.Vector mappings)

INTERNAL: Set the mappings.

setMultipleTableForeignKeyFieldNames

public void setMultipleTableForeignKeyFieldNames(java.util.Vector associations)
                                          throws DescriptorException

INTERNAL: This method is used by the TopLink XML Deployment Descriptor to read and write these mappings

Throws:

DescriptorException

setMultipleTableInsertOrder

public void setMultipleTableInsertOrder(java.util.Vector newValue)

ADVANCED: Sets the Vector of DatabaseTables in the order which INSERTS should take place. This is normally computed correctly by TopLink, however in advanced cases in it may be overridden.

setMultipleTablePrimaryKeyFieldNames

public void setMultipleTablePrimaryKeyFieldNames(java.util.Vector associations)
                                          throws DescriptorException

INTERNAL: This method is used by the TopLink XML Deployment Descriptor to read and write these mappings

Throws:

DescriptorException

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.

See Also:

VersionLockingPolicy, TimestampLockingPolicy, FieldLockingPolicy

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.

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.

See Also:

addPrimaryKeyFieldName(String)

setPrimaryKeyFields

public void setPrimaryKeyFields(java.util.Vector thePrimaryKeyFields)

INTERNAL: Set the primary key fields

setProperties

public void setProperties(java.util.Hashtable properties)

INTERNAL: Set the user defined properties.

setProperty

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

PUBLIC: Set the user defined property.

setQueryKeys

public void setQueryKeys(java.util.Hashtable queryKeys)

INTERNAL: Set the query keys.

setQueryManager

public void setQueryManager(DescriptorQueryManager queryManager)

INTERNAL: Set the query manager.

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".

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.

setSequenceNumberField

public void setSequenceNumberField(oracle.toplink.internal.helper.DatabaseField sequenceNumberField)

INTERNAL: Set the sequence number field.

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.

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.

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.

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.

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.

See Also:

alwaysRefreshCacheOnRemote(), dontAlwaysRefreshCacheOnRemote()

setShouldBeReadOnly

public void setShouldBeReadOnly(boolean shouldBeReadOnly)

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

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 porformance as there is no need for the registration, clone and merge for the read-only classes.

setShouldDisableCacheHits

public void setShouldDisableCacheHits(boolean shouldDisableCacheHits)

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

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.

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).

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

setTableName

public void setTableName(java.lang.String tableName)
                  throws DescriptorException

PUBLIC: Specify the table name for the class of objects the receiver describes. If the table has a qualifier it should be specified using the dot notation, (i.e. "userid.employee"). This method is used for single table.

Throws:

DescriptorException

setTableNames

public void setTableNames(java.util.Vector tableNames)

PUBLIC: Specify the all table names for the class of objects the receiver describes. If the table has a qualifier it should be specified using the dot notation, (i.e. "userid.employee"). This method is used for multiple tables

setTableQualifier

public void setTableQualifier(java.lang.String tableQualifier)

PUBLIC: Set the table Qualifier for this descriptor. This table creator will be used for all tables in this descriptor

setTables

public void setTables(java.util.Vector theTables)

INTERNAL: Sets the tables

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.

setWriteLockFieldName

public void setWriteLockFieldName(java.lang.String fieldName)

Deprecated.

PUBLIC: OBSOLETE Set the optimistic write lock field name. If used this field will be increamented whenever the object is updated. Before writing, this field is checked to see if it has changed since the object was read, if it has an OptimisticLockException will be triggered.

See Also:

OptimisticLockException

shouldAlwaysConformResultsInUnitOfWork

public boolean shouldAlwaysConformResultsInUnitOfWork()

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

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.

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.

See Also:

setShouldAlwaysRefreshCacheOnRemote(boolean)

shouldBeReadOnly

public boolean shouldBeReadOnly()

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

shouldDisableCacheHits

public boolean shouldDisableCacheHits()

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

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.

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.

See Also:

setShouldOnlyRefreshCacheIfNewerVersion(boolean)

shouldOrderMappings

public boolean shouldOrderMappings()

INTERNAL: Return if mappings should be ordered or not. By default this is set to true to prevent attributes from being merged in the wrong order

shouldUseCacheIdentityMap

public boolean shouldUseCacheIdentityMap()

PUBLIC: Return true if this descriptor is using CacheIdentityMap

shouldUseFullIdentityMap

public boolean shouldUseFullIdentityMap()

PUBLIC: Return true if this descriptor is using FullIdentityMap

shouldUseHardCacheWeakIdentityMap

public boolean shouldUseHardCacheWeakIdentityMap()

PUBLIC: Return true if this descriptor is using HardCacheWeakIdentityMap.

shouldUseNoIdentityMap

public boolean shouldUseNoIdentityMap()

PUBLIC: Return true if this descriptor is using NoIdentityMap

shouldUseRemoteCacheIdentityMap

public boolean shouldUseRemoteCacheIdentityMap()

PUBLIC: Return true if this descriptor is using CacheIdentityMap

shouldUseRemoteFullIdentityMap

public boolean shouldUseRemoteFullIdentityMap()

PUBLIC: Return true if this descriptor is using FullIdentityMap

shouldUseRemoteHardCacheWeakIdentityMap

public boolean shouldUseRemoteHardCacheWeakIdentityMap()

PUBLIC: Return true if this descriptor is using HardCacheWeakIdentityMap

shouldUseRemoteNoIdentityMap

public boolean shouldUseRemoteNoIdentityMap()

PUBLIC: Return true if this descriptor is using NoIdentityMap

shouldUseRemoteSoftCacheWeakIdentityMap

public boolean shouldUseRemoteSoftCacheWeakIdentityMap()

PUBLIC: Return true if this descriptor is using SoftCacheWeakIdentityMap

shouldUseRemoteWeakIdentityMap

public boolean shouldUseRemoteWeakIdentityMap()

PUBLIC: Return true if this descriptor is using WeakIdentityMap

shouldUseSoftCacheWeakIdentityMap

public boolean shouldUseSoftCacheWeakIdentityMap()

PUBLIC: Return true if this descriptor is using SoftCacheWeakIdentityMap.

shouldUseWeakIdentityMap

public boolean shouldUseWeakIdentityMap()

PUBLIC: Return true if this descriptor is using WeakIdentityMap

toString

public java.lang.String toString()

PUBLIC: Returns a brief string representation of the receiver.

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.

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 in JDK1.1 is "FullIdentityMap", in JDK1.2 it is the "SoftCacheWeakIdentityMap".

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.

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.

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.

See Also:

useCloneCopyPolicy()

useConstructorCopyPolicy

public void useConstructorCopyPolicy()

Deprecated. Replaced by useInstantiationCopyPolicy(), which is more accurately named.

OBSOLETE: 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.

See Also:

useInstantiationCopyPolicy()

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.

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.

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.

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.

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.

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 in JDK1.1 is "FullIdentityMap", in JDK1.2 it is the "SoftCacheWeakIdentityMap".

useHardCacheWeakIdentityMap

public void useHardCacheWeakIdentityMap()

PUBLIC: Set the class of identity map to be the hard cache weak identity map. This map uses weak references in JDK 1.2 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 in JDK1.1 is "FullIdentityMap", in JDK1.2 it is the "SoftCacheWeakIdentityMap".

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.

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 in JDK1.1 is "FullIdentityMap", in JDK1.2 it is the "SoftCacheWeakIdentityMap".

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 in JDK1.1 is "FullIdentityMap", in JDK1.2 it is the "SoftCacheWeakIdentityMap".

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 in JDK1.1 is "FullIdentityMap", in JDK1.2 it is the "SoftCacheWeakIdentityMap".

useRemoteHardCacheWeakIdentityMap

public void useRemoteHardCacheWeakIdentityMap()

PUBLIC: Set the class of identity map to be the hard cache weak identity map. This map uses weak references in JDK 1.2 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 in JDK1.1 is "FullIdentityMap", in JDK1.2 it is the "SoftCacheWeakIdentityMap".

useRemoteNoIdentityMap

public void useRemoteNoIdentityMap()

PUBLIC: Set the class of identity map to be the no identity map. This map does no caching. The default in JDK1.1 is "FullIdentityMap", in JDK1.2 it is the "SoftCacheWeakIdentityMap".

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 in JDK1.1 is "FullIdentityMap", in JDK1.2 it is the "SoftCacheWeakIdentityMap".

useRemoteWeakIdentityMap

public void useRemoteWeakIdentityMap()

PUBLIC: Set the class of identity map to be the weak identity map. The default in JDK1.1 is "FullIdentityMap", in JDK1.2 it is the "SoftCacheWeakIdentityMap".

usesCacheIdentityMap

public boolean usesCacheIdentityMap()

Deprecated. replaced by shouldUseCacheIdentityMap() This was rename to avoid confusing with useCacheIdentityMap.

OBSOLETE:

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.

See Also:

SelectedFieldsLockingPolicy

usesFieldLocking

public boolean usesFieldLocking()

INTERNAL: Return true if the receiver uses either all or changed fields for optimistic locking.

usesFullIdentityMap

public boolean usesFullIdentityMap()

Deprecated. replaced by shouldUseFullIdentityMap() This was rename to avoid confusing with useFullIdentityMap.

OBSOLETE:

usesHardCacheWeakIdentityMap

public boolean usesHardCacheWeakIdentityMap()

Deprecated. replaced by shouldUseHardCacheWeakIdentityMap() This was rename to avoid confusing with useHardCacheWeakIdentityMap.

OBSOLETE:

usesNoIdentityMap

public boolean usesNoIdentityMap()

Deprecated. replaced by shouldUseNoIdentityMap() This was rename to avoid confusing with useNoIdentityMap.

OBSOLETE:

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 in JDK1.1 is "FullIdentityMap", in JDK1.2 it is the "SoftCacheWeakIdentityMap".

usesOptimisticLocking

public boolean usesOptimisticLocking()

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

usesSequenceNumbers

public boolean usesSequenceNumbers()

PUBLIC: Return true if the receiver uses sequence numbers.

usesSoftCacheWeakIdentityMap

public boolean usesSoftCacheWeakIdentityMap()

Deprecated. replaced by shouldUseSoftCacheWeakIdentityMap() This was rename to avoid confusing with useSoftCacheWeakIdentityMap.

OBSOLETE:

usesWeakIdentityMap

public boolean usesWeakIdentityMap()

Deprecated. replaced by shouldUseWeakIdentityMap() This was rename to avoid confusing with useWeakIdentityMap.

OBSOLETE:

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)

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.

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)

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.

See Also:

TimestampLockingPolicy

useWeakIdentityMap

public void useWeakIdentityMap()

PUBLIC: Set the class of identity map to be the weak identity map. The default in JDK1.1 is "FullIdentityMap", in JDK1.2 it is the "SoftCacheWeakIdentityMap".