Skip to content

Commit fa918ff

Browse files
m0musm0mus
committed
Initial contribution
Signed-off-by: Dmitry Kornilov <dmitry.kornilov@oracle.com>
0 parents  commit fa918ff

40 files changed

+4087
-0
lines changed

‎LICENSE.md

Lines changed: 637 additions & 0 deletions
Large diffs are not rendered by default.

‎README.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Java API for JSON Binding (JSON-B)
2+
3+
JSON-B is a standard binding layer for converting Java objects to/from JSON messages. It defines a default mapping algorithm for converting existing Java classes to JSON, while enabling developers to customize the mapping process through the use of Java annotations.
4+
5+
## Links
6+
7+
- JSON-B community web site: http://json-b.net
8+
- Eclipse Project for JSON-B: https://projects.eclipse.org/projects/ee4j.jsonb
9+
- Discussion groups: jsonb-dev@eclipse.org
10+
- JSR-367 page on JCP site: https://jcp.org/en/jsr/detail?id=367
11+
- Yasson (Reference Implementation): https://github.com/eclipse-ee4j/yasson

‎api/pom.xml

Lines changed: 611 additions & 0 deletions
Large diffs are not rendered by default.

‎api/src/main/java/javax/json/bind/Jsonb.java

Lines changed: 357 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,357 @@
1+
/*
2+
* Copyright (c) 2016, 2018 Oracle and/or its affiliates. All rights reserved.
3+
*
4+
* This program and the accompanying materials are made available under the
5+
* terms of the Eclipse Public License v. 2.0, which is available at
6+
* http://www.eclipse.org/legal/epl-2.0.
7+
*
8+
* This Source Code may also be made available under the following Secondary
9+
* Licenses when the conditions for such availability set forth in the
10+
* Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
11+
* version 2 with the GNU Classpath Exception, which is available at
12+
* https://www.gnu.org/software/classpath/license.html.
13+
*
14+
* SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
15+
*/
16+
17+
package javax.json.bind;
18+
19+
import java.io.InputStream;
20+
import java.io.OutputStream;
21+
import java.io.Reader;
22+
import java.io.Writer;
23+
import java.lang.reflect.Type;
24+
25+
/**
26+
* <p>{@code Jsonb} provides an abstraction over the JSON Binding framework operations:</p>
27+
*
28+
* <ul>
29+
* <li>{@code fromJson}: read JSON input, deserialize to Java objects content tree
30+
* <li>{@code toJson}: serialize Java objects content tree to JSON input
31+
* </ul>
32+
*
33+
* <p>Instance of this class is created using {@link javax.json.bind.JsonbBuilder JsonbBuilder}
34+
* builder methods:</p>
35+
* <pre>{@code
36+
* // Example 1 - Creating Jsonb using default JsonbBuilder instance provided by default JsonbProvider
37+
* Jsonb jsonb = JsonbBuilder.create();
38+
*
39+
* // Example 2 - Creating Jsonb instance for a specific provider specified by a class name
40+
* Jsonb jsonb = JsonbBuilder.newBuilder("foo.bar.ProviderImpl).build();
41+
*
42+
* // Example 3 - Creating Jsonb instance from a custom provider implementation
43+
* Jsonb jsonb = new CustomJsonbBuilder().build();
44+
* }</pre>
45+
*
46+
* <b>Deserializing (reading) JSON</b><br>
47+
* <blockquote>
48+
* Can de-serialize JSON data that represents either an entire JSON
49+
* document or a subtree of a JSON document.
50+
* </blockquote>
51+
* <blockquote>
52+
* Reading (deserializing) object content tree from a File:<br><br>
53+
* <pre>
54+
* Jsonb jsonb = JsonbBuilder.create();
55+
* Book book = jsonb.fromJson(new FileReader("jsonfile.json"), Book.class);</pre>
56+
* If the deserialization process is unable to deserialize the JSON content to an object
57+
* content tree, fatal error is reported that terminates processing by
58+
* throwing JsonbException.
59+
* </blockquote>
60+
*
61+
* <p><b>Serializing (writing) to JSON</b></p>
62+
* <blockquote>
63+
* Serialization writes the representation of a Java object content tree into
64+
* JSON data.
65+
* </blockquote>
66+
* <blockquote>
67+
* Writing (serializing) object content tree to a File:<br><br>
68+
* <pre>
69+
* jsonb.toJson(object, new FileWriter("foo.json"));</pre>
70+
* Writing (serializing) to a Writer:<br><br>
71+
* <pre>
72+
* jsonb.toJson(object, new PrintWriter(System.out));
73+
* </pre>
74+
* </blockquote>
75+
*
76+
* <p><b>Encoding</b></p>
77+
* <blockquote>
78+
* In deserialization operations ({@code fromJson}), encoding of JSON data is detected automatically.
79+
* Use the {@link javax.json.bind.JsonbConfig JsonbConfig} API to configure expected
80+
* input encoding used within deserialization operations. Client applications are
81+
* expected to supply a valid character encoding as defined in the
82+
* <a href="http://tools.ietf.org/html/rfc7159">RFC 7159</a> and supported by Java Platform.
83+
*
84+
* In serialization operations ({@code toJson}), UTF-8 encoding is used by default
85+
* for writing JSON data.
86+
* Use the {@link javax.json.bind.JsonbConfig JsonbConfig} API to configure the
87+
* output encoding used within serialization operations. Client applications are
88+
* expected to supply a valid character encoding as defined in the
89+
* <a href="http://tools.ietf.org/html/rfc7159">RFC 7159</a> and supported by Java Platform.
90+
* </blockquote>
91+
*
92+
* <p>For optimal use, {@code JsonbBuilder} and {@code Jsonb} instances should be
93+
* reused - for a typical use-case, only one {@code Jsonb} instance is
94+
* required by an application.</p>
95+
*
96+
* <p>All the methods in this class are safe for use by multiple concurrent threads.</p>
97+
*
98+
* <p>Calling {@code Closable.close()} method will cleanup all CDI managed components
99+
* (such as adapters with CDI dependencies) created during interaction with Jsonb.
100+
* Calling {@code close()} must be done after all threads has finished interaction with Jsonb.
101+
* If there are remaining threads working with Jsonb and {@code close()} is called, behaviour is undefined.
102+
* </p>
103+
*
104+
* @see Jsonb
105+
* @see JsonbBuilder
106+
* @see java.util.ServiceLoader
107+
* @since JSON Binding 1.0
108+
*/
109+
public interface Jsonb extends AutoCloseable {
110+
111+
/**
112+
* Reads in a JSON data from the specified string and return the resulting
113+
* content tree.
114+
*
115+
* @param str
116+
* The string to deserialize JSON data from.
117+
* @param type
118+
* Type of the content tree's root object.
119+
* @param <T>
120+
* Type of the content tree's root object.
121+
*
122+
* @return the newly created root object of the java content tree
123+
*
124+
* @throws JsonbException
125+
* If any unexpected error(s) occur(s) during deserialization.
126+
* @throws NullPointerException
127+
* If any of the parameters is {@code null}.
128+
*/
129+
<T> T fromJson(String str, Class<T> type) throws JsonbException;
130+
131+
/**
132+
* Reads in a JSON data from the specified string and return the resulting
133+
* content tree.
134+
*
135+
* @param str
136+
* The string to deserialize JSON data from.
137+
* @param runtimeType
138+
* Runtime type of the content tree's root object.
139+
* @param <T>
140+
* Type of the content tree's root object.
141+
*
142+
* @return the newly created root object of the java content tree
143+
*
144+
* @throws JsonbException
145+
* If any unexpected error(s) occur(s) during deserialization.
146+
* @throws NullPointerException
147+
* If any of the parameters is {@code null}.
148+
*/
149+
<T> T fromJson(String str, Type runtimeType) throws JsonbException;
150+
151+
/**
152+
* Reads in a JSON data from the specified Reader and return the
153+
* resulting content tree.
154+
*
155+
* @param reader
156+
* The character stream is read as a JSON data.
157+
* @param type
158+
* Type of the content tree's root object.
159+
* @param <T>
160+
* Type of the content tree's root object.
161+
*
162+
* @return the newly created root object of the java content tree
163+
*
164+
* @throws JsonbException
165+
* If any unexpected error(s) occur(s) during deserialization.
166+
* @throws NullPointerException
167+
* If any of the parameters is {@code null}.
168+
*/
169+
<T> T fromJson(Reader reader, Class<T> type) throws JsonbException;
170+
171+
/**
172+
* Reads in a JSON data from the specified Reader and return the
173+
* resulting content tree.
174+
*
175+
* @param reader
176+
* The character stream is read as a JSON data.
177+
*
178+
* @param runtimeType
179+
* Runtime type of the content tree's root object.
180+
*
181+
* @param <T>
182+
* Type of the content tree's root object.
183+
*
184+
* @return the newly created root object of the java content tree
185+
*
186+
* @throws JsonbException
187+
* If any unexpected error(s) occur(s) during deserialization.
188+
* @throws NullPointerException
189+
* If any of the parameters is {@code null}.
190+
*/
191+
<T> T fromJson(Reader reader, Type runtimeType) throws JsonbException;
192+
193+
/**
194+
* Reads in a JSON data from the specified InputStream and return the
195+
* resulting content tree.
196+
*
197+
* @param stream
198+
* The stream is read as a JSON data. Upon a
199+
* successful completion, the stream will be closed by this method.
200+
* @param type
201+
* Type of the content tree's root object.
202+
* @param <T>
203+
* Type of the content tree's root object.
204+
*
205+
* @return the newly created root object of the java content tree
206+
*
207+
* @throws JsonbException
208+
* If any unexpected error(s) occur(s) during deserialization.
209+
* @throws NullPointerException
210+
* If any of the parameters is {@code null}.
211+
*/
212+
<T> T fromJson(InputStream stream, Class<T> type) throws JsonbException;
213+
214+
/**
215+
* Reads in a JSON data from the specified InputStream and return the
216+
* resulting content tree.
217+
*
218+
* @param stream
219+
* The stream is read as a JSON data. Upon a
220+
* successful completion, the stream will be closed by this method.
221+
*
222+
* @param runtimeType
223+
* Runtime type of the content tree's root object.
224+
*
225+
* @param <T>
226+
* Type of the content tree's root object.
227+
*
228+
* @return the newly created root object of the java content tree
229+
*
230+
* @throws JsonbException
231+
* If any unexpected error(s) occur(s) during deserialization.
232+
* @throws NullPointerException
233+
* If any of the parameters is {@code null}.
234+
*/
235+
<T> T fromJson(InputStream stream, Type runtimeType) throws JsonbException;
236+
237+
/**
238+
* Writes the Java object tree with root object {@code object} to a String
239+
* instance as JSON.
240+
*
241+
* @param object
242+
* The root object of the object content tree to be serialized. Must not be null.
243+
*
244+
* @return String instance with serialized JSON data.
245+
*
246+
* @throws JsonbException If any unexpected problem occurs during the
247+
* serialization, such as I/O error.
248+
* @throws NullPointerException
249+
* If any of the parameters is {@code null}.
250+
*
251+
* @since JSON Binding 1.0
252+
*/
253+
String toJson(Object object) throws JsonbException;
254+
255+
/**
256+
* Writes the Java object tree with root object {@code object} to a String
257+
* instance as JSON.
258+
*
259+
* @param object
260+
* The root object of the object content tree to be serialized. Must not be null.
261+
*
262+
* @param runtimeType
263+
* Runtime type of the content tree's root object.
264+
*
265+
* @return String instance with serialized JSON data.
266+
*
267+
* @throws JsonbException If any unexpected problem occurs during the
268+
* serialization, such as I/O error.
269+
* @throws NullPointerException
270+
* If any of the parameters is {@code null}.
271+
*
272+
* @since JSON Binding 1.0
273+
*/
274+
String toJson(Object object, Type runtimeType) throws JsonbException;
275+
276+
/**
277+
* Writes the object content tree into a Writer character stream.
278+
*
279+
* @param object
280+
* The object content tree to be serialized.
281+
* @param writer
282+
* The JSON will be sent as a character stream to the given
283+
* {@link Writer}.
284+
*
285+
* @throws JsonbException If any unexpected problem occurs during the
286+
* serialization.
287+
* @throws NullPointerException
288+
* If any of the parameters is {@code null}.
289+
*
290+
* @since JSON Binding 1.0
291+
*/
292+
void toJson(Object object, Writer writer) throws JsonbException;
293+
294+
/**
295+
* Writes the object content tree into a Writer character stream.
296+
*
297+
* @param object
298+
* The object content tree to be serialized.
299+
*
300+
* @param runtimeType
301+
* Runtime type of the content tree's root object.
302+
*
303+
* @param writer
304+
* The JSON will be sent as a character stream to the given
305+
* {@link Writer}.
306+
*
307+
* @throws JsonbException If any unexpected problem occurs during the
308+
* serialization.
309+
* @throws NullPointerException
310+
* If any of the parameters is {@code null}.
311+
*
312+
* @since JSON Binding 1.0
313+
*/
314+
void toJson(Object object, Type runtimeType, Writer writer) throws JsonbException;
315+
316+
/**
317+
* Writes the object content tree into output stream.
318+
*
319+
* @param object
320+
* The object content tree to be serialized.
321+
* @param stream
322+
* The JSON will be sent as a byte stream to the given
323+
* {@link OutputStream}. Upon a successful completion, the stream will be closed
324+
* by this method.
325+
*
326+
* @throws JsonbException If any unexpected problem occurs during the
327+
* serialization.
328+
* @throws NullPointerException
329+
* If any of the parameters is {@code null}.
330+
*
331+
* @since JSON Binding 1.0
332+
*/
333+
void toJson(Object object, OutputStream stream) throws JsonbException;
334+
335+
/**
336+
* Writes the object content tree into output stream.
337+
*
338+
* @param object
339+
* The object content tree to be serialized.
340+
*
341+
* @param runtimeType
342+
* Runtime type of the content tree's root object.
343+
*
344+
* @param stream
345+
* The JSON will be sent as a byte stream to the given
346+
* {@link OutputStream}. Upon a successful completion, the stream will be closed
347+
* by this method.
348+
*
349+
* @throws JsonbException If any unexpected problem occurs during the
350+
* serialization.
351+
* @throws NullPointerException
352+
* If any of the parameters is {@code null}.
353+
*
354+
* @since JSON Binding 1.0
355+
*/
356+
void toJson(Object object, Type runtimeType, OutputStream stream) throws JsonbException;
357+
}

0 commit comments

Comments
 (0)