Module tools.jackson.dataformat.xml
Package tools.jackson.dataformat.xml

Enum Class XmlReadFeature

java.lang.Object
java.lang.Enum<XmlReadFeature>
tools.jackson.dataformat.xml.XmlReadFeature
All Implemented Interfaces:
Serializable, Comparable<XmlReadFeature>, Constable, tools.jackson.core.FormatFeature, tools.jackson.core.util.JacksonFeature
public enum XmlReadFeature extends Enum<XmlReadFeature> implements tools.jackson.core.FormatFeature
Enumeration that defines all togglable features for XML parsers.

NOTE: in Jackson 2.x this was named FromXmlParser.Feature.

  • Enum Constant Details

    • AUTO_DETECT_XSI_TYPE

      public static final XmlReadFeature AUTO_DETECT_XSI_TYPE
      Feature that enables automatic conversion of incoming "xsi:type" (where "type" is the local name and "xsi" prefix is bound to URI XMLConstants.W3C_XML_SCHEMA_INSTANCE_NS_URI), into Jackson simple Property Name of "xsi:type". This is usually needed to read content written using matching ToXmlGenerator.Feature#AUTO_DETECT_XSI_TYPE feature, usually used for Polymorphic handling where it is difficult to specify proper XML Namespace for type identifier.

      Default setting is true (was false in Jackson 2.x).

    • EMPTY_ELEMENT_AS_NULL

      public static final XmlReadFeature EMPTY_ELEMENT_AS_NULL
      Feature that indicates whether empty XML elements (both empty tags like <tag /> and <tag></tag> (with no intervening cdata) are exposed as JsonToken.VALUE_NULL) or not. If they are not returned as `null` tokens, they will be returned as JsonToken.VALUE_STRING tokens with textual value of "" (empty String).

      NOTE: in Jackson 2.x, only "true" empty tags were affected, not split ones. With 3.x both cases handled uniformly.

      Default setting is false.

    • ENFORCE_ROOT_ELEMENT_NAME

      public static final XmlReadFeature ENFORCE_ROOT_ELEMENT_NAME
      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 @JsonRootName, @JacksonXmlRootElement, or the simple class name of the target type (in that priority order).

      When enabled, a mismatch between the actual root element name and the expected name will result in a 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.

      Default setting is false for backwards-compatibility.

      Since:
      3.2

    • PROCESS_XSI_NIL

      public static final XmlReadFeature PROCESS_XSI_NIL
      Feature that indicates whether XML Schema Instance attribute xsi:nil will be processed automatically -- to indicate null values -- or not. If enabled, 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.

      Default setting is true.

    • SKIP_UNKNOWN_XSI_ATTRIBUTES

      public static final XmlReadFeature SKIP_UNKNOWN_XSI_ATTRIBUTES
      Feature that controls whether XML Schema Instance (XSI) namespace attributes other than xsi:nil and xsi:type (which have their own handling via PROCESS_XSI_NIL and AUTO_DETECT_XSI_TYPE) are silently skipped during deserialization. Attributes affected include xsi:schemaLocation and xsi:noNamespaceSchemaLocation.

      When enabled, these attributes are ignored and will not cause UnrecognizedPropertyException. When disabled (default), they are exposed as regular attributes and may require matching POJO properties or DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES to be disabled.

      Default setting is false.

      Since:
      3.2

    • WRAP_ROOT_ELEMENT_NAME

      public static final XmlReadFeature WRAP_ROOT_ELEMENT_NAME
      Feature that, when enabled, exposes the XML root element as an extra outer Object wrapper whose single property is named after the root element's local name. This preserves the root name in the resulting token stream (and therefore in JsonNode, Map, etc.), which is otherwise discarded.

      Example: with this feature enabled, 

         <root><value>3</value></root>
      is exposed as token stream equivalent to 
         { "root" : { "value" : "3" } }
      instead of the default 
         { "value" : "3" }
      The wrapper is purely a token-stream-level addition; the body is exposed exactly as it would be without wrap. Roots that the parser would otherwise expose as null (xsi:nil or, with EMPTY_ELEMENT_AS_NULL enabled, empty elements) become { "root" : null }.

      Designed to pair with XmlWriteFeature.UNWRAP_ROOT_OBJECT_NODE to allow lossless round-tripping of root element name via the Tree Model (JsonNode) and Map bindings.

      Notes:

      • The wrapper key uses the root element's local name only; namespace URI is not encoded into the key (consistent with how child element names are exposed throughout this parser). The full QName of the root remains accessible via FromXmlParser.getRootElementName().
      • This feature modifies the token stream, so it affects all bindings (POJO, Map, JsonNode), not just Tree Model.

      Default setting is false for backwards-compatibility.

      Since:
      3.2

  • Method Details

    • values

      public static XmlReadFeature[] values()
      Returns an array containing the constants of this enum class, in the order they are declared.
      Returns:
      an array containing the constants of this enum class, in the order they are declared

    • valueOf

      public static XmlReadFeature valueOf(String name)
      Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum class has no constant with the specified name
      NullPointerException - if the argument is null

    • collectDefaults

      public static int collectDefaults()
      Method that calculates bit set (flags) of all features that are enabled by default.

    • enabledByDefault

      public boolean enabledByDefault()
      Specified by:
      enabledByDefault in interface tools.jackson.core.util.JacksonFeature

    • getMask

      public int getMask()
      Specified by:
      getMask in interface tools.jackson.core.util.JacksonFeature

    • enabledIn

      public boolean enabledIn(int flags)
      Specified by:
      enabledIn in interface tools.jackson.core.util.JacksonFeature