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>'&quot;'</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>'&quot;'</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 ('&quot;') 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 ('&quot;') 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}