XmlReadFeature.java

package tools.jackson.dataformat.xml;

import javax.xml.XMLConstants;

import tools.jackson.core.FormatFeature;
import tools.jackson.core.JsonToken;

/**
 * Enumeration that defines all togglable features for XML parsers.
 *<p>
 * NOTE: in Jackson 2.x this was named {@code FromXmlParser.Feature}.
 */
public enum XmlReadFeature implements FormatFeature
{
    /**
     * Feature that enables automatic conversion of incoming "xsi:type"
     * (where "type"  is the local name and "xsi" prefix is bound to URI
     * {@link XMLConstants#W3C_XML_SCHEMA_INSTANCE_NS_URI}),
     * into Jackson simple Property Name of {@code "xsi:type"}.
     * This is usually needed to read content written using
     * matching {@code ToXmlGenerator.Feature#AUTO_DETECT_XSI_TYPE} feature,
     * usually used for Polymorphic handling where it is difficult
     * to specify proper XML Namespace for type identifier.
     *<p>
     * Default setting is {@code true} (was {@code false} in Jackson 2.x).
     */
    AUTO_DETECT_XSI_TYPE(true),

    /**
     * Feature that indicates whether empty XML elements
     * (both empty tags like {@code <tag />} and {@code <tag></tag>}
     * (with no intervening cdata)
     * are exposed as {@link JsonToken#VALUE_NULL}) or not.
     * If they are not
     * returned as `null` tokens, they will be returned as {@link JsonToken#VALUE_STRING}
     * tokens with textual value of "" (empty String).
     *<p>
     * NOTE: in Jackson 2.x, only "true" empty tags were affected, not split ones.
     * With 3.x both cases handled uniformly.
     *<p>
     * Default setting is {@code false}.
     */
    EMPTY_ELEMENT_AS_NULL(false),

    /**
     * Feature that controls whether the name of the root XML element is
     * verified against the expected root name during deserialization. The expected
     * root name is determined from {@code @JsonRootName}, {@code @JacksonXmlRootElement},
     * or the simple class name of the target type (in that priority order).
     *<p>
     * When enabled, a mismatch between the actual root element name and the expected
     * name will result in a {@link tools.jackson.databind.exc.MismatchedInputException}.
     * When disabled (the default), any root element name is accepted.
     * Note that Fully-Qualified Names (FQN) comparison is used: that is, both local name
     * and namespace URI must match.
     *<p>
     * Default setting is {@code false} for backwards-compatibility.
     *
     * @since 3.2
     */
    ENFORCE_ROOT_ELEMENT_NAME(false),

    /**
     * Feature that indicates whether XML Schema Instance attribute
     * {@code xsi:nil} will be processed automatically -- to indicate {@code null}
     * values -- or not.
     * If enabled, {@code xsi:nil} attribute on any XML element will mark such
     * elements as "null values" and any other attributes or child elements they
     * might have to be ignored. If disabled this attribute will be exposed like
     * any other attribute.
     *<p>
     * Default setting is {@code true}.
     */
    PROCESS_XSI_NIL(true),

    /**
     * Feature that controls whether XML Schema Instance (XSI) namespace attributes
     * other than {@code xsi:nil} and {@code xsi:type} (which have their own handling
     * via {@link #PROCESS_XSI_NIL} and {@link #AUTO_DETECT_XSI_TYPE}) are silently
     * skipped during deserialization. Attributes affected include {@code xsi:schemaLocation}
     * and {@code xsi:noNamespaceSchemaLocation}.
     *<p>
     * When enabled, these attributes are ignored and will not cause
     * {@code UnrecognizedPropertyException}. When disabled (default), they are
     * exposed as regular attributes and may require matching POJO properties
     * or {@code DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES} to be disabled.
     *<p>
     * Default setting is {@code false}.
     *
     * @since 3.2
     */
    SKIP_UNKNOWN_XSI_ATTRIBUTES(false),

    ;

    private final boolean _defaultState;
    private final int _mask;
    
    /**
     * Method that calculates bit set (flags) of all features that
     * are enabled by default.
     */
    public static int collectDefaults()
    {
        int flags = 0;
        for (XmlReadFeature f : values()) {
            if (f.enabledByDefault()) {
                flags |= f.getMask();
            }
        }
        return flags;
    }
    
    private XmlReadFeature(boolean defaultState) {
        _defaultState = defaultState;
        _mask = (1 << ordinal());
    }

    @Override public boolean enabledByDefault() { return _defaultState; }
    @Override public int getMask() { return _mask; }
    @Override public boolean enabledIn(int flags) { return (flags & getMask()) != 0; }
}