org.eclipse.persistence.oxm.mappings.XMLDirectMapping Maven / Gradle / Ivy
Show all versions of eclipselink Show documentation
/*
* Copyright (c) 1998, 2021 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0 which is available at
* http://www.eclipse.org/legal/epl-2.0,
* or the Eclipse Distribution License v. 1.0 which is available at
* http://www.eclipse.org/org/documents/edl-v10.php.
*
* SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
*/
// Contributors:
// Oracle - initial API and implementation from Oracle TopLink
package org.eclipse.persistence.oxm.mappings;
import org.eclipse.persistence.descriptors.ClassDescriptor;
import org.eclipse.persistence.exceptions.ConversionException;
import org.eclipse.persistence.exceptions.DescriptorException;
import org.eclipse.persistence.internal.core.sessions.CoreAbstractSession;
import org.eclipse.persistence.internal.helper.DatabaseField;
import org.eclipse.persistence.internal.identitymaps.CacheKey;
import org.eclipse.persistence.internal.oxm.XMLConversionManager;
import org.eclipse.persistence.internal.oxm.mappings.DirectMapping;
import org.eclipse.persistence.internal.oxm.mappings.Field;
import org.eclipse.persistence.internal.oxm.record.AbstractMarshalRecord;
import org.eclipse.persistence.internal.oxm.record.AbstractUnmarshalRecord;
import org.eclipse.persistence.internal.queries.ContainerPolicy;
import org.eclipse.persistence.internal.queries.JoinedAttributeManager;
import org.eclipse.persistence.internal.sessions.AbstractRecord;
import org.eclipse.persistence.internal.sessions.AbstractSession;
import org.eclipse.persistence.mappings.AttributeAccessor;
import org.eclipse.persistence.mappings.converters.Converter;
import org.eclipse.persistence.mappings.foundation.AbstractDirectMapping;
import org.eclipse.persistence.oxm.XMLConstants;
import org.eclipse.persistence.oxm.XMLField;
import org.eclipse.persistence.oxm.XMLMarshaller;
import org.eclipse.persistence.oxm.XMLUnmarshaller;
import org.eclipse.persistence.oxm.mappings.converters.XMLConverter;
import org.eclipse.persistence.oxm.mappings.nullpolicy.AbstractNullPolicy;
import org.eclipse.persistence.oxm.mappings.nullpolicy.NullPolicy;
import org.eclipse.persistence.oxm.record.DOMRecord;
import org.eclipse.persistence.oxm.record.XMLRecord;
import org.eclipse.persistence.queries.ObjectBuildingQuery;
import org.eclipse.persistence.sessions.Session;
/**
* XML Direct Mappings map a Java attribute directly to XML attribute or text node.
*
*
XML Direct Mappings can be used in the following scenarios:
* - Mapping to a Text Node
* - Mapping to an Attribute
* - Mapping to a Specified Schema Type
* - Mapping to a List Field
* - Mapping to a Union Field
* - Mapping to a Union of Lists
* - Mapping to a Union of Unions
* - Mapping with a Simple Type Translator
*
*
* Setting the XPath: TopLink XML mappings make use of 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
* mapping using the setXPath method.
*
*
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
*
* XMLDirectMapping pictureMapping = new XMLDirectMapping();
* pictureMapping.setAttributeName("picture");
* pictureMapping.setXPath("picture/text()");
* XMLField pictureField = (XMLField) pictureMapping.getField();
* pictureField.setSchemaType(XMLConstants.HEX_BINARY_QNAME);
*
*
*
Mapping to a Union Field:
*
*
*
*
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="shoe-size" type="size-type"/>
* </xsd:sequence>
* </xsd:complexType>
* <xsd:simpleType name="size-type">
* <xsd:union memberTypes="xsd:decimal xsd:string"/>
* </xsd:simpleType>
* </xsd:schema>
*
*
*
Code Sample
*
* XMLDirectMapping shoeSizeMapping = new XMLDirectMapping();
* shoeSizeMapping.setAttributeName("shoeSize");
* XMLUnionField shoeSizeField = new XMLUnionField();
* shoeSizeField.setXPath("shoe-size/text()");
* shoeSizeField.addSchemaType(XMLConstants.DECIMAL_QNAME);
* shoeSizeField.addSchemaType(XMLConstants.STRING_QNAME);
* shoeSizeMapping.setField(shoeSizeField);
*
*
*
Preserving the Node Type: If the type of a node is not defined in your XML schema,
* you can configure an XML Direct Mapping to use the xsi:type attribute to provide type information.
*
*
Code Sample
*
* XMLDirectMapping numberMapping = new XMLDirectMapping();
* numberMapping.setAttributeName("number");
* numberMapping.setXPath("number/text()");
* XMLField numberField = (XMLField) numberMapping.getField();
* numberField.setIsTypedTextField(true);
*
*
*
More Information: For more information about using the XML Direct Mapping, see the
* "Understanding XML Mappings" chapter of the Oracle TopLink Developer's Guide.
*
* @since Oracle TopLink 10g Release 2 (10.1.3)
*/
public class XMLDirectMapping extends AbstractDirectMapping implements XMLMapping, DirectMapping, XMLNillableMapping {
AbstractNullPolicy nullPolicy;
public boolean isCDATA;
private boolean isWriteOnly;
private boolean isCollapsingStringValues;
private boolean isNormalizingStringValues;
private boolean isNullValueMarshalled = false;
public XMLDirectMapping() {
super();
// The default policy is NullPolicy
nullPolicy = new NullPolicy();
nullPolicy.setNullRepresentedByEmptyNode(true);
isCDATA = false;
}
/**
* Set the AbstractNullPolicy on the mapping
* The default policy is NullPolicy.
*
*/
@Override
public void setNullPolicy(AbstractNullPolicy aNullPolicy) {
nullPolicy = aNullPolicy;
}
/**
* INTERNAL:
* Get the AbstractNullPolicy from the Mapping.
* The default policy is NullPolicy.
*/
@Override
public AbstractNullPolicy getNullPolicy() {
return nullPolicy;
}
/**
* INTERNAL:
*/
@Override
public boolean isXMLMapping() {
return true;
}
/**
* Set the Mapping field name attribute to the given XPath String
* @param xpathString String
*/
@Override
public void setXPath(String xpathString) {
if ((xpathString.indexOf(XMLConstants.ATTRIBUTE) == -1) && (!xpathString.endsWith(XMLConstants.TEXT))) {
xpathString += '/' + XMLConstants.TEXT;
}
setField(new XMLField(xpathString));
}
@Override
public void initialize(AbstractSession session) throws DescriptorException {
super.initialize(session);
((XMLField)getField()).setIsCDATA(this.isCDATA());
String xpathString = ((XMLField)getField()).getXPath();
if (this.isAbstractDirectMapping() && (xpathString.indexOf(XMLConstants.ATTRIBUTE) == -1) && (!xpathString.endsWith(XMLConstants.TEXT))) {
throw DescriptorException.invalidXpathForXMLDirectMapping(this);
}
}
/**
* INTERNAL:
* Allows for subclasses to convert the attribute value.
*/
@Override
public Object getAttributeValue(Object fieldValue, AbstractSession session, AbstractUnmarshalRecord record) {
// Unmarshal DOM
// If attribute is empty string representing (null) then return the nullValue
boolean isNullRepresentedByEmptyNode = nullPolicy.isNullRepresentedByEmptyNode();
boolean isNullRepresentedByXsiNil = nullPolicy.isNullRepresentedByXsiNil();
if (isNullRepresentedByEmptyNode && XMLConstants.EMPTY_STRING.equals(fieldValue)) {
fieldValue = null;
} else if (null == fieldValue && !isNullRepresentedByEmptyNode) {
fieldValue = XMLConstants.EMPTY_STRING;
}
// PERF: Direct variable access.
Object attributeValue = fieldValue;
// If attribute is absent check the policy
if(attributeValue == XMLRecord.noEntry) {
if(!getNullPolicy().getIsSetPerformedForAbsentNode()) {
return attributeValue;
} else {
fieldValue = null;
attributeValue = null;
}
}
if (attributeValue == XMLRecord.NIL && isNullRepresentedByXsiNil) {
fieldValue = null;
attributeValue = null;
}
// Allow for user defined conversion to the object value.
if (converter != null) {
attributeValue = convertDataValueToObjectValue(attributeValue, session, (XMLUnmarshaller) record.getUnmarshaller());
} else {
// PERF: Avoid conversion check when not required.
if ((attributeValue == null) || (attributeValue.getClass() != this.attributeObjectClassification)) {
try {
attributeValue = session.getDatasourcePlatform().convertObject(attributeValue, this.attributeClassification);
} catch (ConversionException e) {
throw ConversionException.couldNotBeConverted(this, getDescriptor(), e);
}
}
}
if (attributeValue == null) {// Translate default null value, conversion may have produced null.
attributeValue = this.nullValue;
}
return attributeValue;
}
/**
* INTERNAL:
* Convert the attribute value to a field value.
* Process any converter if defined, and check for null values.
*/
@Override
public Object getFieldValue(Object attributeValue, CoreAbstractSession session, AbstractMarshalRecord record) {
// Marshal
// PERF: This method is a major performance code point,
// so has been micro optimized and uses direct variable access.
Object fieldValue = attributeValue;
if ((this.nullValue != null) && (this.nullValue.equals(fieldValue)) && !this.isNullValueMarshalled && !((XMLField)field).isRequired()) {
return null;
}
// Allow for user defined conversion to the object value.
fieldValue = convertObjectValueToDataValue(fieldValue, (AbstractSession) session, (XMLMarshaller) record.getMarshaller());
if (fieldValue != null) {
Class fieldClassification = getFieldClassification(field);
// PERF: Avoid conversion if not required.
if(fieldClassification != fieldValue.getClass()){
try {
fieldValue = session.getPlatform(descriptor.getJavaClass()).convertObject(fieldValue, fieldClassification);
} catch (ConversionException exception) {
throw ConversionException.couldNotBeConverted(this, descriptor, exception);
}
}
}
return fieldValue;
}
/**
* Get the XPath String
* @return String the XPath String associated with this Mapping
*/
@Override
public String getXPath() {
return getFieldName();
}
/**
* INTERNAL:
* Return the mapping's attribute value from the row.
* The execution session is passed for the case of building a UnitOfWork clone
* directly from a row, the session set in the query will not know which platform to use
* for converting the value. Allows the correct session to be passed in.
*/
@Override
public Object valueFromRow(AbstractRecord row, JoinedAttributeManager joinManager, ObjectBuildingQuery query, CacheKey cacheKey, AbstractSession executionSession, boolean isTargetProtected, Boolean[] wasCacheUsed) {
// PERF: Direct variable access.
boolean shouldCheckForXsiNil = getNullPolicy().isNullRepresentedByXsiNil();
return getAttributeValue(((DOMRecord)row).getIndicatingNoEntry(this.field, false, shouldCheckForXsiNil), executionSession, (XMLRecord)row);
}
/**
* INTERNAL:
* Get a value from the object and set that in the respective field of the row.
*/
@Override
public void writeFromObjectIntoRow(Object object, AbstractRecord row, AbstractSession session, WriteType writeType) {
if (isReadOnly()) {
return;
}
writeSingleValue(getAttributeValueFromObject(object), object, (XMLRecord)row, session);
}
@Override
protected void writeValueIntoRow(AbstractRecord row, DatabaseField aField, Object fieldValue) {
row.put(getField(), fieldValue);
}
@Override
public void writeSingleValue(Object value, Object parent, XMLRecord row, AbstractSession session) {
Object fieldValue = getFieldValue(value, session, row);
if(fieldValue == null && getNullPolicy() != null) {
getNullPolicy().directMarshal((Field) this.getField(), row, parent);
} else {
writeValueIntoRow(row, getField(), fieldValue);
}
}
@Override
public void setAttributeValueInObject(Object object, Object value) throws DescriptorException {
// PERF: Direct variable access.
if(isWriteOnly()) {
return;
}
try {
if(value == XMLRecord.noEntry) {
return;
}
if (value != null && value instanceof String) {
if(isCollapsingStringValues) {
value = XMLConversionManager.getDefaultXMLManager().collapseStringValue((String)value);
} else if(isNormalizingStringValues) {
value = XMLConversionManager.getDefaultXMLManager().normalizeStringValue((String)value);
}
}
this.attributeAccessor.setAttributeValueInObject(object, value);
} catch (DescriptorException exception) {
exception.setMapping(this);
throw exception;
}
}
@Override
public void setIsCDATA(boolean CDATA) {
isCDATA = CDATA;
}
@Override
public boolean isCDATA() {
return isCDATA;
}
@Override
public boolean isWriteOnly() {
return this.isWriteOnly;
}
@Override
public void setIsWriteOnly(boolean b) {
this.isWriteOnly = b;
}
@Override
public boolean isCloningRequired() {
return false;
}
@Override
public void preInitialize(AbstractSession session) throws DescriptorException {
getAttributeAccessor().setIsWriteOnly(this.isWriteOnly());
getAttributeAccessor().setIsReadOnly(this.isReadOnly());
super.preInitialize(session);
}
/**
* PUBLIC:
* Returns true if this mapping is normalizing string values on unmarshal before setting
* them in the object. Normalize replaces any CR, LF or Tab characters with a
* single space character.
*/
public boolean isNormalizingStringValues() {
return this.isNormalizingStringValues;
}
/**
* PUBLIC:
* Indicates that this mapping should normalize all string values before setting them
* in the object on unmarshal. Normalize replaces any CR, LF or Tab characters with a
* single space character.
*/
@Override
public void setNormalizingStringValues(boolean normalize) {
this.isNormalizingStringValues = normalize;
}
/**
* PUBLIC:
* Indicates that this mapping should collapse all string values before setting them
* in the object on unmarshal. Collapse removes leading and trailing whitespaces, and replaces
* any sequence of whitepsace characters with a single space.
*/
@Override
public void setCollapsingStringValues(boolean collapse) {
this.isCollapsingStringValues = collapse;
}
/**
* PUBLIC:
* Returns true if this mapping should collapse all string values before setting them
* in the object on unmarshal. Collapse removes leading and trailing whitespaces, and replaces
* any sequence of whitepsace characters with a single space.
*/
public boolean isCollapsingStringValues() {
return this.isCollapsingStringValues;
}
/**
* PUBLIC:
* Returns true if this mapping's value should be marshalled, in the case that
* it is equal to the default null value.
*/
public boolean isNullValueMarshalled() {
return this.isNullValueMarshalled;
}
/**
* PUBLIC:
* Set whether this mapping's value should be marshalled, in the case that
* it is equal to the default null value.
*/
@Override
public void setNullValueMarshalled(boolean value) {
this.isNullValueMarshalled = value;
}
/**
* INTERNAL
* @since EclipseLink 2.5.0
*/
@Override
public Object convertObjectValueToDataValue(Object value, Session session, XMLMarshaller marshaller) {
if (hasConverter()) {
if (converter instanceof XMLConverter) {
return ((XMLConverter)converter).convertObjectValueToDataValue(value, session, marshaller);
} else {
return converter.convertObjectValueToDataValue(value, session);
}
}
return value;
}
/**
* INTERNAL
* @since EclipseLink 2.5.0
*/
@Override
public Object convertDataValueToObjectValue(Object fieldValue, Session session, XMLUnmarshaller unmarshaller) {
if (hasConverter()) {
if (converter instanceof XMLConverter) {
return ((XMLConverter)converter).convertDataValueToObjectValue(fieldValue, session, unmarshaller);
} else {
return converter.convertDataValueToObjectValue(fieldValue, session);
}
}
return fieldValue;
}
}