Implement #687: refactor XML read/write Feature names

release-notes/VERSION

@@ -10,4 +10,6 @@ Version: 3.x (for earlier see VERSION-2.x)
 #25: `ACCEPT_EMPTY_STRING_AS_NULL_OBJECT` not honored in xml module for attributes
  (reported by Morten-Olav H)
 #540: Rename "com.fasterxml.jackson" -> "tools.jackson"
+#687: JSTEP-8: rename `FromXmlParser.Feature` as `XmlReadFeature`,
+  `ToXmlGenerator.Feature` as `XmlWriteFeature`
 - Add `XmlMapper.shared()`

src/main/java/tools/jackson/dataformat/xml/XmlFactory.java

@@ -43,13 +43,13 @@ public class XmlFactory
      * Bitfield (set of flags) of all parser features that are enabled
      * by default.
      */
-    final static int DEFAULT_XML_PARSER_FEATURE_FLAGS = FromXmlParser.Feature.collectDefaults();
+    final static int DEFAULT_XML_PARSER_FEATURE_FLAGS = XmlReadFeature.collectDefaults();
 
     /**
      * Bitfield (set of flags) of all generator features that are enabled
      * by default.
      */
-    final static int DEFAULT_XML_GENERATOR_FEATURE_FLAGS = ToXmlGenerator.Feature.collectDefaults();
+    final static int DEFAULT_XML_GENERATOR_FEATURE_FLAGS = XmlWriteFeature.collectDefaults();
 
     /*
     /**********************************************************************
@@ -301,13 +301,13 @@ public boolean canUseSchema(FormatSchema schema) {
     }
 
     @Override
-    public Class<FromXmlParser.Feature> getFormatReadFeatureType() {
-        return FromXmlParser.Feature.class;
+    public Class<XmlReadFeature> getFormatReadFeatureType() {
+        return XmlReadFeature.class;
     }
 
     @Override
-    public Class<ToXmlGenerator.Feature> getFormatWriteFeatureType() {
-        return ToXmlGenerator.Feature.class;
+    public Class<XmlWriteFeature> getFormatWriteFeatureType() {
+        return XmlWriteFeature.class;
     }
 
     @Override

src/main/java/tools/jackson/dataformat/xml/XmlFactoryBuilder.java

@@ -8,8 +8,6 @@
 import tools.jackson.core.StreamReadConstraints;
 import tools.jackson.core.StreamWriteConstraints;
 import tools.jackson.core.base.DecorableTSFactory.DecorableTSFBuilder;
-import tools.jackson.dataformat.xml.deser.FromXmlParser;
-import tools.jackson.dataformat.xml.ser.ToXmlGenerator;
 
 /**
  * {@link tools.jackson.core.TSFBuilder}
@@ -162,65 +160,65 @@ public XmlNameProcessor xmlNameProcessor() {
 
     // // // Parser features
 
-    public XmlFactoryBuilder enable(FromXmlParser.Feature f) {
+    public XmlFactoryBuilder enable(XmlReadFeature f) {
         _formatParserFeatures |= f.getMask();
         return _this();
     }
 
-    public XmlFactoryBuilder enable(FromXmlParser.Feature first, FromXmlParser.Feature... other) {
+    public XmlFactoryBuilder enable(XmlReadFeature first, XmlReadFeature... other) {
         _formatParserFeatures |= first.getMask();
-        for (FromXmlParser.Feature f : other) {
+        for (XmlReadFeature f : other) {
             _formatParserFeatures |= f.getMask();
         }
         return _this();
     }
 
-    public XmlFactoryBuilder disable(FromXmlParser.Feature f) {
+    public XmlFactoryBuilder disable(XmlReadFeature f) {
         _formatParserFeatures &= ~f.getMask();
         return _this();
     }
 
-    public XmlFactoryBuilder disable(FromXmlParser.Feature first, FromXmlParser.Feature... other) {
+    public XmlFactoryBuilder disable(XmlReadFeature first, XmlReadFeature... other) {
         _formatParserFeatures &= ~first.getMask();
-        for (FromXmlParser.Feature f : other) {
+        for (XmlReadFeature f : other) {
             _formatParserFeatures &= ~f.getMask();
         }
         return _this();
     }
 
-    public XmlFactoryBuilder configure(FromXmlParser.Feature f, boolean state) {
+    public XmlFactoryBuilder configure(XmlReadFeature f, boolean state) {
         return state ? enable(f) : disable(f);
     }
 
     // // // Generator features
 
-    public XmlFactoryBuilder enable(ToXmlGenerator.Feature f) {
+    public XmlFactoryBuilder enable(XmlWriteFeature f) {
         _formatGeneratorFeatures |= f.getMask();
         return _this();
     }
 
-    public XmlFactoryBuilder enable(ToXmlGenerator.Feature first, ToXmlGenerator.Feature... other) {
+    public XmlFactoryBuilder enable(XmlWriteFeature first, XmlWriteFeature... other) {
         _formatGeneratorFeatures |= first.getMask();
-        for (ToXmlGenerator.Feature f : other) {
+        for (XmlWriteFeature f : other) {
             _formatGeneratorFeatures |= f.getMask();
         }
         return _this();
     }
 
-    public XmlFactoryBuilder disable(ToXmlGenerator.Feature f) {
+    public XmlFactoryBuilder disable(XmlWriteFeature f) {
         _formatGeneratorFeatures &= ~f.getMask();
         return _this();
     }
 
-    public XmlFactoryBuilder disable(ToXmlGenerator.Feature first, ToXmlGenerator.Feature... other) {
+    public XmlFactoryBuilder disable(XmlWriteFeature first, XmlWriteFeature... other) {
         _formatGeneratorFeatures &= ~first.getMask();
-        for (ToXmlGenerator.Feature f : other) {
+        for (XmlWriteFeature f : other) {
             _formatGeneratorFeatures &= ~f.getMask();
         }
         return _this();
     }
 
-    public XmlFactoryBuilder configure(ToXmlGenerator.Feature f, boolean state) {
+    public XmlFactoryBuilder configure(XmlWriteFeature f, boolean state) {
         return state ? enable(f) : disable(f);
     }
 

src/main/java/tools/jackson/dataformat/xml/XmlMapper.java

@@ -181,21 +181,21 @@ public Builder activateDefaultTyping(PolymorphicTypeValidator ptv, DefaultTyping
         /******************************************************************
          */
 
