Adds @JsonKey annotation. (#179)

Add `@JsonKey` annotation.

This annotation will be used like `@JsonValue` but only when
serializing Map keys.

See jackson-databind/#2871

Author: Anusien

src/main/java/com/fasterxml/jackson/annotation/JsonKey.java

@@ -0,0 +1,52 @@
+package com.fasterxml.jackson.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marker annotation
+ * that indicates that the value of annotated accessor (either field
+ * or "getter" method [a method with non-void return type, no args])
+ * is to be used as the single value to serialize for the instance.
+ * This value will be used only if the instance is being serialized
+ * as a key in a Map type.
+ * Usually value will be of a simple scalar type
+ * (String or Number), but it can be any serializable type (Collection,
+ * Map or Bean).
+ *<p>
+ * At most one accessor of a <code>Class</code> can be annotated with this annotation;
+ * if more than one is found, an exception may be thrown.
+ * Also, if method signature of annotated method is not compatible with Getters,
+ * an exception may be thrown (whether exception is thrown or not is an
+ * implementation detail (due to filtering during introspection, some annotations
+ * may be skipped) and applications should not rely on specific behavior).
+ *<p>
+ * A typical usage is that of annotating <code>toString()</code>
+ * method so that returned String value is used as the JSON serialization;
+ * and if deserialization is needed, there is matching constructor
+ * or factory method annotated with {@link JsonCreator} annotation.
+ *<p>
+ * Boolean argument is only used so that sub-classes can "disable"
+ * annotation if necessary.
+ *
+ * @see JsonValue
+ */
+@Target({ElementType.ANNOTATION_TYPE, ElementType.METHOD,
+		ElementType.FIELD
+})
+@Retention(RetentionPolicy.RUNTIME)
+@JacksonAnnotation
+public @interface JsonKey
+{
+	/**
+	 * Optional argument that defines whether this annotation is active
+	 * or not. The only use for value 'false' if for overriding purposes.
+	 * Overriding may be necessary when used
+	 * with "mix-in annotations" (aka "annotation overrides").
+	 * For most cases, however, default value of "true" is just fine
+	 * and should be omitted.
+	 */
+	boolean value() default true;
+}

src/main/java/com/fasterxml/jackson/annotation/JsonValue.java

@@ -36,8 +36,13 @@
  * This is possible since set of Enum values is constant and it is possible
  * to define mapping, but can not be done in general for POJO types; as such,
  * this is not used for POJO deserialization.
+ *<p>
+ * NOTE: When the instance is being serialized as the key of a Map type,
+ * this will be ignored if an accessor is annotated with
+ * {@link JsonKey}.
  *
  * @see JsonCreator
+ * @see JsonKey
  */
 @Target({ElementType.ANNOTATION_TYPE, ElementType.METHOD,
     ElementType.FIELD // since 2.9