Top Description Fields Constructors Methods
org.eclipse.persistence.oxm

public Class XMLField

extends DatabaseField
implements Field<XMLConversionManager, NamespaceResolver>
Class Inheritance
All Implemented Interfaces
org.eclipse.persistence.internal.oxm.mappings.Field, org.eclipse.persistence.internal.core.helper.CoreField
Known Direct Subclasses
org.eclipse.persistence.oxm.XMLUnionField
Imports
java.util.ArrayList, .HashMap, .Iterator, .Map, .StringTokenizer, javax.xml.datatype.XMLGregorianCalendar, javax.xml.namespace.QName, org.eclipse.persistence.exceptions.XMLMarshalException, org.eclipse.persistence.internal.core.helper.CoreClassConstants, org.eclipse.persistence.internal.core.sessions.CoreAbstractSession, org.eclipse.persistence.internal.helper.DatabaseField, .DatabaseTable, org.eclipse.persistence.internal.oxm.ConversionManager, .XMLConversionManager, .XMLConversionPair, .XPathFragment, .XPathPredicate, org.eclipse.persistence.internal.oxm.mappings.Field, org.eclipse.persistence.internal.oxm.record.AbstractUnmarshalRecord
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
org.eclipse.persistence.oxm.XMLUnionField

Field Summary

Modifier and TypeField and Description
private boolean
isCDATA

private boolean
isInitialized

private boolean
isRequired

protected boolean
isTypedTextField

private XPathFragment<XML_FIELD extends Field>
lastXPathFragment

protected QName
leafElementType

private NamespaceResolver
namespaceResolver

private boolean
nestedArray

private QName
schemaType

protected HashMap<K, V>
userJavaTypes

protected HashMap<K, V>
userXMLTypes

private boolean
usesSingleNode

Makes this maintain the collection of items in a single attribute or element instead of having one element per item in the collection.

private XPathFragment<XML_FIELD extends Field>
xPathFragment

Inherited from org.eclipse.persistence.internal.helper.DatabaseField:
columnDefinitionindexisCreatableisInsertableisNullableisPrimaryKeyisTranslatedisUniqueisUpdatablekeepInRowlengthnamenameForComparisonsNULL_SQL_TYPEprecisionqualifiedNamescalesqlTypetabletypetypeNameuseDelimitersuseUpperCaseForComparisons

Constructor Summary

AccessConstructor and Description
public
XMLField()

Default constructor, create a new XMLField

public
XMLField(String
The xPath statement for this field
xPath)

Default constructor, create a new XMLField based on the specified xPath

Method Summary

Modifier and TypeMethod and Description
public void
addConversion(QName
The qualified name of the XML schema type
qname, Class<?> javaClass)

Add an entry for both an XML Conversion and a Java Conversion entry

public void
addJavaConversion(Class<?>
The class to add
javaClass, QName
The qualified name of the XML schema type
qname)

Add a Java to XML Conversion pair entry

public void
addXMLConversion(QName
The qualified name of the XML schema type
qname, Class<?>
The class to add
javaClass)

Add an XML to Java Conversion pair entry

private void
buildFragments(String xpathString)

