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

Show more of this group Show more artifacts with this name
Show all versions of org.eclipse.persistence.core Show documentation
EclipseLink build based upon Git transaction ecdf3c32c4
There is a newer version: 4.0.2
Show newest version
/*
 * Copyright (c) 1998, 2018 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);
    }

    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;
    }
}