Introduction to Yasson

Copyright © 2017, Oracle and/or its affiliates. All rights reserved.
Introduction to Yasson
Dmitry Kornilov
JSONB Spec Lead
@m0mus
26 Oct 2017

Safe Harbor Statement
The following is intended to outline our general product direction. It is intended for
information purposes only, and may not be incorporated into any contract. It is not a
commitment to deliver any material, code, or functionality, and should not be relied upon
in making purchasing decisions. The development, release, and timing of any features or
functionality described for Oracle’s products remains at the sole discretion of Oracle.
2

Copyright © 2017, Oracle and/or its affiliates. All rights reserved. 3
Dmitry Kornilov
• Senior Manager @ Oracle
• JSON-B (JSR-367) spec lead
• JSON-P (JSR-374) spec lead
• Outstanding Spec Lead 2016
• EclipseLink project committer
• EE4J PMC Member

Program Agenda
JSON Technologies in Java EE 8
JSON Binding
Yasson
Q & A
1
2
3
5
4

JSON Technologies in Java EE 8
5

What is JSON???

This is Jason
7

This is also Jason
8

What is JSON?
• JavaScript Object Notation
• Subset of JavaScript
• Lightweight data-interchange format
• Object, Array, Value
9
{
"name": "Jason Bourne",
"age": 35,
"phoneNumbers": [
{
"type": "home",
"number": "123-456-789"
}
]
}

JSON Support in Java EE 8
• JSON Processing API
– Standard API to parse, generate, transform, query JSON
– Object Model and Streaming API
• similar to DOM and StAX
• JSON Binding API
– Binding JSON documents to Java objects
• similar to JAXB
10

JSON Binding
11

JSON-B Links
• Official web: http://json-b.net
• GitHub repo: https://github.com/javaee/jsonb-spec
• Issues Tracker: https://github.com/javaee/jsonb-spec/issues
• JCP page: https://www.jcp.org/en/jsr/detail?id=367
• Groups: https://javaee.groups.io/g/jsonb-spec
12

JSON Binding
• API to serialize/deserialize Java objects to/from JSON documents
– Similar to JAX-B
– Standardizes the current technologies (Jackson, Genson, Gson)
• Default mapping between classes and JSON
• Customization APIs
– Annotations (@JsonbProperty, @JsonbNillable)
– Runtime configuration builder
• Natural follow on to JSON-P
– Closes the JSON support gap
– Allows to change providers
13

• JSON-B (JSON Binding)
– API and Specification
– JSR-367
– Part of Java EE 8
14
JSON-B and Yasson
• Yasson
– Reference Implementation
– Eclipse Foundation Project
– Part of GlassFish 5
– Part of WAS Liberty

Yasson
15

Yasson Links
• Web site: https://projects.eclipse.org/projects/rt.yasson
• GitHub repo: https://github.com/eclipse/yasson
• Issues Tracker: https://github.com/eclipse/yasson/issues
16

Maven Dependencies
17

<dependency>
<groupId>javax.json.bind</groupId>
<artifactId>javax.json.bind-api</artifactId>
<version>1.0</version>
</dependency>

<dependency>
<groupId>org.eclipse</groupId>
<artifactId>yasson</artifactId>
<version>1.0</version>
</dependency>
<repositories>
<repository>
<id>Yasson Snapshots</id>
<url>https://repo.eclipse.org/content/repositories/
yasson-snapshots/</url>
</repository>
</repositories>

• No configuration, no annotations
• The scope:
– Basic Types
– Specific JDK Types
– Dates
– Classes
– Collections/Arrays
– Enumerations
– JSON-P
18
Default Mapping
import javax.json.bind.Jsonb;
import javax.json.bind.JsonbBuilder;
// Create with default config
Jsonb jsonb = JsonbBuilder.create();

JSON-B Engine
public interface Jsonb extends AutoCloseable {
<T> T fromJson(String str, Class<T> type);
<T> T fromJson(String str, Type runtimeType);
<T> T fromJson(Reader reader, Class<T> type);
<T> T fromJson(Reader reader, Type runtimeType);
<T> T fromJson(InputStream stream, Class<T> type);
<T> T fromJson(InputStream stream, Type runtimeType);
String toJson(Object object);
String toJson(Object object, Type runtimeType);
void toJson(Object object, Writer writer);
void toJson(Object object, Type runtimeType, Writer writer);
void toJson(Object object, OutputStream stream);
void toJson(Object object, Type runtimeType, OutputStream stream);
}

