Package org.eclipse.persistence.oxm.mappings

Class XMLCollectionReferenceMapping

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, org.eclipse.persistence.internal.oxm.mappings.CollectionReferenceMapping<org.eclipse.persistence.internal.sessions.AbstractSession,​AttributeAccessor,​org.eclipse.persistence.internal.queries.ContainerPolicy,​ClassDescriptor,​org.eclipse.persistence.internal.helper.DatabaseField,​org.eclipse.persistence.internal.oxm.record.UnmarshalRecord,​XMLField,​XMLRecord>, org.eclipse.persistence.internal.oxm.mappings.Mapping<org.eclipse.persistence.internal.sessions.AbstractSession,​AttributeAccessor,​org.eclipse.persistence.internal.queries.ContainerPolicy,​ClassDescriptor,​org.eclipse.persistence.internal.helper.DatabaseField,​XMLRecord>, org.eclipse.persistence.internal.oxm.mappings.ObjectReferenceMapping<org.eclipse.persistence.internal.sessions.AbstractSession,​AttributeAccessor,​org.eclipse.persistence.internal.queries.ContainerPolicy,​ClassDescriptor,​org.eclipse.persistence.internal.helper.DatabaseField,​org.eclipse.persistence.internal.oxm.record.UnmarshalRecord,​XMLField,​XMLRecord>, org.eclipse.persistence.internal.oxm.mappings.XMLContainerMapping, ContainerMapping, XMLMapping
    public class XMLCollectionReferenceMapping
