Purpose:Two objects can be considered to be related by aggregation if there is a strict
1:1 relationship between the objects. This means that the target (child or owned) object
cannot exist without the source (parent) object.
In TopLink, it also means the data for the owned object is stored in the same table as
the parent.

isNullAllowed
If all the fields in the database row for the aggregate object are NULL,
then, by default, the mapping will place a null in the appropriate source object
(as opposed to an aggregate object filled with nulls).

addAdditionalFieldsToQuery(ReadQuery selectionQuery,
Expression baseExpression)
INTERNAL:
Used when initializing queries for mappings that use a Map
Called when the selection query is being initialized to add the fields for the map key to the query

void

addFieldNameTranslation(java.lang.String sourceFieldName,
java.lang.String aggregateFieldName)
PUBLIC:
Add a field name translation that maps from a field name in the
source table to a field name in the aggregate descriptor.

void

addFieldsForMapKey(org.eclipse.persistence.internal.sessions.AbstractRecord joinRow)
INTERNAL:
Used when initializing queries for mappings that use a Map
Called when the insert query is being initialized to ensure the fields for the map key are in the insert query

void

addFieldTranslation(org.eclipse.persistence.internal.helper.DatabaseField sourceField,
java.lang.String aggregateFieldName)
PUBLIC:
Add a field translation that maps from a field in the
source table to a field name in the aggregate descriptor.

void

addKeyToDeletedObjectsList(java.lang.Object object,
java.util.Map deletedObjects)
INTERNAL:
For mappings used as MapKeys in MappedKeyContainerPolicy.

addNestedFieldTranslation(java.lang.String attributeName,
org.eclipse.persistence.internal.helper.DatabaseField sourceField,
java.lang.String aggregateFieldName)
INTERNAL:
Add a nested field translation that maps from a field in the source table
to a field name in a nested aggregate descriptor.

allAggregateFieldsAreNull(org.eclipse.persistence.internal.sessions.AbstractRecord databaseRow)
INTERNAL:
Return whether all the aggregate fields in the specified
row are NULL.

void

allowNull()
PUBLIC:
If all the fields in the database row for the aggregate object are NULL,
then, by default, the mapping will place a null in the appropriate source object
(as opposed to an aggregate object filled with nulls).

buildClone(java.lang.Object original,
org.eclipse.persistence.internal.identitymaps.CacheKey cacheKey,
java.lang.Object clone,
org.eclipse.persistence.internal.sessions.AbstractSession cloningSession)
INTERNAL:
Clone the attribute from the original and assign it to the clone.

collectQueryParameters(java.util.Set<org.eclipse.persistence.internal.helper.DatabaseField> record)
INTERNAL:
This method is used to store the FK fields that can be cached that correspond to noncacheable mappings
the FK field values will be used to re-issue the query when cloning the shared cache entity

java.lang.Object

createMapComponentFromJoinedRow(org.eclipse.persistence.internal.sessions.AbstractRecord dbRow,
org.eclipse.persistence.internal.queries.JoinedAttributeManager joinManger,
ObjectBuildingQuery query,
org.eclipse.persistence.internal.identitymaps.CacheKey parentCacheKey,
org.eclipse.persistence.internal.sessions.AbstractSession session,
boolean isTargetProtected)
INTERNAL
Called when a DatabaseMapping is used to map the key in a collection and a join query is executed.

java.lang.Object

createMapComponentFromRow(org.eclipse.persistence.internal.sessions.AbstractRecord dbRow,
ObjectBuildingQuery query,
org.eclipse.persistence.internal.identitymaps.CacheKey parentCacheKey,
org.eclipse.persistence.internal.sessions.AbstractSession session,
boolean isTargetProtected)
INTERNAL
Called when a DatabaseMapping is used to map the key in a collection.

java.lang.Object

