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