FileDocCategorySizeDatePackage
DatabaseMapping.javaAPI DocGlassfish v2 API48077Thu Jul 19 11:52:00 BST 2007oracle.toplink.essentials.mappings

DatabaseMapping

public abstract class DatabaseMapping extends Object implements Serializable, Cloneable

Purpose: Defines how an attribute of an object maps to and from the database

Responsibilities:

  • Define type of relationship (1:1/1:M/M:M/etc.)
  • Define instance variable name and fields names required
  • Define any additional properties (ownership, indirection, read only, etc.)
  • Control building the value for the instance variable from the database row
  • Control building the database fields from the object
  • Control any pre/post updating/inserting/deleting required to maintain the relationship
  • Merges object changes for unit of work.
  • Clones objects for unit of work.
  • cache computed information to optimize performance
author
Sati
since
TOPLink/Java 1.0

Fields Summary
protected static final Vector
NO_FIELDS
Used to reduce memory for mappings with no fields.
protected static final Integer
NO_WEIGHT
Used to share integer instance to reduce memory.
protected static final Integer
WEIGHT_1
protected oracle.toplink.essentials.descriptors.ClassDescriptor
descriptor
Descriptor to which this mapping belongs to
protected AttributeAccessor
attributeAccessor
Wrapper to store the reference objects.
protected boolean
isReadOnly
Makes this mapping read only. No write are performed on it. Default is false
protected boolean
isOptional
Specifies whether this mapping is optional (i.e. field may be null). Used for DDL generation.
protected Vector
fields
Fields associated with the mappings are cached
protected boolean
isRemotelyInitialized
It is needed only in remote initialization and mapping is in parent descriptor
protected Integer
weight
This is a TopLink defined attribute that allows us to sort the mappings
protected Map
properties
used as a temporary store for custom SDK usage
protected boolean
primaryKeyMapping
used as a quick check to see if this mapping is a primary key mapping, set by the object builder during initialization.
Constructors Summary
public DatabaseMapping()
PUBLIC: Default constructor.


            
      
        this.isOptional = true;
        this.isReadOnly = false;
        this.attributeAccessor = new InstanceVariableAttributeAccessor();
    
Methods Summary
public voidaddToCollectionChangeRecord(java.lang.Object newKey, java.lang.Object newValue, ObjectChangeSet objectChangeSet, oracle.toplink.essentials.internal.sessions.UnitOfWorkImpl uow)
INTERNAL: Add a new value and its change set to the collection change record. This is used by attribute change tracking.

        throw DescriptorException.invalidMappingOperation(this, "addToCollectionChangeRecord");
    
public abstract voidbuildBackupClone(java.lang.Object clone, java.lang.Object backup, oracle.toplink.essentials.internal.sessions.UnitOfWorkImpl unitOfWork)
INTERNAL: Clone the attribute from the clone and assign it to the backup.

public java.lang.ObjectbuildBackupCloneForPartObject(java.lang.Object attributeValue, java.lang.Object clone, java.lang.Object backup, oracle.toplink.essentials.internal.sessions.UnitOfWorkImpl unitOfWork)
INTERNAL: Require for cloning, the part must be cloned.

        throw DescriptorException.invalidMappingOperation(this, "buildBackupCloneForPartObject");
    
public ChangeRecordbuildChangeRecord(java.lang.Object newValue, ObjectChangeSet owner, oracle.toplink.essentials.internal.sessions.AbstractSession session)
INTERNAL: Directly build a change record without comparison

        throw DescriptorException.invalidMappingOperation(this, "buildChangeRecord");
    
public abstract voidbuildClone(java.lang.Object original, java.lang.Object clone, oracle.toplink.essentials.internal.sessions.UnitOfWorkImpl unitOfWork, JoinedAttributeManager joinedAttributeManager)
INTERNAL: Clone the attribute from the original and assign it to the clone.

public java.lang.ObjectbuildCloneForPartObject(java.lang.Object attributeValue, java.lang.Object original, java.lang.Object clone, oracle.toplink.essentials.internal.sessions.UnitOfWorkImpl unitOfWork, boolean isExisting)
INTERNAL: Require for cloning, the part must be cloned.

        throw DescriptorException.invalidMappingOperation(this, "buildCloneForPartObject");
    
public abstract voidbuildCloneFromRow(oracle.toplink.essentials.internal.sessions.AbstractRecord databaseRow, JoinedAttributeManager joinManager, java.lang.Object clone, ObjectBuildingQuery sourceQuery, oracle.toplink.essentials.internal.sessions.UnitOfWorkImpl unitOfWork, oracle.toplink.essentials.internal.sessions.AbstractSession executionSession)
INTERNAL: A combination of readFromRowIntoObject and buildClone.

buildClone assumes the attribute value exists on the original and can simply be copied.

