org.eclipse.persistence.oxm.mappings.nullpolicy.NullPolicy Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of eclipselink Show documentation
EclipseLink build based upon Git transaction f2b9fc5
There is a newer version: 5.0.0-B03
/*
 * Copyright (c) 1998, 2020 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.nullpolicy;

import org.eclipse.persistence.internal.oxm.NullCapableValue;
import org.eclipse.persistence.internal.oxm.XPathNode;

/**
 * PUBLIC:
 * Description:
 * This null policy is the default implementation class.

 * Marshal:

 * The boolean value of the isSet() state of a node has no effect on whether a node will be written out
 * for a null value - a set is always performed unless the isSetPerformedForAbsentNode flag
 * is set to false for absent nodes.

 * Unmarshal:

 *
 * The following instance field can be set on top of the two from AbstractNullPolicy:

 * isSetPerformedForAbsentNode: 

 * 
 * 
 * Usage:

 * 
Unmarshal null direct element xsi:nil node:
 *
 * 
Code Sample

 * 
 * XMLDescriptor aDescriptor = new XMLDescriptor();

 * aDescriptor.setJavaClass(Employee.class);

 * aDescriptor.setDefaultRootElement("employee");

 * XMLDirectMapping firstNameMapping = new XMLDirectMapping();

 * firstNameMapping.setAttributeName("firstname");

 * firstNameMapping.setXPath("first-name/text()");

 * AbstractNullPolicy aNullPolicy = new NullPolicy();

 * aDescriptor.addMapping(firstNameMapping);

 * aNullPolicy.setSetPerformedForAbsentNode(false); // no effect

 * aNullPolicy.setNullRepresentedByEmptyNodeNode(false); // default or no effect

 * aNullPolicy.setNullRepresentedByXsiNil(false); // default or no effect

 * 
 * 
Input XML

 * 
 * <employee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

 *   <firstname xsi:nil=true/>

 * </employee>

 * 
 * 
Output Object State

 * 
 * anEmployee.getFirstname() = null

 * anEmployee.isSet(firstname) = true

 * 

 * 
Marshal null composite object (isSet=true) as empty node: .
 *
 * 
Code Sample

 * 
 * XMLDescriptor aDescriptor = new XMLDescriptor();

 * aDescriptor.setJavaClass(Team.class);

 * aDescriptor.setDefaultRootElement("team");

 * XMLCompositeObjectMapping aManagerMapping = new XMLCompositeObjectMapping();

 * aManagerMapping.setAttributeName("manager");

 * aManagerMapping.setXPath("manager/text()");

 * // do not modify the default NullPolicy or the 3 boolean flags

 * AbstractNullPolicy aNullPolicy = afirstNameMapping.getNullPolicy();

 * aDescriptor.addMapping(aManagerMapping);

 * aNullPolicy.setMarshalNullRepresentation(XMLNullRepresentationType.EMPTY_NODE);

 * 
 *
 * 
Input Object State

 * 
 * aTeam.getManager() = null

 * aTeam.isSet(manager) = no effect

 * 
 * Output XML

 * 
 * <team xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

 *   <manager/>

 * </team>

 * 
 *
 * @see org.eclipse.persistence.internal.oxm.NullCapableValue
 * @since Oracle TopLink 11g Release 1 (11.1.1)
 */
public class NullPolicy extends AbstractNullPolicy {
    /**
     * Default Constructor
     */
    public NullPolicy() {
        super();
    }

    /**
     * Specific Constructor to set the Unmarshal flags
     * @param anIsSetMethodName
     * @param bIsSetPerformedForAbsentNode
     * @param bIsNullRepresentedByEmptyNode
     * @param bIsNullRepresentedByXsiNil
     */
    public NullPolicy(String anIsSetMethodName, //
            boolean bIsSetPerformedForAbsentNode, boolean bIsNullRepresentedByEmptyNode, boolean bIsNullRepresentedByXsiNil) {
        this();
        setSetPerformedForAbsentNode(bIsSetPerformedForAbsentNode);
        setNullRepresentedByEmptyNode(bIsNullRepresentedByEmptyNode);
        setNullRepresentedByXsiNil(bIsNullRepresentedByXsiNil);
    }

    /**
     * Specific Constructor to set both the Marshal enum and the Unmarshal flags
     * @param anIsSetMethodName
     * @param bIsSetPerformedForAbsentNode
     * @param bIsNullRepresentedByEmptyNode
     * @param bIsNullRepresentedByXsiNil
     * @param aMarshalNullRepresentation
     */
    public NullPolicy(String anIsSetMethodName, //
            boolean bIsSetPerformedForAbsentNode, boolean bIsNullRepresentedByEmptyNode, boolean bIsNullRepresentedByXsiNil, //
            XMLNullRepresentationType aMarshalNullRepresentation) {
        this(anIsSetMethodName, bIsSetPerformedForAbsentNode, bIsNullRepresentedByEmptyNode, bIsNullRepresentedByXsiNil);
        setMarshalNullRepresentation(aMarshalNullRepresentation);
    }

    @Override
    public void xPathNode(XPathNode xPathNode, NullCapableValue nullCapableValue) {
        // No operation for non-isSet modes
    }

    /**
     * Set the isSetPerformedForAbsentNode flag
     * @param performSet
     */
    public void setSetPerformedForAbsentNode(boolean performSet) {
        isSetPerformedForAbsentNode = performSet;
    }
}