oracle.toplink.essentials.mappings

Class DirectMapMapping

java.lang.Object

oracle.toplink.essentials.mappings.DatabaseMapping

oracle.toplink.essentials.mappings.ForeignReferenceMapping

oracle.toplink.essentials.mappings.CollectionMapping

oracle.toplink.essentials.mappings.DirectCollectionMapping

oracle.toplink.essentials.mappings.DirectMapMapping

All Implemented Interfaces:

Serializable, Cloneable, ContainerMapping, RelationalMapping

public class DirectMapMapping
extends DirectCollectionMapping

Mapping for a collection of key-value pairs. The key and value must be simple types (String, Number, Date, etc.) and stored in a single table along with a foreign key to the source object. A converter can be used on the key and value if the desired object types do not match the data types.

Since:

TopLink 3.5

See Also:

Converter, ObjectTypeConverter, TypeConversionConverter, SerializedObjectConverter, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected DatabaseField	directKeyField The direct key field name is converted and stored
protected Converter	keyConverter Allows user defined conversion between the object attribute value and the database value.

Fields inherited from class oracle.toplink.essentials.mappings.DirectCollectionMapping

changeSetDeleteQuery, Delete, DeleteAll, directField, hasCustomDeleteQuery, hasCustomInsertQuery, Insert, insertQuery, referenceKeyFields, referenceTable, sourceKeyFields, valueConverter

Fields inherited from class oracle.toplink.essentials.mappings.CollectionMapping

containerPolicy, deleteAllQuery, hasCustomDeleteAllQuery, hasOrderBy

Fields inherited from class oracle.toplink.essentials.mappings.ForeignReferenceMapping

cascadeMerge, cascadePersist, cascadeRefresh, cascadeRemove, hasCustomSelectionQuery, indirectionPolicy, isPrivateOwned, referenceClass, referenceClassName, referenceDescriptor, relationshipPartner, relationshipPartnerAttributeName, selectionQuery, tempInitSession

Fields inherited from class oracle.toplink.essentials.mappings.DatabaseMapping

attributeAccessor, descriptor, fields, isOptional, isReadOnly, isRemotelyInitialized, NO_FIELDS, NO_WEIGHT, primaryKeyMapping, properties, weight, WEIGHT_1

Constructor Summary

Constructors

Constructor and Description
DirectMapMapping() DirectMapCollectionMapping constructor

Method Summary