JSON-B Sample
20
Person person1 = new Person();
person1.setName("Jason Voorhees");
person1.setProfession("Maniac killer");
person1.setAge(45);
Person person2 = new Person();
person2.setName("Jason Bourne");
person2.setProfession("Super agent");
person2.setAge(35);
List<Person> persons = new ArrayList<>();
persons.add(person1);
persons.add(person2);
Jsonb jsonb = JsonbBuilder.create();
jsonb.toJson(persons);
[
{
"name": "Jason Voorhees",
"profession": "Maniac killer",
"age": 45
},
{
"name": "Jason Bourne",
"profession": "Super agent",
"age": 35
}
]

Basic Types
– java.lang.String
– java.lang.Character
– java.lang.Byte (byte)
– java.lang.Short (short)
– java.lang.Integer (int)
– java.lang.Long (long)
– java.lang.Float (float)
– java.lang.Double (double)
– java.lang.Boolean (boolean)
Specific Types
– java.math.BigInteger
– java.math.BigDecimal
– java.net.URL
– java.net.URI
– java.util.Optional
– java.util.OptionalInt
– java.util.OptionalLong
– java.util.OptionalDouble
21
Basic and Specific Types

Date/Time
22
java.util.Date ISO_DATE_TIME
java.util.Calendar, java.util.GregorianCalendar ISO_DATE if to time information present, otherwise ISO_DATE_TIME
Java.util.TimeZone, java.util.SimpleTimeZone NormalizedCustomId (see TimeZone javadoc)
java.time.Instant ISO_INSTANT
java.time.LocalDate ISO_LOCAL_DATE
java.time.LocalTime ISO_LOCAL_TIME
java.time.LocalDateTime ISO_LOCAL_DATE_TIME
java.time.ZonedDateTime ISO_ZONED_DATE_TIME
java.time.OffsetDateTime ISO_OFFSET_DATE_TIME
java.time.OffsetTime ISO_OFFSET_TIME
java.time.ZoneId NormalizedZoneId as specified in ZoneId javadoc
java.time.ZoneOffset NormalizedZoneId as specified in ZoneOffset javadoc
java.time.Duration ISO 8601 seconds based representation
java.time.Period ISO 8601 period representation

Date/Time Samples
23
// java.util.Date
SimpleDateFormat sdf = new SimpleDateFormat("dd.MM.yyyy");
Date parsedDate = sdf.parse("15.11.2016");
jsonb.toJson(parsedDate)); // ”2016-11-15T00:00:00"
// java.util.Calendar
Calendar dateCalendar = Calendar.getInstance();
dateCalendar.clear();
dateCalendar.set(2016, 11, 15);
jsonb.toJson(dateCalendar); // ”2016-11-15”
// java.time.Instant
jsonb.toJson(Instant.parse("2016-11-15T23:00:00Z")); // ”2016-11-15T23:00:00Z”
// java.time.Duration
jsonb.toJson(Duration.ofHours(5).plusMinutes(4)); // “PT5H4M"
// java.time.Period
jsonb.toJson(Period.between(
LocalDate.of(1960, Month.JANUARY, 1),
LocalDate.of(1970, Month.JANUARY, 1))); // "P10Y"

Arrays/Collections
• Collection
• Map
• Set
• HashSet
• NavigableSet
• SortedSet
• TreeSet
• LinkedHashSet
• HashMap
• NavigableMap
• SortedMap
• TreeMap
• LinkedHashMap
• List
• ArrayList
• LinkedList
• Deque
• ArrayDeque
• Queue
• PriorityQueue
24

