Why javax.json containts only interfaces?

Question

An example from the docs:

JsonArray value = Json.createArrayBuilder()
     .add(Json.createObjectBuilder()
         .add("type", "home")
         .add("number", "212 555-1234"))
     .add(Json.createObjectBuilder()
         .add("type", "fax")
         .add("number", "646 555-4567"))
     .build();

But JsonArray is an interface, not a class, and a variable's type can't be an interface. So where is class JsonArray? I guess the package javax.json contains it, but why isn't it documented?

Not a big deal though, I've already read the interfaces' details, it shows all the needed methods/constructors/return types, and now I know how to use these "classes".

Possible duplicate of [What is an interface in Java?](http://stackoverflow.com/questions/1321122/what-is-an-interface-in-java) — Winter, Sep 26 '16 at 16:47
Java EE is only a specification; it has no implementation. Third parties must implement the specification. Usually, your code should only depend on java EE sepcification. You then provide an implementation on the classpath at runtime. Javax.json is part (or will eventually be part of) Java EE. — Jazzwave06, Sep 26 '16 at 16:53
“…a variable’s type can’t be an interface.” That is flat-out incorrect. I promise you `List names = new ArrayList<>();` is valid. In fact, `Serializable names = new ArrayList();` is valid. — VGR, Sep 26 '16 at 17:33
@VGR [Indeed](http://stackoverflow.com/questions/8406250/variable-of-interface-type). Good to know, thanks. — klenium, Sep 26 '16 at 19:26

score 2 · Answer 1 · answered Sep 26 '16 at 16:55

The documentation you're reading is about the API as defined in the JSR 353 specification. Different projects can provide an implementation for the API. For example, this page links to the reference implementation.

Other projects like genson provide their own implementation of the standard.

score 1 · Answer 2 · answered Sep 26 '16 at 16:56

Why javax.json containts only interfaces?

Because, on purpose, the implementers want to hide the details of implementation and allow you to create instances only though factory methods (as opposed to instantiating them by new)

So where is class JsonArray? ... but why isn't it documented?

Somewhere well hidden in a private package, probably starting with com.sun. Even if you find it, it would be very unwise to use it directly, because they may change the implementation in the very next jdk security update, breaking any code relying on undocumented features.

score 1 · Accepted Answer · answered Sep 26 '16 at 16:58

Java EE is a specification; it has no implementation. It relies on third-parties to implement the specification. javax.json package is part (or will eventually be part of) java EE. Therefore, including this jar will only provide you with the interface to a json api. You will be required to provide an implementation at runtime for it to work. Usually, your code should be agnostic to the implementation even if, in the fact, this is easier said than done.

Why javax.json containts only interfaces?

3 Answers3