-        public Builder enable(FromXmlParser.Feature... features) {
-            for (FromXmlParser.Feature f : features) {
+        public Builder enable(XmlReadFeature... features) {
+            for (XmlReadFeature f : features) {
                 _formatReadFeatures |= f.getMask();
             }
             return this;
         }
 
-        public Builder disable(FromXmlParser.Feature... features) {
-            for (FromXmlParser.Feature f : features) {
+        public Builder disable(XmlReadFeature... features) {
+            for (XmlReadFeature f : features) {
                 _formatReadFeatures &= ~f.getMask();
             }
             return this;
         }
 
-        public Builder configure(FromXmlParser.Feature feature, boolean state)
+        public Builder configure(XmlReadFeature feature, boolean state)
         {
             if (state) {
                 _formatReadFeatures |= feature.getMask();
@@ -205,21 +205,21 @@ public Builder configure(FromXmlParser.Feature feature, boolean state)
             return this;
         }
 
-        public Builder enable(ToXmlGenerator.Feature... features) {
-            for (ToXmlGenerator.Feature f : features) {
+        public Builder enable(XmlWriteFeature... features) {
+            for (XmlWriteFeature f : features) {
                 _formatWriteFeatures |= f.getMask();
             }
             return this;
         }
 
-        public Builder disable(ToXmlGenerator.Feature... features) {
-            for (ToXmlGenerator.Feature f : features) {
+        public Builder disable(XmlWriteFeature... features) {
+            for (XmlWriteFeature f : features) {
                 _formatWriteFeatures &= ~f.getMask();
             }
             return this;
         }
 
-        public Builder configure(ToXmlGenerator.Feature feature, boolean state)
+        public Builder configure(XmlWriteFeature feature, boolean state)
         {
             if (state) {
                 _formatWriteFeatures |= feature.getMask();

src/main/java/tools/jackson/dataformat/xml/XmlReadFeature.java

@@ -0,0 +1,86 @@
+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 false}.
+     */
+    AUTO_DETECT_XSI_TYPE(false),
+
+    /**
+     * 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 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),
+
+    ;
+
+    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; }
+}