readFromRowIntoObject assumes that one is building an original.

Both of the above assumptions are false in this method, and actually attempts to do both at the same time.

Extract value from the row and set the attribute to this value in the working copy clone. In order to bypass the shared cache when in transaction a UnitOfWork must be able to populate working copies directly from the row.

public voidbuildCopy(java.lang.Object copy, java.lang.Object original, oracle.toplink.essentials.sessions.ObjectCopyingPolicy policy)
INTERNAL: Copy of the attribute of the object. This is NOT used for unit of work but for templatizing an object.

    
public ExpressionbuildObjectJoinExpression(Expression base, Expression argument, oracle.toplink.essentials.internal.sessions.AbstractSession session)
INTERNAL: Used to allow object level comparisons.

        throw QueryException.unsupportedMappingForObjectComparison(this, base);
    
public ExpressionbuildObjectJoinExpression(Expression base, java.lang.Object value, oracle.toplink.essentials.internal.sessions.AbstractSession session)
INTERNAL: Used to allow object level comparisons.

        throw QueryException.unsupportedMappingForObjectComparison(this, base);
    
public voidbuildShallowOriginalFromRow(oracle.toplink.essentials.internal.sessions.AbstractRecord databaseRow, java.lang.Object original, ObjectBuildingQuery query, oracle.toplink.essentials.internal.sessions.AbstractSession executionSession)
INTERNAL: Builds a shallow original object. Only direct attributes and primary keys are populated. In this way the minimum original required for instantiating a working copy clone can be built without placing it in the shared cache (no concern over cycles).

        return;
    
public voidcalculateDeferredChanges(ChangeRecord changeRecord, oracle.toplink.essentials.internal.sessions.AbstractSession session)
INTERNAL: Used by AttributeLevelChangeTracking to update a changeRecord with calculated changes as apposed to detected changes. If an attribute can not be change tracked it's changes can be detected through this process.

        throw DescriptorException.invalidMappingOperation(this, "calculatedDeferredChanges");
    
public voidcascadeMerge(java.lang.Object sourceElement, MergeManager mergeManager)
INTERNAL: Cascade the merge to the component object, if appropriate.

        throw DescriptorException.invalidMappingOperation(this, "cascadeMerge");
    
public abstract voidcascadePerformRemoveIfRequired(java.lang.Object object, oracle.toplink.essentials.internal.sessions.UnitOfWorkImpl uow, IdentityHashtable visitedObjects)
INTERNAL: Cascade registerNew for Create through mappings that require the cascade

public abstract voidcascadeRegisterNewIfRequired(java.lang.Object object, oracle.toplink.essentials.internal.sessions.UnitOfWorkImpl uow, IdentityHashtable visitedObjects)
INTERNAL: Cascade registerNew for Create through mappings that require the cascade

public java.lang.Objectclone()
INTERNAL: Clones itself.

        // Bug 3037701 - clone the AttributeAccessor
        DatabaseMapping mapping = null;
        try {
            mapping = (DatabaseMapping)super.clone();
        } catch (CloneNotSupportedException e) {
            throw new InternalError();
        }
        mapping.setAttributeAccessor((AttributeAccessor)attributeAccessor.clone());
        return mapping;
    
protected java.util.VectorcloneFields(java.util.Vector fields)
INTERNAL: Helper method to clone vector of fields (used in aggregate initialization cloning).

        Vector clonedFields = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance();
        for (Enumeration fieldsEnum = fields.elements(); fieldsEnum.hasMoreElements();) {
            clonedFields.addElement(((DatabaseField)fieldsEnum.nextElement()).clone());
        }

        return clonedFields;
    
protected java.util.VectorcollectFields()
This method must be overwritten in the subclasses to return a vector of all the fields this mapping represents.

        return NO_FIELDS;
    
public abstract ChangeRecordcompareForChange(java.lang.Object clone, java.lang.Object backup, ObjectChangeSet owner, oracle.toplink.essentials.internal.sessions.AbstractSession session)
INTERNAL: This method was created in VisualAge.

return
prototype.changeset.ChangeRecord

public abstract booleancompareObjects(java.lang.Object firstObject, java.lang.Object secondObject, oracle.toplink.essentials.internal.sessions.AbstractSession session)
INTERNAL: Compare the attributes belonging to this mapping for the objects.