createMapComponentFromSerializableKeyInfo(java.lang.Object keyInfo,
org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL:
Create an instance of the Key object from the key information extracted from the map.

createSerializableMapKeyInfo(java.lang.Object key,
org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL:
Creates the Array of simple types used to recreate this map.

void

deleteMapKey(java.lang.Object objectDeleted,
org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL:
For mappings used as MapKeys in MappedKeyContainerPolicy, Delete the passed object if necessary.

void

dontAllowNull()
PUBLIC:
If all the fields in the database row for the aggregate object are NULL,
then, by default, the mapping will place a null in the appropriate source object
(as opposed to an aggregate object filled with nulls).

java.util.Map

extractIdentityFieldsForQuery(java.lang.Object object,
org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL:
Extract the fields for the Map key from the object to use in a query.

getNestedJoinQuery(org.eclipse.persistence.internal.queries.JoinedAttributeManager joinManager,
ObjectLevelReadQuery query,
org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL:
Return the query that is used when this mapping is part of a joined relationship
This method is used when this mapping is used to map the key in a Map

isLockableMapping()
INTERNAL:
Return whether this mapping should be traversed when we are locking

boolean

isNullAllowed()
PUBLIC:
Return if all the fields in the database row for the aggregate object are NULL,
then, by default, the mapping will place a null in the appropriate source object
(as opposed to an aggregate object filled with nulls).

iterateOnMapKey(org.eclipse.persistence.internal.descriptors.DescriptorIterator iterator,
java.lang.Object element)
INTERNAL:
Called when iterating through descriptors to handle iteration on this mapping when it is used as a MapKey

void

postInitialize(org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL:
For an aggregate mapping the reference descriptor is cloned.

void

postInitializeMapKey(org.eclipse.persistence.internal.queries.MappedKeyMapContainerPolicy policy)
INTERNAL:
Making any mapping changes necessary to use a the mapping as a map key after initializing the mapping.

void

preinitializeMapKey(org.eclipse.persistence.internal.helper.DatabaseTable table)
INTERNAL:
Making any mapping changes necessary to use a the mapping as a map key prior to initializing the mapping

setAggregateToSourceFields(java.util.Map<java.lang.String,org.eclipse.persistence.internal.helper.DatabaseField> aggregateToSource)
INTERNAL:
Set the hashtable that stores target field name to the source field name.

setIsNullAllowed(boolean isNullAllowed)
PUBLIC:
Configure if all the fields in the database row for the aggregate object are NULL,
then, by default, the mapping will place a null in the appropriate source object
(as opposed to an aggregate object filled with nulls).

void

setTableForAggregateMappingKey(org.eclipse.persistence.internal.helper.DatabaseTable table)
INTERNAL:
If this mapping is used as the key of a CollectionTableMapMapping, the table used by this
mapping will be the relation table.

protected void

translateField(org.eclipse.persistence.internal.helper.DatabaseField sourceField,
org.eclipse.persistence.internal.helper.DatabaseField mappingField,
ClassDescriptor clonedDescriptor)
INTERNAL:
Apply the field translation from the sourceField to the mappingField.

protected void

translateFields(ClassDescriptor clonedDescriptor,
org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL:
If field names are different in the source and aggregate objects then the translation
is done here.

valueFromObject(java.lang.Object object,
org.eclipse.persistence.internal.helper.DatabaseField field,
org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL:
Extract value of the field from the object

writeFromAttributeIntoRow(java.lang.Object attribute,
org.eclipse.persistence.internal.sessions.AbstractRecord row,
org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL:
A subclass should implement this method if it wants different behavior.

void

writeFromObjectIntoRow(java.lang.Object object,
org.eclipse.persistence.internal.sessions.AbstractRecord databaseRow,
org.eclipse.persistence.internal.sessions.AbstractSession session,
DatabaseMapping.WriteType writeType)
INTERNAL:
Get the attribute value from the object and add the appropriate
values to the specified database row.

isNullAllowed

protected boolean isNullAllowed

If all the fields in the database row for the aggregate object are NULL,
then, by default, the mapping will place a null in the appropriate source object
(as opposed to an aggregate object filled with nulls).
To change this behavior, set the value of this variable to false. Then the mapping
will build a new instance of the aggregate object that is filled with nulls
and place it in the source object.

nestedFieldTranslations

Map of nested attributes that need to apply an override name to their
a nested aggregate mapping's database field. Aggregate to source fields
map is the existing EclipseLink functionality and works well when all
embeddable mappings have unique database fields. This map adds specific
attribute to database field override.

addNestedFieldTranslation

INTERNAL:
Add a nested field translation that maps from a field in the source table
to a field name in a nested aggregate descriptor. These are handled
slightly different that regular field translations in that they are
unique based on the attribute name. It solves the case where multiple
nested embeddables have mappings to similarly named default columns.

addOverrideManyToManyMapping

INTERNAL:
In JPA users may specify overrides to apply to a many to many mapping
on a shared embeddable descriptor. These settings are applied at
initialize time, after the reference descriptor is cloned.

addOverrideUnidirectionalOneToManyMapping

INTERNAL:
In JPA users may specify overrides to apply to a unidirectional one to
many mapping on a shared embeddable descriptor. These settings are
applied at initialize time, after the reference descriptor is cloned.

addKeyToDeletedObjectsList

INTERNAL:
For mappings used as MapKeys in MappedKeyContainerPolicy. Add the target of this mapping to the deleted
objects list if necessary
This method is used for removal of private owned relationships.
AggregateObjectMappings are dealt with in their parent delete, so this is a no-op.

allAggregateFieldsAreNull

INTERNAL:
Return whether all the aggregate fields in the specified
row are NULL.

allowNull

public void allowNull()

PUBLIC:
If all the fields in the database row for the aggregate object are NULL,
then, by default, the mapping will place a null in the appropriate source object
(as opposed to an aggregate object filled with nulls). This behavior can be
explicitly set by calling #allowNull().
To change this behavior, call #dontAllowNull(). Then the mapping
will build a new instance of the aggregate object that is filled with nulls
and place it in the source object.
In either situation, when writing, the mapping will place a NULL in all the
fields in the database row for the aggregate object.
Note: Any aggregate that has a relationship mapping automatically does not allow
null.

INTERNAL:
Build and return an aggregate object from the specified row.
If a null value is allowed and all the appropriate fields in the row are NULL, return a null.
If an aggregate is referenced by the target object, return it (maintain identity)
Otherwise, simply create a new aggregate object and return it.

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.

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

clone

public java.lang.Object clone()

INTERNAL:
Clone the aggregate to source field names. AggregateCollectionMapping
needs each nested embedded mapping to have its own list of aggregate
to source field names so that it can apply nested override names to
shared aggregate object mappings.

collectQueryParameters

INTERNAL:
This method is used to store the FK fields that can be cached that correspond to noncacheable mappings
the FK field values will be used to re-issue the query when cloning the shared cache entity

createMapComponentFromSerializableKeyInfo

INTERNAL:
Create an instance of the Key object from the key information extracted from the map.
This may return the value directly in case of a simple key or will be used as the FK to load a related entity.

deleteMapKey

INTERNAL:
For mappings used as MapKeys in MappedKeyContainerPolicy, Delete the passed object if necessary.
This method is used for removal of private owned relationships.
AggregateObjectMappings are dealt with in their parent delete, so this is a no-op.

dontAllowNull

public void dontAllowNull()

PUBLIC:
If all the fields in the database row for the aggregate object are NULL,
then, by default, the mapping will place a null in the appropriate source object
(as opposed to an aggregate object filled with nulls). This behavior can be
explicitly set by calling #allowNull().
To change this behavior, call #dontAllowNull(). Then the mapping
will build a new instance of the aggregate object that is filled with nulls
and place it in the source object.
In either situation, when writing, the mapping will place a NULL in all the
fields in the database row for the aggregate object.
Note: Any aggregate that has a relationship mapping automatically does not allow
null.

getAdditionalSelectionCriteriaForMapKey

INTERNAL:
Return the selection criteria necessary to select the target object when this mapping
is a map key.
AggregateObjectMappings do not need any additional selection criteria when they are map keys

getIdentityFieldsForMapKey

public java.util.List<org.eclipse.persistence.internal.helper.DatabaseField> getIdentityFieldsForMapKey()

INTERNAL:
Return the fields that make up the identity of the mapped object. For mappings with
a primary key, it will be the set of fields in the primary key. For mappings without
a primary key it will likely be all the fields

initialize

INTERNAL:
For an aggregate mapping the reference descriptor is cloned. The cloned descriptor is then
assigned primary keys and table names before initialize. Once the cloned descriptor is initialized
it is assigned as reference descriptor in the aggregate mapping. This is a very specific
behavior for aggregate mappings. The original descriptor is used only for creating clones and
after that the aggregate mapping never uses it.
Some initialization is done in postInitialize to ensure the target descriptor's references are initialized.

initializeChildInheritance

INTERNAL:
For an aggregate mapping the reference descriptor is cloned.
If the reference descriptor is involved in an inheritance tree,
all the parent and child descriptors are cloned also.
The cloned descriptors are then assigned primary keys and
table names before initialize.
This is a very specific behavior for aggregate mappings.

initializeParentInheritance

INTERNAL:
For an aggregate mapping the reference descriptor is cloned.
If the reference descriptor is involved in an inheritance tree,
all the parent and child descriptors are cloned also.
The cloned descriptors are then assigned primary keys and
table names before initialize.
This is a very specific behavior for aggregate mappings.

isCascadedLockingSupported

isNullAllowed

public boolean isNullAllowed()

PUBLIC:
Return if all the fields in the database row for the aggregate object are NULL,
then, by default, the mapping will place a null in the appropriate source object
(as opposed to an aggregate object filled with nulls).
To change this behavior, set the value of this variable to false. Then the mapping
will build a new instance of the aggregate object that is filled with nulls
and place it in the source object.
Note: Any aggregate that has a relationship mapping automatically does not allow
null.

postInitialize

INTERNAL:
For an aggregate mapping the reference descriptor is cloned. The cloned descriptor is then
assigned primary keys and table names before initialize. Once the cloned descriptor is initialized
it is assigned as reference descriptor in the aggregate mapping. This is a very specific
behavior for aggregate mappings. The original descriptor is used only for creating clones and
after that the aggregate mapping never uses it.
Some initialization is done in postInitialize to ensure the target descriptor's references are initialized.

INTERNAL:
Build an aggregate object from the specified return row and put it
in the specified target object.
Return row is merged into object after execution of insert or update call
according to ReturningPolicy.

requiresDataModificationEventsForMapKey

public boolean requiresDataModificationEventsForMapKey()

INTERNAL:
Return whether this mapping requires extra queries to update the rows if it is
used as a key in a map. This will typically be true if there are any parts to this mapping
that are not read-only.

setAggregateToSourceFields

INTERNAL:
Set the hashtable that stores target field name to the source field name.

setIsNullAllowed

public void setIsNullAllowed(boolean isNullAllowed)

PUBLIC:
Configure if all the fields in the database row for the aggregate object are NULL,
then, by default, the mapping will place a null in the appropriate source object
(as opposed to an aggregate object filled with nulls).
To change this behavior, set the value of this variable to false. Then the mapping
will build a new instance of the aggregate object that is filled with nulls
and place it in the source object.
Note: Any aggregate that has a relationship mapping automatically does not allow
null.

translateFields

INTERNAL:
If field names are different in the source and aggregate objects then the translation
is done here. The aggregate field name is converted to source field name from the
field name mappings stored.

addPrimaryKeyJoinField

INTERNAL:
Add a primary key join column (secondary field).
If this contain primary keys and the descriptor(or its subclass) has multiple tables
(secondary tables or joined inheritance strategy), this should also know the primary key
join columns to handle some cases properly.