Modifier and Type	Method and Description
void	addToCollectionChangeRecord(Object newKey, Object newValue, ObjectChangeSet objectChangeSet, UnitOfWorkImpl uow) INTERNAL: Add a new value and its change set to the collection change record.
Object	buildCloneForPartObject(Object attributeValue, Object original, Object clone, UnitOfWorkImpl unitOfWork, boolean isExisting) INTERNAL: Require for cloning, the part must be cloned.
protected Object	buildKeyClone(Object element, UnitOfWorkImpl unitOfWork, boolean isExisting) INTERNAL: Clone the key, if necessary.
ChangeRecord	compareForChange(Object clone, Object backUp, ObjectChangeSet owner, AbstractSession session) INTERNAL: This method compares the changes between two direct collections.
boolean	compareObjects(Object firstObject, Object secondObject, AbstractSession session) INTERNAL: Compare the attributes belonging to this mapping for the objects.
void	convertClassNamesToClasses(ClassLoader classLoader) INTERNAL: Convert all the class-name-based settings in this mapping to actual class-based settings This method is implemented by subclasses as necessary.
Object	extractResultFromBatchQuery(DatabaseQuery query, AbstractRecord databaseRow, AbstractSession session, AbstractRecord argumentRow) INTERNAL: Ovewrite super method
DatabaseField	getDirectKeyField() INTERNAL:
Class	getKeyClass() PUBLIC: This is a helper method to get the object class from the key converter if it is a TypeConversionConverter.
Converter	getKeyConverter() PUBLIC: Return the converter on the mapping.
Class	getValueClass() PUBLIC: This is a helper method to get the object class from the value converter if it is a TypeConversionConverter.
void	initialize(AbstractSession session) INTERNAL: Initialize and validate the mapping properties.
protected void	initializeContainerPolicy(AbstractSession session) set the key and value fields that are used to build the container from database rows
protected void	initializeDeleteQuery(AbstractSession session)
protected void	initializeDirectKeyField(AbstractSession session) The field name on the reference table is initialized and cached.
protected void	initializeInsertQuery(AbstractSession session) Initialize insert query.
protected void	initializeSelectionStatement(AbstractSession session)
boolean	isDirectMapMapping() INTERNAL: Related mapping should implement this method to return true.
void	mergeChangesIntoObject(Object target, ChangeRecord changeRecord, Object source, MergeManager mergeManager) INTERNAL: Merge changes from the source to the target object.
void	mergeIntoObject(Object target, boolean isTargetUnInitialized, Object source, MergeManager mergeManager) INTERNAL: Merge changes from the source to the target object.
void	postInsert(WriteObjectQuery query) INTERNAL: Insert the private owned object.
protected void	postUpdateWithChangeSet(WriteObjectQuery writeQuery) INTERNAL: Update private owned part.
void	removeFromCollectionChangeRecord(Object newKey, Object newValue, ObjectChangeSet objectChangeSet, UnitOfWorkImpl uow) INTERNAL: Remove a value and its change set from the collection change record.
void	setDirectKeyField(DatabaseField keyField) INTERNAL:
void	setDirectKeyFieldName(String fieldName) PUBLIC: Set the direct key field name in the reference table.
void	setKeyClass(Class keyClass) PUBLIC: This is a helper method to set the key converter to a TypeConversionConverter.
void	setKeyConverter(Converter keyConverter) PUBLIC: Set the converter on the mapping.
void	setValueClass(Class valueClass) PUBLIC: This is a helper method to set the value converter to a TypeConversionConverter.
void	simpleAddToCollectionChangeRecord(Object referenceKey, Object objectToAdd, ObjectChangeSet changeSet, AbstractSession session) ADVANCED: This method is used to have an object add to a collection once the changeSet is applied The referenceKey parameter should only be used for direct Maps.
void	simpleRemoveFromCollectionChangeRecord(Object referenceKey, Object objectToRemove, ObjectChangeSet changeSet, AbstractSession session) ADVANCED: This method is used to have an object removed from a collection once the changeSet is applied The referenceKey parameter should only be used for direct Maps.
void	updateChangeRecord(Object clone, Object newValue, Object oldValue, ObjectChangeSet objectChangeSet, UnitOfWorkImpl uow) INTERNAL: Either create a new change record or update the change record with the new value.
void	useMapClass(Class concreteClass) PUBLIC: Configure the mapping to use an instance of the specified container class to hold the target objects.
void	useTransparentMap() PUBLIC: Configure the mapping to use an instance of the specified container class to hold the target objects.

Methods inherited from class oracle.toplink.essentials.mappings.DirectCollectionMapping

