001package io.ebean.text.json;
002
003import io.ebean.FetchPath;
004import io.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   */
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   * Write the bean or collection in JSON format to the writer.
154   *
155   * @throws JsonIOException When IOException occurs
156   */
157  void toJson(Object value, Writer writer) throws JsonIOException;
158
159  /**
160   * Write the bean or collection to the JsonGenerator.
161   *
162   * @throws JsonIOException When IOException occurs
163   */
164  void toJson(Object value, JsonGenerator generator) throws JsonIOException;
165
166  /**
167   * Return the bean or collection as JSON string using FetchPath.
168   *
169   * @throws JsonIOException When IOException occurs
170   */
171  String toJson(Object value, FetchPath fetchPath) throws JsonIOException;
172
173  /**
174   * Write the bean or collection as json to the writer using the FetchPath.
175   */
176  void toJson(Object value, Writer writer, FetchPath fetchPath) throws JsonIOException;
177
178  /**
179   * Write the bean or collection to the JsonGenerator using the FetchPath.
180   */
181  void toJson(Object value, JsonGenerator generator, FetchPath fetchPath) throws JsonIOException;
182
183  /**
184   * Deprecated in favour of using PathProperties by itself.
185   * Write json to the JsonGenerator using the JsonWriteOptions.
186   */
187  void toJson(Object value, JsonGenerator generator, JsonWriteOptions options) throws JsonIOException;
188
189  /**
190   * Deprecated in favour of using PathProperties by itself.
191   * With additional options.
192   *
193   * @throws JsonIOException When IOException occurs
194   */
195  void toJson(Object value, Writer writer, JsonWriteOptions options) throws JsonIOException;
196
197  /**
198   * Deprecated in favour of using PathProperties by itself.
199   * Convert a bean or collection to json string.
200   *
201   * @throws JsonIOException When IOException occurs
202   */
203  String toJson(Object value, JsonWriteOptions options) throws JsonIOException;
204
205  /**
206   * Return true if the type is known as an Entity bean or a List Set or
207   * Map of entity beans.
208   */
209  boolean isSupportedType(Type genericType);
210
211  /**
212   * Create and return a new JsonGenerator for the given writer.
213   *
214   * @throws JsonIOException When IOException occurs
215   */
216  JsonGenerator createGenerator(Writer writer) throws JsonIOException;
217
218  /**
219   * Create and return a new JsonParser for the given reader.
220   *
221   * @throws JsonIOException When IOException occurs
222   */
223  JsonParser createParser(Reader reader) throws JsonIOException;
224
225  /**
226   * Write a scalar types known to Ebean to Jackson.
227   * <p>
228   * Ebean has built in support for java8 and Joda types as well as the other
229   * standard JDK types like URI, URL, UUID etc. This is a fast simple way to
230   * write any of those types to Jackson.
231   * </p>
232   */
233  void writeScalar(JsonGenerator generator, Object scalarValue) throws IOException;
234
235}