Module org.eclipse.persistence.core
Package org.eclipse.persistence.oxm

Class XMLField

java.lang.Object
org.eclipse.persistence.internal.helper.DatabaseField
org.eclipse.persistence.oxm.XMLField
All Implemented Interfaces:
Serializable, 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 statements
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:

  • Field Details

    • userXMLTypes

      protected HashMap userXMLTypes

    • userJavaTypes

      protected HashMap userJavaTypes

    • isTypedTextField

      protected boolean isTypedTextField

    • leafElementType

      protected QName leafElementType

  • Constructor Details

    • XMLField

      public XMLField()
      Default constructor, create a new XMLField

    • XMLField

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

  • Method Details

    • initialize

      public void initialize()
      Specified by:
      initialize in interface Field<XMLConversionManager,NamespaceResolver>

    • getXPath

      public 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(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

    • getNamespaceResolver

      public NamespaceResolver getNamespaceResolver()
      Get the NamespaceResolver associated with this XMLField
      Specified by:
      getNamespaceResolver in interface Field<XMLConversionManager,NamespaceResolver>
      Returns:
      The NamespaceResolver associated with this XMLField
      See Also:

    • setNamespaceResolver

      public void setNamespaceResolver(NamespaceResolver newNamespaceResolver)
      Set the NamespaceResolver associated with this XMLField
      Specified by:
      setNamespaceResolver in interface Field<XMLConversionManager,NamespaceResolver>
      Parameters:
      newNamespaceResolver - The namespaceResolver to be associated with this XMLField
      See Also:

    • 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(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

    • getSchemaType

      public QName getSchemaType()
      Return the schema type associated with this field
      Specified by:
      getSchemaType in interface Field<XMLConversionManager,NamespaceResolver>
      Returns:
      the schema type

    • 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

    • isSelfField

      public boolean isSelfField()
      INTERNAL: Indicates if the xpath for this field is "."
      Specified by:
      isSelfField in interface Field<XMLConversionManager,NamespaceResolver>
      Returns:
      true if the xpath is ".", false otherwise

    • isUnionField

      public boolean isUnionField()
      INTERNAL: Returns false since this is a union field The subclass XMLUnionField returns true for this
      Specified by:
      isUnionField in interface Field<XMLConversionManager,NamespaceResolver>

    • setName

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

    • setName

      public void setName(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

    • getXPathFragment

      public XPathFragment getXPathFragment()
      INTERNAL: Maintain a direct pointer to the first XPathFragment. For example given the following XPath first/middle/@last, first is the first XPathFragment.
      Specified by:
      getXPathFragment in interface Field<XMLConversionManager,NamespaceResolver>

    • setXPathFragment

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

    • getLastXPathFragment

      public XPathFragment getLastXPathFragment()
      INTERNAL: Return the last XPathFragment.
      Specified by:
      getLastXPathFragment in interface Field<XMLConversionManager,NamespaceResolver>

    • 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 Class<?> getJavaClass(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 Class<?> getJavaClass(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 QName getXMLType(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 QName getXMLType(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 ArrayList getUserXMLTypesForDeploymentXML()
      INTERNAL:

    • setUserXMLTypesForDeploymentXML

      public void setUserXMLTypesForDeploymentXML(ArrayList pairs) throws Exception
      INTERNAL:
      Throws:
      Exception

    • getUserJavaTypesForDeploymentXML

      public ArrayList getUserJavaTypesForDeploymentXML()
      INTERNAL:

    • setUserJavaTypesForDeploymentXML

      public void setUserJavaTypesForDeploymentXML(ArrayList pairs) throws Exception
      INTERNAL:
      Throws:
      Exception

    • convertValueBasedOnSchemaType

      public Object convertValueBasedOnSchemaType(Object value, XMLConversionManager xmlConversionManager, AbstractUnmarshalRecord record)
      INTERNAL: Called from DOMRecord and XMLReader. MappingNodeValues call XMLReader which calls this method so that other XMLReader subclasses can override.
      Specified by:
      convertValueBasedOnSchemaType in interface Field<XMLConversionManager,NamespaceResolver>

    • addXMLConversion

      public void addXMLConversion(QName qname, 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(Class<?> javaClass, 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(QName qname, 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

    • removeXMLConversion

      public void removeXMLConversion(QName qname)
      Remove an XML to Java Conversion entry

    • removeJavaConversion

      public void removeJavaConversion(Class<?> javaClass)
      Remove a Java to XML Conversion entry

    • removeConversion

      public void removeConversion(QName qname, Class<?> javaClass)
      Remove both a Java to XML Conversion and the corresponding XML to Java Conversion entry

    • setLeafElementType

      public void setLeafElementType(QName type)
      Assumes type is in the format prefix:localPart, or localPart.

    • getLeafElementType

      public QName getLeafElementType()
      Specified by:
      getLeafElementType in interface Field<XMLConversionManager,NamespaceResolver>

    • hasLastXPathFragment

      public boolean hasLastXPathFragment()
      INTERNAL:
      Specified by:
      hasLastXPathFragment in interface Field<XMLConversionManager,NamespaceResolver>

    • getSchemaTypeForValue

      public QName getSchemaTypeForValue(Object value, CoreAbstractSession session)
      INTERNAL:
      Specified by:
      getSchemaTypeForValue in interface Field<XMLConversionManager,NamespaceResolver>

    • setIsCDATA

      public void setIsCDATA(boolean CDATA)
      INTERNAL:
      Specified by:
      setIsCDATA in interface Field<XMLConversionManager,NamespaceResolver>

    • isCDATA

      public boolean isCDATA()
      INTERNAL:
      Specified by:
      isCDATA in interface Field<XMLConversionManager,NamespaceResolver>

    • isSchemaType

      public boolean isSchemaType(QName schemaType)
      INTERNAL
      Specified by:
      isSchemaType in interface Field<XMLConversionManager,NamespaceResolver>

    • isRequired

      public boolean isRequired()
      Indicates if 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:
      isRequired in interface Field<XMLConversionManager,NamespaceResolver>
      See Also:

    • 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:

    • equals

      public boolean equals(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

    • setNestedArray

      public void setNestedArray(boolean nestedArray)
      Set nested array flag. Used in JSON marshalling.
      Specified by:
      setNestedArray in interface Field<XMLConversionManager,NamespaceResolver>
      Parameters:
      nestedArray - flag.

    • isNestedArray

      public boolean isNestedArray()
      INTERNAL:
      Specified by:
      isNestedArray in interface Field<XMLConversionManager,NamespaceResolver>
      Returns:
      True if content is nested array.

    • 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