addReferenceKeyField, addReferenceKeyFieldName, buildCopy, buildElementClone, calculateDeferredChanges, cascadePerformRemoveIfRequired, cascadeRegisterNewIfRequired, clone, compareCollectionsForChange, extractKeyFromReferenceRow, extractPrimaryKeyFromRow, getDeleteQuery, getDirectField, getDirectFieldName, getInsertQuery, getReferenceClass, getReferenceClassName, getReferenceDescriptor, getReferenceKeyFieldNames, getReferenceKeyFields, getReferenceTable, getReferenceTableName, getReferenceTableQualifiedName, getRelationshipPartner, getSourceKeyFieldNames, getSourceKeyFields, getValueConverter, hasCustomDeleteQuery, hasCustomInsertQuery, initializeDeleteAllQuery, initializeDirectField, initializeReferenceDescriptor, initializeReferenceKeys, initializeReferenceTable, initializeSelectionCriteria, initializeSelectionQuery, initializeSourceKeys, initializeSourceKeysWithDefaults, isCascadedLockingSupported, isChangeTrackingSupported, isDirectCollectionMapping, isKeyForSourceSpecified, isPrivateOwned, isRelationalMapping, iterateOnElement, iterateOnRealAttributeValue, performDataModificationEvent, postUpdate, preDelete, prepareTranslationRow, setContainerPolicy, setCustomDeleteQuery, setCustomInsertQuery, setDeleteQuery, setDeleteSQLString, setDirectField, setDirectFieldClassification, setDirectFieldName, setHasCustomDeleteQuery, setHasCustomInsertQuery, setInsertQuery, setInsertSQLString, setReferenceClass, setReferenceClassName, setReferenceKeyFieldName, setReferenceKeyFieldNames, setReferenceKeyFields, setReferenceTable, setReferenceTableName, setSessionName, setSourceKeyFieldNames, setSourceKeyFields, setValueConverter, useCollectionClass, useMapClass, valueFromRow, verifyDelete

Methods inherited from class oracle.toplink.essentials.mappings.CollectionMapping

addAggregateOrderBy, addAscendingOrdering, addDescendingOrdering, addOrderBy, buildBackupCloneForPartObject, buildChangeRecord, cascadeMerge, compareObjectsAndWrite, compareObjectsWithoutPrivateOwned, compareObjectsWithPrivateOwned, getContainerPolicy, getDeleteAllQuery, getRealAttributeValueFromObject, getRealCollectionAttributeValueFromObject, hasCustomDeleteAllQuery, hasOrderBy, isCollectionMapping, objectAddedDuringUpdate, objectRemovedDuringUpdate, objectUnchangedDuringUpdate, objectUnchangedDuringUpdate, readPrivateOwnedForObject, setCustomDeleteAllQuery, setDeleteAllCall, setDeleteAllQuery, setDeleteAllSQLString, setHasCustomDeleteAllQuery, shouldUseValueFromRowWithJoin, useSortedSetClass, useTransparentCollection, useTransparentList, useTransparentMap, useTransparentSet, validateBeforeInitialization, valueFromRowInternalWithJoin

Methods inherited from class oracle.toplink.essentials.mappings.ForeignReferenceMapping

buildBackupClone, buildClone, buildCloneFromRow, createUnitOfWorkValueHolder, dontDoMerge, dontUseIndirection, getAttributeValueFromObject, getAttributeValueWithClonedValueHolders, getIndirectionPolicy, getJoinCriteria, getRelationshipPartnerAttributeName, getSelectionCriteria, getSelectionQuery, getTempSession, hasCustomSelectionQuery, isAttributeValueInstantiated, isCascadeMerge, isCascadePersist, isCascadeRefresh, isCascadeRemove, isForeignReferenceMapping, iterate, prepareHistoricalQuery, prepareNestedJoins, privateOwnedRelationship, setCascadeAll, setCascadeMerge, setCascadePersist, setCascadeRefresh, setCascadeRemove, setCustomSelectionQuery, setHasCustomSelectionQuery, setIndirectionPolicy, setIsPrivateOwned, setRealAttributeValueInObject, setReferenceDescriptor, setRelationshipPartner, setRelationshipPartnerAttributeName, setSelectionCall, setSelectionCriteria, setSelectionQuery, setSelectionSQLString, setTempSession, setUsesIndirection, shouldInitializeSelectionCriteria, shouldMergeCascadeParts, shouldMergeCascadeReference, shouldObjectModifyCascadeToParts, shouldObjectModifyCascadeToPartsForPreDelete, trimRowForJoin, trimRowForJoin, useBasicIndirection, usesIndirection, useWeavedIndirection, valueFromRowInternal

Methods inherited from class oracle.toplink.essentials.mappings.DatabaseMapping