• javax.json.JsonArray
• javax.json.JsonStructure
• javax.json.JsonValue
• javax.json.JsonPointer
• javax.json.JsonString
• javax.json.JsonNumber
• javax.json.JsonObject
25
JSON-P Types
// JsonObject
JsonBuilderFactory f =
Json.createBuilderFactory(null);
JsonObject jsonObject =
f.createObjectBuilder()
.add(“name", "Jason Bourne")
.add(“city", "Prague")
.build();
jsonb.toJson(jsonObject);

Classes
• Public and protected static nested classes
• Anonymous classes (serialization only)
• Inheritance is supported
• Default no-argument constructor is required for deserialization
26

Fields
• Final fields are serialized
• Static fields are skipped
• Transient fields are skipped
• Null fields are skipped
• Fields order
– Lexicographical order
– Parent class fields are serialized before child class fields
27

public class Parent {
public int parentB;
public int parentA;
}
{
"parentA": 1,
"parentB": 2
}
28
Fields Order Sample

public class Parent {
public int parentB;
public int parentA;
}
public class Child extends Parent {
public int childB;
public int childA;
}
{
"parentA": 1,
"parentB": 2
}
{
"parentA": 1,
"parentB": 2,
"childA": 3,
"childB": 4
}
29
Fields Order Sample

Serialization
• Existing fields with public getters
• Public fields with no getters
• Public getter/setter pair without a
corresponding field
Deserialization
• Existing fields with public setters
• Public fields with no setters
• Public getter/setter pair without a
corresponding field
30
Scope and Field Access Strategy

public class Foo {
public final int publicFinalField;
private final int privateFinalField;
public static int publicStaticField;
public int publicWithNoGetter;
public int publicWithPrivateGetter;
public Integer publicNullField = null;
private int privateWithNoGetter;
private int privateWithPublicGetter;
public int getNoField() {};
public void setNoField(int value) {};
}
{
"publicFinalField": 1,
"publicWithNoGetter": 1,
"privateWithPublicGetter": 1,
"noField": 1
}
31
Scope and Field Access Strategy

• Annotations
• Runtime configuration
– JsonbConfig
– JsonbBuilder
32
Yasson Configuration
JsonbConfig config = new JsonbConfig()
.withFormatting(…)
.withNullValues(…)
.withEncoding(…)
.withStrictIJSON(…)
.withPropertyNamingStrategy(…)
.withPropertyOrderStrategy(…)
.withPropertyVisibilityStrategy(…)
.withAdapters(…)
.withBinaryDataStrategy(…);
Jsonb jsonb = JsonbBuilder.newBuilder()
.withConfig(…)
.withProvider(…)
.build();

Customizations
• Property names
• Property order
• Ignoring properties
• Null handling
• Custom instantiation
• Fields visibility
• Date/Number Formats
• Binary Encoding
• Adapters
• Serializers/Deserializers

• Annotation
– @JsonbProperty
• Scope:
– Field
– Getter/Setter
– Parameter
34
Property Names
public class Customer {
private int id;
@JsonbProperty("name")
public String firstName;
}
public int id;
public String firstName;
@JsonbProperty("name")
public String getFirstName() {
return firstName;
}
}

Property Naming Strategy
• Supported naming strategies
– IDENTITY (myMixedCaseProperty)
– LOWER_CASE_WITH_DASHES (my-mixed-case-property)
– LOWER_CASE_WITH_UNDERSCORES (my_mixed_case_property)
– UPPER_CAMEL_CASE (MyMixedCaseProperty)
– UPPER_CAMEL_CASE_WITH_SPACES (My Mixed Case Property)
– CASE_INSENSITIVE (mYmIxEdCaSePrOpErTy)
– Or a custom implementation
• JsonbConfig
– withPropertyNamingStrategy(…):
35

• Strategies:
– LEXICOGRAPHICAL (A-Z)
– ANY
– REVERSE (Z-A)
• Annotation
– @JsonbPropertyOrder on class
• JsonbConfig
– withPropertyOrderStrategy(…)
36
Property Order Strategy
@JsonbPropertyOrder("bar2", "bar1")
public class Foo {
public int bar2;
public int bar1;
}

• Annotation
– @JsonbTransient
37
Ignoring Properties
public int id;
public String name;
@JsonbTransient
public BigDecimal salary;
}

