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}