001package io.ebean.text.json;
002
003import com.fasterxml.jackson.core.JsonGenerator;
004import com.fasterxml.jackson.core.JsonParser;
005import io.ebean.FetchPath;
006import io.ebean.plugin.BeanType;
007
008import java.io.IOException;
009import java.io.Reader;
010import java.io.Writer;
011import java.lang.reflect.Type;
012import java.util.List;
013
014/**
015 * Converts objects to and from JSON format.
016 */
017public interface JsonContext {
018
019  /**
020   * Convert json string input into a Bean of a specific type.
021   *
022   * @throws JsonIOException When IOException occurs
023   */
024  <T> T toBean(Class<T> rootType, String json) throws JsonIOException;
025
026  /**
027   * Convert json string input into a Bean of a specific type additionally using JsonReadOptions.
028   *
029   * @throws JsonIOException When IOException occurs
030   */
031  <T> T toBean(Class<T> rootType, String json, JsonReadOptions options) throws JsonIOException;
032
033  /**
034   * Convert json reader input into a Bean of a specific type.
035   *
036   * @throws JsonIOException When IOException occurs
037   */
038  <T> T toBean(Class<T> rootType, Reader json) throws JsonIOException;
039
040  /**
041   * Convert json reader input into a Bean of a specific type additionally using JsonReadOptions.
042   *
043   * @throws JsonIOException When IOException occurs
044   */
045  <T> T toBean(Class<T> rootType, Reader json, JsonReadOptions options) throws JsonIOException;
046
047  /**
048   * Convert json parser input into a Bean of a specific type.
049   *
050   * @throws JsonIOException When IOException occurs
051   */
052  <T> T toBean(Class<T> cls, JsonParser parser) throws JsonIOException;
053
054  /**
055   * Convert json parser input into a Bean of a specific type additionally using JsonReadOptions..
056   *
057   * @throws JsonIOException When IOException occurs
058   */
059  <T> T toBean(Class<T> cls, JsonParser parser, JsonReadOptions options) throws JsonIOException;
060
061  /**
062   * Read json parser input into a given Bean. <br>
063   * Note: This is a kind of "update". Only properties in the json will be modified. Embedded Lists and Maps will become new
064   * instances, so the object identity will not be preserved here.
065   *
066   * @throws JsonIOException When IOException occurs
067   */
068  <T> void toBean(T target, JsonParser parser) throws JsonIOException;
069
070  /**
071   * Read json parser input into a given Bean additionally using JsonReadOptions.<br>
072   * See {@link #toBean(Class, JsonParser)} for details modified.
073   *
074   * @throws JsonIOException When IOException occurs
075   */
076  <T> void toBean(T target, JsonParser parser, JsonReadOptions options) throws JsonIOException;
077
078  /**
079   * Read json reader input into a given Bean.<br>
080   * See {@link #toBean(Class, JsonParser)} for details
081   *
082   * @throws JsonIOException When IOException occurs
083   */
084  <T> void toBean(T target, Reader json) throws JsonIOException;
085
086  /**
087   * Read json reader input into a given Bean additionally using JsonReadOptions.<br>
088   * See {@link #toBean(Class, JsonParser)} for details modified.
089   *
090   * @throws JsonIOException When IOException occurs
091   */
092  <T> void toBean(T target, Reader json, JsonReadOptions options) throws JsonIOException;
093
094  /**
095   * Read json string input into a given Bean.<br>
096   * See {@link #toBean(Class, JsonParser)} for details
097   *
098   * @throws JsonIOException When IOException occurs
099   */
100  <T> void toBean(T target, String json) throws JsonIOException;
101
102  /**
103   * Read json string input into a given Bean additionally using JsonReadOptions.<br>
104   * See {@link #toBean(Class, JsonParser)} for details
105   *
106   * @throws JsonIOException When IOException occurs
107   */
108  <T> void toBean(T target, String json, JsonReadOptions options) throws JsonIOException;
109
110  /**
111   * Create and return a new bean reading for the bean type given the JSON options and source.
112   * <p>
113   * Note that JsonOption provides an option for setting a persistence context and also enabling further lazy loading. Further lazy
114   * loading requires a persistence context so if that is set on then a persistence context is created if there is not one set.
115   */
116  <T> JsonBeanReader<T> createBeanReader(Class<T> cls, JsonParser parser, JsonReadOptions options) throws JsonIOException;
117
118  /**
119   * Create and return a new bean reading for the bean type given the JSON options and source.
120   * <p>
121   * Note that JsonOption provides an option for setting a persistence context and also enabling
122   * further lazy loading. Further lazy loading requires a persistence context so if that is set
123   * on then a persistence context is created if there is not one set.
124   */
125  <T> JsonBeanReader<T> createBeanReader(BeanType<T> beanType, JsonParser parser, JsonReadOptions options) throws JsonIOException;
126
127  /**
128   * Convert json string input into a list of beans of a specific type.
129   *
130   * @throws JsonIOException When IOException occurs
131   */
132  <T> List<T> toList(Class<T> rootType, String json) throws JsonIOException;
133
134  /**
135   * Convert json string input into a list of beans of a specific type additionally using JsonReadOptions.
136   *
137   * @throws JsonIOException When IOException occurs
138   */
139  <T> List<T> toList(Class<T> rootType, String json, JsonReadOptions options) throws JsonIOException;
140
141  /**
142   * Convert json reader input into a list of beans of a specific type.
143   *
144   * @throws JsonIOException When IOException occurs
145   */
146  <T> List<T> toList(Class<T> rootType, Reader json) throws JsonIOException;
147
148  /**
149   * Convert json reader input into a list of beans of a specific type additionally using JsonReadOptions.
150   *
151   * @throws JsonIOException When IOException occurs
152   */
153  <T> List<T> toList(Class<T> rootType, Reader json, JsonReadOptions options) throws JsonIOException;
154
155  /**
156   * Convert json parser input into a list of beans of a specific type.
157   *
158   * @throws JsonIOException When IOException occurs
159   */
160  <T> List<T> toList(Class<T> cls, JsonParser json) throws JsonIOException;
161
162  /**
163   * Convert json parser input into a list of beans of a specific type additionally using JsonReadOptions.
164   *
165   * @throws JsonIOException When IOException occurs
166   */
167  <T> List<T> toList(Class<T> cls, JsonParser json, JsonReadOptions options) throws JsonIOException;
168
169  /**
170   * Use the genericType to determine if this should be converted into a List or
171   * bean.
172   *
173   * @throws JsonIOException When IOException occurs
174   */
175  Object toObject(Type genericType, Reader json) throws JsonIOException;
176
177  /**
178   * Use the genericType to determine if this should be converted into a List or
179   * bean.
180   *
181   * @throws JsonIOException When IOException occurs
182   */
183  Object toObject(Type genericType, String json) throws JsonIOException;
184
185  /**
186   * Use the genericType to determine if this should be converted into a List or
187   * bean.
188   *
189   * @throws JsonIOException When IOException occurs
190   */
191  Object toObject(Type genericType, JsonParser jsonParser) throws JsonIOException;
192
193  /**
194   * Return the bean or collection as JSON string.
195   *
196   * @throws JsonIOException When IOException occurs
197   */
198  String toJson(Object value) throws JsonIOException;
199
200  /**
201   * Return the bean or collection as JSON string in pretty format.
202   *
203   * @throws JsonIOException When IOException occurs
204   */
205  String toJsonPretty(Object value) throws JsonIOException;
206
207  /**
208   * Write the bean or collection in JSON format to the writer.
209   *
210   * @throws JsonIOException When IOException occurs
211   */
212  void toJson(Object value, Writer writer) throws JsonIOException;
213
214  /**
215   * Write the bean or collection to the JsonGenerator.
216   *
217   * @throws JsonIOException When IOException occurs
218   */
219  void toJson(Object value, JsonGenerator generator) throws JsonIOException;
220
221  /**
222   * Return the bean or collection as JSON string using FetchPath.
223   *
224   * @throws JsonIOException When IOException occurs
225   */
226  String toJson(Object value, FetchPath fetchPath) throws JsonIOException;
227
228  /**
229   * Write the bean or collection as json to the writer using the FetchPath.
230   */
231  void toJson(Object value, Writer writer, FetchPath fetchPath) throws JsonIOException;
232
233  /**
234   * Write the bean or collection to the JsonGenerator using the FetchPath.
235   */
236  void toJson(Object value, JsonGenerator generator, FetchPath fetchPath) throws JsonIOException;
237
238  /**
239   * Deprecated in favour of using PathProperties by itself.
240   * Write json to the JsonGenerator using the JsonWriteOptions.
241   */
242  void toJson(Object value, JsonGenerator generator, JsonWriteOptions options) throws JsonIOException;
243
244  /**
245   * Deprecated in favour of using PathProperties by itself.
246   * With additional options.
247   *
248   * @throws JsonIOException When IOException occurs
249   */
250  void toJson(Object value, Writer writer, JsonWriteOptions options) throws JsonIOException;
251
252  /**
253   * Deprecated in favour of using PathProperties by itself.
254   * Convert a bean or collection to json string.
255   *
256   * @throws JsonIOException When IOException occurs
257   */
258  String toJson(Object value, JsonWriteOptions options) throws JsonIOException;
259
260  /**
261   * Return true if the type is known as an Entity bean or a List Set or
262   * Map of entity beans.
263   */
264  boolean isSupportedType(Type genericType);
265
266  /**
267   * Create and return a new JsonGenerator for the given writer.
268   *
269   * @throws JsonIOException When IOException occurs
270   */
271  JsonGenerator createGenerator(Writer writer) throws JsonIOException;
272
273  /**
274   * Create and return a new JsonParser for the given reader.
275   *
276   * @throws JsonIOException When IOException occurs
277   */
278  JsonParser createParser(Reader reader) throws JsonIOException;
279
280  /**
281   * Write a scalar types known to Ebean to Jackson.
282   * <p>
283   * Ebean has built in support for java8 and Joda types as well as the other
284   * standard JDK types like URI, URL, UUID etc. This is a fast simple way to
285   * write any of those types to Jackson.
286   * </p>
287   */
288  void writeScalar(JsonGenerator generator, Object scalarValue) throws IOException;
289
290}