Baseline work for #196, generic support for format-specific features

Author: cowtowncoder

src/main/java/com/fasterxml/jackson/core/FormatFeature.java

@@ -0,0 +1,33 @@
+package com.fasterxml.jackson.core;
+
+/**
+ * Marker interface that is to be implemented by data format - specific features.
+ * Interface used since Java Enums can not extend classes or other Enums, but
+ * they can implement interfaces; and as such we may be able to use limited
+ * amount of generic functionality.
+ *<p>
+ * Note that this type is only implemented by non-JSON formats:
+ * types {@link JsonParser.Feature} and {@link JsonGenerator.Feature} do NOT
+ * implement it. This is to make it easier to avoid ambiguity with method
+ * calls.
+ * 
+ * @since 2.6 (to be fully used in 2.7 and beyond)
+ */
+public interface FormatFeature
+{
+    /**
+     * Accessor for checking whether this feature is enabled by default.
+     */
+    public boolean enabledByDefault();
+    
+    /**
+     * Returns bit mask for this feature instance; must be a single bit,
+     * that is of form <code>(1 << N)</code>
+     */
+    public int getMask();
+
+    /**
+     * Convenience method for checking whether feature is enabled in given bitmask
+     */
+    public boolean enabledIn(int flags);
+}

src/main/java/com/fasterxml/jackson/core/JsonFactory.java

@@ -413,10 +413,31 @@ protected Object readResolve() {
      * @since 2.4
      */
     public boolean canUseCharArrays() { return true; }
-    
+
+    /**
+     * Method for accessing kind of {@link FormatFeature} that a parser
+     * {@link JsonParser} produced by this factory would accept, if any;
+     * <code>null</code> returned if none.
+     *
+     * @since 2.6
+     */
+    public Class<? extends FormatFeature> getFormatReadFeatureType() {
+        return null;
+    }
+
+    /**
+     * Method for accessing kind of {@link FormatFeature} that a parser
+     * {@link JsonGenerator} produced by this factory would accept, if any;
+     * <code>null</code> returned if none.
+     *
+     * @since 2.6
+     */
+    public Class<? extends FormatFeature> getFormatWriteFeatureType() {
+        return null;
+    }
     /*
     /**********************************************************
-    /* Format detection functionality (since 1.8)
+    /* Format detection functionality
     /**********************************************************
      */
 
@@ -454,6 +475,10 @@ public String getFormatName()
         return null;
     }
 
