EclipseLink 2.2.0, build 'v20110202-r8913' API Reference

org.eclipse.persistence.oxm
Class XMLField

java.lang.Object
  extended by org.eclipse.persistence.internal.helper.DatabaseField
      extended by org.eclipse.persistence.oxm.XMLField
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable
Direct Known Subclasses:
XMLUnionField

public class XMLField
extends org.eclipse.persistence.internal.helper.DatabaseField

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 Summary
protected  java.util.HashMap userJavaTypes
           
protected  java.util.HashMap userXMLTypes
           
 
Fields inherited from class org.eclipse.persistence.internal.helper.DatabaseField
columnDefinition, index, isInsertable, isNullable, isUnique, isUpdatable, length, name, NULL_SQL_TYPE, precision, qualifiedName, scale, sqlType, table, type, typeName, useDelimiters
 
Constructor Summary
XMLField()
          Default constructor, create a new XMLField
XMLField(java.lang.String xPath)
          Default constructor, create a new XMLField based on the specified xPath
 
Method Summary
 void addConversion(javax.xml.namespace.QName qname, java.lang.Class javaClass)
          Add an entry for both an XML Conversion and a Java Conversion entry
 void addJavaConversion(java.lang.Class javaClass, javax.xml.namespace.QName qname)
          Add a Java to XML Conversion pair entry
 void addXMLConversion(javax.xml.namespace.QName qname, java.lang.Class javaClass)
          Add an XML to Java Conversion pair entry
protected  javax.xml.namespace.QName buildQNameFromString(java.lang.String stringValue, XMLRecord record)
           
 java.lang.Object convertValueBasedOnSchemaType(java.lang.Object value, org.eclipse.persistence.internal.oxm.XMLConversionManager xmlConversionManager, XMLRecord record)
          INTERNAL:
 boolean equals(java.lang.Object object)
           
 java.lang.Class getJavaClass(javax.xml.namespace.QName qname)
          Return the class for a given qualified XML Schema type
 org.eclipse.persistence.internal.oxm.XPathFragment getLastXPathFragment()
          INTERNAL: Return the last XPathFragment.
 javax.xml.namespace.QName getLeafElementType()
           
 NamespaceResolver getNamespaceResolver()
          Get the NamespaceResolver associated with this XMLField
 javax.xml.namespace.QName getSchemaType()
          Return the schema type associated with this field
 java.util.ArrayList getUserJavaTypesForDeploymentXML()
          INTERNAL:
 java.util.ArrayList getUserXMLTypesForDeploymentXML()
          INTERNAL:
 javax.xml.namespace.QName getXMLType(java.lang.Class javaClass)
          Return the qualified XML Schema type for a given class
 java.lang.String getXPath()
          Returns the xpath statement associated with this XMLField
 org.eclipse.persistence.internal.oxm.XPathFragment getXPathFragment()
          INTERNAL: Maintain a direct pointer to the first XPathFragment.
 int hashCode()
           
 boolean hasLastXPathFragment()
          INTERNAL:
 void initialize()
           
 boolean isCDATA()
          INTERNAL:
 boolean isRequired()
          Indicates if this XMLField represents a "required" XML element or attribute ([minOccurs="1"] for elements, [use="required"] for attributes).
 boolean isSchemaType(javax.xml.namespace.QName schemaType)
          INTERNAL
 boolean isSelfField()
          INTERNAL: Indicates if the xpath for this field is "."
 boolean isTypedTextField()
          Returns if the field is a typed text field True when we should base conversions on the "type" attribute on elements
 boolean isUnionField()
          INTERNAL: Returns false since this is a union field The subclass XMLUnionField returns true for this
 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
 void removeJavaConversion(java.lang.Class javaClass)
          Remove a Java to XML Conversion entry
 void removeXMLConversion(javax.xml.namespace.QName qname)
          Remove an XML to Java Conversion entry
 void setIsCDATA(boolean CDATA)
          INTERNAL:
 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
 void setLastXPathFragment(org.eclipse.persistence.internal.oxm.XPathFragment lastXPathFragment)
          INTERNAL: Maintain a direct pointer to the last XPathFragment.
 void setLeafElementType(javax.xml.namespace.QName type)
          Assumes type is in the format prefix:localPart, or localPart.
 void setName(java.lang.String xPath)
          This has the same effect as calling the setXPath method
 void setName(java.lang.String xPath, java.lang.String startDelimiter, java.lang.String endDelimiter)
          Override setName in superclass
 void setNamespaceResolver(NamespaceResolver newNamespaceResolver)
          Set the NamespaceResolver associated with this XMLField
 void setRequired(boolean isRequired)
          Set whether this XMLField represents a "required" XML element or attribute ([minOccurs="1"] for elements, [use="required"] for attributes).
 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
 void setUserJavaTypesForDeploymentXML(java.util.ArrayList pairs)
          INTERNAL:
 void setUserXMLTypesForDeploymentXML(java.util.ArrayList pairs)
          INTERNAL:
 void setUsesSingleNode(boolean usesSingleNode)
          PUBLIC: Sets whether the mapping uses a single node.
 void setXPath(java.lang.String xPath)
          Set the xpath statment for this XMLField.
 void setXPathFragment(org.eclipse.persistence.internal.oxm.XPathFragment xPathFragment)
          INTERNAL: Return the first XPathFragment.
 boolean usesSingleNode()
          PUBLIC: Checks whether the mapping uses a single node.
 
