oracle.toplink.mappings
Class CollectionMapping

java.lang.Object
oracle.toplink.mappings.DatabaseMapping
oracle.toplink.mappings.ForeignReferenceMapping
oracle.toplink.mappings.CollectionMapping

All Implemented Interfaces:

java.lang.Cloneable, ContainerMapping, java.io.Serializable

Direct Known Subclasses:

AggregateCollectionMapping, DirectCollectionMapping, ManyToManyMapping, NestedTableMapping, OneToManyMapping, SDKObjectCollectionMapping

public abstract class CollectionMapping

extends ForeignReferenceMapping

implements ContainerMapping

Purpose: Abstract class for relationship mappings which store collection of objects

Since:

TOPLink/Java 1.0

See Also:

Serialized Form

Constructor Summary

CollectionMapping()
PUBLIC: Default constructor.

Method Summary

void	addAscendingOrdering(java.lang.String queryKeyName) PUBLIC: Provide order suppor for queryKeyName in ascending order
void	addDescendingOrdering(java.lang.String queryKeyName) PUBLIC: Provide order suppor for queryKeyName in descending order
java.lang.Object	getRealCollectionAttributeValueFromObject(java.lang.Object object, oracle.toplink.publicinterface.Session session) Convenience method.
void	setContainerPolicy(oracle.toplink.internal.queryframework.ContainerPolicy containerPolicy) ADVANCED: Configure the mapping to use a container policy.
void	setCustomDeleteAllQuery(ModifyQuery query) PUBLIC: The default delete all query for mapping can be overridden by specifying the new query.
void	setDeleteAllSQLString(java.lang.String sqlString) PUBLIC: Set the receiver's delete SQL string.
void	setSessionName(java.lang.String name) PUBLIC: Set the name of the session to execute the mapping's queries under.
void	simpleAddToCollectionChangeRecord(java.lang.Object referenceKey, java.lang.Object changeSetToAdd, oracle.toplink.internal.sessions.ObjectChangeSet changeSet, oracle.toplink.publicinterface.Session 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(java.lang.Object referenceKey, java.lang.Object changeSetToRemove, oracle.toplink.internal.sessions.ObjectChangeSet changeSet, oracle.toplink.publicinterface.Session 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	useCollectionClass(java.lang.Class concreteClass) PUBLIC: Configure the mapping to use an instance of the specified container class to hold the target objects.
void	useMapClass(java.lang.Class concreteClass, java.lang.String methodName) PUBLIC: Configure the mapping to use an instance of the specified container class to hold the target objects.
void	useSortedSetClass(java.lang.Class concreteClass, java.util.Comparator comparator) PUBLIC: Configure the mapping to use an instance of the specified container class to hold the target objects.
void	useTransparentCollection() PUBLIC: If transparent indirection is used, a special collection will be placed in the source object's attribute.
void	useTransparentMap(java.lang.String methodName) PUBLIC: If transparent indirection is used, a special map will be placed in the source object's attribute.

Methods inherited from class oracle.toplink.mappings.ForeignReferenceMapping

dontUseBatchReading, dontUseIndirection, getReferenceClass, getRelationshipPartnerAttributeName, privateOwnedRelationship, setCustomSelectionQuery, setIndirectionPolicy, setReferenceClass, setRelationshipPartnerAttributeName, setSelectionCriteria, setSelectionSQLString, setUsesBatchReading, setUsesIndirection, shouldUseBatchReading, useBasicIndirection, useBatchReading, useContainerIndirection, useIndirection, usesIndirection

Methods inherited from class oracle.toplink.mappings.DatabaseMapping

getAttributeClassification, getAttributeName, getGetMethodName, getSetMethodName, readOnly, readWrite, setAttributeName, setGetMethodName, setIsReadOnly, setSetMethodName, setWeight

Methods inherited from class java.lang.Object

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

Constructor Detail

CollectionMapping

public CollectionMapping()

PUBLIC: Default constructor.

Method Detail

addAscendingOrdering

public void addAscendingOrdering(java.lang.String queryKeyName)

PUBLIC: Provide order suppor for queryKeyName in ascending order

addDescendingOrdering

public void addDescendingOrdering(java.lang.String queryKeyName)

PUBLIC: Provide order suppor for queryKeyName in descending order

getRealCollectionAttributeValueFromObject

public java.lang.Object getRealCollectionAttributeValueFromObject(java.lang.Object object,
                                                                  oracle.toplink.publicinterface.Session session)
                                                           throws DescriptorException

Convenience method. Return the value of an attribute, unwrapping value holders if necessary. If the value is null, build a new container.

Overrides:

getRealCollectionAttributeValueFromObject in class DatabaseMapping

Throws:

DescriptorException

setContainerPolicy

public void setContainerPolicy(oracle.toplink.internal.queryframework.ContainerPolicy containerPolicy)

ADVANCED: Configure the mapping to use a container policy. The policy manages the access to the collection.

Specified by:

setContainerPolicy in interface ContainerMapping

setCustomDeleteAllQuery

public void setCustomDeleteAllQuery(ModifyQuery query)

PUBLIC: The default delete all query for mapping can be overridden by specifying the new query. This query is responsible for doing the deletion required by the mapping, such as deletion from join table for M-M, or optimized delete all of target objects for 1-M.

setDeleteAllSQLString

public void setDeleteAllSQLString(java.lang.String sqlString)

PUBLIC: Set the receiver's delete SQL string. This allows the user to override the SQL generated by TopLink, with there own SQL or procedure call. The arguments are translated from the fields of the source row, through replacing the field names marked by '#' with the values for those fields. This SQL is responsible for doing the deletion required by the mapping, such as deletion from join table for M-M, or optimized delete all of target objects for 1-M. Example, 'delete from PROJ_EMP where EMP_ID = #EMP_ID'.

setSessionName

public void setSessionName(java.lang.String name)

PUBLIC: Set the name of the session to execute the mapping's queries under. This can be used by the session broker to override the default session to be used for the target class.

simpleAddToCollectionChangeRecord

public void simpleAddToCollectionChangeRecord(java.lang.Object referenceKey,
                                              java.lang.Object changeSetToAdd,
                                              oracle.toplink.internal.sessions.ObjectChangeSet changeSet,
                                              oracle.toplink.publicinterface.Session 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 DatabaseMapping

simpleRemoveFromCollectionChangeRecord

public void simpleRemoveFromCollectionChangeRecord(java.lang.Object referenceKey,
                                                   java.lang.Object changeSetToRemove,
                                                   oracle.toplink.internal.sessions.ObjectChangeSet changeSet,
                                                   oracle.toplink.publicinterface.Session 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 DatabaseMapping

useCollectionClass

public void useCollectionClass(java.lang.Class concreteClass)

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

The container class must implement (directly or indirectly) the java.util.Collection interface.

Specified by:

useCollectionClass in interface ContainerMapping

useSortedSetClass

public void useSortedSetClass(java.lang.Class concreteClass,
                              java.util.Comparator comparator)

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

The container class must implement (directly or indirectly) the java.util.SortedSet interface.

useMapClass

public void useMapClass(java.lang.Class concreteClass,
                        java.lang.String methodName)

PUBLIC: Configure the mapping to use an instance of the specified container class to hold the target objects. The key used to index a value in the Map is the value returned by a call to the specified zero-argument method. The method must be implemented by the class (or a superclass) of any value to be inserted into the Map.

The container class must implement (directly or indirectly) the java.util.Map interface.

To facilitate resolving the method, the mapping's referenceClass must set before calling this method.

Specified by:

useMapClass in interface ContainerMapping

useTransparentCollection

public void useTransparentCollection()

PUBLIC: If transparent indirection is used, a special collection will be placed in the source object's attribute. Fetching of the contents of the collection from the database will be delayed until absolutely necessary. (Any message sent to the collection will cause the contents to be faulted in from the database.) This can result in rather significant performance gains, without having to change the source object's attribute from Collection (or List or Vector) to ValueHolderInterface.

useTransparentMap

public void useTransparentMap(java.lang.String methodName)

PUBLIC: If transparent indirection is used, a special map will be placed in the source object's attribute. Fetching of the contents of the map from the database will be delayed until absolutely necessary. (Any message sent to the map will cause the contents to be faulted in from the database.) This can result in rather significant performance gains, without having to change the source object's attribute from Map (or Dictionary or Hashtable) to ValueHolderInterface.

The key used in the Map is the value returned by a call to the zero parameter method named methodName. The method should be a zero argument method implemented (or inherited) by the value to be inserted into the Map.