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   * Create and return a new bean reading for the bean type given the JSON options and source.
063   * <p>
064   * Note that JsonOption provides an option for setting a persistence context and also enabling
065   * further lazy loading. Further lazy loading requires a persistence context so if that is set
066   * on then a persistence context is created if there is not one set.
067   */
068  <T> JsonBeanReader<T> createBeanReader(Class<T> cls, JsonParser parser, JsonReadOptions options) throws JsonIOException;
069
070  /**
071   * Create and return a new bean reading for the bean type given the JSON options and source.
072   * <p>
073   * Note that JsonOption provides an option for setting a persistence context and also enabling
074   * further lazy loading. Further lazy loading requires a persistence context so if that is set
075   * on then a persistence context is created if there is not one set.
076   */
077  <T> JsonBeanReader<T> createBeanReader(BeanType<T> beanType, JsonParser parser, JsonReadOptions options) throws JsonIOException;
078
079  /**
080   * Convert json string input into a list of beans of a specific type.
081   *
082   * @throws JsonIOException When IOException occurs
083   */
084  <T> List<T> toList(Class<T> rootType, String json) throws JsonIOException;
085
086  /**
087   * Convert json string input into a list of beans of a specific type additionally using JsonReadOptions.
088   *
089   * @throws JsonIOException When IOException occurs
090   */
091  <T> List<T> toList(Class<T> rootType, String json, JsonReadOptions options) throws JsonIOException;
092
093  /**
094   * Convert json reader input into a list of beans of a specific type.
095   *
096   * @throws JsonIOException When IOException occurs
097   */
098  <T> List<T> toList(Class<T> rootType, Reader json) throws JsonIOException;
099
100  /**
101   * Convert json reader input into a list of beans of a specific type additionally using JsonReadOptions.
102   *
103   * @throws JsonIOException When IOException occurs
104   */
105  <T> List<T> toList(Class<T> rootType, Reader json, JsonReadOptions options) throws JsonIOException;
106
107  /**
108   * Convert json parser input into a list of beans of a specific type.
109   *
110   * @throws JsonIOException When IOException occurs
111   */
112  <T> List<T> toList(Class<T> cls, JsonParser json) throws JsonIOException;
113
114  /**
115   * Convert json parser input into a list of beans of a specific type additionally using JsonReadOptions.
116   *
117   * @throws JsonIOException When IOException occurs
118   */
119  <T> List<T> toList(Class<T> cls, JsonParser json, JsonReadOptions options) throws JsonIOException;
120
121  /**
122   * Use the genericType to determine if this should be converted into a List or
123   * bean.
124   *
125   * @throws JsonIOException When IOException occurs
126   */
127  Object toObject(Type genericType, Reader json) throws JsonIOException;
128
129  /**
130   * Use the genericType to determine if this should be converted into a List or
131   * bean.
132   *
133   * @throws JsonIOException When IOException occurs
134   */
135  Object toObject(Type genericType, String json) throws JsonIOException;
136
137  /**
138   * Use the genericType to determine if this should be converted into a List or
139   * bean.
140   *
141   * @throws JsonIOException When IOException occurs
142   */
143  Object toObject(Type genericType, JsonParser jsonParser) throws JsonIOException;
144
145  /**
146   * Return the bean or collection as JSON string.
147   *
148   * @throws JsonIOException When IOException occurs
149   */
150  String toJson(Object value) throws JsonIOException;
151
152  /**
153   * Return the bean or collection as JSON string in pretty format.
154   *
155   * @throws JsonIOException When IOException occurs
156   */
157  String toJsonPretty(Object value) throws JsonIOException;
158
159  /**
160   * Write the bean or collection in JSON format to the writer.
161   *
162   * @throws JsonIOException When IOException occurs
163   */
164  void toJson(Object value, Writer writer) throws JsonIOException;
165
166  /**
167   * Write the bean or collection to the JsonGenerator.
168   *
169   * @throws JsonIOException When IOException occurs
170   */
171  void toJson(Object value, JsonGenerator generator) throws JsonIOException;
172
173  /**
174   * Return the bean or collection as JSON string using FetchPath.
175   *
176   * @throws JsonIOException When IOException occurs
177   */
178  String toJson(Object value, FetchPath fetchPath) throws JsonIOException;
179
180  /**
181   * Write the bean or collection as json to the writer using the FetchPath.
182   */
183  void toJson(Object value, Writer writer, FetchPath fetchPath) throws JsonIOException;
184
185  /**
186   * Write the bean or collection to the JsonGenerator using the FetchPath.
187   */
188  void toJson(Object value, JsonGenerator generator, FetchPath fetchPath) throws JsonIOException;
189
190  /**
191   * Deprecated in favour of using PathProperties by itself.
192   * Write json to the JsonGenerator using the JsonWriteOptions.
193   */
194  void toJson(Object value, JsonGenerator generator, JsonWriteOptions options) throws JsonIOException;
195
196  /**
197   * Deprecated in favour of using PathProperties by itself.
198   * With additional options.
199   *
200   * @throws JsonIOException When IOException occurs
201   */
202  void toJson(Object value, Writer writer, JsonWriteOptions options) throws JsonIOException;
203
204  /**
205   * Deprecated in favour of using PathProperties by itself.
206   * Convert a bean or collection to json string.
207   *
208   * @throws JsonIOException When IOException occurs
209   */
210  String toJson(Object value, JsonWriteOptions options) throws JsonIOException;
211
212  /**
213   * Return true if the type is known as an Entity bean or a List Set or
214   * Map of entity beans.
215   */
216  boolean isSupportedType(Type genericType);
217
218  /**
219   * Create and return a new JsonGenerator for the given writer.
220   *
221   * @throws JsonIOException When IOException occurs
222   */
223  JsonGenerator createGenerator(Writer writer) throws JsonIOException;
224
225  /**
226   * Create and return a new JsonParser for the given reader.
227   *
228   * @throws JsonIOException When IOException occurs
229   */
230  JsonParser createParser(Reader reader) throws JsonIOException;
231
232  /**
233   * Write a scalar types known to Ebean to Jackson.
234   * <p>
235   * Ebean has built in support for java8 and Joda types as well as the other
236   * standard JDK types like URI, URL, UUID etc. This is a fast simple way to
237   * write any of those types to Jackson.
238   * </p>
239   */
240  void writeScalar(JsonGenerator generator, Object scalarValue) throws IOException;
241
242}