001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.marshall;
018
019import java.util.*;
020
021/**
022 * Per-property null-coercion modes consulted by parsers when an explicit {@code null} (or absent
023 * {@link Optional}) is encountered on the wire.
024 *
025 * <p>
026 * Juneau's analog of Jackson's {@code com.fasterxml.jackson.annotation.Nulls}.  The selected mode
027 * decides what the parser does <em>at the moment of setting</em> the bean property — it does not
028 * affect serialization.
029 *
030 * <p>
031 * Precedence:
032 * <ol>
033 *    <li>Per-property {@link MarshalledProp#nulls() @MarshalledProp(nulls=…)}.
034 *    <li>Context-level default on {@link org.apache.juneau.marshall.parser.Parser.Builder#nulls(Nulls)}.
035 *    <li>{@link #LEAVE} when neither is set.
036 * </ol>
037 *
038 * <h5 class='section'>Optional contract:</h5>
039 * <p>
040 * For an {@link Optional}-typed property, {@link #EMPTY} and {@link #DEFAULT} both resolve to
041 * {@link Optional#empty()} — never a bare {@code null} inside the {@link Optional}.  The same rule
042 * applies to {@link OptionalInt}, {@link OptionalLong}, and {@link OptionalDouble}.
043 *
044 * @since 10.0.0
045 */
046public enum Nulls {
047
048   /** Sentinel meaning "no value configured" — falls through to the next-higher precedence level. */
049   NOT_SET,
050
051   /**
052    * Pass the {@code null} value through to the setter unchanged.
053    *
054    * <p>
055    * For an {@link Optional}-typed property this resolves to {@link Optional#empty()} per the shared
056    * Optional contract — never a bare {@code null} inside the {@link Optional}.
057    *
058    * <p>
059    * This is the default behavior when no policy is configured.
060    */
061   LEAVE,
062
063   /**
064    * Substitute the type's "empty" value:
065    * <ul>
066    *    <li>{@link String} → {@code ""}
067    *    <li>{@link Collection} → empty collection (preserves declared type when possible)
068    *    <li>{@link Map} → empty map
069    *    <li>Array → zero-length array of the declared element type
070    *    <li>{@link Optional} / {@link OptionalInt} / {@link OptionalLong} / {@link OptionalDouble} →
071    *       the corresponding {@code empty()} sentinel
072    *    <li>Primitive — the Java primitive default ({@code 0}, {@code false}, {@code (char)0})
073    *    <li>Other reference types — falls back to {@link #LEAVE}
074    * </ul>
075    */
076   EMPTY,
077
078   /**
079    * Substitute the bean-constructed default for this property — the value the property holds on a
080    * fresh no-arg-constructed instance of the bean.
081    *
082    * <p>
083    * The reference instance is built once per bean class (and cached on its {@code ClassMeta}).  When
084    * no reference instance can be built (no accessible no-arg ctor / constructor throws), this mode
085    * silently falls back to {@link #LEAVE}.
086    */
087   DEFAULT,
088
089   /**
090    * Do not call the setter at all.
091    *
092    * <p>
093    * Any value already present on the bean (typically the bean's own field-initializer value) is
094    * preserved.  This is useful for properties whose absence on the wire should be treated as "no
095    * change" rather than "reset to null".
096    */
097   SKIP;
098}