public voidconvertClassNamesToClasses(java.lang.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.

param
classLoader

public UnitOfWorkValueHoldercreateUnitOfWorkValueHolder(ValueHolderInterface attributeValue, java.lang.Object original, java.lang.Object clone, oracle.toplink.essentials.internal.sessions.AbstractRecord row, oracle.toplink.essentials.internal.sessions.UnitOfWorkImpl unitOfWork, boolean buildDirectlyFromRow)
INTERNAL: Builder the unit of work value holder.

param
buildDirectlyFromRow indicates that we are building the clone directly from a row as opposed to building the original from the row, putting it in the shared cache, and then cloning the original.

        throw DescriptorException.invalidMappingOperation(this, "createUnitOfWorkValueHolder");
    
protected java.util.VectorextractNestedExpressions(java.util.List expressions, ExpressionBuilder newRoot, boolean rootExpressionsAllowed)
INTERNAL: Extract the nested attribute expressions that apply to this mapping. This is used for partial objects and joining.

param
rootExpressionsAllowed true if newRoot itself can be one of the expressions returned

        Vector nestedExpressions = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(expressions.size());

        for (Iterator expressionsEnum = expressions.iterator();
                 expressionsEnum.hasNext();) {
            Expression next = (Expression)expressionsEnum.next();

            // The expressionBuilder can be one of the locked expressions in
            // the ForUpdateOfClause.
            if (!next.isQueryKeyExpression()) {
                continue;
            }
            QueryKeyExpression expression = (QueryKeyExpression)next;
            QueryKeyExpression base = expression;
            boolean afterBase = false;
            while (!base.getBaseExpression().isExpressionBuilder()) {
                afterBase = true;
                base = (QueryKeyExpression)base.getBaseExpression();
            }
            if (afterBase && base.getName().equals(getAttributeName())) {
                nestedExpressions.addElement(expression.rebuildOn(base, newRoot));
            } else if (rootExpressionsAllowed && expression.getBaseExpression().isExpressionBuilder() && expression.getName().equals(getAttributeName())) {
                nestedExpressions.addElement(newRoot);
            }
        }
        return nestedExpressions;
    
public AttributeAccessorgetAttributeAccessor()
ADVANCED: Return the attributeAccessor. The attribute accessor is responsible for setting and retrieving the attribute value from the object for this mapping.

        return attributeAccessor;
    
public java.lang.ClassgetAttributeClassification()
PUBLIC: The classification type for the attribute this mapping represents

        return null;
    
public java.lang.StringgetAttributeName()
PUBLIC: Return the name of the attribute set in the mapping.

        return getAttributeAccessor().getAttributeName();
    
public java.lang.ObjectgetAttributeValueFromObject(java.lang.Object object)
INTERNAL: Return the value of an attribute which this mapping represents for an object.

        try {
            return getAttributeAccessor().getAttributeValueFromObject(object);
        } catch (DescriptorException exception) {
            exception.setMapping(this);
            throw exception;
        }
    
public ContainerPolicygetContainerPolicy()
INTERNAL: Return the mapping's containerPolicy.

        throw DescriptorException.invalidMappingOperation(this, "getContainerPolicy");
    
public oracle.toplink.essentials.descriptors.ClassDescriptorgetDescriptor()
INTERNAL: Return the descriptor to which this mapping belongs

        return descriptor;
    
public DatabaseFieldgetField()
INTERNAL: Return the field associated with this mapping if there is exactly one. This is required for object relational mapping to print them, but because they are defined in Enterprise they cannot be cast to. Mappings that have a field include direct mappings and object relational mappings.

        return null;
    
public java.lang.ClassgetFieldClassification(DatabaseField fieldToClassify)
INTERNAL: Return the classifiction for the field contained in the mapping. This is used to convert the row value to a consistent java value. By default this is unknown.

        return null;
    
public java.util.VectorgetFields()
INTERNAL: Returns a vector of all the fields this mapping represents.

        return this.fields;
    
public java.lang.StringgetGetMethodName()
PUBLIC: This method is invoked reflectively on the reference object to return the value of the attribute in the object. This method returns the name of the getMethodName or null if not using method access.

        if (!(getAttributeAccessor() instanceof MethodAttributeAccessor)) {
            return null;
        }
        return ((MethodAttributeAccessor)getAttributeAccessor()).getGetMethodName();
    
public java.util.MapgetProperties()
INTERNAL: used as a temporary store for custom SDK usage

        if (properties == null) {//Lazy initialize to conserve space and allocation time.
            properties = new HashMap(5);
        }
        return properties;
    
public java.lang.ObjectgetProperty(java.lang.Object property)
INTERNAL: used as a temporary store for custom SDK usage

        if (properties == null) {
            return null;
        }

        return getProperties().get(property);
    
public java.lang.ObjectgetRealAttributeValueFromObject(java.lang.Object object, oracle.toplink.essentials.internal.sessions.AbstractSession session)
INTERNAL: Return the value of an attribute unwrapping value holders if required.

        return getAttributeValueFromObject(object);
    
public java.lang.ObjectgetRealCollectionAttributeValueFromObject(java.lang.Object object, oracle.toplink.essentials.internal.sessions.AbstractSession session)
INTERNAL: Return the value of an attribute, unwrapping value holders if necessary. If the value is null, build a new container.

        throw DescriptorException.invalidMappingOperation(this, "getRealCollectionAttributeValueFromObject");
    
public oracle.toplink.essentials.descriptors.ClassDescriptorgetReferenceClassDescriptor()
PUBLIC: Return the referenceDescriptor. This is a descriptor which is associated with the reference class.

		ClassDescriptor desc = getReferenceDescriptor();
		if (desc instanceof ClassDescriptor) {
			return (ClassDescriptor)desc;
		} else {
			throw ValidationException.cannotCastToClass(desc, desc.getClass(), ClassDescriptor.class);
		}
    
public oracle.toplink.essentials.descriptors.ClassDescriptorgetReferenceDescriptor()
INTERNAL: Return the referenceDescriptor. This is a descriptor which is associated with the reference class. Replaced by {@link #getReferenceClassDescriptor()}

        return null;
    
public oracle.toplink.essentials.mappings.DatabaseMappinggetRelationshipPartner()
INTERNAL: Return the relationshipPartner mapping for this bi-directional mapping. If the relationshipPartner is null then this is a uni-directional mapping.

        return null;
    
public java.lang.StringgetSetMethodName()
PUBLIC: This method is invoked reflectively on the reference object to set the value of the attribute in the object. This method returns the name of the setMethodName or null if not using method access.

        if (!(getAttributeAccessor() instanceof MethodAttributeAccessor)) {
            return null;
        }
        return ((MethodAttributeAccessor)getAttributeAccessor()).getSetMethodName();
    
public java.lang.IntegergetWeight()
INTERNAL: Return the weight of the mapping, used to sort mappings to ensure that DirectToField Mappings get merged first

        return this.weight;
    
public booleanhasConstraintDependency()
INTERNAL: The returns if the mapping has any constraint dependencies, such as foreign keys and join tables.

        return false;
    
public booleanhasDependency()
INTERNAL: Return if the mapping has any ownership or other dependency over its target object(s).

        return isPrivateOwned();
    
public booleanhasInverseConstraintDependency()
INTERNAL: The returns if the mapping has any inverse constraint dependencies, such as foreign keys and join tables.

        return false;
    
public voidinitialize(oracle.toplink.essentials.internal.sessions.AbstractSession session)
INTERNAL: Allow for initialization of properties and validation.

        ;
    
public booleanisAbstractCompositeCollectionMapping()
INTERNAL: Related mapping should implement this method to return true.

        return false;
    
public booleanisAbstractCompositeDirectCollectionMapping()
INTERNAL: Related mapping should implement this method to return true.

        return false;
    
public booleanisAbstractCompositeObjectMapping()
INTERNAL: Related mapping should implement this method to return true.

        return false;
    
public booleanisAbstractDirectMapping()
INTERNAL: Related mapping should implement this method to return true.

        return false;
    
public booleanisAggregateCollectionMapping()
INTERNAL: Related mapping should implement this method to return true.

        return false;
    
public booleanisAggregateMapping()
INTERNAL: Related mapping should implement this method to return true.

        return false;
    
public booleanisAggregateObjectMapping()
INTERNAL: Related mapping should implement this method to return true.

        return false;
    
public booleanisCascadedLockingSupported()
INTERNAL: Used when determining if a mapping supports cascaded version optimistic locking.

        return false;
    
public booleanisChangeTrackingSupported()
INTERNAL: Return if this mapping supports change tracking.

        return false;
    
public booleanisCloningRequired()
INTERNAL: Return if this mapping requires its attribute value to be cloned.

        return true;
    
public booleanisCollectionMapping()
INTERNAL: Related mapping should implement this method to return true.

        return false;
    
public booleanisDatabaseMapping()
INTERNAL:

        return true;
    
public booleanisDirectCollectionMapping()
INTERNAL: Related mapping should implement this method to return true.

        return false;
    
public booleanisDirectMapMapping()
INTERNAL: Related mapping should implement this method to return true.

        return false;
    
public booleanisDirectToFieldMapping()
INTERNAL: Related mapping should implement this method to return true.

        return false;
    
public booleanisDirectToXMLTypeMapping()
INTERNAL: Related mapping should implement this method to return true.

        return false;
    
public booleanisEISMapping()
INTERNAL: All EIS mappings should implement this method to return true.

        return false;
    
public booleanisForeignReferenceMapping()
INTERNAL: Related mapping should implement this method to return true.

        return false;
    
public booleanisJoiningSupported()
INTERNAL: Return if this mapping support joining.

        return false;
    
public booleanisManyToManyMapping()
INTERNAL: Related mapping should implement this method to return true.

        return false;
    
public booleanisNestedTableMapping()
INTERNAL: Related mapping should implement this method to return true.

        return false;
    
public booleanisObjectReferenceMapping()
INTERNAL: Related mapping should implement this method to return true.

        return false;
    
public booleanisObjectTypeMapping()
INTERNAL: Related mapping should implement this method to return true.

        return false;
    
public booleanisOneToManyMapping()
INTERNAL: Related mapping should implement this method to return true.

        return false;
    
public booleanisOneToOneMapping()
INTERNAL: Related mapping should implement this method to return true.

        return false;
    
public booleanisOptional()
INTERNAL: Return whether the value of this mapping is optional (that is, can be null). This is a hint and is used when generating DDL. It should be disregarded for primitive types.

        return isOptional;
    
public booleanisPrimaryKeyMapping()
INTERNAL: Set by the Object builder during initialization returns true if this mapping is used as a primary key mapping.

        return this.primaryKeyMapping;
    
public booleanisPrivateOwned()
INTERNAL: Return if the mapping has ownership over its target object(s).

        return false;
    
public booleanisReadOnly()
INTERNAL: Returns true if mapping is read only else false.

        return isReadOnly;
    
public booleanisReferenceMapping()
INTERNAL: Related mapping should implement this method to return true.

        return false;
    
public booleanisRelationalMapping()
INTERNAL: All relational mappings should implement this method to return true.

        return false;
    
protected booleanisRemotelyInitialized()

        return isRemotelyInitialized;
    
public booleanisSerializedObjectMapping()
INTERNAL: Related mapping should implement this method to return true.

        return false;
    
public booleanisStructureMapping()
INTERNAL: Related mapping should implement this method to return true.

        return false;
    
public booleanisTransformationMapping()
INTERNAL: Related mapping should implement this method to return true.

        return false;
    
public booleanisTypeConversionMapping()
INTERNAL: Related mapping should implement this method to return true.

        return false;
    
public booleanisUsingMethodAccess()
PUBLIC: Return if method access is used.

        return getAttributeAccessor() instanceof MethodAttributeAccessor;
    
public booleanisVariableOneToOneMapping()
INTERNAL: Related mapping should implement this method to return true.

        return false;
    
public booleanisWriteOnly()
INTERNAL: Some mappings support no attribute (transformation).

        return false;
    
public booleanisXMLMapping()
INTERNAL: All relational mappings should implement this method to return true.

        return false;
    
public abstract voiditerate(DescriptorIterator iterator)
INTERNAL: Iterate on the appropriate attribute value.

public voiditerateOnRealAttributeValue(DescriptorIterator iterator, java.lang.Object realAttributeValue)
INTERNAL: Iterate on the attribute value. The value holder has already been processed.

        throw DescriptorException.invalidMappingOperation(this, "iterateOnRealAttributeValue");
    
public abstract voidmergeChangesIntoObject(java.lang.Object target, ChangeRecord changeRecord, java.lang.Object source, MergeManager mergeManager)
INTERNAL: Merge changes from the source to the target object.

public abstract voidmergeIntoObject(java.lang.Object target, boolean isTargetUninitialized, java.lang.Object source, MergeManager mergeManager)
INTERNAL: Merge changes from the source to the target object.

public voidperformDataModificationEvent(java.lang.Object[] event, oracle.toplink.essentials.internal.sessions.AbstractSession session)
INTERNAL: Perform the commit event. This is used in the uow to delay data modifications.

        throw DescriptorException.invalidDataModificationEvent(this);
    
public voidpostDelete(WriteObjectQuery query)
INTERNAL: A subclass should implement this method if it wants different behaviour. Recurse thru the parts to delete the reference objects after the actual object is deleted.

        return;
    
public voidpostInitialize(oracle.toplink.essentials.internal.sessions.AbstractSession session)
INTERNAL: Allow for initialization of properties and validation that have dependecies no the descriptor being initialized.

        // Nothing by default.
    
public voidpostInsert(WriteObjectQuery query)
INTERNAL: A subclass should implement this method if it wants different behaviour. Recurse thru the parts to insert the reference objects after the actual object is inserted.

        return;
    
public voidpostUpdate(WriteObjectQuery query)
INTERNAL: A subclass should implement this method if it wants different behaviour. Recurse thru the parts to update the reference objects after the actual object is updated.

        return;
    
public voidpreDelete(WriteObjectQuery query)
INTERNAL: A subclass should implement this method if it wants different behaviour. Recurse thru the parts to delete the reference objects before the actual object is deleted.

        return;
    
public voidpreInitialize(oracle.toplink.essentials.internal.sessions.AbstractSession session)
INTERNAL: Allow for initialization of properties and validation.

        try {
            getAttributeAccessor().initializeAttributes(getDescriptor().getJavaClass());
        } catch (DescriptorException exception) {
            exception.setMapping(this);
            session.getIntegrityChecker().handleError(exception);
        }
    
public voidpreInsert(WriteObjectQuery query)
INTERNAL: A subclass should implement this method if it wants different behaviour. Recurse thru the parts to insert the reference objects before the actual object is inserted.

        return;
    
public voidpreUpdate(WriteObjectQuery query)
INTERNAL: A subclass should implement this method if it wants different behaviour. Recurse thru the parts to update the reference objects before the actual object is updated.

        return;
    
public voidprepareCascadeLockingPolicy()
INTERNAL: A subclass that supports cascade version optimistic locking should implement this method to properly prepare the locking policy for their mapping type.

        return;
    
public java.lang.ObjectreadFromRowIntoObject(oracle.toplink.essentials.internal.sessions.AbstractRecord databaseRow, JoinedAttributeManager joinManager, java.lang.Object targetObject, ObjectBuildingQuery sourceQuery)
INTERNAL: Extract value from the row and set the attribute to this value in the object. return value as this value will have been converted to the appropriate type for the object.

        // This version can be called directly for reading a sequence number
        // field, a write lock value, or a return row into an object, and hence
        // the query is just a placeholder.  Getting the correct execution
        // session will generate an exception, so just pass in any session.
        // In general call this version only if no field conversion needed.
        return readFromRowIntoObject(databaseRow, joinManager, targetObject, sourceQuery, sourceQuery.getSession());
    
public java.lang.ObjectreadFromRowIntoObject(oracle.toplink.essentials.internal.sessions.AbstractRecord databaseRow, JoinedAttributeManager joinManager, java.lang.Object targetObject, ObjectBuildingQuery sourceQuery, oracle.toplink.essentials.internal.sessions.AbstractSession executionSession)
INTERNAL: Extract value from the row and set the attribute to this value in the object. return value as this value will have been converted to the appropriate type for the object.

        Object attributeValue = valueFromRow(databaseRow, joinManager, sourceQuery, executionSession);
        setAttributeValueInObject(targetObject, attributeValue);
        return attributeValue;
    
public voidreadOnly()
PUBLIC: To make mapping read only. Read-only mappings can be used if two attributes map to the same field. Read-only mappings cannot be used for the primary key or other required fields.

        setIsReadOnly(true);
    
public voidreadWrite()
PUBLIC: The mapping can be dynamically made either readOnly or readWriteOnly. This makes mapping go back to default mode.

        setIsReadOnly(false);
    
public voidrehashFieldDependancies(oracle.toplink.essentials.internal.sessions.AbstractSession 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.

        // Should be overwritten by any mapping with fields.
    
public voidremoveFromCollectionChangeRecord(java.lang.Object newKey, java.lang.Object newValue, ObjectChangeSet objectChangeSet, oracle.toplink.essentials.internal.sessions.UnitOfWorkImpl uow)
INTERNAL: Remove a value and its change set from the collection change record. This is used by attribute change tracking.

        throw DescriptorException.invalidMappingOperation(this, "removeFromCollectionChangeRecord");
    
public voidsetAttributeAccessor(AttributeAccessor attributeAccessor)
ADVANCED: Set the attributeAccessor. The attribute accessor is responsible for setting and retrieving the attribute value from the object for this mapping. This can be set to an implementor of AttributeAccessor if the attribute requires advanced conversion of the mapping value, or a real attribute does not exist.

        String attributeName = getAttributeName();
        this.attributeAccessor = attributeAccessor;
        if (attributeAccessor.getAttributeName() == null) {
            attributeAccessor.setAttributeName(attributeName);
        }
    
public voidsetAttributeName(java.lang.String attributeName)
PUBLIC: Sets the name of the attribute in the mapping.

        getAttributeAccessor().setAttributeName(attributeName);
    
public voidsetAttributeValueInObject(java.lang.Object object, java.lang.Object value)
INTERNAL: Set the value of the attribute mapped by this mapping.

        // PERF: Direct variable access.
        try {
            this.attributeAccessor.setAttributeValueInObject(object, value);
        } catch (DescriptorException exception) {
            exception.setMapping(this);
            throw exception;
        }
    
public voidsetDescriptor(oracle.toplink.essentials.descriptors.ClassDescriptor descriptor)
INTERNAL: Set the descriptor to which this mapping belongs

        this.descriptor = descriptor;
    
protected voidsetFields(java.util.Vector fields)
INTERNAL: Set the mapping's field collection.

        this.fields = fields;
    
public voidsetGetMethodName(java.lang.String methodName)
PUBLIC: This method is invoked reflectively on the reference object to return the value of the attribute in the object. This method sets the name of the getMethodName.

        if (methodName == null) {
            return;
        }

        // This is done because setting attribute name by defaults create InstanceVariableAttributeAccessor	
        if (getAttributeAccessor() instanceof InstanceVariableAttributeAccessor) {
            String attributeName = this.attributeAccessor.getAttributeName();
            setAttributeAccessor(new MethodAttributeAccessor());
            getAttributeAccessor().setAttributeName(attributeName);
        }

        ((MethodAttributeAccessor)getAttributeAccessor()).setGetMethodName(methodName);
    
public voidsetIsOptional(boolean isOptional)
INTERNAL: Used to specify whether the value of this mapping may be null. It is used when generating DDL.

        this.isOptional = isOptional;
    
public voidsetIsPrimaryKeyMapping(boolean pkMapping)
INTERNAL: Set by the Object builder during initialization returns true if this mapping is used as a primary key mapping.

        this.primaryKeyMapping = pkMapping;
    
public voidsetIsReadOnly(boolean aBoolean)
PUBLIC: Set this mapping to be read only. Read-only mappings can be used if two attributes map to the same field. Read-only mappings cannot be used for the primary key or other required fields.

        isReadOnly = aBoolean;
    
public voidsetProperties(java.util.Map properties)
INTERNAL: used as a temporary store for custom SDK usage

        this.properties = properties;
    
public voidsetProperty(java.lang.Object property, java.lang.Object value)
ADVANCED: Allow user defined properties.

        getProperties().put(property, value);
    
public voidsetRealAttributeValueInObject(java.lang.Object object, java.lang.Object value)
INTERNAL: Set the value of the attribute mapped by this mapping, placing it inside a value holder if necessary.

        try {
            this.setAttributeValueInObject(object, value);
        } catch (DescriptorException exception) {
            exception.setMapping(this);
            throw exception;
        }
    
public voidsetSetMethodName(java.lang.String methodName)
PUBLIC: This method is invoked reflectively on the reference object to get the value of the attribute. The method defined on the object should actually return the value that needs to be set in the attribute accessor.

        if (methodName == null) {
            return;
        }

        // This is done because setting attribute name by defaults create InstanceVariableAttributeAccessor		
        if (!(getAttributeAccessor() instanceof MethodAttributeAccessor)) {
            String attributeName = this.attributeAccessor.getAttributeName();
            setAttributeAccessor(new MethodAttributeAccessor());
            getAttributeAccessor().setAttributeName(attributeName);
        }

        ((MethodAttributeAccessor)getAttributeAccessor()).setSetMethodName(methodName);
    
public voidsetWeight(java.lang.Integer newWeight)
ADVANCED: Set the weight of the mapping, used to sort mappings DirectToField Mappings have a default weight of 1 while all other Mappings have a default weight of MAXINT. Ordering of Mappings can be achieved by setting the weight of a particular mapping to a value within the above mentioned limits. By ordering mappings the user can control what order relationships are processed by TopLink.

        this.weight = newWeight;
    
public voidsimpleAddToCollectionChangeRecord(java.lang.Object referenceKey, java.lang.Object changeSetToAdd, ObjectChangeSet changeSet, oracle.toplink.essentials.internal.sessions.AbstractSession session)
ADVANCED: This method is used to add an object to a collection once the changeSet is applied. The referenceKey parameter should only be used for direct Maps.

        throw DescriptorException.invalidMappingOperation(this, "simpleAddToCollectionChangeRecord");
    
public voidsimpleRemoveFromCollectionChangeRecord(java.lang.Object referenceKey, java.lang.Object changeSetToAdd, ObjectChangeSet changeSet, oracle.toplink.essentials.internal.sessions.AbstractSession session)
ADVANCED: This method is used to remove an object from a collection once the changeSet is applied. The referenceKey parameter should only be used for direct Maps.

        throw DescriptorException.invalidMappingOperation(this, "simpleRemoveFromCollectionChangeRecord");
    
public java.lang.StringtoString()
INTERNAL: Print the mapping attribute name, this is used in error messages.

        return getClass().getName() + "[" + getAttributeName() + "]";
    
public voidupdateChangeRecord(java.lang.Object clone, java.lang.Object newValue, java.lang.Object oldValue, ObjectChangeSet objectChangeSet, oracle.toplink.essentials.internal.sessions.UnitOfWorkImpl uow)
INTERNAL: Either create a new change record or update the change record with the new value. This is used by attribute change tracking.

        throw DescriptorException.invalidMappingOperation(this, "updateChangeRecord");
    
public voidvalidateAfterInitialization(oracle.toplink.essentials.internal.sessions.AbstractSession session)
INTERNAL: Allow for subclasses to perform validation.

    
public voidvalidateBeforeInitialization(oracle.toplink.essentials.internal.sessions.AbstractSession session)
INTERNAL: Allow for subclasses to perform validation.

    
public java.lang.ObjectvalueFromObject(java.lang.Object anObject, DatabaseField field, oracle.toplink.essentials.internal.sessions.AbstractSession session)
INTERNAL: A subclass should extract the value from the object for the field, if it does not map the field then it should return null. Return the Value from the object.

        return null;
    
public java.lang.ObjectvalueFromRow(oracle.toplink.essentials.internal.sessions.AbstractRecord row, JoinedAttributeManager joinManager, ObjectBuildingQuery query)
INTERNAL: A subclass should implement this method if it wants different behaviour. Returns the value for the mapping from the database row.

        return valueFromRow(row, joinManager, query, query.getSession().getExecutionSession(query));
    
public java.lang.ObjectvalueFromRow(oracle.toplink.essentials.internal.sessions.AbstractRecord row, JoinedAttributeManager joinManager, ObjectBuildingQuery query, oracle.toplink.essentials.internal.sessions.AbstractSession session)
INTERNAL:

        return null;
    
public booleanverifyDelete(java.lang.Object object, oracle.toplink.essentials.internal.sessions.AbstractSession session)
INTERNAL: To verify if the specified object has been deleted or not.

        return true;
    
public voidwriteFromAttributeIntoRow(java.lang.Object attribute, oracle.toplink.essentials.internal.sessions.AbstractRecord row, oracle.toplink.essentials.internal.sessions.AbstractSession session)
INTERNAL: A subclass should implement this method if it wants different behaviour. Write the foreign key values from the attribute to the row.

        // Do nothing by default.
    
public voidwriteFromObjectIntoRow(java.lang.Object object, oracle.toplink.essentials.internal.sessions.AbstractRecord row, oracle.toplink.essentials.internal.sessions.AbstractSession session)
INTERNAL: A subclass should implement this method if it wants different behaviour. Write the attribute value from the object to the row.

        // Do nothing by default.
    
public voidwriteFromObjectIntoRowForShallowDelete(java.lang.Object object, oracle.toplink.essentials.internal.sessions.AbstractRecord row, oracle.toplink.essentials.internal.sessions.AbstractSession session)
INTERNAL: This row is built for shallow delete which happens in case of circular dependencies for bidirectional deletes.

        // Do nothing by default.
    
public voidwriteFromObjectIntoRowForShallowInsert(java.lang.Object object, oracle.toplink.essentials.internal.sessions.AbstractRecord row, oracle.toplink.essentials.internal.sessions.AbstractSession session)
INTERNAL: This row is built for shallow insert which happens in case of of circular dependencies bidirectional inserts.

        writeFromObjectIntoRow(object, row, session);
    
public voidwriteFromObjectIntoRowForShallowInsertWithChangeRecord(ChangeRecord changeRecord, oracle.toplink.essentials.internal.sessions.AbstractRecord row, oracle.toplink.essentials.internal.sessions.AbstractSession session)
INTERNAL: This row is built for shallow insert which happens in case of bidirectional inserts.

        writeFromObjectIntoRowWithChangeRecord(changeRecord, row, session);
    
public voidwriteFromObjectIntoRowForUpdate(WriteObjectQuery query, oracle.toplink.essentials.internal.sessions.AbstractRecord row)
INTERNAL: Write the attribute value from the object to the row for update.

        writeFromObjectIntoRow(query.getObject(), row, query.getSession());
    
public voidwriteFromObjectIntoRowForWhereClause(ObjectLevelModifyQuery query, oracle.toplink.essentials.internal.sessions.AbstractRecord row)
INTERNAL: A subclass should implement this method if it wants different behaviour. Write the attribute value from the object to the row.

        Object object;
        if (query.isDeleteObjectQuery()) {
            object = query.getObject();
        } else {
            object = query.getBackupClone();
        }
        writeFromObjectIntoRow(object, row, query.getSession());
    
public voidwriteFromObjectIntoRowWithChangeRecord(ChangeRecord changeRecord, oracle.toplink.essentials.internal.sessions.AbstractRecord row, oracle.toplink.essentials.internal.sessions.AbstractSession session)
INTERNAL: A subclass should implement this method if it wants different behaviour. Write the attribute value from the object to the row.

        // Do nothing by default.
    
public voidwriteInsertFieldsIntoRow(oracle.toplink.essentials.internal.sessions.AbstractRecord databaseRow, oracle.toplink.essentials.internal.sessions.AbstractSession session)
INTERNAL: Write fields needed for insert into the template for with null values.

        // Do nothing by default.
    
public voidwriteUpdateFieldsIntoRow(oracle.toplink.essentials.internal.sessions.AbstractRecord databaseRow, oracle.toplink.essentials.internal.sessions.AbstractSession session)
INTERNAL: Write fields needed for update into the template for with null values. By default inserted fields are used.

        writeInsertFieldsIntoRow(databaseRow, session);