public Object
convertValueBasedOnSchemaType(Object value, XMLConversionManager xmlConversionManager, AbstractUnmarshalRecord<ABSTRACT_SESSION extends CoreAbstractSession<DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, LOGIN extends CoreLogin<PLATFORM extends CorePlatform>, PLATFORM extends CorePlatform<CONVERSION_MANAGER extends CoreConversionManager>, PROJECT extends CoreProject<DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, LOGIN extends CoreLogin<PLATFORM extends CorePlatform>, SESSION extends CoreSession>, SESSION_EVENT_MANAGER extends CoreSessionEventManager<SESSION_EVENT_LISTENER extends CoreSessionEventListener>>, FIELD extends CoreField, UNMARSHALLER extends Unmarshaller<ABSTRACT_SESSION extends CoreAbstractSession<DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, LOGIN extends CoreLogin<PLATFORM extends CorePlatform>, PLATFORM extends CorePlatform<CONVERSION_MANAGER extends CoreConversionManager>, PROJECT extends CoreProject<DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, LOGIN extends CoreLogin<PLATFORM extends CorePlatform>, SESSION extends CoreSession>, SESSION_EVENT_MANAGER extends CoreSessionEventManager<SESSION_EVENT_LISTENER extends CoreSessionEventListener>>, CONTEXT extends Context<ABSTRACT_SESSION extends CoreAbstractSession<DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, LOGIN extends CoreLogin<PLATFORM extends CorePlatform>, PLATFORM extends CorePlatform<CONVERSION_MANAGER extends CoreConversionManager>, PROJECT extends CoreProject<DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, LOGIN extends CoreLogin<PLATFORM extends CorePlatform>, SESSION extends CoreSession>, SESSION_EVENT_MANAGER extends CoreSessionEventManager<SESSION_EVENT_LISTENER extends CoreSessionEventListener>>, DESCRIPTOR extends Descriptor<?, ?, ?, ?, ?, NAMESPACE_RESOLVER, ?, ?, ?, ?>, FIELD extends Field, NAMESPACE_RESOLVER extends NamespaceResolver, PROJECT extends CoreProject<DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, LOGIN extends CoreLogin<PLATFORM extends CorePlatform>, SESSION extends CoreSession>, SESSION extends CoreSession<DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, LOGIN extends CoreLogin<PLATFORM extends CorePlatform>, PLATFORM extends CorePlatform, PROJECT extends CoreProject<DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, LOGIN extends CoreLogin<PLATFORM extends CorePlatform>, SESSION extends CoreSession>, SESSION_EVENT_MANAGER extends CoreSessionEventManager>, SESSION_EVENT_LISTENER extends CoreSessionEventListener>, DESCRIPTOR extends Descriptor, ID_RESOLVER extends IDResolver, MEDIA_TYPE extends MediaType, ROOT extends Root, UNMARSHALLER_HANDLER extends UnmarshallerHandler, UNMARSHALLER_LISTENER extends Unmarshaller.Listener>> record)

Implements org.eclipse.persistence.internal.oxm.mappings.Field.convertValueBasedOnSchemaType.

INTERNAL: Called from DOMRecord and XMLReader.
public boolean
equals(Object
the reference object with which to compare.
object)

Overrides org.eclipse.persistence.internal.helper.DatabaseField.equals.

Determine whether the receiver is equal to a DatabaseField.
public Class<?>

Returns:

The class corresponding to the specified schema type, if no corresponding match found returns null
getJavaClass(QName
The qualified name of the XML Schema type to use as a key in the lookup
qname)

INTERNAL Return the class for a given qualified XML Schema type

public Class<?>

Returns:

the class for a given qualified XML Schema type.
getJavaClass(QName
The qualified name of the XML Schema type to use as a key in the lookup
qname, ConversionManager conversionManager)

Implements org.eclipse.persistence.internal.oxm.mappings.Field.getJavaClass.

INTERNAL
public XPathFragment<XML_FIELD extends Field>
getLastXPathFragment()

Implements org.eclipse.persistence.internal.oxm.mappings.Field.getLastXPathFragment.

INTERNAL: Return the last XPathFragment.
public QName
getLeafElementType()

Implements org.eclipse.persistence.internal.oxm.mappings.Field.getLeafElementType.

public NamespaceResolver

Returns:

The NamespaceResolver associated with this XMLField
getNamespaceResolver()

Implements org.eclipse.persistence.internal.oxm.mappings.Field.getNamespaceResolver.

Get the NamespaceResolver associated with this XMLField
public QName

Returns:

the schema type
getSchemaType()

Implements org.eclipse.persistence.internal.oxm.mappings.Field.getSchemaType.

Return the schema type associated with this field
public QName
getSchemaTypeForValue(Object value, CoreAbstractSession<DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, LOGIN extends CoreLogin<PLATFORM extends CorePlatform>, PLATFORM extends CorePlatform<CONVERSION_MANAGER extends CoreConversionManager>, PROJECT extends CoreProject<DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, LOGIN extends CoreLogin<PLATFORM extends CorePlatform>, SESSION extends CoreSession>, SESSION_EVENT_MANAGER extends CoreSessionEventManager<SESSION_EVENT_LISTENER extends CoreSessionEventListener>> session)

