java api for json binding - introduction and update

Copyright © 2014, Oracle and/or its affiliates. All rights reserved.

Java API for JSON BindingIntroduction and update

Martin Grebac JSON-‐B Spec lead Development Manager TopLink & Metro Oracle

Accept: application/json


Program Agenda

Introduction

JSR; Status; Next Steps

API

Integration

Q & A

1

2

3

4

5

4


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.

5


Introduction

6


What is JSON Binding?

• Converting Java objects to & from JSON

7




8

public class Employee { public int id; public String firstName; public String lastName; public String email; …. }




9

!Employee e = new Employee(); e.id = 1111; e.firstName = “Martin”; e.lastName = “Grebac”; e.email = “[email protected]”;




9

!Employee e = new Employee(); e.id = 1111; e.firstName = “Martin”; e.lastName = “Grebac”; e.email = “[email protected]”;

{ "id": 1111, "firstName" : "Martin", "lastName" : "Grebac", "email": "[email protected]" }




10

JAX-‐RS

Objects

XML

JSON

JAXB

JSON-‐B


Standardizing current technology

• Many mature or emerging JSON binding frameworks out there

11

!• Jackson • Genson • Gson • EclipseLink

MOXy • Fleece • JSON-‐lib • Flexjson • Json-‐io • JSONiJ • Xstream • …


Standard API -‐ Advantages

• Switch providers easily • Implementation compete on common ground (performance or feature-‐wise) • Loss of implementation/participant is no issue for standard • More people able to help on forums or stackoverflow ;) even those not using your implementation of choice

12


JSR; Status; Next Steps

14


Status

• JSR Proposal Submitted • https://www.jcp.org/en/jsr/detail?id=367

JSR 367 – Java API for JSON Binding (JSON-‐B)

15

https://www.jcp.org/en/jsr/detail?id=367



Proposal – In short• API with similar feel to JAXB !• javax.json.bind !• Spec project: http://jsonb-‐spec.java.net (stay tuned) !• RI project: http://eclipselink.org !• Standalone, looking for Java EE 8

http://jsonb-spec.java.net

http://eclipselink.org


Status


• JSR Review period finished 08/Sep/2014 • JSR Review ballot finished 22/Sep/2014


17




Status


• JSR Review period finished 08/Sep/2014 • JSR Review ballot finished 22/Sep/2014 !• Accepting EG nominations:

• https://www.jcp.org/en/jsr/egnom?id=367


18




Next StepsJSR 367 – Java API for JSON Binding (JSON-‐B)

19

• Form Expert Group • Early Draft


Next StepsJSR 367 – Java API for JSON Binding (JSON-‐B)

20

• Form Expert Group • Early Draft


API – Goals, Non-‐goals -‐ Proposal

21


Proposal – Goals• Binding JSON (RFC 7159) documents •Maintain consistency with JAXB API and other Java SE & EE APIs where applicable • Define default object-‐JSON mapping • Annotation based customizations for object-‐JSON mapping • Support binding using JSON-‐P APIs !• Explore mapping subset of Json documents (Json Pointer) • Explore options to map 3rd party objects • Explore bi-‐directional mappings


Proposal – Non-‐goals• JSON Schema • Tooltime • Roundtrip • JEP 198 -‐ Lightweight JSON API


Runtime API -‐ ProposalAnything subject to change anytime

24


import javax.json.bind.*; !public void init() { !

JsonContext context = JsonContext.newInstance(); !// JsonContext context = // JsonContext.newInstance(“com.provider.ProviderFactory");

!Marshaller marshaller = context.createMarshaller(); !Unmarshaller unmarshaller = context.createUnmarshaller; !

}

Proposal – Runtime Initialization – Default


public void init() { !

JsonContext context = new JsonContextBuilder() .setScope (MyClass.class, …) .excludeField(“field”, MyClass.class) .addFilter(myContextFilterImplementation) .build();

}

Proposal – Runtime Initialization – Context Builder


public void init() { !JsonContext context = JsonContext.newInstance(); !Marshaller marshaller = context.createMarshaller() .setProperty(Marshaller.PROPERTY) .setPrettyPrinting(true); !Unmarshaller unmarshaller = context.createUnmarshaller() .setCloseStreams(true); !

}