buildObjectJoinExpression, buildObjectJoinExpression, buildShallowOriginalFromRow, cloneFields, collectFields, extractNestedExpressions, getAttributeAccessor, getAttributeClassification, getAttributeName, getDescriptor, getField, getFieldClassification, getFields, getGetMethodName, getProperties, getProperty, getReferenceClassDescriptor, getSetMethodName, getWeight, hasConstraintDependency, hasDependency, hasInverseConstraintDependency, isAbstractCompositeCollectionMapping, isAbstractCompositeDirectCollectionMapping, isAbstractCompositeObjectMapping, isAbstractDirectMapping, isAggregateCollectionMapping, isAggregateMapping, isAggregateObjectMapping, isCloningRequired, isDatabaseMapping, isDirectToFieldMapping, isDirectToXMLTypeMapping, isEISMapping, isJoiningSupported, isManyToManyMapping, isNestedTableMapping, isObjectReferenceMapping, isObjectTypeMapping, isOneToManyMapping, isOneToOneMapping, isOptional, isPrimaryKeyMapping, isReadOnly, isReferenceMapping, isRemotelyInitialized, isSerializedObjectMapping, isStructureMapping, isTransformationMapping, isTypeConversionMapping, isUsingMethodAccess, isVariableOneToOneMapping, isWriteOnly, isXMLMapping, postDelete, postInitialize, preInitialize, preInsert, prepareCascadeLockingPolicy, preUpdate, readFromRowIntoObject, readFromRowIntoObject, readOnly, readWrite, rehashFieldDependancies, setAttributeAccessor, setAttributeName, setAttributeValueInObject, setDescriptor, setFields, setGetMethodName, setIsOptional, setIsPrimaryKeyMapping, setIsReadOnly, setProperties, setProperty, setSetMethodName, setWeight, toString, validateAfterInitialization, valueFromObject, valueFromRow, writeFromAttributeIntoRow, writeFromObjectIntoRow, writeFromObjectIntoRowForShallowDelete, writeFromObjectIntoRowForShallowInsert, writeFromObjectIntoRowForShallowInsertWithChangeRecord, writeFromObjectIntoRowForUpdate, writeFromObjectIntoRowForWhereClause, writeFromObjectIntoRowWithChangeRecord, writeInsertFieldsIntoRow, writeUpdateFieldsIntoRow

Methods inherited from class java.lang.Object

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

Field Detail

directKeyField

protected DatabaseField directKeyField

The direct key field name is converted and stored

keyConverter

protected Converter keyConverter

Allows user defined conversion between the object attribute value and the database value.

Constructor Detail

DirectMapMapping

public DirectMapMapping()

DirectMapCollectionMapping constructor

Method Detail

getKeyConverter

public Converter getKeyConverter()

PUBLIC: Return the converter on the mapping. A converter can be used to convert between the key's object value and database value.

setKeyConverter

public void setKeyConverter(Converter keyConverter)

PUBLIC: Set the converter on the mapping. A converter can be used to convert between the key's object value and database value.

addToCollectionChangeRecord

public void addToCollectionChangeRecord(Object newKey,
                                        Object newValue,
                                        ObjectChangeSet objectChangeSet,
                                        UnitOfWorkImpl uow)
                                 throws DescriptorException

INTERNAL: Add a new value and its change set to the collection change record. This is used by attribute change tracking. If a value has changed then issue a remove first with the key then an add.

Overrides:

addToCollectionChangeRecord in class DirectCollectionMapping

Throws:

DescriptorException

buildCloneForPartObject

public Object buildCloneForPartObject(Object attributeValue,
                                      Object original,
                                      Object clone,
                                      UnitOfWorkImpl unitOfWork,
                                      boolean isExisting)

INTERNAL: Require for cloning, the part must be cloned. Ignore the objects, use the attribute value.

Overrides:

buildCloneForPartObject in class CollectionMapping

buildKeyClone

