Javadoc improvements, adding base class for PTV (wrt #2195)

Author: cowtowncoder

src/main/java/com/fasterxml/jackson/databind/jsontype/BasicPolymorphicTypeValidator.java

@@ -25,7 +25,7 @@
  * @since 2.10
  */
 public class BasicPolymorphicTypeValidator
-    extends PolymorphicTypeValidator
+    extends PolymorphicTypeValidator.Base
     implements java.io.Serializable
 {
     private static final long serialVersionUID = 1L;

src/main/java/com/fasterxml/jackson/databind/jsontype/PolymorphicTypeValidator.java

@@ -4,22 +4,46 @@
 import com.fasterxml.jackson.databind.cfg.MapperConfig;
 
 /**
- * Interface for classes that handle validation of class name-based subtypes used
+ * Interface for classes that handle validation of class-name - based subtypes used
  * with Polymorphic Deserialization: both via "default typing" and explicit
  * {@code @JsonTypeInfo} when using Java Class name as Type Identifier.
- * The main purpose, initially, is to allow pluggable allow/deny lists to avoid
+ * The main purpose, initially, is to allow pluggable allow lists to avoid
  * security problems that occur with unlimited class names
  * (See <a href="https://medium.com/@cowtowncoder/on-jackson-cves-dont-panic-here-is-what-you-need-to-know-54cd0d6e8062">
  * this article</a> for full explanation).
  *<p>
- * Call fal
+ * Calls to methods are done as follows:
+ * <ol>
+ *  <li>When a deserializer is needed for a polymorphic property (including root values) -- either
+ *     for explicitly annotated polymorphic type, or "default typing" -- {@link #validateBaseType}
+ *     is called to see if validity can be determined for all possible types: if 
+ *     {@link Validity#ALLOWED} is returned no futher checks are made for any subtypes; of
+ *     {@link Validity#DENIED} is returned, an exception will be thrown to indicate invalid polymorphic
+ *     property
+ *   </li>
+ *  <li>If neither deny nor allowed was returned for property with specific base type, first time
+ *     specific Type Id (Class Name) is encountered, method {@link #validateSubClassName} is called
+ *     with resolved class name: it may indicate allowed/denied, resulting in either allowed use or
+ *     denial with exception
+ *   </li>
+ *  <li>If no denial/allowance indicated, class name is resolved to actual {@link Class}, and
+ *  {@link #validateSubType(MapperConfig, JavaType, JavaType)} is called: if
+ *  {@link Validity#ALLOWED} is returned, usage is accepted; otherwise (denied or indeterminate)
+ *  usage is not allowed and exception is thrown
+ *   </li>
+ * </ol>
  *<p>
  * Notes on implementations: implementations must be thread-safe and shareable (usually meaning they
  * are stateless). Determinations for validity are usually effectively cached on per-property
  * basis (by virtue of subtype deserializers being cached by polymorphic deserializers) so
  * caching at validator level is usually not needed. If caching is used, however, it must be done
  * in thread-safe manner as validators are shared within {@link ObjectMapper} as well as possible
  * across mappers (in case of default/standard validator).
+ *<p>
+ * Also note that it is strongly recommended that all implementations are based on provided
+ * abstract base class, {@link PolymorphicTypeValidator.Base} which contains helper methods
+ * and default implementations for returning {@link Validity#INDETERMINATE} for validation
+ * methods (to allow only overriding relevant methods implementation cares about)
  *
  * @since 2.10
  */
@@ -116,4 +140,33 @@ public abstract Validity validateSubClassName(MapperConfig<?> config, JavaType b
      */
     public abstract Validity validateSubType(MapperConfig<?> config, JavaType baseType,
             JavaType subType) throws JsonMappingException;
+
+    /**
+     * Shared base class with partial implementation (with all validation calls returning
+     * {@link Validity#INDETERMINATE}) and convenience methods for indicating failure reasons.
+     * Use of this base class is strongly recommended over directly implement
+     */
+    public abstract static class Base
+        extends PolymorphicTypeValidator
+        implements java.io.Serializable
+    {
+        private static final long serialVersionUID = 1L;
+
+        @Override
+        public Validity validateBaseType(MapperConfig<?> config, JavaType baseType) {
+            return Validity.INDETERMINATE;
+        }
+    
+        @Override
+        public Validity validateSubClassName(MapperConfig<?> config, JavaType baseType, String subClassName)
+                throws JsonMappingException {
+            return Validity.INDETERMINATE;
+        }
+    
+        @Override
+        public Validity validateSubType(MapperConfig<?> config, JavaType baseType, JavaType subType)
+                throws JsonMappingException {
+            return Validity.INDETERMINATE;
+        }
+    }
 }

src/main/java/com/fasterxml/jackson/databind/jsontype/impl/LaissezFaireSubTypeValidator.java

@@ -13,7 +13,7 @@
  * @since 2.10
  */
 public final class LaissezFaireSubTypeValidator
-    extends PolymorphicTypeValidator
+    extends PolymorphicTypeValidator.Base
 {
     private static final long serialVersionUID = 1L;
 
@@ -35,4 +35,4 @@ public Validity validateSubType(MapperConfig<?> ctxt, JavaType baseType,
             JavaType subType) {
         return Validity.ALLOWED;
     }
-}
+}

src/test/java/com/fasterxml/jackson/databind/testutil/NoCheckSubTypeValidator.java

@@ -9,7 +9,7 @@
  * use of any subtypes.
  */
 public final class NoCheckSubTypeValidator
-    extends PolymorphicTypeValidator
+    extends PolymorphicTypeValidator.Base
 {
     private static final long serialVersionUID = 1L;