Proposal – Runtime Initialization – Fluent


public void marshal() { !!

Marshaller marshaller = jsonContext.createMarshaller(); !//to String String string = marshaller.marshal(myObject); !//to Writer marshaller.marshal(myObject, new FileWriter(“file.json”)); !!

}

Proposal – Marshalling (Writing)


public void marshal() { !

Marshaller marshaller = jsonContext.createMarshaller(); !//to JSONP JsonGenerator FileWriter writer = new FileWriter(“file.json”); JsonGenerator generator = Json.createGenerator(writer); marshaller.marshal(myObject, generator); !//expose as JSONP JsonParser JsonParser parser = marshaller.getJsonParser(myObject); !//other JSONP constructs JsonObjectBuilder, … !

}

Proposal – Marshalling (Writing)


public void unmarshal() { !

Unmarshaller unmarshaller = jsonContext.createUnmarshaller(); !//from String String s = "{\"field\":\"Value\"}"; MyClass myInstance1 = (MyClass) unmarshaller.unmarshal(s); MyClass myInstance2 = unmarshaller.unmarshal(s, MyClass.class); !//from Reader unmarshaller.unmarshal(new FileReader("file.json")); !

}

Proposal – Unmarshalling (Reading)



Unmarshaller unmarshaller = jsonContext.createUnmarshaller(); !//from JSONP JsonParser File stream = new FileInputStream(“file.json”); JsonParser jsonParser = Json.createParser(stream); !MyClass myInstance = unmarshaller.unmarshal(jsonParser); !//other JSONP constructs … JsonStructure, JsonObject, JsonArray … !

}




Unmarshaller u = jsonContext.createUnmarshaller(); !//expose JSONP JsonGenerator UnmarshallerJsonGenerator generator = u.getJsonGenerator(); generator.write(…); generator.write(…); … MyClass myInstance = (MyClass) generator.getResult(); !

}



!String myString = Jsonb.marshal(myObject); !MyObject object = Jsonb.unmarshal(someJsonString, MyObject.class); !… !

Proposal – The Shortcut -‐ Jsonb


Mapping API -‐ Proposal

34


Proposal – Default Mapping – Primitive types

char _char; “_char" : "c", String _string; "_string" : “string”, !byte _byte; "_byte" : 123, short _short; "_short" : 32767, int _int; "_int" : 2147483647, long _long; "_long" : 9223372036854775807, float _float; "_float" : 3.4028235E38, double _double; "_double" : 1.7976931348623157E308, !boolean _boolean; "_boolean" : true, Boolean _Boolean; "_Boolean" : false, Byte _Byte; “_Byte" : 127, Short _Short; "_Short" : 32767, Integer _Integer; "_Integer" : 2147483647, Long _Long; "_Long" : 9223372036854775807,

Float _Float; "_Float" : 3.4028235E38, Double _Double; "_Double" : 1.7976931348623157E308, !//defaults -‐ Jackson: "NaN", Moxy: NaN //Genson throws exception … Float _NaNFloat = Float.NaN; !//same as above Double _NaNDouble = Double.NaN; BigInteger _BigInteger; "_BigInteger" : 4611686014132, BigDecimal _BigDecimal; "_BigDecimal" : 850705917302332501249, !String[] _stringArr; “_stringArr" : [ "abc", "def", "ghi" ], int[] _intArray; "_intArr" : [ 123, 456, 789 ], !String[] _stringArrSingle; "_stringArrSingle" : [ "abc" ], int[] _intArrSingle; "_intArrSingle" : [ 123 ]


Proposal – Default Mapping – Dates

• Date • Calendar • JDK 8 Date&Time API !• Adapter / JsonDe/serializer, … • JsonFormat annotation • .useDateFormat(new SimpleDateFormat(…)) • .setDateFormat(new SimpleDateFormat(…))

Proposal – Default Mapping -‐ Dates -‐ JsonAdapter

public class DateAdapter implements JsonAdapter<Date> { public String marshal(Date d) {…} public Date unmarshal(String s) {…} } !public class Parent { @JsonJavaTypeAdapter(DateAdapter.class) public Date date; }


