1 /* Jackson JSON-processor. 2 * 3 * Copyright (c) 2007- Tatu Saloranta, tatu.saloranta@iki.fi 4 */ 5 6 package com.fasterxml.jackson.core; 7 8 import java.io.IOException; 9 import java.util.Iterator; 10 11 import com.fasterxml.jackson.core.type.ResolvedType; 12 import com.fasterxml.jackson.core.type.TypeReference; 13 14 /** 15 * Abstract class that defines the interface that {@link JsonParser} and 16 * {@link JsonGenerator} use to serialize and deserialize regular 17 * Java objects (POJOs aka Beans). 18 *<p> 19 * The standard implementation of this class is 20 * <code>com.fasterxml.jackson.databind.ObjectMapper</code>, 21 * defined in the "jackson-databind". 22 */ 23 public abstract class ObjectCodec 24 extends TreeCodec // since 2.3 25 implements Versioned // since 2.3 26 { ObjectCodec()27 protected ObjectCodec() { } 28 29 // Since 2.3 30 @Override version()31 public abstract Version version(); 32 33 /* 34 /********************************************************** 35 /* API for de-serialization (JSON-to-Object) 36 /********************************************************** 37 */ 38 39 /** 40 * Method to deserialize JSON content into a non-container 41 * type (it can be an array type, however): typically a bean, array 42 * or a wrapper type (like {@link java.lang.Boolean}). 43 *<p> 44 * Note: this method should NOT be used if the result type is a 45 * container ({@link java.util.Collection} or {@link java.util.Map}. 46 * The reason is that due to type erasure, key and value types 47 * can not be introspected when using this method. 48 */ readValue(JsonParser p, Class<T> valueType)49 public abstract <T> T readValue(JsonParser p, Class<T> valueType) 50 throws IOException; 51 52 /** 53 * Method to deserialize JSON content into a Java type, reference 54 * to which is passed as argument. Type is passed using so-called 55 * "super type token" 56 * and specifically needs to be used if the root type is a 57 * parameterized (generic) container type. 58 */ readValue(JsonParser p, TypeReference<T> valueTypeRef)59 public abstract <T> T readValue(JsonParser p, TypeReference<T> valueTypeRef) 60 throws IOException; 61 62 /** 63 * Method to deserialize JSON content into a POJO, type specified 64 * with fully resolved type object (so it can be a generic type, 65 * including containers like {@link java.util.Collection} and 66 * {@link java.util.Map}). 67 */ readValue(JsonParser p, ResolvedType valueType)68 public abstract <T> T readValue(JsonParser p, ResolvedType valueType) 69 throws IOException; 70 71 /** 72 * Method for reading sequence of Objects from parser stream, 73 * all with same specified value type. 74 */ readValues(JsonParser p, Class<T> valueType)75 public abstract <T> Iterator<T> readValues(JsonParser p, Class<T> valueType) 76 throws IOException; 77 78 /** 79 * Method for reading sequence of Objects from parser stream, 80 * all with same specified value type. 81 */ readValues(JsonParser p, TypeReference<T> valueTypeRef)82 public abstract <T> Iterator<T> readValues(JsonParser p, TypeReference<T> valueTypeRef) 83 throws IOException; 84 85 /** 86 * Method for reading sequence of Objects from parser stream, 87 * all with same specified value type. 88 */ readValues(JsonParser p, ResolvedType valueType)89 public abstract <T> Iterator<T> readValues(JsonParser p, ResolvedType valueType) 90 throws IOException; 91 92 /* 93 /********************************************************** 94 /* API for serialization (Object-to-JSON) 95 /********************************************************** 96 */ 97 98 /** 99 * Method to serialize given Java Object, using generator 100 * provided. 101 */ writeValue(JsonGenerator gen, Object value)102 public abstract void writeValue(JsonGenerator gen, Object value) throws IOException; 103 104 /* 105 /********************************************************** 106 /* TreeCodec pass-through methods 107 /********************************************************** 108 */ 109 110 /** 111 * Method to deserialize JSON content as tree expressed 112 * using set of {@link TreeNode} instances. Returns 113 * root of the resulting tree (where root can consist 114 * of just a single node if the current event is a 115 * value event, not container). Empty or whitespace 116 * documents return null. 117 * 118 * @return next tree from p, or null if empty. 119 */ 120 @Override readTree(JsonParser p)121 public abstract <T extends TreeNode> T readTree(JsonParser p) throws IOException; 122 123 @Override writeTree(JsonGenerator gen, TreeNode tree)124 public abstract void writeTree(JsonGenerator gen, TreeNode tree) throws IOException; 125 126 /** 127 * Method for construct root level Object nodes 128 * for Tree Model instances. 129 */ 130 @Override createObjectNode()131 public abstract TreeNode createObjectNode(); 132 133 /** 134 * Method for construct root level Array nodes 135 * for Tree Model instances. 136 */ 137 @Override createArrayNode()138 public abstract TreeNode createArrayNode(); 139 140 /** 141 * Method for constructing a {@link JsonParser} for reading 142 * contents of a JSON tree, as if it was external serialized 143 * JSON content. 144 */ 145 @Override treeAsTokens(TreeNode n)146 public abstract JsonParser treeAsTokens(TreeNode n); 147 148 /* 149 /********************************************************** 150 /* Extended tree conversions beyond TreeCodec 151 /********************************************************** 152 */ 153 154 /** 155 * Convenience method for converting given JSON tree into instance of specified 156 * value type. This is equivalent to first constructing a {@link JsonParser} to 157 * iterate over contents of the tree, and using that parser for data binding. 158 */ treeToValue(TreeNode n, Class<T> valueType)159 public abstract <T> T treeToValue(TreeNode n, Class<T> valueType) 160 throws JsonProcessingException; 161 162 /* 163 /********************************************************** 164 /* Basic accessors 165 /********************************************************** 166 */ 167 168 /** 169 * @deprecated Since 2.1: Use {@link #getFactory} instead. 170 */ 171 @Deprecated getJsonFactory()172 public JsonFactory getJsonFactory() { return getFactory(); } 173 174 /** 175 * Accessor for finding underlying data format factory 176 * ({@link JsonFactory}) codec will use for data binding. 177 * 178 * @since 2.1 179 */ getFactory()180 public JsonFactory getFactory() { return getJsonFactory(); } 181 } 182