oracle.toplink.mappings
Class CollectionMapping

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

All Implemented Interfaces:

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

Direct Known Subclasses:

AggregateCollectionMapping, DirectCollectionMapping, EISOneToManyMapping, 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

Field Summary

Fields inherited from class oracle.toplink.mappings.ForeignReferenceMapping

INNER_JOIN, NONE, OUTER_JOIN

Constructor Summary

CollectionMapping()
Default constructor.

Method Summary

void	addAggregateOrderBy(java.lang.String aggregateName, java.lang.String queryKeyName, boolean isDescending) Provide order support for queryKeyName in ascending order.
void	addAscendingOrdering(java.lang.String queryKeyName) Provide order support for queryKeyName in ascending order
void	addDescendingOrdering(java.lang.String queryKeyName) Provide order support for queryKeyName in descending order.
void	addOrderBy(java.lang.String queryKeyName, boolean isDescending) Provide order support for queryKeyName in descending or ascending order.
java.lang.Object	getRealCollectionAttributeValueFromObject(java.lang.Object object, oracle.toplink.internal.sessions.AbstractSession session) Convenience method.
void	setContainerPolicy(oracle.toplink.internal.queryframework.ContainerPolicy containerPolicy) ADVANCED: Configure the mapping to use a container policy.
void	setCustomDeleteAllQuery(ModifyQuery query) The default delete all query for mapping can be overridden by specifying the new query.
void	setDeleteAllCall(Call call) Set the receiver's delete all call.
void	setDeleteAllSQLString(java.lang.String sqlString) Set the receiver's delete all SQL string.
void	setSessionName(java.lang.String name) 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.internal.sessions.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(java.lang.Object referenceKey, java.lang.Object changeSetToRemove, oracle.toplink.internal.sessions.ObjectChangeSet changeSet, oracle.toplink.internal.sessions.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	useCollectionClass(java.lang.Class concreteClass) Configure the mapping to use an instance of the specified container class to hold the target objects.
void	useMapClass(java.lang.Class concreteClass) 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 keyName) 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) Configure the mapping to use an instance of the specified container class to hold the target objects.
void	useTransparentCollection() If transparent indirection is used, a special collection will be placed in the source object's attribute.
void	useTransparentList() If transparent indirection is used, a special collection will be placed in the source object's attribute.
void	useTransparentMap(java.lang.String methodName) If transparent indirection is used, a special map will be placed in the source object's attribute.
void	useTransparentSet() If transparent indirection is used, a special collection will be placed in the source object's attribute.

Methods inherited from class oracle.toplink.mappings.ForeignReferenceMapping

dontUseBatchReading, dontUseIndirection, getJoinFetch, getReferenceClass, getRelationshipPartnerAttributeName, isCascadeMerge, isCascadePersist, isCascadeRefresh, isCascadeRemove, isInnerJoinFetched, isJoinFetched, isOuterJoinFetched, isPrivateOwned, privateOwnedRelationship, setCascadeAll, setCascadeMerge, setCascadePersist, setCascadeRefresh, setCascadeRemove, setCustomSelectionQuery, setIndirectionPolicy, setIsPrivateOwned, setJoinFetch, setReferenceClass, setRelationshipPartnerAttributeName, setSelectionCall, setSelectionCriteria, setSelectionSQLString, setUsesBatchReading, setUsesIndirection, shouldUseBatchReading, useBasicIndirection, useBatchReading, useContainerIndirection, useInnerJoinFetch, useOuterJoinFetch, usesIndirection

Methods inherited from class oracle.toplink.mappings.DatabaseMapping

getAttributeAccessor, getAttributeClassification, getAttributeName, getGetMethodName, getProperty, getSetMethodName, isLazy, isOptional, isUsingMethodAccess, readOnly, readWrite, setAttributeAccessor, setAttributeName, setGetMethodName, setIsLazy, setIsOptional, setIsReadOnly, setProperty, setSetMethodName, setWeight

Methods inherited from class java.lang.Object

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

Constructor Detail

CollectionMapping

public CollectionMapping()

Default constructor.

Method Detail

addAscendingOrdering

public void addAscendingOrdering(java.lang.String queryKeyName)

Provide order support for queryKeyName in ascending order

addDescendingOrdering

public void addDescendingOrdering(java.lang.String queryKeyName)

Provide order support for queryKeyName in descending order.

addOrderBy

public void addOrderBy(java.lang.String queryKeyName,
                       boolean isDescending)

Provide order support for queryKeyName in descending or ascending order. Called from the EJBAnnotationsProcessor when an @OrderBy is found.

addAggregateOrderBy

public void addAggregateOrderBy(java.lang.String aggregateName,
                                java.lang.String queryKeyName,
                                boolean isDescending)

Provide order support for queryKeyName in ascending order. Called from the EJBAnnotationsProcessor when an @OrderBy on an aggregate is found.

getRealCollectionAttributeValueFromObject

public java.lang.Object getRealCollectionAttributeValueFromObject(java.lang.Object object,
                                                                  oracle.toplink.internal.sessions.AbstractSession 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)

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 of all the rows from join table for M-M, or optimized delete all of target objects for 1-M.

setDeleteAllSQLString

public void setDeleteAllSQLString(java.lang.String sqlString)

Set the receiver's delete all 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 of all the rows 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'.

setDeleteAllCall

public void setDeleteAllCall(Call call)

Set the receiver's delete all call. 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. This call is responsible for doing the deletion required by the mapping, such as deletion of all the rows from join table for M-M, or optimized delete all of target objects for 1-M. Example, 'new SQLCall("delete from PROJ_EMP where EMP_ID = #EMP_ID")'.

setSessionName

public void setSessionName(java.lang.String name)

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.internal.sessions.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 DatabaseMapping

simpleRemoveFromCollectionChangeRecord

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

useCollectionClass

public void useCollectionClass(java.lang.Class concreteClass)

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)

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

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

useMapClass

public void useMapClass(java.lang.Class concreteClass)

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 an instance of the composite primary key class.

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

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

useTransparentCollection

public void useTransparentCollection()

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.

useTransparentSet

public void useTransparentSet()

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 Set to ValueHolderInterface.

useTransparentList

public void useTransparentList()

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 List to ValueHolderInterface.

useTransparentMap

public void useTransparentMap(java.lang.String methodName)

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.