001/******************************************************************************* 002 * Copyright (c) 2016 EclipseSource. 003 * 004 * Permission is hereby granted, free of charge, to any person obtaining a copy 005 * of this software and associated documentation files (the "Software"), to deal 006 * in the Software without restriction, including without limitation the rights 007 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 008 * copies of the Software, and to permit persons to whom the Software is 009 * furnished to do so, subject to the following conditions: 010 * 011 * The above copyright notice and this permission notice shall be included in all 012 * copies or substantial portions of the Software. 013 * 014 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 015 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 016 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 017 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 018 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 019 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 020 * SOFTWARE. 021 ******************************************************************************/ 022package com.restfb.json; 023 024 025/** 026 * A handler for parser events. Instances of this class can be given to a {@link JsonParser}. The 027 * parser will then call the methods of the given handler while reading the input. 028 * <p> 029 * The default implementations of these methods do nothing. Subclasses may override only those 030 * methods they are interested in. They can use <code>getLocation()</code> to access the current 031 * character position of the parser at any point. The <code>start*</code> methods will be called 032 * while the location points to the first character of the parsed element. The <code>end*</code> 033 * methods will be called while the location points to the character position that directly follows 034 * the last character of the parsed element. Example: 035 * </p> 036 * 037 * <pre> 038 * ["lorem ipsum"] 039 * ^ ^ 040 * startString endString 041 * </pre> 042 * <p> 043 * Subclasses that build an object representation of the parsed JSON can return arbitrary handler 044 * objects for JSON arrays and JSON objects in {@link #startArray()} and {@link #startObject()}. 045 * These handler objects will then be provided in all subsequent parser events for this particular 046 * array or object. They can be used to keep track the elements of a JSON array or object. 047 * </p> 048 * 049 * @param <A> 050 * The type of handlers used for JSON arrays 051 * @param <O> 052 * The type of handlers used for JSON objects 053 * @see JsonParser 054 */ 055public abstract class JsonHandler<A, O> { 056 057 JsonParser parser; 058 059 /** 060 * Returns the current parser location. 061 * 062 * @return the current parser location 063 */ 064 protected Location getLocation() { 065 return parser.getLocation(); 066 } 067 068 /** 069 * Indicates the beginning of a <code>null</code> literal in the JSON input. This method will be 070 * called when reading the first character of the literal. 071 */ 072 public void startNull() { 073 } 074 075 /** 076 * Indicates the end of a <code>null</code> literal in the JSON input. This method will be called 077 * after reading the last character of the literal. 078 */ 079 public void endNull() { 080 } 081 082 /** 083 * Indicates the beginning of a boolean literal (<code>true</code> or <code>false</code>) in the 084 * JSON input. This method will be called when reading the first character of the literal. 085 */ 086 public void startBoolean() { 087 } 088 089 /** 090 * Indicates the end of a boolean literal (<code>true</code> or <code>false</code>) in the JSON 091 * input. This method will be called after reading the last character of the literal. 092 * 093 * @param value 094 * the parsed boolean value 095 */ 096 public void endBoolean(boolean value) { 097 } 098 099 /** 100 * Indicates the beginning of a string in the JSON input. This method will be called when reading 101 * the opening double quote character (<code>'"'</code>). 102 */ 103 public void startString() { 104 } 105 106 /** 107 * Indicates the end of a string in the JSON input. This method will be called after reading the 108 * closing double quote character (<code>'"'</code>). 109 * 110 * @param string 111 * the parsed string 112 */ 113 public void endString(String string) { 114 } 115 116 /** 117 * Indicates the beginning of a number in the JSON input. This method will be called when reading 118 * the first character of the number. 119 */ 120 public void startNumber() { 121 } 122 123 /** 124 * Indicates the end of a number in the JSON input. This method will be called after reading the 125 * last character of the number. 126 * 127 * @param string 128 * the parsed number string 129 */ 130 public void endNumber(String string) { 131 } 132 133 /** 134 * Indicates the beginning of an array in the JSON input. This method will be called when reading 135 * the opening square bracket character (<code>'['</code>). 136 * <p> 137 * This method may return an object to handle subsequent parser events for this array. This array 138 * handler will then be provided in all calls to {@link #startArrayValue(Object) 139 * startArrayValue()}, {@link #endArrayValue(Object) endArrayValue()}, and 140 * {@link #endArray(Object) endArray()} for this array. 141 * </p> 142 * 143 * @return a handler for this array, or <code>null</code> if not needed 144 */ 145 public A startArray() { 146 return null; 147 } 148 149 /** 150 * Indicates the end of an array in the JSON input. This method will be called after reading the 151 * closing square bracket character (<code>']'</code>). 152 * 153 * @param array 154 * the array handler returned from {@link #startArray()}, or <code>null</code> if not 155 * provided 156 */ 157 public void endArray(A array) { 158 } 159 160 /** 161 * Indicates the beginning of an array element in the JSON input. This method will be called when 162 * reading the first character of the element, just before the call to the <code>start</code> 163 * method for the specific element type ({@link #startString()}, {@link #startNumber()}, etc.). 164 * 165 * @param array 166 * the array handler returned from {@link #startArray()}, or <code>null</code> if not 167 * provided 168 */ 169 public void startArrayValue(A array) { 170 } 171 172 /** 173 * Indicates the end of an array element in the JSON input. This method will be called after 174 * reading the last character of the element value, just after the <code>end</code> method for the 175 * specific element type (like {@link #endString(String) endString()}, {@link #endNumber(String) 176 * endNumber()}, etc.). 177 * 178 * @param array 179 * the array handler returned from {@link #startArray()}, or <code>null</code> if not 180 * provided 181 */ 182 public void endArrayValue(A array) { 183 } 184 185 /** 186 * Indicates the beginning of an object in the JSON input. This method will be called when reading 187 * the opening curly bracket character (<code>'{'</code>). 188 * <p> 189 * This method may return an object to handle subsequent parser events for this object. This 190 * object handler will be provided in all calls to {@link #startObjectName(Object) 191 * startObjectName()}, {@link #endObjectName(Object, String) endObjectName()}, 192 * {@link #startObjectValue(Object, String) startObjectValue()}, 193 * {@link #endObjectValue(Object, String) endObjectValue()}, and {@link #endObject(Object) 194 * endObject()} for this object. 195 * </p> 196 * 197 * @return a handler for this object, or <code>null</code> if not needed 198 */ 199 public O startObject() { 200 return null; 201 } 202 203 /** 204 * Indicates the end of an object in the JSON input. This method will be called after reading the 205 * closing curly bracket character (<code>'}'</code>). 206 * 207 * @param object 208 * the object handler returned from {@link #startObject()}, or null if not provided 209 */ 210 public void endObject(O object) { 211 } 212 213 /** 214 * Indicates the beginning of the name of an object member in the JSON input. This method will be 215 * called when reading the opening quote character ('"') of the member name. 216 * 217 * @param object 218 * the object handler returned from {@link #startObject()}, or <code>null</code> if not 219 * provided 220 */ 221 public void startObjectName(O object) { 222 } 223 224 /** 225 * Indicates the end of an object member name in the JSON input. This method will be called after 226 * reading the closing quote character (<code>'"'</code>) of the member name. 227 * 228 * @param object 229 * the object handler returned from {@link #startObject()}, or null if not provided 230 * @param name 231 * the parsed member name 232 */ 233 public void endObjectName(O object, String name) { 234 } 235 236 /** 237 * Indicates the beginning of the name of an object member in the JSON input. This method will be 238 * called when reading the opening quote character ('"') of the member name. 239 * 240 * @param object 241 * the object handler returned from {@link #startObject()}, or <code>null</code> if not 242 * provided 243 * @param name 244 * the member name 245 */ 246 public void startObjectValue(O object, String name) { 247 } 248 249 /** 250 * Indicates the end of an object member value in the JSON input. This method will be called after 251 * reading the last character of the member value, just after the <code>end</code> method for the 252 * specific member type (like {@link #endString(String) endString()}, {@link #endNumber(String) 253 * endNumber()}, etc.). 254 * 255 * @param object 256 * the object handler returned from {@link #startObject()}, or null if not provided 257 * @param name 258 * the parsed member name 259 */ 260 public void endObjectValue(O object, String name) { 261 } 262 263}