Implements org.eclipse.persistence.internal.oxm.mappings.Field.getSchemaTypeForValue.

INTERNAL:
private HashMap<K, V>

Returns:

a HashMap of Java to XML Schema type conversion pairs
getUserJavaTypes()

public ArrayList<E>
getUserJavaTypesForDeploymentXML()

INTERNAL:

private HashMap<K, V>

Returns:

a HashMap of XML Schema types to Java types conversion pairs
getUserXMLTypes()

public ArrayList<E>
getUserXMLTypesForDeploymentXML()

INTERNAL:

public QName

Returns:

QName The qualified XML Schema type, if no corresponding match found returns null
getXMLType(Class<?>
The class to use as a key in the lookup
javaClass)

Return the qualified XML Schema type for a given class

public QName

Returns:

the XML Schema type for a given class.
getXMLType(Class<?>
The class to use as a key in the lookup
javaClass, ConversionManager conversionManager)

Implements org.eclipse.persistence.internal.oxm.mappings.Field.getXMLType.

Return the qualified XML Schema type for a given class
public String

Returns:

The xpath statement associated with this XMLField
getXPath()

Implements org.eclipse.persistence.internal.oxm.mappings.Field.getXPath.

Returns the xpath statement associated with this XMLField
public XPathFragment<XML_FIELD extends Field>
getXPathFragment()

Implements org.eclipse.persistence.internal.oxm.mappings.Field.getXPathFragment.

INTERNAL: Maintain a direct pointer to the first XPathFragment.
public int
hashCode()

Overrides org.eclipse.persistence.internal.helper.DatabaseField.hashCode.

Return the hashcode of the name, because it is fairly unique.
public boolean
hasLastXPathFragment()

Implements org.eclipse.persistence.internal.oxm.mappings.Field.hasLastXPathFragment.

INTERNAL:
private boolean
hasPath(String xpathString)

public void
initialize()

Implements org.eclipse.persistence.internal.oxm.mappings.Field.initialize.

private void
initializeXPathFragment(XPathFragment<XML_FIELD extends Field> xPathFragment)

public boolean
isCDATA()

Implements org.eclipse.persistence.internal.oxm.mappings.Field.isCDATA.

INTERNAL:
public boolean

Returns:

True if content is nested array.
isNestedArray()

Implements org.eclipse.persistence.internal.oxm.mappings.Field.isNestedArray.

INTERNAL:
public boolean
isRequired()

Implements org.eclipse.persistence.internal.oxm.mappings.Field.isRequired.

Indicates if this XMLField represents a "required" XML element or attribute ([minOccurs="1"] for elements, [use="required"] for attributes).
public boolean
isSchemaType(QName schemaType)

Implements org.eclipse.persistence.internal.oxm.mappings.Field.isSchemaType.

INTERNAL
public boolean

Returns:

true if the xpath is ".", false otherwise
isSelfField()

Implements org.eclipse.persistence.internal.oxm.mappings.Field.isSelfField.

INTERNAL: Indicates if the xpath for this field is "."
public boolean

Returns:

True when we should base conversions on the "type" attribute on elements, otherwise false
isTypedTextField()

Implements org.eclipse.persistence.internal.oxm.mappings.Field.isTypedTextField.

Returns if the field is a typed text field True when we should base conversions on the "type" attribute on elements
public boolean
isUnionField()

Implements org.eclipse.persistence.internal.oxm.mappings.Field.isUnionField.

INTERNAL: Returns false since this is a union field The subclass XMLUnionField returns true for this
public void
removeConversion(QName qname, Class<?> javaClass)

Remove both a Java to XML Conversion and the corresponding XML to Java Conversion entry

public void
removeJavaConversion(Class<?> javaClass)

Remove a Java to XML Conversion entry

public void
removeXMLConversion(QName qname)

Remove an XML to Java Conversion entry