Proposal – Default Mapping -‐ Enum

@JsonEnum public enum Options { @JsonEnumValue(“1”) OPTION_1, @JsonEnumValue(“2”) OPTION_2, @JsonEnumValue(“3”) OPTION_3; }

{ “option” : 1 } !!!!!{ “option” : 1 }

option : OPTION_1


Proposal – Null value handling -‐ Default

public String longDescription; !

{ } !!!!!!!{ }

longDescription : null (do not redefine)


Proposal – Null value handling -‐ JsonNillable

@JsonNillable(true) public String longDescription; !

{ “longDescription” : null } !!!!!{ “longDescription” : null }

longDescription : null


Proposal – Customized Mapping -‐ Names

@JsonProperty(“longdesc”); public String longDescription; !

{ “longdesc” : “This is long description”, } !!!!!{ “longdesc” : “This is long description”, }

longDescription : “This is long description”


Proposal – Customized Mapping -‐ Names

private String longDescription; !@JsonProperty(“long-‐desc”); public String getLongDescription() {

return longDescription; } !@JsonProperty(“longDesc”); public void setLongDescription(String ld) { this.longDescription = ld; }

{ “longDesc” : “This is long description”, } !!!!!{ “long-‐desc” : “This is long description”, }



Proposal – Customized Mapping – Ignoring fields,properties

@JsonTransient public String longDescription;

{ “longDesc” : “This is long description”, } !!!!!!{ }



@JsonTransient public String longDescription;

!!!!!!!!!{ }

longDescription : “This is not the long description from json document”



private String longDescription; !@JsonTransient public String getLongDescription() {

return longDescription; } !public void setLongDescription(String ld) { this.longDescription = ld; }

{ “longDesc” : “This is long description”, } !!!!!{ }




private String longDescription; !public String getLongDescription() {

return longDescription; } !@JsonTransient public void setLongDescription(String ld) { this.longDescription = ld; }

{ “longDesc” : “This is long description” } !!!!!{ “longDesc” : “Different description” }

longDescription : “Different description”


Proposal – Customized Mapping – Ordering

@JsonPropertyOrder(“title”, “author”) public class Employee { public String author; public String title; }

!!!!!!!{ “title” : “Effective Java”, “author” : “Joshua Bloch” }

Book: : author : title


Proposal – Customized Mapping – Access

@JsonAccessorType(JsonAccessType.FIELD) public class Employee { private String author; private String title; } !NONE FIELD PUBLIC PROTECTED_PUBLIC ANY … ?


Proposal – Simple value mapping

public class Description { private String longDescription; ! @JsonValue public String getLongDescription() {

return longDescription; } ! public void setLongDescription(String ld) { this.longDescription = ld; } }

!!!!!!!!{ “title” : “Title”, “author” : “Author Name”, “description” : “This is long description”, “summary” : “Summary”, }

Description: : longDescription = “This is long description”

Book: : title : author : longDescription : summary


Need joke to cool down …

50


@mgrebac

51


http://www.tehnrd.com/



• Hear someone talking about how cool, efficient, and great to work with Jason is …



• Hear someone talking about how cool, efficient, and great to work with Jason is … !• … and then realizing they are talking about JSON!


Proposal -‐ Inheritance, Polymorphism@JsonDiscriminatorProperty(“type”) public abstract class ContactInfo {} !!public class Address extends ContactInfo { public String street; } !!public class Email extends ContactInfo { public String email; } !!public class Phone extends ContactInfo { public String phoneNumber; } !


Proposal -‐ Inheritance, Polymorphism@JsonDiscriminatorProperty(“type”) public abstract class ContactInfo {} !@JsonDiscriminatorValue(“address-‐type”) public class Address extends ContactInfo { public String street; } !@JsonDiscriminatorValue(“email-‐type”) public class Email extends ContactInfo { public String email; } !@JsonDiscriminatorValue(“phone-‐type”) public class Phone extends ContactInfo { public String phoneNumber; } !


