Tatu Saloranta | 68bb83d | 2013-04-19 10:41:15 -0700 | [diff] [blame] | 1 | /* Jackson JSON-processor. |
| 2 | * |
| 3 | * Copyright (c) 2007- Tatu Saloranta, tatu.saloranta@iki.fi |
| 4 | */ |
| 5 | |
Tatu Saloranta | 08a6743 | 2012-01-29 16:43:38 -0800 | [diff] [blame] | 6 | package com.fasterxml.jackson.core; |
| 7 | |
Tatu Saloranta | 1252598 | 2013-02-12 22:56:57 -0800 | [diff] [blame] | 8 | import java.util.Iterator; |
| 9 | |
Tatu Saloranta | 08a6743 | 2012-01-29 16:43:38 -0800 | [diff] [blame] | 10 | /** |
| 11 | * Marker interface used to denote JSON Tree nodes, as far as |
| 12 | * the core package knows them (which is very little): mostly |
| 13 | * needed to allow {@link ObjectCodec} to have some level |
| 14 | * of interoperability. |
Tatu Saloranta | 1252598 | 2013-02-12 22:56:57 -0800 | [diff] [blame] | 15 | * Most functionality is within <code>JsonNode</code> |
Tatu Saloranta | 08a6743 | 2012-01-29 16:43:38 -0800 | [diff] [blame] | 16 | * base class in <code>mapper</code> package. |
| 17 | *<p> |
| 18 | * Note that in Jackson 1.x <code>JsonNode</code> itself |
| 19 | * was part of core package: Jackson 2.x refactored this |
| 20 | * since conceptually Tree Model is part of mapper package, |
| 21 | * and so part visible to <code>core</code> package should |
| 22 | * be minimized. |
Tatu Saloranta | 1252598 | 2013-02-12 22:56:57 -0800 | [diff] [blame] | 23 | *<p> |
| 24 | * NOTE: starting with Jackson 2.2, there is more functionality |
| 25 | * available via this class, and the intent is that this should |
| 26 | * form actual base for multiple alternative tree representations; |
| 27 | * for example, immutable trees could use different implementation |
| 28 | * than mutable trees. It should also be possible to move actual |
| 29 | * Tree Model implementation out of databind package eventually |
| 30 | * (Jackson 3?). |
Tatu Saloranta | bb63997 | 2013-08-30 21:45:13 -0700 | [diff] [blame] | 31 | * |
| 32 | * @since 2.2 |
Tatu Saloranta | 08a6743 | 2012-01-29 16:43:38 -0800 | [diff] [blame] | 33 | */ |
| 34 | public interface TreeNode |
| 35 | { |
| 36 | /* |
| 37 | /********************************************************** |
| 38 | /* Minimal introspection methods |
| 39 | /********************************************************** |
| 40 | */ |
| 41 | |
| 42 | /** |
| 43 | * Method that can be used for efficient type detection |
| 44 | * when using stream abstraction for traversing nodes. |
| 45 | * Will return the first {@link JsonToken} that equivalent |
| 46 | * stream event would produce (for most nodes there is just |
| 47 | * one token but for structured/container types multiple) |
| 48 | */ |
Francis Galiegue | 4d5def1 | 2012-09-29 12:26:42 +0200 | [diff] [blame] | 49 | JsonToken asToken(); |
Tatu Saloranta | 08a6743 | 2012-01-29 16:43:38 -0800 | [diff] [blame] | 50 | |
| 51 | /** |
Tatu Saloranta | 01ba053 | 2012-03-09 18:21:05 -0800 | [diff] [blame] | 52 | * If this node is a numeric type (as per {@link JsonToken#isNumeric}), |
Tatu Saloranta | 08a6743 | 2012-01-29 16:43:38 -0800 | [diff] [blame] | 53 | * returns native type that node uses to store the numeric value; |
| 54 | * otherwise returns null. |
| 55 | * |
| 56 | * @return Type of number contained, if any; or null if node does not |
| 57 | * contain numeric value. |
| 58 | */ |
Francis Galiegue | 4d5def1 | 2012-09-29 12:26:42 +0200 | [diff] [blame] | 59 | JsonParser.NumberType numberType(); |
Tatu Saloranta | 08a6743 | 2012-01-29 16:43:38 -0800 | [diff] [blame] | 60 | |
Tatu Saloranta | 1252598 | 2013-02-12 22:56:57 -0800 | [diff] [blame] | 61 | /** |
| 62 | * Method that returns number of child nodes this node contains: |
| 63 | * for Array nodes, number of child elements, for Object nodes, |
| 64 | * number of fields, and for all other nodes 0. |
| 65 | * |
| 66 | * @return For non-container nodes returns 0; for arrays number of |
| 67 | * contained elements, and for objects number of fields. |
| 68 | * |
| 69 | * @since 2.2 |
| 70 | */ |
| 71 | int size(); |
| 72 | |
| 73 | /** |
| 74 | * Method that returns true for all value nodes: ones that |
| 75 | * are not containers, and that do not represent "missing" nodes |
| 76 | * in the path. Such value nodes represent String, Number, Boolean |
| 77 | * and null values from JSON. |
| 78 | *<p> |
| 79 | * Note: one and only one of methods {@link #isValueNode}, |
| 80 | * {@link #isContainerNode} and {@link #isMissingNode} ever |
| 81 | * returns true for any given node. |
| 82 | * |
| 83 | * @since 2.2 |
| 84 | */ |
| 85 | boolean isValueNode(); |
| 86 | |
| 87 | /** |
| 88 | * Method that returns true for container nodes: Arrays and Objects. |
| 89 | *<p> |
| 90 | * Note: one and only one of methods {@link #isValueNode}, |
| 91 | * {@link #isContainerNode} and {@link #isMissingNode} ever |
| 92 | * returns true for any given node. |
| 93 | * |
| 94 | * @since 2.2 |
| 95 | */ |
| 96 | boolean isContainerNode(); |
| 97 | |
| 98 | /** |
| 99 | * Method that returns true for "virtual" nodes which represent |
| 100 | * missing entries constructed by path accessor methods when |
| 101 | * there is no actual node matching given criteria. |
| 102 | *<p> |
| 103 | * Note: one and only one of methods {@link #isValueNode}, |
| 104 | * {@link #isContainerNode} and {@link #isMissingNode} ever |
| 105 | * returns true for any given node. |
| 106 | * |
| 107 | * @since 2.2 |
| 108 | */ |
| 109 | boolean isMissingNode(); |
| 110 | |
| 111 | /** |
| 112 | * Method that returns true if this node is an Array node, false |
| 113 | * otherwise. |
| 114 | * Note that if true is returned, {@link #isContainerNode} |
| 115 | * must also return true. |
| 116 | * |
| 117 | * @since 2.2 |
| 118 | */ |
| 119 | boolean isArray(); |
| 120 | |
| 121 | /** |
| 122 | * Method that returns true if this node is an Object node, false |
| 123 | * otherwise. |
| 124 | * Note that if true is returned, {@link #isContainerNode} |
| 125 | * must also return true. |
| 126 | * |
| 127 | * @since 2.2 |
| 128 | */ |
| 129 | boolean isObject(); |
Tatu Saloranta | bb63997 | 2013-08-30 21:45:13 -0700 | [diff] [blame] | 130 | |
Tatu Saloranta | 08a6743 | 2012-01-29 16:43:38 -0800 | [diff] [blame] | 131 | /* |
| 132 | /********************************************************** |
Tatu Saloranta | 1252598 | 2013-02-12 22:56:57 -0800 | [diff] [blame] | 133 | /* Basic traversal through structured entries (Arrays, Objects) |
| 134 | /********************************************************** |
| 135 | */ |
| 136 | |
| 137 | /** |
| 138 | * Method for accessing value of the specified field of |
| 139 | * an object node. If this node is not an object (or it |
| 140 | * does not have a value for specified field name), or |
| 141 | * if there is no field with such name, null is returned. |
| 142 | *<p> |
| 143 | * NOTE: handling of explicit null values may vary between |
| 144 | * implementations; some trees may retain explicit nulls, others |
| 145 | * not. |
| 146 | * |
| 147 | * @return Node that represent value of the specified field, |
| 148 | * if this node is an object and has value for the specified |
| 149 | * field. Null otherwise. |
| 150 | * |
| 151 | * @since 2.2 |
| 152 | */ |
| 153 | TreeNode get(String fieldName); |
| 154 | |
| 155 | /** |
| 156 | * Method for accessing value of the specified element of |
| 157 | * an array node. For other nodes, null is returned. |
| 158 | *<p> |
| 159 | * For array nodes, index specifies |
| 160 | * exact location within array and allows for efficient iteration |
| 161 | * over child elements (underlying storage is guaranteed to |
| 162 | * be efficiently indexable, i.e. has random-access to elements). |
| 163 | * If index is less than 0, or equal-or-greater than |
| 164 | * <code>node.size()</code>, null is returned; no exception is |
| 165 | * thrown for any index. |
| 166 | * |
| 167 | * @return Node that represent value of the specified element, |
| 168 | * if this node is an array and has specified element. |
| 169 | * Null otherwise. |
| 170 | * |
| 171 | * @since 2.2 |
| 172 | */ |
| 173 | TreeNode get(int index); |
Tatu Saloranta | 8457e63 | 2013-03-26 16:36:16 -0700 | [diff] [blame] | 174 | |
| 175 | /** |
| 176 | * Method for accessing value of the specified field of |
| 177 | * an object node. |
| 178 | * For other nodes, a "missing node" (virtual node |
| 179 | * for which {@link #isMissingNode} returns true) is returned. |
| 180 | * |
| 181 | * @return Node that represent value of the specified field, |
| 182 | * if this node is an object and has value for the specified field; |
| 183 | * otherwise "missing node" is returned. |
| 184 | * |
| 185 | * @since 2.2 |
| 186 | */ |
| 187 | TreeNode path(String fieldName); |
| 188 | |
| 189 | /** |
| 190 | * Method for accessing value of the specified element of |
| 191 | * an array node. |
| 192 | * For other nodes, a "missing node" (virtual node |
| 193 | * for which {@link #isMissingNode} returns true) is returned. |
| 194 | *<p> |
| 195 | * For array nodes, index specifies |
| 196 | * exact location within array and allows for efficient iteration |
| 197 | * over child elements (underlying storage is guaranteed to |
| 198 | * be efficiently indexable, i.e. has random-access to elements). |
| 199 | * If index is less than 0, or equal-or-greater than |
| 200 | * <code>node.size()</code>, "missing node" is returned; no exception is |
| 201 | * thrown for any index. |
| 202 | * |
| 203 | * @return Node that represent value of the specified element, |
| 204 | * if this node is an array and has specified element; |
| 205 | * otherwise "missing node" is returned. |
| 206 | * |
| 207 | * @since 2.2 |
| 208 | */ |
| 209 | TreeNode path(int index); |
Tatu Saloranta | 1252598 | 2013-02-12 22:56:57 -0800 | [diff] [blame] | 210 | |
| 211 | /** |
| 212 | * Method for accessing names of all fields for this node, iff |
| 213 | * this node is an Object node. Number of field names accessible |
| 214 | * will be {@link #size}. |
| 215 | * |
| 216 | * @since 2.2 |
| 217 | */ |
| 218 | Iterator<String> fieldNames(); |
Tatu Saloranta | bb63997 | 2013-08-30 21:45:13 -0700 | [diff] [blame] | 219 | |
| 220 | /** |
Tatu Saloranta | a12195a | 2013-09-02 21:24:15 -0700 | [diff] [blame] | 221 | * Method for locating node specified by given JSON pointer instances. |
| 222 | * Method will never return null; if no matching node exists, |
| 223 | * will return a node for which {@link TreeNode#isMissingNode()} returns true. |
Tatu Saloranta | bb63997 | 2013-08-30 21:45:13 -0700 | [diff] [blame] | 224 | * |
| 225 | * @return Node that matches given JSON Pointer: if no match exists, |
Tatu Saloranta | a12195a | 2013-09-02 21:24:15 -0700 | [diff] [blame] | 226 | * will return a node for which {@link TreeNode#isMissingNode()} returns true. |
Tatu Saloranta | bb63997 | 2013-08-30 21:45:13 -0700 | [diff] [blame] | 227 | * |
| 228 | * @since 2.3 |
| 229 | */ |
Tatu Saloranta | 808d5fc | 2013-09-03 20:30:42 -0700 | [diff] [blame] | 230 | TreeNode at(JsonPointer ptr); |
Tatu Saloranta | a12195a | 2013-09-02 21:24:15 -0700 | [diff] [blame] | 231 | |
| 232 | /** |
| 233 | * Convenience method that is functionally equivalent to: |
| 234 | *<pre> |
Tatu Saloranta | d493cf0 | 2013-09-03 18:27:30 -0700 | [diff] [blame] | 235 | * return at(JsonPointer.valueOf(jsonPointerExpression)); |
Tatu Saloranta | a12195a | 2013-09-02 21:24:15 -0700 | [diff] [blame] | 236 | *</pre> |
| 237 | *<p> |
| 238 | * Note that if the same expression is used often, it is preferable to construct |
| 239 | * {@link JsonPointer} instance once and reuse it: this method will not perform |
| 240 | * any caching of compiled expressions. |
| 241 | * |
Tatu Saloranta | d493cf0 | 2013-09-03 18:27:30 -0700 | [diff] [blame] | 242 | * @param jsonPointerExpression Expression to compile as a {@link JsonPointer} |
| 243 | * instance |
| 244 | * |
Tatu Saloranta | a12195a | 2013-09-02 21:24:15 -0700 | [diff] [blame] | 245 | * @return Node that matches given JSON Pointer: if no match exists, |
| 246 | * will return a node for which {@link TreeNode#isMissingNode()} returns true. |
| 247 | * |
| 248 | * @since 2.3 |
| 249 | */ |
Tatu Saloranta | 32e4e91 | 2014-01-26 19:59:28 -0800 | [diff] [blame] | 250 | TreeNode at(String jsonPointerExpression) throws IllegalArgumentException; |
Tatu Saloranta | 1252598 | 2013-02-12 22:56:57 -0800 | [diff] [blame] | 251 | |
| 252 | /* |
| 253 | /********************************************************** |
| 254 | /* Converting to/from Streaming API |
Tatu Saloranta | 08a6743 | 2012-01-29 16:43:38 -0800 | [diff] [blame] | 255 | /********************************************************** |
| 256 | */ |
| 257 | |
| 258 | /** |
| 259 | * Method for constructing a {@link JsonParser} instance for |
| 260 | * iterating over contents of the tree that this node is root of. |
| 261 | * Functionally equivalent to first serializing tree using |
| 262 | * {@link ObjectCodec} and then re-parsing but |
| 263 | * more efficient. |
Cowtowncoder | 0334f7e | 2014-11-21 15:54:58 -0800 | [diff] [blame] | 264 | *<p> |
| 265 | * NOTE: constructed parser instance will NOT initially point to a token, |
| 266 | * so before passing it to deserializers, it is typically necessary to |
| 267 | * advance it to the first available token by calling {@link JsonParser#nextToken()}. |
| 268 | *<p> |
| 269 | * Also note that calling this method will <b>NOT</b> pass {@link ObjectCodec} |
| 270 | * reference, so data-binding callback methods like {@link JsonParser#readValueAs(Class)} |
| 271 | * will not work with calling {@link JsonParser#setCodec}). |
| 272 | * It is often better to call {@link #traverse(ObjectCodec)} to pass the codec explicitly. |
Tatu Saloranta | 08a6743 | 2012-01-29 16:43:38 -0800 | [diff] [blame] | 273 | */ |
Francis Galiegue | 4d5def1 | 2012-09-29 12:26:42 +0200 | [diff] [blame] | 274 | JsonParser traverse(); |
Tatu Saloranta | 08a6743 | 2012-01-29 16:43:38 -0800 | [diff] [blame] | 275 | |
Tatu Saloranta | e4061af | 2013-02-26 14:37:30 -0800 | [diff] [blame] | 276 | /** |
| 277 | * Same as {@link #traverse()}, but additionally passes {@link com.fasterxml.jackson.core.ObjectCodec} |
| 278 | * to use if {@link JsonParser#readValueAs(Class)} is used (otherwise caller must call |
| 279 | * {@link JsonParser#setCodec} on response explicitly). |
Cowtowncoder | 0334f7e | 2014-11-21 15:54:58 -0800 | [diff] [blame] | 280 | *<p> |
| 281 | * NOTE: constructed parser instance will NOT initially point to a token, |
| 282 | * so before passing it to deserializers, it is typically necessary to |
| 283 | * advance it to the first available token by calling {@link JsonParser#nextToken()}. |
Tatu Saloranta | e4061af | 2013-02-26 14:37:30 -0800 | [diff] [blame] | 284 | * |
| 285 | * @since 2.1 |
| 286 | */ |
| 287 | JsonParser traverse(ObjectCodec codec); |
Tatu Saloranta | 08a6743 | 2012-01-29 16:43:38 -0800 | [diff] [blame] | 288 | } |