Improve javadocs wrt #1214

Author: cowtowncoder

src/main/java/com/fasterxml/jackson/databind/annotation/JsonDeserialize.java

@@ -25,6 +25,17 @@
  *  )
  *</pre>
  *<p>
+ * Something to note on usage:
+ *<ul>
+ * <li>All other annotations regarding behavior during building should be on <b>Builder</b>
+ *    class and NOT on target POJO class: for example &#64;JsonIgnoreProperties should be on
+ *    Builder to prevent "unknown property" errors.
+ *  </li>
+ * <li>Similarly configuration overrides (see {@link com.fasterxml.jackson.databind.ObjectMapper#configOverride})
+ *    should be targeted at Builder class, not target POJO class.
+ *  </li>
+ * </ul>
+ *
  */
 @Target({ElementType.ANNOTATION_TYPE, ElementType.METHOD, ElementType.FIELD, ElementType.TYPE, ElementType.PARAMETER})
 @Retention(RetentionPolicy.RUNTIME)

src/main/java/com/fasterxml/jackson/databind/annotation/JsonPOJOBuilder.java

@@ -14,8 +14,16 @@
  * Annotation is typically used if the naming convention
  * of a Builder class is different from defaults:
  *<ul>
+ * <li>By default, setters are expected to have names like `withName()` (for property "name");
+ *     override by {@link #withPrefix()} property.
+ *  </li>
  * </ul>
- * 
+ *<p>
+ * In addition to configuration using this annotation, note that many other configuration
+ * annotations are also applied to Builders, for example
+ * {@link com.fasterxml.jackson.annotation.JsonIgnoreProperties} can be used to ignore
+ * "unknown" properties.
+ *
  * @since 2.0
  */
 @Target({ElementType.ANNOTATION_TYPE, ElementType.TYPE})

src/test/java/com/fasterxml/jackson/databind/creators/BuilderSimpleTest.java

@@ -4,6 +4,7 @@
 
 import com.fasterxml.jackson.annotation.JsonAnySetter;
 import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.fasterxml.jackson.annotation.JsonSetter;
 import com.fasterxml.jackson.core.JsonProcessingException;
@@ -302,19 +303,46 @@ public ValueClass822(int x, Map<String,Object> stuff) {
      */
 
     private final ObjectMapper MAPPER = new ObjectMapper();
-    
+
     public void testSimple() throws Exception
     {
         String json = "{\"x\":1,\"y\":2}";
         Object o = MAPPER.readValue(json, ValueClassXY.class);
         assertNotNull(o);
-    	    assertSame(ValueClassXY.class, o.getClass());
-    	    ValueClassXY value = (ValueClassXY) o;
-    	    // note: ctor adds one to both values
-    	    assertEquals(value._x, 2);
-    	    assertEquals(value._y, 3);
+        assertSame(ValueClassXY.class, o.getClass());
+        ValueClassXY value = (ValueClassXY) o;
+        // note: ctor adds one to both values
+        assertEquals(value._x, 2);
+        assertEquals(value._y, 3);
     }
 
+    // related to [databind#1214]
+    public void testSimpleWithIgnores() throws Exception
+    {
+        // 'z' is unknown, and would fail by default:
+        String json = "{\"x\":1,\"y\":2,\"z\":3}";
+        Object o = null;
+
+        try {
+            o = MAPPER.readValue(json, ValueClassXY.class);
+            fail("Should not pass");
+        } catch (JsonMappingException e) {
+            verifyException(e, "Unrecognized field \"z\"");
+        }
+
+        // but with config overrides should pass
+        ObjectMapper ignorantMapper = new ObjectMapper();
+        ignorantMapper.configOverride(SimpleBuilderXY.class)
+                .setIgnorals(JsonIgnoreProperties.Value.forIgnoreUnknown(true));
+        o = ignorantMapper.readValue(json, ValueClassXY.class);
+        assertNotNull(o);
+        assertSame(ValueClassXY.class, o.getClass());
+        ValueClassXY value = (ValueClassXY) o;
+        // note: ctor adds one to both values
+        assertEquals(value._x, 2);
+        assertEquals(value._y, 3);
+    }
+    
     public void testMultiAccess() throws Exception
     {
         String json = "{\"c\":3,\"a\":2,\"b\":-9}";