protected Object buildKeyClone(Object element,
                               UnitOfWorkImpl unitOfWork,
                               boolean isExisting)

INTERNAL: Clone the key, if necessary. DirectCollections hold on to objects that do not have Descriptors (e.g. int, String). These objects do not need to be cloned, unless they use a converter - they are immutable.

compareForChange

public ChangeRecord compareForChange(Object clone,
                                     Object backUp,
                                     ObjectChangeSet owner,
                                     AbstractSession session)

INTERNAL: This method compares the changes between two direct collections. Comparisons are made on equality not identity.

Overrides:

compareForChange in class DirectCollectionMapping

Returns:

prototype.changeset.ChangeRecord

compareObjects

public boolean compareObjects(Object firstObject,
                              Object secondObject,
                              AbstractSession session)

INTERNAL: Compare the attributes belonging to this mapping for the objects.

Overrides:

compareObjects in class DirectCollectionMapping

convertClassNamesToClasses

public void convertClassNamesToClasses(ClassLoader classLoader)

INTERNAL: Convert all the class-name-based settings in this mapping to actual class-based settings This method is implemented by subclasses as necessary.

Overrides:

convertClassNamesToClasses in class DirectCollectionMapping

Parameters:

classLoader -

getDirectKeyField

public DatabaseField getDirectKeyField()

INTERNAL:

initialize

public void initialize(AbstractSession session)
                throws DescriptorException

INTERNAL: Initialize and validate the mapping properties.

Overrides:

initialize in class DirectCollectionMapping

Throws:

DescriptorException

initializeContainerPolicy

protected void initializeContainerPolicy(AbstractSession session)

set the key and value fields that are used to build the container from database rows

initializeDeleteQuery

protected void initializeDeleteQuery(AbstractSession session)

Overrides:

initializeDeleteQuery in class DirectCollectionMapping

initializeDirectKeyField

protected void initializeDirectKeyField(AbstractSession session)
                                 throws DescriptorException

The field name on the reference table is initialized and cached.

Throws:

DescriptorException

initializeInsertQuery

protected void initializeInsertQuery(AbstractSession session)

Initialize insert query. This query is used to insert the collection of objects into the reference table.

Overrides:

initializeInsertQuery in class DirectCollectionMapping

initializeSelectionStatement

protected void initializeSelectionStatement(AbstractSession session)

Overrides:

initializeSelectionStatement in class DirectCollectionMapping

isDirectMapMapping

public boolean isDirectMapMapping()

INTERNAL: Related mapping should implement this method to return true.

Overrides:

isDirectMapMapping in class DatabaseMapping

mergeChangesIntoObject

public void mergeChangesIntoObject(Object target,
                                   ChangeRecord changeRecord,
                                   Object source,
                                   MergeManager mergeManager)

INTERNAL: Merge changes from the source to the target object. Because this is a collection mapping, values are added to or removed from the collection based on the changeset

Overrides:

mergeChangesIntoObject in class DirectCollectionMapping

mergeIntoObject

public void mergeIntoObject(Object target,
                            boolean isTargetUnInitialized,
                            Object source,
                            MergeManager mergeManager)

INTERNAL: Merge changes from the source to the target object.

Overrides:

mergeIntoObject in class DirectCollectionMapping

postInsert

public void postInsert(WriteObjectQuery query)
                throws DatabaseException

INTERNAL: Insert the private owned object.

Overrides:

postInsert in class DirectCollectionMapping

Throws:

DatabaseException

postUpdateWithChangeSet

protected void postUpdateWithChangeSet(WriteObjectQuery writeQuery)
                                throws DatabaseException

INTERNAL: Update private owned part.

Overrides:

postUpdateWithChangeSet in class DirectCollectionMapping

Throws:

DatabaseException

removeFromCollectionChangeRecord

public void removeFromCollectionChangeRecord(Object newKey,
                                             Object newValue,
                                             ObjectChangeSet objectChangeSet,
                                             UnitOfWorkImpl uow)
                                      throws DescriptorException