Proposal -‐ Inheritance, Polymorphism@JsonDiscriminatorProperty(“type”) public abstract class ContactInfo {} !@JsonDiscriminatorValue(“address-‐type”) public class Address extends ContactInfo { public String street; } !@JsonDiscriminatorValue(“email-‐type”) public class Email extends ContactInfo { public String email; } !@JsonDiscriminatorValue(“phone-‐type”) public class Phone extends ContactInfo { public String phoneNumber; } !

!{ “type” : “address-‐type”, “street” : “1099 Lombard Street” } !!!!{ “type” : “email-‐type”, “email” : “[email protected]” }

Address

Email


Proposal – Inheritance, Polymorphism supporting@JsonSeeAlso( {Address.class, Phone.class, Email.class} ) @JsonDiscriminatorProperty(“type”) public abstract class ContactInfo {}


Proposal – Instantiation – Factories, Constructors

public class CreatedClass { @JsonCreator public static CreatedClass create() { return new CreatedClass(); } } !public class ConstrClass { public ConstrClass( @JsonProperty(“name”) name, @JsonProperty(“email”) email) { … } }

{ “created” : { }, “constructed” : { “email” : “[email protected]”, “name” : “Larry Ellison” } }

ParentClass { // by CreatedClass.create() CreatedClass created; ! /* by new ConstrClass( “[email protected]”, “Larry Ellison” ) */ ConstructedClass constructed; }


Proposal – Lifecycle events

@JsonPreUnmarshal @JsonPostUnmarshal !@JsonPreMarshal @JsonPostMarshal


Explore mapping 3rd party objects• Mix-‐in annotations (Jackson) • External metadata format (MOXy) • …

Explore binding JSON document subset -‐ JSONPointer ?{ "title": "Recent Uploads tagged javaone", "link": "http://www.flickr.com/photos/tags/javaone/", "description": "", "modified": "2014-‐03-‐22T16:40:19Z", "generator": "http://www.flickr.com/", "items": [ { "title": "IMG_1377", "link": "http://www.flickr.com/photos/soniaauv/13332491484/", "media": {"m":"http://farm4.staticflickr.com/3788/13332491484_a96c2599e8_m.jpg"}, "date_taken": "2007-‐05-‐07T12:33:19-‐08:00", "description": " …<\/p> ", "published": "2014-‐03-‐22T16:40:19Z", "author": "[email protected] (S.O.N.I.A. ETS)", "author_id": "117446064@N05", "tags": "javaone preparations 2007 vision:outdoor=0983 vision:plant=0872" }, { "title": "IMG_1388", "link": "http://www.flickr.com/photos/soniaauv/13332247843/", "media": {"m":"http://farm3.staticflickr.com/2824/13332247843_f5805b59fd_m.jpg"}, "date_taken": "2007-‐05-‐07T21:45:56-‐08:00", "description": " …<\/p> ", "published": "2014-‐03-‐22T16:40:26Z", "author": "[email protected] (S.O.N.I.A. ETS)", "author_id": "117446064@N05", "tags": "javaone preparations 2007 vision:mountain=0853 vision:sky=0722" }, …

{

public class FlickrExtract { ! @JsonPointer(“/link”) public String linkUrl; @JsonPointer(“/items/0/title”) public String firstPictureTitle; !}

Explore binding JSON document subset -‐ JSONPointer ?{ "title": "Recent Uploads tagged javaone", "link": "http://www.flickr.com/photos/tags/javaone/", "description": "", "modified": "2014-‐03-‐22T16:40:19Z", "generator": "http://www.flickr.com/", "items": [ { "title": "IMG_1377", "link": "http://www.flickr.com/photos/soniaauv/13332491484/", "media": {"m":"http://farm4.staticflickr.com/3788/13332491484_a96c2599e8_m.jpg"}, "date_taken": "2007-‐05-‐07T12:33:19-‐08:00", "description": " …<\/p> ", "published": "2014-‐03-‐22T16:40:19Z", "author": "[email protected] (S.O.N.I.A. ETS)", "author_id": "117446064@N05", "tags": "javaone preparations 2007 vision:outdoor=0983 vision:plant=0872" }, { "title": "IMG_1388", "link": "http://www.flickr.com/photos/soniaauv/13332247843/", "media": {"m":"http://farm3.staticflickr.com/2824/13332247843_f5805b59fd_m.jpg"}, "date_taken": "2007-‐05-‐07T21:45:56-‐08:00", "description": " …<\/p> ", "published": "2014-‐03-‐22T16:40:26Z", "author": "[email protected] (S.O.N.I.A. ETS)", "author_id": "117446064@N05", "tags": "javaone preparations 2007 vision:mountain=0853 vision:sky=0722" }, …

{

public class FlickrExtract { ! @JsonPointer(“/items/0/media”) public Media media; !} !public class Media { public String m; }

Explore binding JSON document subset -‐ JSONPath ?{ "title": "Recent Uploads tagged javaone", "link": "http://www.flickr.com/photos/tags/javaone/", "description": "", "modified": "2014-‐03-‐22T16:40:19Z", "generator": "http://www.flickr.com/", "items": [ { "title": "IMG_1377", "link": "http://www.flickr.com/photos/soniaauv/13332491484/", "media": {"m":"http://farm4.staticflickr.com/3788/13332491484_a96c2599e8_m.jpg"}, "date_taken": "2007-‐05-‐07T12:33:19-‐08:00", "description": " …<\/p> ", "published": "2014-‐03-‐22T16:40:19Z", "author": "[email protected] (S.O.N.I.A. ETS)", "author_id": "117446064@N05", "tags": "javaone preparations 2007 vision:outdoor=0983 vision:plant=0872" }, { "title": "IMG_1388", "link": "http://www.flickr.com/photos/soniaauv/13332247843/", "media": {"m":"http://farm3.staticflickr.com/2824/13332247843_f5805b59fd_m.jpg"}, "date_taken": "2007-‐05-‐07T21:45:56-‐08:00", "description": " …<\/p> ", "published": "2014-‐03-‐22T16:40:26Z", "author": "[email protected] (S.O.N.I.A. ETS)", "author_id": "117446064@N05", "tags": "javaone preparations 2007 vision:mountain=0853 vision:sky=0722" }, …

{

public class FlickrExtract { ! @JsonPath(“$.link”) public String linkUrl; @JsonPath(“$.items.*.title”) public String[] pictureTitles; !}


Integration

64


Affected, used, under consideration specifications

• JSR 353 – Java API for JSON Processing (JSON-‐P) • JSR 339 – Java API for RESTful services (JAX-‐RS) • JSR 349 – Bean Validation (BV) • JSR ??? – JEP 198 – Light-‐Weight JSON API

65


JAX-‐RS

• JAX-‐RS allowed to standardize on JSON-‐Binding • Custom JSON-‐Binding

66


JSON-‐P

• Already covered

67


JPA

• Explore mapping bidirectional references

Back-‐reference (Inverse reference) support

68

public class A { @JsonManagedReference public B getB(); } !public class B { @JsonBackReference public A getA(); }

public class A { public B getB(); } !!public class B { @XmlInverseReference(mappedBy=“b”) public A getA(); }


Call to ACTION!• Participate as an observer

• users@jsonb-‐spec.java.net • Join EG

• https://jcp.org/en/jsr/detail?id=367

69


Q & A• Participate as an observer

• users@jsonb-‐spec.java.net • Join EG

• https://jcp.org/en/jsr/detail?id=367

70


Related Talk(s)

• CON5742 -‐ JSON Pointer and JSON Patch: Updates to the Java API for JSON Processing • Kin-‐Man Chung • Tuesday, September 30, 4-‐5pm, Cyril Magnin II/III

71


Sources, References

• https://jcp.org/en/jsr/detail?id=367 • http://www.developer.com/lang/jscript/top-‐7-‐open-‐source-‐json-‐binding-‐providers-‐available-‐today.html • http://goessner.net/articles/JsonPath/ • http://eclipselink.org

72

https://jcp.org/en/jsr/detail?id=367

http://www.developer.com/lang/jscript/top-7-open-source-json-binding-providers-available-today.html

http://goessner.net/articles/JsonPath/

http://eclipselink.org


My JSON joke fell flat because I got the quotes wrong.

– Jeff Waugh’s tweet

73


Safe Harbor Statement

The preceding 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.

74

java api for json binding - introduction and update

Software