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 * A handler for parser events. Instances of this class can be given to a {@link JsonParser}. The parser will then call 026 * the methods of the given handler while reading the input. 027 * <p> 028 * The default implementations of these methods do nothing. Subclasses may override only those methods they are 029 * interested in. They can use <code>getLocation()</code> to access the current character position of the parser at any 030 * point. The <code>start*</code> methods will be called while the location points to the first character of the parsed 031 * element. The <code>end*</code> methods will be called while the location points to the character position that 032 * directly follows the last character of the parsed element. Example: 033 * </p> 034 * 035 * <pre> 036 * ["lorem ipsum"] 037 * ^ ^ 038 * startString endString 039 * </pre> 040 * <p> 041 * Subclasses that build an object representation of the parsed JSON can return arbitrary handler objects for JSON 042 * arrays and JSON objects in {@link #startArray()} and {@link #startObject()}. These handler objects will then be 043 * provided in all subsequent parser events for this particular array or object. They can be used to keep track the 044 * elements of a JSON array or object. 045 * </p> 046 * 047 * @param <A> 048 * The type of handlers used for JSON arrays 049 * @param <O> 050 * The type of handlers used for JSON objects 051 * @see JsonParser 052 */ 053public abstract class JsonHandler<A, O> { 054 055 JsonParser parser; 056 057 /** 058 * Returns the current parser location. 059 * 060 * @return the current parser location 061 */ 062 protected Location getLocation() { 063 return parser.getLocation(); 064 } 065 066 /** 067 * Indicates the beginning of a <code>null</code> literal in the JSON input. This method will be called when reading 068 * the first character of the literal. 069 */ 070 public void startNull() {} 071 072 /** 073 * Indicates the end of a <code>null</code> literal in the JSON input. This method will be called after reading the 074 * last character of the literal. 075 */ 076 public void endNull() {} 077 078 /** 079 * Indicates the beginning of a boolean literal (<code>true</code> or <code>false</code>) in the JSON input. This 080 * method will be called when reading the first character of the literal. 081 */ 082 public void startBoolean() {} 083 084 /** 085 * Indicates the end of a boolean literal (<code>true</code> or <code>false</code>) in the JSON input. This method 086 * will be called after reading the last character of the literal. 087 * 088 * @param value 089 * the parsed boolean value 090 */ 091 public void endBoolean(boolean value) {} 092 093 /** 094 * Indicates the beginning of a string in the JSON input. This method will be called when reading the opening double 095 * quote character (<code>'"'</code>). 096 */ 097 public void startString() {} 098 099 /** 100 * Indicates the end of a string in the JSON input. This method will be called after reading the closing double quote 101 * character (<code>'"'</code>). 102 * 103 * @param string 104 * the parsed string 105 */ 106 public void endString(String string) {} 107 108 /** 109 * Indicates the beginning of a number in the JSON input. This method will be called when reading the first character 110 * of the number. 111 */ 112 public void startNumber() {} 113 114 /** 115 * Indicates the end of a number in the JSON input. This method will be called after reading the last character of the 116 * number. 117 * 118 * @param string 119 * the parsed number string 120 */ 121 public void endNumber(String string) {} 122 123 /** 124 * Indicates the beginning of an array in the JSON input. This method will be called when reading the opening square 125 * bracket character (<code>'['</code>). 126 * <p> 127 * This method may return an object to handle subsequent parser events for this array. This array handler will then be 128 * provided in all calls to {@link #startArrayValue(Object) startArrayValue()}, {@link #endArrayValue(Object) 129 * endArrayValue()}, and {@link #endArray(Object) endArray()} for this array. 130 * </p> 131 * 132 * @return a handler for this array, or <code>null</code> if not needed 133 */ 134 public A startArray() { 135 return null; 136 } 137 138 /** 139 * Indicates the end of an array in the JSON input. This method will be called after reading the closing square 140 * bracket character (<code>']'</code>). 141 * 142 * @param array 143 * the array handler returned from {@link #startArray()}, or <code>null</code> if not provided 144 */ 145 public void endArray(A array) {} 146 147 /** 148 * Indicates the beginning of an array element in the JSON input. This method will be called when reading the first 149 * character of the element, just before the call to the <code>start</code> method for the specific element type 150 * ({@link #startString()}, {@link #startNumber()}, etc.). 151 * 152 * @param array 153 * the array handler returned from {@link #startArray()}, or <code>null</code> if not provided 154 */ 155 public void startArrayValue(A array) {} 156 157 /** 158 * Indicates the end of an array element in the JSON input. This method will be called after reading the last 159 * character of the element value, just after the <code>end</code> method for the specific element type (like 160 * {@link #endString(String) endString()}, {@link #endNumber(String) endNumber()}, etc.). 161 * 162 * @param array 163 * the array handler returned from {@link #startArray()}, or <code>null</code> if not provided 164 */ 165 public void endArrayValue(A array) {} 166 167 /** 168 * Indicates the beginning of an object in the JSON input. This method will be called when reading the opening curly 169 * bracket character (<code>'{'</code>). 170 * <p> 171 * This method may return an object to handle subsequent parser events for this object. This object handler will be 172 * provided in all calls to {@link #startObjectName(Object) startObjectName()}, {@link #endObjectName(Object, String) 173 * endObjectName()}, {@link #startObjectValue(Object, String) startObjectValue()}, 174 * {@link #endObjectValue(Object, String) endObjectValue()}, and {@link #endObject(Object) endObject()} for this 175 * object. 176 * </p> 177 * 178 * @return a handler for this object, or <code>null</code> if not needed 179 */ 180 public O startObject() { 181 return null; 182 } 183 184 /** 185 * Indicates the end of an object in the JSON input. This method will be called after reading the closing curly 186 * bracket character (<code>'}'</code>). 187 * 188 * @param object 189 * the object handler returned from {@link #startObject()}, or null if not provided 190 */ 191 public void endObject(O object) {} 192 193 /** 194 * Indicates the beginning of the name of an object member in the JSON input. This method will be called when reading 195 * the opening quote character ('"') of the member name. 196 * 197 * @param object 198 * the object handler returned from {@link #startObject()}, or <code>null</code> if not provided 199 */ 200 public void startObjectName(O object) {} 201 202 /** 203 * Indicates the end of an object member name in the JSON input. This method will be called after reading the closing 204 * quote character (<code>'"'</code>) of the member name. 205 * 206 * @param object 207 * the object handler returned from {@link #startObject()}, or null if not provided 208 * @param name 209 * the parsed member name 210 */ 211 public void endObjectName(O object, String name) {} 212 213 /** 214 * Indicates the beginning of the name of an object member in the JSON input. This method will be called when reading 215 * 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 provided 219 * @param name 220 * the member name 221 */ 222 public void startObjectValue(O object, String name) {} 223 224 /** 225 * Indicates the end of an object member value in the JSON input. This method will be called after reading the last 226 * character of the member value, just after the <code>end</code> method for the specific member type (like 227 * {@link #endString(String) endString()}, {@link #endNumber(String) endNumber()}, etc.). 228 * 229 * @param object 230 * the object handler returned from {@link #startObject()}, or null if not provided 231 * @param name 232 * the parsed member name 233 */ 234 public void endObjectValue(O object, String name) {} 235 236}