+    /**
+     * Convenience method for trying to determine whether input via given accessor
+     * is of format type supported by this factory.
+     */
     public MatchStrength hasFormat(InputAccessor acc) throws IOException
     {
         // since we can't keep this abstract, only implement for "vanilla" instance

src/main/java/com/fasterxml/jackson/core/JsonGenerator.java

@@ -305,9 +305,10 @@ public final JsonGenerator configure(Feature f, boolean state) {
 
 
     /**
-     * Bulk access method for getting state of all standard {@link Feature}s.
+     * Bulk access method for getting state of all standard (non-dataformat-specific)
+     * {@link JsonGenerator.Feature}s.
      * 
-     * @return Bit mask that defines current states of all standard {@link Feature}s.
+     * @return Bit mask that defines current states of all standard {@link JsonGenerator.Feature}s.
      * 
      * @since 2.3
      */
@@ -325,6 +326,60 @@ public final JsonGenerator configure(Feature f, boolean state) {
      */
     public abstract JsonGenerator setFeatureMask(int values);
 
+    /**
+     * Bulk set method for (re)setting states of features specified by <code>mask</code>.
+     * Functionally equivalent to
+     *<code>
+     *    int oldState = getFeatureMask();
+     *    int newState = (oldState & ~mask) | (values & mask);
+     *    setFeatureMask(newState);
+     *</code>
+     * 
+     * @param values Bit mask of set/clear state for features to change
+     * @param mask Bit mask of features to change
+     * 
+     * @since 2.6
+     */
+    public JsonGenerator overrideStdFeatures(int values, int mask) {
+        int oldState = getFeatureMask();
+        int newState = (oldState & ~mask) | (values & mask);
+        return setFeatureMask(newState);
+    }
+
+    /**
+     * Bulk access method for getting state of all {@link FormatFeature}s, format-specific
+     * on/off configuration settings.
+     * 
+     * @return Bit mask that defines current states of all standard {@link FormatFeature}s.
+     * 
+     * @since 2.6
+     */
+    public int getFormatFeatures() {
+        return 0;
+    }
+    
+    /**
+     * Bulk set method for (re)setting states of {@link FormatFeature}s,
+     * by specifying values (set / clear) along with a mask, to determine
+     * which features to change, if any.
+     *<p>
+     * Default implementation will simply throw an exception to indicate that
+     * the generator implementation does not support any {@link FormatFeature}s.
+     * 
+     * @param values Bit mask of set/clear state for features to change
+     * @param mask Bit mask of features to change
+     * 
+     * @since 2.6
+     */
+    public JsonGenerator overrideFormatFeatures(int values, int mask) {
+        throw new IllegalArgumentException("No FormatFeatures defined for generator of type "+getClass().getName());
+        /*
+        int oldState = getFeatureMask();
+        int newState = (oldState & ~mask) | (values & mask);
+        return setFeatureMask(newState);
+        */
+    }
+    
     /*
     /**********************************************************
     /* Public API, Schema configuration
@@ -509,9 +564,12 @@ public Object getOutputTarget() {
      *
      * @since 2.6
      */
+    public abstract int getOutputBuffered();
+    /*
     public int getOutputBuffered() {
         return -1;
     }
+    */
 
     /**
      * Helper method, usually equivalent to:

src/main/java/com/fasterxml/jackson/core/JsonParser.java

@@ -529,7 +529,58 @@ public JsonParser setFeatureMask(int mask) {
         _features = mask;
         return this;
     }
+
+    /**
+     * Bulk set method for (re)setting states of features specified by <code>mask</code>.
+     * Functionally equivalent to
+     *<code>
+     *    int oldState = getFeatureMask();
+     *    int newState = (oldState & ~mask) | (values & mask);
+     *    setFeatureMask(newState);
+     *</code>
+     * 
+     * @param values Bit mask of set/clear state for features to change
+     * @param mask Bit mask of features to change
+     * 
+     * @since 2.6
+     */
+    public JsonParser overrideStdFeatures(int values, int mask) {
+        _features = (_features & ~mask) | (values & mask);
+        return this;
+    }
+
+    /**
+     * Bulk access method for getting state of all {@link FormatFeature}s, format-specific
+     * on/off configuration settings.
+     * 
+     * @return Bit mask that defines current states of all standard {@link FormatFeature}s.
+     * 
+     * @since 2.6
+     */
+    public int getFormatFeatures() {
+        return 0;
+    }
 
+    /**
+     * Bulk set method for (re)setting states of {@link FormatFeature}s,
+     * by specifying values (set / clear) along with a mask, to determine
+     * which features to change, if any.
+     *<p>
+     * Default implementation will simply throw an exception to indicate that
+     * the generator implementation does not support any {@link FormatFeature}s.
+     * 
+     * @param values Bit mask of set/clear state for features to change
+     * @param mask Bit mask of features to change
+     * 
+     * @since 2.6
+     */
+    public JsonParser overrideFormatFeatures(int values, int mask) {
+        throw new IllegalArgumentException("No FormatFeatures defined for parser of type "+getClass().getName());
+        /*
+        _formatFeatures = (_formatFeatures & ~mask) | (values & mask);
+        */
+    }
+
     /*
     /**********************************************************
     /* Public API, traversal

src/main/java/com/fasterxml/jackson/core/util/VersionUtil.java

@@ -135,7 +135,7 @@ public static Version mavenVersionFor(ClassLoader cl, String groupId, String art
     }
 
     /**
-     * Method used by {@link PackageVersion} to decode version injected by Maven build.
+     * Method used by <code>PackageVersion</code> classes to decode version injected by Maven build.
      */
     public static Version parseVersion(String s, String groupId, String artifactId)
     {