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;

/**
 * Annotation used to indicate that a property should be serialized
 * "unwrapped"; that is, if it would be serialized as JSON Object, its
 * properties are instead included as properties of its containing
 * Object. For example, consider case of POJO like:
 * 
 *<pre>
 *  public class Parent {
 *    public int age;
 *    public Name name;
 *  }
 *  public class Name {
 *    public String first, last;
 *  }
 *</pre>  
 * which would normally be serialized as follows (assuming @JsonUnwrapped
 * had no effect):
 *<pre>
 *  {
 *    "age" : 18,
 *    "name" : {
 *      "first" : "Joey",
 *      "last" : "Sixpack"
 *    }
 *  }
 *</pre>
 * can be changed to this:
 *<pre>
 *  {
 *    "age" : 18,
 *    "first" : "Joey",
 *    "last" : "Sixpack"
 *  }
 *</pre>
 * by changing Parent class to:
 *<pre>
 *  public class Parent {
 *    public int age;
 *    &#064;JsonUnwrapped
 *    public Name name;
 *  }
 *</pre>
 * Annotation can only be added to properties, and not classes, as it is contextual.
 *<p>
 * Also note that annotation only applies if
 *<ul>
 * <li>Value is serialized as JSON Object (can not unwrap JSON arrays using this
 *   mechanism)
 *   </li>
 * <li>Serialization is done using <code>BeanSerializer</code>, not a custom serializer
 *   </li>
 * <li>No type information is added; if type information needs to be added, structure can
 *   not be altered regardless of inclusion strategy; so annotation is basically ignored.
 *   </li>
 * </ul>
 */
@Target({ElementType.ANNOTATION_TYPE, ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@JacksonAnnotation
public @interface JsonUnwrapped
{
    /**
     * Property that is usually only used when overriding (masking) annotations,
     * using mix-in annotations. Otherwise default value of 'true' is fine, and
     * value need not be explicitly included.
     */
    boolean enabled() default true;

    /**
     * Optional property that can be used to add prefix String to use in front
     * of names of properties that are unwrapped: this can be done for example to prevent
     * name collisions.
     */
    String prefix() default "";

    /**
     * Optional property that can be used to add suffix String to append at the end
     * of names of properties that are unwrapped: this can be done for example to prevent
     * name collisions.
     */
    String suffix() default "";
}

@@ -284,17 +284,19 @@
 wrapped%22
-;
+ --
  that is
@@ -419,17 +419,72 @@
 * Object
-.
+ -- and deserialized reproducing %22missing%22 structure.%0A *
  For exa
@@ -740,16 +740,23 @@
 ssuming 
+%7B@code 
 @JsonUnw
@@ -757,24 +757,25 @@
 sonUnwrapped
+%7D
 %0A * had no e
@@ -1268,16 +1268,120 @@
 extual.%0A
+ * When values are deserialized %22wrapping%22 is applied so that serialized output can%0A * be read back in.%0A
  *%3Cp%3E%0A *
@@ -1422,16 +1422,17 @@
 plies if
+:
 %0A *%3Cul%3E%0A
@@ -1465,20 +1465,18 @@
  as 
-JSON
+an
  Object 
 (can
@@ -1471,16 +1471,22 @@
  Object 
+valie 
 (can not
@@ -1497,18 +1497,19 @@
 rap 
-JSON array
+Array value
 s us
@@ -1555,47 +1555,69 @@
 %3Cli%3E
-Serialization is done using %3C
+Reading/writing is done using Jackson standard %7B@
 code
-%3E
+ 
 Bean
-S
+Des
 eria
@@ -1625,30 +1625,50 @@
 izer
-%3C/code%3E, not a
+%7D /%0A *  %7B@code BeanSerializer%7D; or
  custom 
 seri
@@ -1663,16 +1663,18 @@
  custom 
+de
 serializ
@@ -1679,199 +1679,161 @@
 izer
-%0A *   %3C/li%3E%0A * %3Cli%3ENo type information is added; if type information needs to be added, structure can%0A *   not be altered regardless of inclusion strategy; so annotation is basically ignored.
+/serializer MUST explicitly support similar%0A *  operation.%0A *   %3C/li%3E%0A * %3Cli%3EWill not work with polymorphic type handling (%22polymorphic deserialization%22)
 %0A * 

Fix #184 (javadoc improvement for `@JsonUnwrapped`)