• PropertyVisibilityStrategy
interface
• Annotation
– @JsonbVisibility
• JsonbConfig
– withPropertyVisibilityStrategy(…)
38
Property Visibility
public interface PropertyVisibilityStrategy {
boolean isVisible(Field field);
boolean isVisible(Method method);
}
public class MyStrategy implements
PropertyVisibilityStrategy {
/* ... */
}
@JsonbVisibility(MyStrategy.class)
public class Bar {
private int field1;
private int field2;
}

• Null fields are skipped by default
• Annotation
– @JsonbNillable
• JsonbConfig
– withNullValues(true)
39
Null Handling
public int id = 1;
@JsonbProperty("name", true)
public String name = null;
}
@JsonbNillable
public int id = 1;
public String name = null;
}

Custom Instantiation
40
public String name;
@JsonbCreator
public static Customer create(
@JsonbProperty("id") int id) {
return CustomerDao.getByPrimaryKey(id);
}
}
public class Order {
public int id;
public Customer customer;
}
{
"id": 123,
"customer": {
"id": 562,
}
}

• Annotations
– @JsonbDateFormat
– @JsonbNumberFormat
• JsonbConfig
– withDateFormat(…)
– withLocale(…)
41
Date/Number Format
public class FormatSample {
public Date defaultDate;
@JsonbDateFormat("dd.MM.yyyy")
public Date formattedDate;
public BigDecimal defaultNumber;
@JsonbNumberFormat(“#0.00")
public BigDecimal formattedNumber;
}

• Supported encodings
– BYTE (default)
– BASE_64
– BASE_64_URL
• JsonbConfig
– withBinaryDataStrategy(…)
42
Binary Data Encoding
.withBinaryDataStrategy(
BinaryDataStrategy.BASE_64);
Jsonb jsonb = JsonbBuilder.create(config);
String json = jsonb.toJson(obj);

I-JSON
• I-JSON (”Internet JSON”) is a restricted profile of JSON
– https://tools.ietf.org/html/draft-ietf-json-i-json-06
• JSON-B fully supports I-JSON by default with three exceptions:
– JSON Binding does not restrict the serialization of top-level JSON texts that are
neither objects nor arrays. The restriction should happen at application level.
– JSON Binding does not serialize binary data with base64url encoding.
– JSON Binding does not enforce additional restrictions on dates/times/duration.
• JsonbConfig
– withStrictIJSON(true)
43

• Inspired by JAXB
• Annotations
– @JsonbTypeAdapter annotation
• JsonbConfig
– withAdapters(…)
44
Adapters
public interface JsonbAdapter<Original, Adapted> {
Adapted adaptToJson(Original obj);
Original adaptFromJson(Adapted obj);
}
@JsonbTypeAdapter(AnimalAdapter.class)
public Animal animal;
.withAdapters(new AnimalAdapter());

• Low level control on
serialization/deserialization
• Annotations
– @JsonbTypeSerializer
– @JsonbTypeDeserializer
• JsonbConfig
– withSerializers(…)
– withDeserializers(…)
45
Serializers/Deserializers
public interface JsonbSerializer<T> {
void serialize(T obj, JsonGenerator generator,
SerializationContext ctx);
public interface JsonbDeserializer<T> {
T deserialize(JsonParser parser,
DeserializationContext ctx, Type rtType);
}
@JsonbTypeSerializer(AnimalSerializer.class)
@JsonbTypeDeserializer(AnimalDeserializer.class)
public Animal animal;
.withSerializers(new AnimalSerializer())
.withDeserializers(new AnimalDeserializer());

JSON-B Demo
• GitHub
– https://github.com/m0mus/json_demo
• Demonstrates
– JSON-P
• JsonParser
• JsonGenerator
• Working with large files
• JsonPointer
• JsonPatch
• Using Java8 streams
46
– JSON-B
• Default mapping
• Adapters
• Serializers/Deserializers
• Mapping of generic class
• Using together with JSON-P

Q & A
47

Introduction to Yasson

Recommended

Recommended

More Related Content

What's hot

What's hot (10)

Similar to Introduction to Yasson

Similar to Introduction to Yasson (20)

More from Dmitry Kornilov

More from Dmitry Kornilov (13)

Recently uploaded

Recently uploaded (20)

Introduction to Yasson