Methods inherited from class org.eclipse.persistence.internal.helper.DatabaseField
clone, equals, getColumnDefinition, getIndex, getLength, getName, getNameDelimited, getNameForComparisons, getPrecision, getQualifiedName, getQualifiedNameDelimited, getScale, getSqlType, getTable, getTableName, getType, getTypeName, getUseUpperCaseForComparisons, hasTableName, initDDLFields, isInsertable, isNullable, isObjectRelationalDatabaseField, isReadOnly, isUnique, isUpdatable, resetQualifiedName, setColumnDefinition, setIndex, setInsertable, setLength, setName, setNameForComparisons, setNullable, setPrecision, setScale, setSqlType, setTable, setTableName, setType, setTypeName, setUnique, setUpdatable, setUseDelimiters, shouldUseDelimiters, toString, useUpperCaseForComparisons
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

userXMLTypes

protected java.util.HashMap userXMLTypes

userJavaTypes

protected java.util.HashMap userJavaTypes
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

initialize

public void initialize()

getXPath

public java.lang.String getXPath()
Returns the xpath statement associated with this XMLField

Returns:
The xpath statement associated with this XMLField

setXPath

public void setXPath(java.lang.String xPath)
Set the xpath statment for this XMLField.

Parameters:
xPath - The xpath statement to be associated with this XMLField

getNamespaceResolver

public NamespaceResolver getNamespaceResolver()
Get the NamespaceResolver associated with this XMLField

Returns:
The NamespaceResolver associated with this XMLField
See Also:
NamespaceResolver

setNamespaceResolver

public void setNamespaceResolver(NamespaceResolver newNamespaceResolver)
Set the NamespaceResolver associated with this XMLField

Parameters:
newNamespaceResolver - The namespaceResolver to be associated with this XMLField
See Also:
NamespaceResolver

setUsesSingleNode

public void setUsesSingleNode(boolean usesSingleNode)
PUBLIC: Sets whether the mapping uses a single node.

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.

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

Parameters:
value - QName to be added to the list of schema types

getSchemaType

public javax.xml.namespace.QName getSchemaType()
Return the schema type associated with this field

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

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

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 "."

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


setName

public void setName(java.lang.String xPath,
                    java.lang.String startDelimiter,
                    java.lang.String endDelimiter)
Override setName in superclass

Overrides:
setName in class org.eclipse.persistence.internal.helper.DatabaseField

setName

public void setName(java.lang.String xPath)
This has the same effect as calling the setXPath method

Overrides:
setName in class org.eclipse.persistence.internal.helper.DatabaseField
Parameters:
xPath - The xPath associated with this XMLField

getXPathFragment

public org.eclipse.persistence.internal.oxm.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.


setXPathFragment

public void setXPathFragment(org.eclipse.persistence.internal.oxm.XPathFragment xPathFragment)
INTERNAL: Return the first XPathFragment.


getLastXPathFragment

public org.eclipse.persistence.internal.oxm.XPathFragment getLastXPathFragment()
INTERNAL: Return the last XPathFragment.


setLastXPathFragment

public void setLastXPathFragment(org.eclipse.persistence.internal.oxm.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)
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

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

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

convertValueBasedOnSchemaType

public java.lang.Object convertValueBasedOnSchemaType(java.lang.Object value,
                                                      org.eclipse.persistence.internal.oxm.XMLConversionManager xmlConversionManager,
                                                      XMLRecord record)
INTERNAL:


buildQNameFromString

protected javax.xml.namespace.QName buildQNameFromString(java.lang.String stringValue,
                                                         XMLRecord record)

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 -

getLeafElementType

public javax.xml.namespace.QName getLeafElementType()

hasLastXPathFragment

public boolean hasLastXPathFragment()
INTERNAL:

Returns:

setIsCDATA

public void setIsCDATA(boolean CDATA)
INTERNAL:

Parameters:
CDATA -

isCDATA

public boolean isCDATA()
INTERNAL:

Returns:

isSchemaType

public boolean isSchemaType(javax.xml.namespace.QName schemaType)
INTERNAL


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.

See Also:
SchemaModelGenerator

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.

See Also:
SchemaModelGenerator

equals

public boolean equals(java.lang.Object object)
Overrides:
equals in class org.eclipse.persistence.internal.helper.DatabaseField

hashCode

public int hashCode()
Overrides:
hashCode in class org.eclipse.persistence.internal.helper.DatabaseField

EclipseLink 2.2.0, build 'v20110202-r8913' API Reference