Merge branch '2.4'
Conflicts:
pom.xml
release-notes/VERSION
diff --git a/pom.xml b/pom.xml
index 7ebca33..e0ce08c 100644
--- a/pom.xml
+++ b/pom.xml
@@ -4,13 +4,13 @@
<parent>
<groupId>com.fasterxml.jackson</groupId>
<artifactId>jackson-parent</artifactId>
- <version>2.4</version>
+ <version>2.5-SNAPSHOT</version>
</parent>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-annotations</artifactId>
<name>Jackson-annotations</name>
- <version>2.4.5-SNAPSHOT</version>
+ <version>2.5.0-SNAPSHOT</version>
<packaging>bundle</packaging>
<description>Core annotations used for value types, used by Jackson data binding package.
</description>
diff --git a/release-notes/VERSION b/release-notes/VERSION
index 9d7c8f1..7622c22 100644
--- a/release-notes/VERSION
+++ b/release-notes/VERSION
@@ -3,12 +3,21 @@
NOTE: Annotations module will never contain changes in patch versions,
only .0 releases can have changes. We may still release patch versions, but
they will be identical to .0 versions, and only released for convenience
- (developers can line up all Jackson components with same patch version number)
+ (developers can line up all Jackson components with same patch version number).
+ Main components will typically depend on .0 versions: please do NOT file
+ issues against this being a bug; it is intentional.
------------------------------------------------------------------------
=== Releases ===
------------------------------------------------------------------------
+2.5.0 (not yet released)
+
+#47: Add `@JsonCreator.mode` property to explicitly choose between delegating- and property-based creators
+- Added `@JsonInclude.content` to allow specifying inclusion criteria
+ for `java.util.Map` entries separate from inclusion of `Map` values
+ themselves
+
2.4.4 (24-Nov-2014)
2.4.3 (02-Oct-2014)
2.4.2 (13-Aug-2014)
diff --git a/src/main/java/com/fasterxml/jackson/annotation/JsonCreator.java b/src/main/java/com/fasterxml/jackson/annotation/JsonCreator.java
index 0888d70..396ce99 100644
--- a/src/main/java/com/fasterxml/jackson/annotation/JsonCreator.java
+++ b/src/main/java/com/fasterxml/jackson/annotation/JsonCreator.java
@@ -26,11 +26,58 @@
* Also note that all {@link JsonProperty} annotations MUST use actual name
* (NOT empty String for "default"): this because Java bytecode does not
* retain names of method or constructor arguments.
+ *<br />
+ * NOTE: as of JDK 8, some of above changes, with introduction of names for
+ * constructor and method parameters.
+ *
*/
@Target({ElementType.ANNOTATION_TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR})
@Retention(RetentionPolicy.RUNTIME)
@JacksonAnnotation
public @interface JsonCreator
{
- // no values, since there's no property
+ /**
+ * Property that is used to indicate how argument(s) is/are bound for creator,
+ * in cases there may be multiple alternatives. Currently the one case is that
+ * of a single-argument creator method, for which both so-called "delegating" and
+ * "property-based" bindings are possible: since
+ * delegating mode can not be used for multi-argument creators, the only choice
+ * there is "property-based" mode.
+ * Check {@link Mode} for more complete explanation of possible choices.
+ *<p>
+ * Default value of {@link Mode#DEFAULT} means that caller is to use standard
+ * heuristics for choosing mode to use.
+ *
+ * @since 2.5
+ */
+ public Mode mode() default Mode.DEFAULT;
+
+ /**
+ * @since 2.5
+ */
+ public enum Mode {
+ /**
+ * Pseudo-mode that indicates that caller is to use default heuristics for
+ * choosing mode to use. This typically favors use of delegating mode for
+ * single-argument creators that take structured types.
+ */
+ DEFAULT,
+
+ /**
+ * Mode that indicates that if creator takes a single argument, the whole incoming
+ * data value is to be bound into declared type of that argument; this "delegate"
+ * value is then passed as the argument to creator.
+ */
+ DELEGATING,
+
+ /**
+ * Mode that indicates that the argument(s) for creator are to be bound from matching
+ * properties of incoming Object value, using creator argument names (explicit or implicit)
+ * to match incoming Object properties to arguments.
+ *<p>
+ * Note that this mode is currently (2.5) always used for multiple-argument creators;
+ * the only ambiguous case is that of a single-argument creator.
+ */
+ PROPERTIES
+ }
}
diff --git a/src/main/java/com/fasterxml/jackson/annotation/JsonFormat.java b/src/main/java/com/fasterxml/jackson/annotation/JsonFormat.java
index c4868b7..792f593 100644
--- a/src/main/java/com/fasterxml/jackson/annotation/JsonFormat.java
+++ b/src/main/java/com/fasterxml/jackson/annotation/JsonFormat.java
@@ -224,7 +224,7 @@
public Value(String p, Shape sh, Locale l, TimeZone tz)
{
pattern = p;
- shape = sh;
+ shape = (sh == null) ? Shape.ANY : sh;
locale = l;
_timezone = tz;
timezoneStr = null;
@@ -236,7 +236,7 @@
public Value(String p, Shape sh, Locale l, String tzStr, TimeZone tz)
{
pattern = p;
- shape = sh;
+ shape = (sh == null) ? Shape.ANY : sh;
locale = l;
_timezone = tz;
timezoneStr = tzStr;
@@ -294,7 +294,8 @@
if (timezoneStr == null) {
return null;
}
- _timezone = tz = TimeZone.getTimeZone(timezoneStr);
+ tz = TimeZone.getTimeZone(timezoneStr);
+ _timezone = tz;
}
return tz;
}
diff --git a/src/main/java/com/fasterxml/jackson/annotation/JsonInclude.java b/src/main/java/com/fasterxml/jackson/annotation/JsonInclude.java
index 3d2db1e..da9fd9d 100644
--- a/src/main/java/com/fasterxml/jackson/annotation/JsonInclude.java
+++ b/src/main/java/com/fasterxml/jackson/annotation/JsonInclude.java
@@ -22,10 +22,19 @@
public @interface JsonInclude
{
/**
- * Inclusion rule to use.
+ * Inclusion rule to use for instances (values) of types (Classes) or
+ * properties annotated.
*/
public Include value() default Include.ALWAYS;
-
+
+ /**
+ * Inclusion rule to use for entries ("content") of annotated
+ * {@link java.util.Map}s; defaults to {@link Include#ALWAYS}.
+ *
+ * @since 2.5
+ */
+ public Include content() default Include.ALWAYS;
+
/*
/**********************************************************
/* Value enumerations needed
@@ -38,7 +47,7 @@
* of Java Beans are to be included in serialization.
*<p>
* Note: Jackson 1.x had similarly named ("Inclusion") enumeration included
- * in <code>JsonSerialize</code> annotation: it is not deprecated
+ * in <code>JsonSerialize</code> annotation: it is now deprecated
* and this value used instead.
*/
public enum Include
@@ -69,6 +78,8 @@
* Value that indicates that only properties that have values
* that values that are null or what is considered empty are
* not to be included.
+ * Definition of emptiness is data type specific; see below
+ * for details on actual handling.
*<p>
* Default emptiness is defined for following type:
*<ul>
@@ -81,8 +92,11 @@
* and return value of 0 indicates empty String (note that <code>String.isEmpty()</code>
* was added in Java 1.6 and as such can not be used by Jackson
* </li>
+ * <li>For date/time types, if timestamp from Epoch is zero (January 1st, 1970, UTC),
+ * value is considered empty.
+ * </li>
* <ul>
- * and for other types, non-null values are to be included.
+ * and for other types, null values are excluded but other exclusions (if any).
*<p>
* Note that this default handling can be overridden by custom
* <code>JsonSerializer</code> implementation: if method <code>isEmpty()</code>
diff --git a/src/main/java/com/fasterxml/jackson/annotation/JsonTypeInfo.java b/src/main/java/com/fasterxml/jackson/annotation/JsonTypeInfo.java
index d931a46..9da5bea 100644
--- a/src/main/java/com/fasterxml/jackson/annotation/JsonTypeInfo.java
+++ b/src/main/java/com/fasterxml/jackson/annotation/JsonTypeInfo.java
@@ -175,17 +175,18 @@
* Inclusion mechanism similar to <code>PROPERTY</code> with respect
* to deserialization; but one that is produced by a "regular" accessible
* property during serialization. This means that <code>TypeSerializer</code>
- * will do nothing, and expect a property with defined name to be output
+ * will do nothing, and expects a property with defined name to be output
* using some other mechanism (like default POJO property serialization, or
* custom serializer).
*<p>
- * Note that this behavior is quite similar to that of using {@link JsonTypeId};
+ * Note that this behavior is quite similar to that of using {@link JsonTypeId}
+ * annotation;
* except that here <code>TypeSerializer</code> is basically suppressed;
* whereas with {@link JsonTypeId}, output of regular property is suppressed.
* This mostly matters with respect to output order; this choice is the only
* way to ensure specific placement of type id during serialization.
*
- * @since 2.3.0
+ * @since 2.3.0 but databind <b>only since 2.5.0</b>.
*/
EXISTING_PROPERTY
;