INTERNAL: Remove a value and its change set from the collection change record. This is used by attribute change tracking.

Overrides:

removeFromCollectionChangeRecord in class DirectCollectionMapping

Throws:

DescriptorException

setDirectKeyField

public void setDirectKeyField(DatabaseField keyField)

INTERNAL:

setDirectKeyFieldName

public void setDirectKeyFieldName(String fieldName)

PUBLIC: Set the direct key field name in the reference table. This is the field that the primitive data value of the Map key is stored in.

updateChangeRecord

public void updateChangeRecord(Object clone,
                               Object newValue,
                               Object oldValue,
                               ObjectChangeSet objectChangeSet,
                               UnitOfWorkImpl uow)
                        throws DescriptorException

INTERNAL: Either create a new change record or update the change record with the new value. This is used by attribute change tracking.

Overrides:

updateChangeRecord in class DirectCollectionMapping

Throws:

DescriptorException

useMapClass

public void useMapClass(Class concreteClass)

PUBLIC: Configure the mapping to use an instance of the specified container class to hold the target objects.

The default container class is java.util.Hashtable.

The container class must implements (directly or indirectly) the Map interface.

Note: Do not use both useMapClass(Class concreteClass), useTransparentMap(). The last use of one of the two methods will overide the previous one.

Overrides:

useMapClass in class CollectionMapping

useTransparentMap

public void useTransparentMap()

PUBLIC: Configure the mapping to use an instance of the specified container class to hold the target objects.

jdk1.2.x: The container class must implement (directly or indirectly) the Map interface.

jdk1.1.x: The container class must be a subclass of Hashtable.

Note: Do not use both useMapClass(Class concreteClass), useTransparentMap(). The last use of one of the two methods will overide the previous one.

setKeyClass

public void setKeyClass(Class keyClass)

PUBLIC: This is a helper method to set the key converter to a TypeConversionConverter. This ensures that the key value from the database is converted to the correct Java type. The converter can also be set directly. Note that setting the converter to another converter will overwrite this setting.

getKeyClass

public Class getKeyClass()

PUBLIC: This is a helper method to get the object class from the key converter if it is a TypeConversionConverter. This returns null if not using a TypeConversionConverter key converter.

setValueClass

public void setValueClass(Class valueClass)

PUBLIC: This is a helper method to set the value converter to a TypeConversionConverter. This ensures that the value from the database is converted to the correct Java type. The converter can also be set directly. Note that setting the converter to another converter will overwrite this setting.

simpleAddToCollectionChangeRecord

public void simpleAddToCollectionChangeRecord(Object referenceKey,
                                              Object objectToAdd,
                                              ObjectChangeSet changeSet,
                                              AbstractSession session)

ADVANCED: This method is used to have an object add to a collection once the changeSet is applied The referenceKey parameter should only be used for direct Maps.

Overrides:

simpleAddToCollectionChangeRecord in class DirectCollectionMapping

simpleRemoveFromCollectionChangeRecord

public void simpleRemoveFromCollectionChangeRecord(Object referenceKey,
                                                   Object objectToRemove,
                                                   ObjectChangeSet changeSet,
                                                   AbstractSession session)

ADVANCED: This method is used to have an object removed from a collection once the changeSet is applied The referenceKey parameter should only be used for direct Maps.

Overrides:

simpleRemoveFromCollectionChangeRecord in class DirectCollectionMapping

getValueClass

public Class getValueClass()

PUBLIC: This is a helper method to get the object class from the value converter if it is a TypeConversionConverter. This returns null if not using a TypeConversionConverter value converter.

extractResultFromBatchQuery

public Object extractResultFromBatchQuery(DatabaseQuery query,
                                          AbstractRecord databaseRow,
                                          AbstractSession session,
                                          AbstractRecord argumentRow)

INTERNAL: Ovewrite super method