extends XMLObjectReferenceMapping
implements org.eclipse.persistence.internal.oxm.mappings.CollectionReferenceMapping<org.eclipse.persistence.internal.sessions.AbstractSession,​AttributeAccessor,​org.eclipse.persistence.internal.queries.ContainerPolicy,​ClassDescriptor,​org.eclipse.persistence.internal.helper.DatabaseField,​org.eclipse.persistence.internal.oxm.record.UnmarshalRecord,​XMLField,​XMLRecord>, ContainerMapping
    TopLink OXM version of a 1-M mapping. A list of source-target key field associations is used to link the source xpaths to their related target xpaths, and hence their primary key (unique identifier) values used when (un)marshalling. It is important to note that each target xpath is assumed to be set as a primary key field on the target (reference) class descriptor - this is necessary in order to locate the correct target object instance in the session cache when resolving mapping references. The usesSingleNode flag should be set to true if the keys are to be written out in space-separated lists.
    See Also:
    XMLObjectReferenceMapping, ContainerMapping, Serialized Form

    • Field Detail

      • containerPolicy

        protected org.eclipse.persistence.internal.queries.ContainerPolicy containerPolicy

    • Constructor Detail

      • XMLCollectionReferenceMapping

        public XMLCollectionReferenceMapping()
        PUBLIC: The default constructor initializes the sourceToTargetKeyFieldAssociations and sourceToTargetKeys data structures.

    • Method Detail

      • getField

        public org.eclipse.persistence.internal.helper.DatabaseField getField()
        Description copied from class: DatabaseMapping
        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 in an Enterprise context they cannot be cast to. Mappings that have a field include direct mappings and object relational mappings.
        Specified by:
        getField in interface org.eclipse.persistence.internal.oxm.mappings.Mapping<org.eclipse.persistence.internal.sessions.AbstractSession,​AttributeAccessor,​org.eclipse.persistence.internal.queries.ContainerPolicy,​ClassDescriptor,​org.eclipse.persistence.internal.helper.DatabaseField,​XMLRecord>
        Overrides:
        getField in class DatabaseMapping

      • getXPath

        public java.lang.String getXPath()
        Get the XPath String
        Returns:
        String the XPath String associated with this Mapping

      • setXPath

        public void setXPath​(java.lang.String xpathString)
        Set the Mapping field name attribute to the given XPath String
        Parameters:
        xpathString - String

      • buildFieldValue

        public java.lang.Object buildFieldValue​(java.lang.Object targetObject,
                                        XMLField xmlFld,
                                        org.eclipse.persistence.internal.sessions.AbstractSession session)
        INTERNAL: Retrieve the target object's primary key value that is mapped to a given source xpath (in the source-target key field association list).
        Specified by:
        buildFieldValue in interface org.eclipse.persistence.internal.oxm.mappings.ObjectReferenceMapping<org.eclipse.persistence.internal.sessions.AbstractSession,​AttributeAccessor,​org.eclipse.persistence.internal.queries.ContainerPolicy,​ClassDescriptor,​org.eclipse.persistence.internal.helper.DatabaseField,​org.eclipse.persistence.internal.oxm.record.UnmarshalRecord,​XMLField,​XMLRecord>
        Overrides:
        buildFieldValue in class XMLObjectReferenceMapping
        Parameters:
        targetObject - - the reference class instance that holds the required pk value
        xmlFld -
        session -
        Returns:
        null if the target object is null, the reference class is null, or a primary key field name does not exist on the reference descriptor that matches the target field name - otherwise, return the associated primary key value

      • buildReference

        public void buildReference​(org.eclipse.persistence.internal.oxm.record.UnmarshalRecord record,
                           XMLField xmlField,
                           java.lang.Object object,
                           org.eclipse.persistence.internal.sessions.AbstractSession session,
                           java.lang.Object container)
        INTERNAL: Create (if necessary) and populate a reference object that will be used during the mapping reference resolution phase after unmarshalling is complete.
        Specified by:
        buildReference in interface org.eclipse.persistence.internal.oxm.mappings.CollectionReferenceMapping<org.eclipse.persistence.internal.sessions.AbstractSession,​AttributeAccessor,​org.eclipse.persistence.internal.queries.ContainerPolicy,​ClassDescriptor,​org.eclipse.persistence.internal.helper.DatabaseField,​org.eclipse.persistence.internal.oxm.record.UnmarshalRecord,​XMLField,​XMLRecord>

      • buildReference

        public void buildReference​(java.lang.Object srcObject,
                           XMLField xmlField,
                           java.lang.Object object,
                           org.eclipse.persistence.internal.sessions.AbstractSession session,
                           java.lang.Object container,
                           org.eclipse.persistence.internal.oxm.ReferenceResolver resolver)
        INTERNAL: Create (if necessary) and populate a reference object that will be used during the mapping reference resolution phase after unmarshalling is complete.

      • getContainerPolicy

        public org.eclipse.persistence.internal.queries.ContainerPolicy getContainerPolicy()
        INTERNAL: Return the mapping's containerPolicy.
        Specified by:
        getContainerPolicy in interface ContainerMapping
        Specified by:
        getContainerPolicy in interface org.eclipse.persistence.internal.oxm.mappings.Mapping<org.eclipse.persistence.internal.sessions.AbstractSession,​AttributeAccessor,​org.eclipse.persistence.internal.queries.ContainerPolicy,​ClassDescriptor,​org.eclipse.persistence.internal.helper.DatabaseField,​XMLRecord>
        Overrides:
        getContainerPolicy in class DatabaseMapping

      • readFromRowIntoObject

        public java.lang.Object readFromRowIntoObject​(org.eclipse.persistence.internal.sessions.AbstractRecord databaseRow,
                                              org.eclipse.persistence.internal.queries.JoinedAttributeManager joinManager,
                                              java.lang.Object targetObject,
                                              org.eclipse.persistence.internal.identitymaps.CacheKey parentCacheKey,
                                              ObjectBuildingQuery sourceQuery,
                                              org.eclipse.persistence.internal.sessions.AbstractSession executionSession,
                                              boolean isTargetProtected)
                                       throws DatabaseException
        INTERNAL: Extract the primary key values from the row, then create an org.eclipse.persistence.internal.oxm.Reference instance and stored it on the session's org.eclipse.persistence.internal.oxm.ReferenceResolver.
        Overrides:
        readFromRowIntoObject in class XMLObjectReferenceMapping
        Throws:
        DatabaseException

      • readFromRowIntoObject

        public java.lang.Object readFromRowIntoObject​(org.eclipse.persistence.internal.sessions.AbstractRecord databaseRow,
                                              org.eclipse.persistence.internal.queries.JoinedAttributeManager joinManager,
                                              java.lang.Object targetObject,
                                              org.eclipse.persistence.internal.identitymaps.CacheKey parentCacheKey,
                                              ObjectBuildingQuery sourceQuery,
                                              org.eclipse.persistence.internal.sessions.AbstractSession executionSession,
                                              boolean isTargetProtected,
                                              java.lang.Object container)
                                       throws DatabaseException
        INTERNAL: Extract the primary key values from the row, then create an org.eclipse.persistence.internal.oxm.Reference instance and stored it on the session's org.eclipse.persistence.internal.oxm.ReferenceResolver.
        Throws:
        DatabaseException

      • setContainerPolicy

        public void setContainerPolicy​(org.eclipse.persistence.internal.queries.ContainerPolicy containerPolicy)
        ADVANCED: Set the mapping's containerPolicy.
        Specified by:
        setContainerPolicy in interface ContainerMapping

      • useCollectionClass

        public void useCollectionClass​(java.lang.Class concreteContainerClass)
        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 Collection interface.

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

        Specified by:
        useCollectionClass in interface ContainerMapping

      • useCollectionClassName

        public void useCollectionClassName​(java.lang.String concreteContainerClassName)
        Description copied from interface: ContainerMapping
        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:
        useCollectionClassName in interface org.eclipse.persistence.internal.oxm.mappings.CollectionReferenceMapping<org.eclipse.persistence.internal.sessions.AbstractSession,​AttributeAccessor,​org.eclipse.persistence.internal.queries.ContainerPolicy,​ClassDescriptor,​org.eclipse.persistence.internal.helper.DatabaseField,​org.eclipse.persistence.internal.oxm.record.UnmarshalRecord,​XMLField,​XMLRecord>
        Specified by:
        useCollectionClassName in interface ContainerMapping

      • useListClassName

        public void useListClassName​(java.lang.String concreteContainerClassName)
        Description copied from interface: ContainerMapping
        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.List interface.

        Specified by:
        useListClassName in interface ContainerMapping

      • useMapClass

        public void useMapClass​(java.lang.Class concreteContainerClass,
                        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 the 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 the value to be inserted into the Map.

        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.

        The referenceClass must be set before calling this method.

        Specified by:
        useMapClass in interface ContainerMapping

      • useMapClassName

        public void useMapClassName​(java.lang.String concreteContainerClass,
                            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 the 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 the value to be inserted into the Map.

        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.

        The referenceClass must be set before calling this method.

        Specified by:
        useMapClassName in interface ContainerMapping

      • usesSingleNode

        public boolean usesSingleNode()
        INTERNAL: For the purpose of XMLCollectionReferenceMappings, 'usesSingleNode' refers to the fact that the source key xpath fields should all be written as space-separated lists. Would be used for mapping to an IDREFS field in a schema
        Specified by:
        usesSingleNode in interface org.eclipse.persistence.internal.oxm.mappings.CollectionReferenceMapping<org.eclipse.persistence.internal.sessions.AbstractSession,​AttributeAccessor,​org.eclipse.persistence.internal.queries.ContainerPolicy,​ClassDescriptor,​org.eclipse.persistence.internal.helper.DatabaseField,​org.eclipse.persistence.internal.oxm.record.UnmarshalRecord,​XMLField,​XMLRecord>

      • setUsesSingleNode

        public void setUsesSingleNode​(boolean useSingleNode)
        Specified by:
        setUsesSingleNode in interface org.eclipse.persistence.internal.oxm.mappings.CollectionReferenceMapping<org.eclipse.persistence.internal.sessions.AbstractSession,​AttributeAccessor,​org.eclipse.persistence.internal.queries.ContainerPolicy,​ClassDescriptor,​org.eclipse.persistence.internal.helper.DatabaseField,​org.eclipse.persistence.internal.oxm.record.UnmarshalRecord,​XMLField,​XMLRecord>

      • writeFromObjectIntoRow

        public void writeFromObjectIntoRow​(java.lang.Object object,
                                   org.eclipse.persistence.internal.sessions.AbstractRecord row,
                                   org.eclipse.persistence.internal.sessions.AbstractSession session,
                                   DatabaseMapping.WriteType writeType)
        INTERNAL: Write the attribute value from the object to the row.
        Overrides:
        writeFromObjectIntoRow in class XMLObjectReferenceMapping

      • writeSingleValue

        public void writeSingleValue​(java.lang.Object value,
                             java.lang.Object parent,
                             XMLRecord row,
                             org.eclipse.persistence.internal.sessions.AbstractSession session)
        Description copied from interface: XMLMapping
        INTERNAL: A method that marshals a single value to the provided Record based on this mapping's XPath. Used for Sequenced marshalling.
        Specified by:
        writeSingleValue in interface org.eclipse.persistence.internal.oxm.mappings.Mapping<org.eclipse.persistence.internal.sessions.AbstractSession,​AttributeAccessor,​org.eclipse.persistence.internal.queries.ContainerPolicy,​ClassDescriptor,​org.eclipse.persistence.internal.helper.DatabaseField,​XMLRecord>
        Specified by:
        writeSingleValue in interface XMLMapping
        Overrides:
        writeSingleValue in class XMLObjectReferenceMapping
        Parameters:
        value - - The value to be marshalled
        row - - The Record the value is being marshalled too.

      • isCollectionMapping

        public boolean isCollectionMapping()
        Description copied from class: DatabaseMapping
        INTERNAL: Related mapping should implement this method to return true.
        Specified by:
        isCollectionMapping in interface org.eclipse.persistence.internal.oxm.mappings.Mapping<org.eclipse.persistence.internal.sessions.AbstractSession,​AttributeAccessor,​org.eclipse.persistence.internal.queries.ContainerPolicy,​ClassDescriptor,​org.eclipse.persistence.internal.helper.DatabaseField,​XMLRecord>
        Overrides:
        isCollectionMapping in class DatabaseMapping

      • getReuseContainer

        public boolean getReuseContainer()
        Return true if the original container on the object should be used if present. If it is not present then the container policy will be used to create the container.
        Specified by:
        getReuseContainer in interface org.eclipse.persistence.internal.oxm.mappings.XMLContainerMapping

      • setReuseContainer

        public void setReuseContainer​(boolean reuseContainer)
        Specify whether the original container on the object should be used if present. If it is not present then the container policy will be used to create the container.
        Specified by:
        setReuseContainer in interface org.eclipse.persistence.internal.oxm.mappings.XMLContainerMapping

      • isDefaultEmptyContainer

        public boolean isDefaultEmptyContainer()
        INTERNAL Return true if an empty container should be set on the object if there is no presence of the collection in the XML document.
        Specified by:
        isDefaultEmptyContainer in interface org.eclipse.persistence.internal.oxm.mappings.XMLContainerMapping
        Since:
        EclipseLink 2.3.3

      • setDefaultEmptyContainer

        public void setDefaultEmptyContainer​(boolean defaultEmptyContainer)
        INTERNAL Indicate whether by default an empty container should be set on the field/property if the collection is not present in the XML document.
        Specified by:
        setDefaultEmptyContainer in interface org.eclipse.persistence.internal.oxm.mappings.XMLContainerMapping
        Since:
        EclipseLink 2.3.3

      • getWrapperNullPolicy

        public AbstractNullPolicy getWrapperNullPolicy()
        Specified by:
        getWrapperNullPolicy in interface org.eclipse.persistence.internal.oxm.mappings.XMLContainerMapping

      • setWrapperNullPolicy

        public void setWrapperNullPolicy​(AbstractNullPolicy policy)
        Specified by:
        setWrapperNullPolicy in interface org.eclipse.persistence.internal.oxm.mappings.XMLContainerMapping