Merge pull request #45 from johnjohndoe/update-readme
Update readme
diff --git a/pom.xml b/pom.xml
index 2820d4b..91462f7 100644
--- a/pom.xml
+++ b/pom.xml
@@ -4,18 +4,18 @@
<parent>
<groupId>com.fasterxml.jackson</groupId>
<artifactId>jackson-parent</artifactId>
- <version>2.5-SNAPSHOT</version>
+ <version>2.5</version>
</parent>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-annotations</artifactId>
<name>Jackson-annotations</name>
- <version>2.5.0-SNAPSHOT</version>
+ <version>2.5.1-SNAPSHOT</version>
<packaging>bundle</packaging>
<description>Core annotations used for value types, used by Jackson data binding package.
</description>
- <url>http://wiki.fasterxml.com/JacksonHome</url>
+ <url>http://github.com/FasterXML/jackson</url>
<scm>
<connection>scm:git:git@github.com:FasterXML/jackson-annotations.git</connection>
<developerConnection>scm:git:git@github.com:FasterXML/jackson-annotations.git</developerConnection>
diff --git a/release-notes/VERSION b/release-notes/VERSION
index b8f4142..a3de549 100644
--- a/release-notes/VERSION
+++ b/release-notes/VERSION
@@ -3,17 +3,34 @@
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 (xx-xxx-2014)
+2.5.0 (01-Jan-2015)
+#47: Add `@JsonCreator.mode` property to explicitly choose between delegating-
+ and property-based creators, or to disable specific creator (Mode.DISABLED)
+#48: Allow `@JsonView` for (method) parameters too
+#49: Add `@JsonTypeInfo.skipWritingDefault`
+#50: Add `ObjectIdGenerator.maySerializeAsObject()`,
+ `ObjectIdGenerator.ObjectIdGenerator.maySerializeAsObject()` to support JSOG
- Added `@JsonInclude.content` to allow specifying inclusion criteria
for `java.util.Map` entries separate from inclusion of `Map` values
themselves
+- Finalize fix for [databind#490], by ensuring new mapping initialized for new context
+- Added `@JsonProperty.defaultValue()` (related to [databind#596])
+
+2.4.4 (24-Nov-2014)
+2.4.3 (02-Oct-2014)
+2.4.2 (13-Aug-2014)
+2.4.1
+
+No changes since 2.4.0.
2.4.0 (29-May-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..dd1dee2 100644
--- a/src/main/java/com/fasterxml/jackson/annotation/JsonCreator.java
+++ b/src/main/java/com/fasterxml/jackson/annotation/JsonCreator.java
@@ -26,11 +26,65 @@
* 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,
+
+ /**
+ * Pseudo-mode that indicates that creator is not to be used. This can be used as a result
+ * value for explicit disabling, usually either by custom annotation introspector,
+ * or by annotation mix-ins (for example when choosing different creator).
+ */
+ DISABLED
+ }
}
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 1a1a4dd..da9fd9d 100644
--- a/src/main/java/com/fasterxml/jackson/annotation/JsonInclude.java
+++ b/src/main/java/com/fasterxml/jackson/annotation/JsonInclude.java
@@ -47,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
@@ -78,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>
@@ -90,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/JsonProperty.java b/src/main/java/com/fasterxml/jackson/annotation/JsonProperty.java
index ce3d336..bc76175 100644
--- a/src/main/java/com/fasterxml/jackson/annotation/JsonProperty.java
+++ b/src/main/java/com/fasterxml/jackson/annotation/JsonProperty.java
@@ -77,10 +77,16 @@
* @since 2.4
*/
int index() default INDEX_UNKNOWN;
-
- /* NOTE: considering of adding ability to specify default
- * String value -- would work well for scalar types, most of
- * which can coerce from Strings. But won't add for 2.0 yet.
+
+ /**
+ * Property that may be used to <b>document</b> expected default value
+ * for the property: most often used as source information for generating
+ * schemas (like JSON Schema or protobuf/thrift schema), or documentation.
+ * It may also be used by Jackson extension modules; core jackson databind
+ * does not have any automated handling beyond simply exposing this
+ * value through bean property introspection.
+ *
+ * @since 2.5
*/
- //String defaultValue() default "";
+ String defaultValue() default "";
}
diff --git a/src/main/java/com/fasterxml/jackson/annotation/JsonTypeInfo.java b/src/main/java/com/fasterxml/jackson/annotation/JsonTypeInfo.java
index 9da5bea..ecf74d6 100644
--- a/src/main/java/com/fasterxml/jackson/annotation/JsonTypeInfo.java
+++ b/src/main/java/com/fasterxml/jackson/annotation/JsonTypeInfo.java
@@ -246,12 +246,16 @@
* There are certain special values that indicate alternate behavior:
*<ul>
* <li>{@link None} means "there is no default implementation" (in which
- * case an error results from unmappable type)
+ * case an error results from unmappable type).
+ * With Jackson 2.5 and above, {@link JsonTypeInfo} itself will also be
+ * accepted to mean "no default implementation specified"
* <li><code>com.fasterxml.jackson.databind.annotation.NoClass</code> means that
* objects with unmappable (or missing) type are to be mapped to null references.
+ * With Jackson 2.5, {@link java.lang.Void} may also be used to indicate this
+ * behavior
* </ul>
- *
- * TODO: In 2.5, change default to {@link java.lang.Void}
+ *<p>
+ * TODO: change default value to be {@link JsonTypeInfo}.class in 2.6
*/
public Class<?> defaultImpl() default None.class;
@@ -268,6 +272,18 @@
* @since 2.0
*/
public boolean visible() default false;
+
+ // 19-Dec-2014, tatu: Was hoping to implement for 2.5, but didn't quite make it.
+ // Hope for better luck with 2.6.
+ /**
+ * Property that defines whether type serializer is allowed to omit writing
+ * of type id, in case that value written has type same as {@link #defaultImpl()}.
+ * If true, omission is allowed (although writer may or may not be able to do that);
+ * if false, type id should always be written still.
+ *
+ * @since 2.5
+ public boolean skipWritingDefault() default false;
+ /*
/*
/**********************************************************
@@ -280,7 +296,7 @@
* annotation property, to indicate that there is no default implementation
* specified.
*
- * @deprecated Since 2.4, use {@link java.lang.Void} instead.
+ * @deprecated Since 2.5, use {@link java.lang.Void} instead.
*/
@Deprecated
public abstract static class None { }
diff --git a/src/main/java/com/fasterxml/jackson/annotation/JsonView.java b/src/main/java/com/fasterxml/jackson/annotation/JsonView.java
index 4243fb4..2400bba 100644
--- a/src/main/java/com/fasterxml/jackson/annotation/JsonView.java
+++ b/src/main/java/com/fasterxml/jackson/annotation/JsonView.java
@@ -21,7 +21,9 @@
* If multiple View class identifiers are included, property will
* be part of all of them.
*/
-@Target({ElementType.ANNOTATION_TYPE, ElementType.METHOD, ElementType.FIELD})
+@Target({ElementType.ANNOTATION_TYPE, ElementType.METHOD, ElementType.FIELD,
+ ElementType.PARAMETER // since 2.5
+})
@Retention(RetentionPolicy.RUNTIME)
@JacksonAnnotation
public @interface JsonView {
diff --git a/src/main/java/com/fasterxml/jackson/annotation/ObjectIdGenerator.java b/src/main/java/com/fasterxml/jackson/annotation/ObjectIdGenerator.java
index b426562..163fbfe 100644
--- a/src/main/java/com/fasterxml/jackson/annotation/ObjectIdGenerator.java
+++ b/src/main/java/com/fasterxml/jackson/annotation/ObjectIdGenerator.java
@@ -30,6 +30,39 @@
* @return True if this instance can be used as-is; false if not
*/
public abstract boolean canUseFor(ObjectIdGenerator<?> gen);
+
+ /**
+ * Accessor that needs to be overridden to return <code>true</code>
+ * if the Object Id may be serialized as JSON Object; used by, for example,
+ * JSOG handling.
+ * The reason accessor is needed is because handling such Object Ids is
+ * more complex and may incur additional buffering or performance overhead,
+ * avoiding of which makes sense for common case of scalar object ids
+ * (or native object ids some formats support).
+ *<p>
+ * Default implementation returns <code>false</code>, so needs to be overridden
+ * by Object-producing generators.
+ *
+ * @since 2.5
+ */
+ public boolean maySerializeAsObject() {
+ return false;
+ }
+
+ /**
+ * Accessor that may be called (after verifying (via {@link #maySerializeAsObject()})
+ * whether given name
+ *
+ * @param name Name of property to check
+ * @param parser Parser that points to property name, in case generator needs
+ * further verification (note: untyped, because <code>JsonParser</code> is defined
+ * in `jackson-core`, and this package does not depend on it).
+ *
+ * @since 2.5
+ */
+ public boolean isValidReferencePropertyName(String name, Object parser) {
+ return false;
+ }
/*
/**********************************************************
diff --git a/src/main/java/com/fasterxml/jackson/annotation/ObjectIdGenerators.java b/src/main/java/com/fasterxml/jackson/annotation/ObjectIdGenerators.java
index a083207..516437f 100644
--- a/src/main/java/com/fasterxml/jackson/annotation/ObjectIdGenerators.java
+++ b/src/main/java/com/fasterxml/jackson/annotation/ObjectIdGenerators.java
@@ -7,14 +7,8 @@
*/
public class ObjectIdGenerators
{
- /*
- /**********************************************************
- /* Shared base class for concrete implementations
- /**********************************************************
- */
-
/**
- * Helper class for implementations contained.
+ * Shared base class for concrete implementations.
*/
@SuppressWarnings("serial")
private abstract static class Base<T> extends ObjectIdGenerator<T>
diff --git a/src/main/java/com/fasterxml/jackson/annotation/ObjectIdResolver.java b/src/main/java/com/fasterxml/jackson/annotation/ObjectIdResolver.java
index afbb0b6..2cfaa99 100644
--- a/src/main/java/com/fasterxml/jackson/annotation/ObjectIdResolver.java
+++ b/src/main/java/com/fasterxml/jackson/annotation/ObjectIdResolver.java
@@ -3,21 +3,19 @@
import com.fasterxml.jackson.annotation.ObjectIdGenerator.IdKey;
/**
- * Definition of API used for constructing POJO from Object Identifiers (as
- * annotated using {@link JsonIdentityInfo}).
- *
+ * Definition of API used for resolving actual Java object from
+ * Object Identifiers (as annotated using {@link JsonIdentityInfo}).
+ *
* @since 2.4
*/
public interface ObjectIdResolver {
/**
* Method called when a POJO is deserialized and has an Object Identifier.
* Method exists so that implementation can keep track of existing object in
- * json stream that could be useful for further resolution.
+ * JSON stream that could be useful for further resolution.
*
- * @param id
- * The Object Identifer
- * @param ob
- * The POJO associated to that Identifier
+ * @param id The Object Identifer
+ * @param pojo The POJO associated to that Identifier
*/
void bindItem(IdKey id, Object pojo);
@@ -25,8 +23,7 @@
* Method called when deserialization encounters the given Object Identifier
* and requires the POJO associated with it.
*
- * @param id
- * The Object Identifier
+ * @param id The Object Identifier
* @return The POJO, or null if unable to resolve.
*/
Object resolveId(IdKey id);
diff --git a/src/main/java/com/fasterxml/jackson/annotation/SimpleObjectIdResolver.java b/src/main/java/com/fasterxml/jackson/annotation/SimpleObjectIdResolver.java
index b383ddd..b45f236 100644
--- a/src/main/java/com/fasterxml/jackson/annotation/SimpleObjectIdResolver.java
+++ b/src/main/java/com/fasterxml/jackson/annotation/SimpleObjectIdResolver.java
@@ -11,12 +11,16 @@
* @author Pascal Gélinas
*/
public class SimpleObjectIdResolver implements ObjectIdResolver {
- private Map<IdKey,Object> _items = new HashMap<ObjectIdGenerator.IdKey,Object>();
+ protected Map<IdKey,Object> _items;
+
+ public SimpleObjectIdResolver() { }
@Override
public void bindItem(IdKey id, Object ob)
{
- if (_items.containsKey(id)) {
+ if (_items == null) {
+ _items = new HashMap<ObjectIdGenerator.IdKey,Object>();
+ } else if (_items.containsKey(id)) {
throw new IllegalStateException("Already had POJO for id (" + id.key.getClass().getName() + ") [" + id
+ "]");
}
@@ -24,20 +28,19 @@
}
@Override
- public Object resolveId(IdKey id)
- {
- return _items.get(id);
+ public Object resolveId(IdKey id) {
+ return (_items == null) ? null : _items.get(id);
}
@Override
- public boolean canUseFor(ObjectIdResolver resolverType)
- {
+ public boolean canUseFor(ObjectIdResolver resolverType) {
return resolverType.getClass() == getClass();
}
-
+
@Override
- public ObjectIdResolver newForDeserialization(Object context)
- {
- return this;
+ public ObjectIdResolver newForDeserialization(Object context) {
+ // 19-Dec-2014, tatu: Important: must re-create without existing mapping; otherwise bindings leak
+ // (and worse, cause unnecessary memory retention)
+ return new SimpleObjectIdResolver();
}
}