public void
setIsCDATA(boolean CDATA)

Implements org.eclipse.persistence.internal.oxm.mappings.Field.setIsCDATA.

INTERNAL:
public void
setIsTypedTextField(boolean
The boolean value specifiy if this is a typed text field
value)

Implements org.eclipse.persistence.internal.oxm.mappings.Field.setIsTypedTextField.

Set if the field is a typed text field True when we should base conversions on the "type" attribute on elements
public void
setLastXPathFragment(XPathFragment<XML_FIELD extends Field> lastXPathFragment)

INTERNAL: Maintain a direct pointer to the last XPathFragment.

public void
setLeafElementType(QName type)

Assumes type is in the format prefix:localPart, or localPart.

public void
setName(String xPath, String startDelimiter, String endDelimiter)

Overrides org.eclipse.persistence.internal.helper.DatabaseField.setName.

Override setName in superclass
public void
setName(String
The xPath associated with this XMLField
xPath)

Overrides org.eclipse.persistence.internal.helper.DatabaseField.setName.

Implements org.eclipse.persistence.internal.core.helper.CoreField.setName.

This has the same effect as calling the setXPath method
public void
setNamespaceResolver(NamespaceResolver
The namespaceResolver to be associated with this XMLField
newNamespaceResolver)

Implements org.eclipse.persistence.internal.oxm.mappings.Field.setNamespaceResolver.

Set the NamespaceResolver associated with this XMLField
public void
setNestedArray(boolean
flag.
nestedArray)

Implements org.eclipse.persistence.internal.oxm.mappings.Field.setNestedArray.

Set nested array flag.
public void
setRequired(boolean isRequired)

Implements org.eclipse.persistence.internal.oxm.mappings.Field.setRequired.

Set whether this XMLField represents a "required" XML element or attribute ([minOccurs="1"] for elements, [use="required"] for attributes).
public void
setSchemaType(QName
QName to be added to the list of schema types
value)

Implements org.eclipse.persistence.internal.oxm.mappings.Field.setSchemaType.

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
public void
setUserJavaTypesForDeploymentXML(ArrayList<E> pairs)

INTERNAL:

public void
setUserXMLTypesForDeploymentXML(ArrayList<E> pairs)

INTERNAL:

public void
setUsesSingleNode(boolean
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)

Implements org.eclipse.persistence.internal.oxm.mappings.Field.setUsesSingleNode.

PUBLIC: Sets whether the mapping uses a single node.
public void
setXPath(String
The xpath statement to be associated with this XMLField
xPath)

Implements org.eclipse.persistence.internal.oxm.mappings.Field.setXPath.

Set the xpath statment for this XMLField.
public void
setXPathFragment(XPathFragment<XML_FIELD extends Field> xPathFragment)

INTERNAL: Return the first XPathFragment.

public boolean

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.
usesSingleNode()

Implements org.eclipse.persistence.internal.oxm.mappings.Field.usesSingleNode.

PUBLIC: Checks whether the mapping uses a single node.
Inherited from org.eclipse.persistence.internal.helper.DatabaseField:
cloneconvertClassNamesToClassesequalsgetColumnDefinitiongetIndexgetLengthgetNamegetNameDelimitedgetNameForComparisonsgetPrecisiongetQualifiedNamegetQualifiedNameDelimitedgetScalegetSqlTypegetTablegetTableNamegetTypegetTypeNamegetUseUpperCaseForComparisonshasTableNameinitDDLFieldsisCreatableisInsertableisNullableisObjectRelationalDatabaseFieldisPrimaryKeyisReadOnlyisTranslatedisUniqueisUpdatablekeepInRowresetQualifiedNamesetColumnDefinitionsetCreatablesetIndexsetInsertablesetIsTranslatedsetKeepInRowsetLengthsetNamesetNameForComparisonssetNullablesetPrecisionsetPrimaryKeysetScalesetSqlTypesetTablesetTableNamesetTypesetTypeNamesetUniquesetUpdatablesetUseDelimitersshouldUseDelimiterstoStringuseUpperCaseForComparisons