Package org.eclipse.persistence.oxm

Class XMLField

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, CoreField, Field<XMLConversionManager,​NamespaceResolver>
    Direct Known Subclasses:
    XMLUnionField
    public class XMLField
extends DatabaseField
implements Field<XMLConversionManager,​NamespaceResolver>
    TopLink XML mappings make use of XMLFields based on XPath statements to find the relevant data in an XML document. The XPath statement is relative to the context node specified in the descriptor. The XPath may contain node type, path, and positional information. The XPath is specified on the field using the setXPath method or by using the appropriate constructor.

    The following XPath statements may be used to specify the location of XML data relating to an object's name attribute:

    XPath Description
    @name The "@" character indicates that the node is an attribute.
    text() "text()" indicates that the node is a text node. In this case the name value in the text node belongs to the context node.
    full-name/text() The name information is stored in the text node of the full-name element.
    personal-info/name/text() The XPath statement may be used to specify any valid path.
    name[2]/text() The XPath statement may contain positional information. In this case the name information is stored in the text node of the second occurrence of the name element.

    Mapping to a Specific Schema Type: In most cases TopLink can determine the target format in the XML document. However, there are cases where you must specify which one of a number of possible targets TopLink should use. For example, a java.util.Calendar could be marshalled to a schema date, time, or dateTime, or a byte[] could be marshalled to a schema hexBinary or base64Binary node.

    XML Schema
    <?xml version="1.0" encoding="UTF-8"?>
    <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <xsd:element name="customer" type="customer-type"/>
      <xsd:complexType name="customer-type">
        <xsd:sequence>
          <xsd:element name="picture" type="xsd:hexBinary"/>
          <xsd:element name="resume" type="xsd:base64Binary"/>
        </xsd:sequence>
      </xsd:complexType>
    </xsd:schema>

    Code Sample
    XMLField pictureField = new XMLField("picture/text()")
    pictureField.setSchemaType(XMLConstants.HEX_BINARY_QNAME);

    Setting custom conversion pairs: By default in TopLink XML built-in schema types are associated with java classes and vice versa. These default pairs can be modified by the user using the addJavaConversion and addXMLConversion api. For example by default a java.util.Calendar is mapped to the dateTime schema type so the XML will be formated based on that type. Below are the default schema type to java type conversion pairs and the default java type to schema type conversion pairs.

    XML schema type to Java type default conversion pairs

    Schema Type Java Type
    base64Binary byte[]
    boolean boolean
    byte byte
    date java.util.Calendar
    dateTime java.util.Calendar
    decimal java.math.BigDecimal
    double double
    float float
    hexBinary byte[]
    int int
    integer java.math.BigInteger
    long long
    QName javax.xml.namespace.QName
    time java.util.Calendar
    unsignedByte short
    unsignedInt long
    unsignedShort int
    anySimpleType java.lang.String

    Java type to XML schema type default conversion pairs

    Java Type Schema Type
    byte[] hexBinary
    java.lang.Byte[] hexBinary
    java.math.BigDecimal decimal
    java.math.BigInteger integer
    boolean boolean
    java.lang.Boolean boolean
    java.lang.Byte Byte
    byte byte
    java.util.Calendar dateTime
    java.util.GregorianCalendar dateTime
    double double
    java.lang.Double double
    float float
    java.lang.Float float
    int int
    java.lang.Integer int
    long long
    java.lang.Long long
    short short
    java.lang.Short short
    javax.xml.namespace.QName QName
    java.lang.String string
    See Also:
    XMLUnionField, Serialized Form

    • Field Detail

      • userXMLTypes

        protected java.util.HashMap userXMLTypes

      • userJavaTypes

        protected java.util.HashMap userJavaTypes

      • isTypedTextField

        protected boolean isTypedTextField

      • leafElementType

        protected javax.xml.namespace.QName leafElementType

    • Constructor Detail

      • XMLField

        public XMLField()
        Default constructor, create a new XMLField

      • XMLField

        public XMLField​(java.lang.String xPath)
        Default constructor, create a new XMLField based on the specified xPath
        Parameters:
        xPath - The xPath statement for this field

    • Method Detail

      • getXPath

        public java.lang.String getXPath()
        Returns the xpath statement associated with this XMLField
        Specified by:
        getXPath in interface Field<XMLConversionManager,​NamespaceResolver>
        Returns:
        The xpath statement associated with this XMLField

      • setXPath

        public void setXPath​(java.lang.String xPath)
        Set the xpath statment for this XMLField.
        Specified by:
        setXPath in interface Field<XMLConversionManager,​NamespaceResolver>
        Parameters:
        xPath - The xpath statement to be associated with this XMLField

      • setUsesSingleNode

        public void setUsesSingleNode​(boolean usesSingleNode)
        PUBLIC: Sets whether the mapping uses a single node.
        Specified by:
        setUsesSingleNode in interface Field<XMLConversionManager,​NamespaceResolver>
        Parameters:
        usesSingleNode - True if the items in the collection are in a single node or false if each of the items in the collection is in its own node

      • usesSingleNode

        public boolean usesSingleNode()
        PUBLIC: Checks whether the mapping uses a single node.
        Specified by:
        usesSingleNode in interface Field<XMLConversionManager,​NamespaceResolver>
        Returns:
        True if the items in the collection are in a single node or false if each of the items in the collection is in its own node.

      • setSchemaType

        public void setSchemaType​(javax.xml.namespace.QName value)
        Sets the schematype associated with this XMLField This is an optional setting; when set the schema type will be used to format the XML appropriately
        Specified by:
        setSchemaType in interface Field<XMLConversionManager,​NamespaceResolver>
        Parameters:
        value - QName to be added to the list of schema types

      • isTypedTextField

        public boolean isTypedTextField()
        Returns if the field is a typed text field True when we should base conversions on the "type" attribute on elements
        Specified by:
        isTypedTextField in interface Field<XMLConversionManager,​NamespaceResolver>
        Returns:
        True when we should base conversions on the "type" attribute on elements, otherwise false

      • setIsTypedTextField

        public void setIsTypedTextField​(boolean value)
        Set if the field is a typed text field True when we should base conversions on the "type" attribute on elements
        Specified by:
        setIsTypedTextField in interface Field<XMLConversionManager,​NamespaceResolver>
        Parameters:
        value - The boolean value specifiy if this is a typed text field

      • setName

        public void setName​(java.lang.String xPath,
                    java.lang.String startDelimiter,
                    java.lang.String endDelimiter)
        Override setName in superclass
        Overrides:
        setName in class DatabaseField

      • setName

        public void setName​(java.lang.String xPath)
        This has the same effect as calling the setXPath method
        Specified by:
        setName in interface CoreField
        Overrides:
        setName in class DatabaseField
        Parameters:
        xPath - The xPath associated with this XMLField

      • setXPathFragment

        public void setXPathFragment​(XPathFragment xPathFragment)
        INTERNAL: Return the first XPathFragment.

      • setLastXPathFragment

        public void setLastXPathFragment​(XPathFragment lastXPathFragment)
        INTERNAL: Maintain a direct pointer to the last XPathFragment. For example given the following XPath first/middle/@last, @last is the last XPathFragment.

      • getJavaClass

        public java.lang.Class getJavaClass​(javax.xml.namespace.QName qname)
        INTERNAL Return the class for a given qualified XML Schema type
        Parameters:
        qname - The qualified name of the XML Schema type to use as a key in the lookup
        Returns:
        The class corresponding to the specified schema type, if no corresponding match found returns null

      • getJavaClass

        public java.lang.Class getJavaClass​(javax.xml.namespace.QName qname,
                                    ConversionManager conversionManager)
        INTERNAL
        Specified by:
        getJavaClass in interface Field<XMLConversionManager,​NamespaceResolver>
        Parameters:
        qname - The qualified name of the XML Schema type to use as a key in the lookup
        Returns:
        the class for a given qualified XML Schema type.
        Since:
        EclipseLink 2.6.0

      • getXMLType

        public javax.xml.namespace.QName getXMLType​(java.lang.Class javaClass)
        Return the qualified XML Schema type for a given class
        Parameters:
        javaClass - The class to use as a key in the lookup
        Returns:
        QName The qualified XML Schema type, if no corresponding match found returns null

      • getXMLType

        public javax.xml.namespace.QName getXMLType​(java.lang.Class javaClass,
                                            ConversionManager conversionManager)
        Description copied from interface: Field
        Return the qualified XML Schema type for a given class
        Specified by:
        getXMLType in interface Field<XMLConversionManager,​NamespaceResolver>
        Parameters:
        javaClass - The class to use as a key in the lookup
        Returns:
        the XML Schema type for a given class.
        Since:
        EclipseLink 2.6.0

      • getUserXMLTypesForDeploymentXML

        public java.util.ArrayList getUserXMLTypesForDeploymentXML()
        INTERNAL:

      • setUserXMLTypesForDeploymentXML

        public void setUserXMLTypesForDeploymentXML​(java.util.ArrayList pairs)
                                     throws java.lang.Exception
        INTERNAL:
        Throws:
        java.lang.Exception

      • getUserJavaTypesForDeploymentXML

        public java.util.ArrayList getUserJavaTypesForDeploymentXML()
        INTERNAL:

      • setUserJavaTypesForDeploymentXML

        public void setUserJavaTypesForDeploymentXML​(java.util.ArrayList pairs)
                                      throws java.lang.Exception
        INTERNAL:
        Throws:
        java.lang.Exception

      • addXMLConversion

        public void addXMLConversion​(javax.xml.namespace.QName qname,
                             java.lang.Class javaClass)
        Add an XML to Java Conversion pair entry
        Parameters:
        qname - The qualified name of the XML schema type
        javaClass - The class to add

      • addJavaConversion

        public void addJavaConversion​(java.lang.Class javaClass,
                              javax.xml.namespace.QName qname)
        Add a Java to XML Conversion pair entry
        Parameters:
        javaClass - The class to add
        qname - The qualified name of the XML schema type

      • addConversion

        public void addConversion​(javax.xml.namespace.QName qname,
                          java.lang.Class javaClass)
        Add an entry for both an XML Conversion and a Java Conversion entry
        Parameters:
        qname - The qualified name of the XML schema type
        javaClass -

      • removeXMLConversion

        public void removeXMLConversion​(javax.xml.namespace.QName qname)
        Remove an XML to Java Conversion entry
        Parameters:
        qname -

      • removeJavaConversion

        public void removeJavaConversion​(java.lang.Class javaClass)
        Remove a Java to XML Conversion entry
        Parameters:
        javaClass -

      • removeConversion

        public void removeConversion​(javax.xml.namespace.QName qname,
                             java.lang.Class javaClass)
        Remove both a Java to XML Conversion and the corresponding XML to Java Conversion entry
        Parameters:
        qname -
        javaClass -

      • setLeafElementType

        public void setLeafElementType​(javax.xml.namespace.QName type)
        Assumes type is in the format prefix:localPart, or localPart.
        Parameters:
        type -

      • setRequired

        public void setRequired​(boolean isRequired)
        Set whether this XMLField represents a "required" XML element or attribute ([minOccurs="1"] for elements, [use="required"] for attributes). NOTE: This API is used only for Schema Generation.
        Specified by:
        setRequired in interface Field<XMLConversionManager,​NamespaceResolver>
        See Also:
        SchemaModelGenerator

      • equals

        public boolean equals​(java.lang.Object object)
        Description copied from class: DatabaseField
        Determine whether the receiver is equal to a DatabaseField. Return true if the receiver and field have the same name and table. Also return true if the table of the receiver or field are unspecified, ie. have no name.
        Overrides:
        equals in class DatabaseField

      • hashCode

        public int hashCode()
        Description copied from class: DatabaseField
        Return the hashcode of the name, because it is fairly unique.
        Overrides:
        hashCode in class DatabaseField