Wrapping object and class name handling removed (#303)

Wrapping object option removed
Class name handling removed

Signed-off-by: David Kral <david.k.kral@oracle.com>

Author: Verdent

api/src/main/java/jakarta/json/bind/annotation/JsonbPolymorphicType.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2021, 2022 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v. 2.0, which is available at
@@ -16,26 +16,22 @@
 
 package jakarta.json.bind.annotation;
 
-import java.lang.annotation.ElementType;
-import java.lang.annotation.Repeatable;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Subtype is tightly bound to the {@link JsonbPolymorphicType}.
+ * Subtype is tightly bound to the {@link JsonbTypeInfo}.
  * <br>
  * Type defines class which instance will be created when processing specific alias, or when processing
  * instance of the specified type, to determine which alias should be used.
  * <br>
  * Alias is used instead of a class name. It has to be unique value among all the defined subtypes
- * bound to the specific {@link JsonbPolymorphicType}. An exception should be thrown when processing and
+ * bound to the specific {@link JsonbTypeInfo}. An exception should be thrown when processing and
  * validating aliases and duplicate alias is found.
- * <br>
- * An exception have to be thrown when processing unknown alias and
  * <pre><code>
  * // Example
- * {@literal @}JsonbPolymorphicType({
+ * {@literal @}JsonbTypeInfo({
  *      {@literal @}JsonbSubtype(alias = "dog", type = Dog.class)
  *      {@literal @}JsonbSubtype(alias = "cat", type = Cat.class)
  * })
@@ -53,7 +49,7 @@
  *
  * jsonb.toJson(new Dog());// {"@type":"dog","isDog":true}
  * jsonb.toJson(new Cat());// {"@type":"cat","isCat":true}
- * jsonb.toJson(new Rat());// An exception thrown
+ * jsonb.toJson(new Rat());// {"isRat":true}
  * </code></pre>
  */
 @JsonbAnnotation

api/src/main/java/jakarta/json/bind/annotation/JsonbSubtype.java

@@ -0,0 +1,64 @@
+/*
+ * Copyright (c) 2021, 2022 Oracle and/or its affiliates. All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0, which is available at
+ * http://www.eclipse.org/legal/epl-2.0.
+ *
+ * This Source Code may also be made available under the following Secondary
+ * Licenses when the conditions for such availability set forth in the
+ * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
+ * version 2 with the GNU Classpath Exception, which is available at
+ * https://www.gnu.org/software/classpath/license.html.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+ */
+
+package jakarta.json.bind.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Configuration annotation of the type information handling.
+ * <br>
+ * This annotation is required on the most common parent of all classes when type information will be applied.
+ * <pre><code>
+ * // Example
+ * {@literal @}JsonbTypeInfo(key = "@key")
+ * interface Animal {}
+ *
+ * class Dog implements Animal {}
+ * class Cat implements Animal {}
+ * </code></pre>
+ * This annotation is tightly bound to {@link JsonbSubtype}. It is recommended to use
+ * {@link JsonbSubtype} annotations to specify all the possible classes and their aliases.
+ */
+@JsonbAnnotation
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.ANNOTATION_TYPE, ElementType.TYPE})
+public @interface JsonbTypeInfo {
+
+    /**
+     * Default type information key name.
+     */
+    String DEFAULT_KEY_NAME = "@type";
+
+    /**
+     * Key used for keeping the type information (alias).
+     * Default value is {@code @type}.
+     *
+     * @return key name
+     */
+    String key() default DEFAULT_KEY_NAME;
+
+    /**
+     * Allowed aliases of the handled type.
+     *
+     * @return list of allowed aliases
+     */
+    JsonbSubtype[] value() default {};
+
+}

api/src/main/java/jakarta/json/bind/annotation/JsonbTypeInfo.java

@@ -318,27 +318,22 @@ Deserialization into anonymous classes is not supported. Serialization of anonym
 
 === Polymorphic Types
 
-Polymorphic type handling is supported for deserialization and serialization. Polymorphic handling is ensured by annotation `@JsonbPolymorphicType` and `@JsonbSubtype`. `@JsonbPolymorphicType` defines how the overall polymorphic information strategy will be serialized/deserialized and defines all the supported aliases using `@JsonbSubtype` annotations. `@JsonbSubtype` ensures proper and safe mapping between class alias and type. Implementation must validate mapped types if they are assignable from the annotated type. If not, an exception must be thrown.
+Polymorphic type handling is supported for deserialization and serialization. Polymorphic handling is ensured by annotation `JsonbTypeInfo` and `@JsonbSubtype`. `JsonbTypeInfo` defines key name of the property to store type information in it and defines all the supported aliases using `@JsonbSubtype` annotations. `@JsonbSubtype` ensures proper and safe mapping between class alias and type. Implementation must validate mapped types if they are assignable from the annotated type. If not, an exception must be thrown.
 
-Polymorphic information is obtained from `@JsonbSubtype` annotation as a type alias mapped to the type or if `classNames` property of the `@JsonbPolymorphicType` is enabled, it corresponds to the fully qualified class name, if no suitable alias is found. Implementation must ensure to support `allowedPackages` option of the `@JsonbPolymorphicType` which is only used when `classNames` option is enabled, it is ignored otherwise. It is not allowed to create instances of the classes outside the allowed packages. In such cases an exception must be thrown. It is also required to have `allowedPackages` option set if `classNames` option is enabled. If the `allowedPackages` is null or empty an exception must be thrown.
+Type information is obtained from `@JsonbSubtype` annotation as a type alias mapped to the type. If no matching class is found for obtained alias during deserialization, an exception must be thrown.
 
-Available serialization formats:
+New property with type information is added to the serialized object. The property key name is taken from the `key` property of the annotation `JsonbTypeInfo`. This type information property key name has to be unique in the resulting JSON document. If any naming collision with class or any other `JsonbTypeInfo` properties occurs, an exception must be thrown. It is required for all polymorphism fields to be serialized as the first properties in the JSON and any actual object properties are serialized after.
 
-* Property - new property with polymorphic information is added to the serialized object. The property key name is taken from the `key` property of the annotation `@JsonbPolymorphicType`. This polymorphic information property key name has to be unique in the resulting JSON document. If any naming collision with class properties occurs, an exception must be thrown. It is required for all polymorphism fields to be serialized as the first properties in the JSON and any actual object properties are serialized after.
-* Wrapping object - serialized object is wrapped with another object with a single property. The key corresponds to the polymorphic information of the type and the value is the serialized object
+If no `JsonbTypeInfo` is used on handled class or its predecessors, it is not possible to ensure proper polymorphic type handling and in such cases deserialization is not supported.
 
-If no `@JsonbPolymorphicType` is used on handled class or its predecessors, it is not possible to ensure proper polymorphic handling and in such cases deserialization is not supported for polymorphic types.
-
-If the type predecessor has set `@JsonbPolymorphicType` and the current type also, but with the different format, an exception must be thrown.
-
-If there are multiple different polymorphic customizations that need to be merged, an exception must be thrown. For example, if class has a predecessor with `@JsonbPolymorphicType` and one of its interfaces also has `@JsonbPolymorphicType` set, or two or more interfaces do have `@JsonbPolymorphicType` set, then an exception must be thrown.
+If there are multiple different type polymorphic customizations that need to be merged, an exception must be thrown. Multiple inheritance of this customization is not supported.
 
 [source,java]
 ----
-@JsonbPolymorphicType({...})
+@JsonbTypeInfo({...})
 interface Vehicle {}
 
-@JsonbPolymorphicType({...})
+@JsonbTypeInfo({...})
 interface Machine {}
 
 class Car implements Vehicle, Machine {}
@@ -347,15 +342,15 @@ class Car implements Vehicle, Machine {}
 In case of the following example:
 [source,java]
 ----
-@JsonbPolymorphicType(key = "@vehicle", value = {@JsonbSubtype(alias = "car", type = Car.class)})
+@JsonbTypeInfo(key = "@vehicle", value = {@JsonbSubtype(alias = "car", type = Car.class)})
 class Vehicle {...}
 
-@JsonbPolymorphicType(key = "@car", value = {@JsonbSubtype(alias = "myCar", type = MyCar.class)})
+@JsonbTypeInfo(key = "@car", value = {@JsonbSubtype(alias = "myCar", type = MyCar.class)})
 class Car extends Vehicle {...}
 
 class MyCar extends Car {...}
 ----
-No exception is thrown since there is just one parent `@JsonbPolymorphicType` and one on the currently handled type. The order of the polymorphic information properties must be the same in which they appear in the polymorphic definition chain. Resulting JSON when serializing MyCar class would look like this:
+The order of the type information properties must be the same in which they appear in the polymorphic type chain. Resulting JSON when serializing MyCar class would look like this:
 [source,json]
 ----
 {