    001/* ============
    002 * Orson Charts
    003 * ============
    004 *
    005 * (C)opyright 2013, 2014, by Object Refinery Limited.
    006 *
    007 * http://www.object-refinery.com/orsoncharts/index.html
    008 *
    009 * JSON.simple
    010 * -----------
    011 * The code in this file originates from the JSON.simple project by
    012 * FangYidong<fangyidong@yahoo.com.cn>:
    013 *
    014 *     https://code.google.com/p/json-simple/
    015 *
    016 * which is licensed under the Apache Software License version 2.0.
    017 *
    018 * It has been modified locally and repackaged under
    019 * com.orsoncharts.util.json.* to avoid conflicts with any other version that
    020 * may be present on the classpath.
    021 *
    022 */
    023
    024package com.orsoncharts.util.json.parser;
    025
    026import java.io.IOException;
    027
    028/**
    029 * A simplified and stoppable SAX-like content handler for stream processing of
    030 * JSON text.
    031 *
    032 * @see com.orsoncharts.util.json.parser.JSONParser#parse(java.io.Reader,
    033 *     ContentHandler, boolean)
    034 */
    035public interface ContentHandler {
    036
    037    /**
    038     * Receive notification of the beginning of JSON processing.
    039     * The parser will invoke this method only once.
    040     *
    041     * @throws ParseException  JSONParser will stop and throw the same
    042     *     exception to the caller when receiving this exception.
    043     * @throws IOException if there is an I/O problem.
    044     */
    045    void startJSON() throws ParseException, IOException;
    046
    047    /**
    048     * Receive notification of the end of JSON processing.
    049     *
    050     * @throws ParseException if there is a parsing problem.
    051     * @throws IOException if there is an I/O problem.
    052     */
    053    void endJSON() throws ParseException, IOException;
    054
    055    /**
    056     * Receive notification of the beginning of a JSON object.
    057     *
    058     * @return false if the handler wants to stop parsing after return.
    059     * @throws ParseException  JSONParser will stop and throw the same
    060     *     exception to the caller when receiving this exception.
    061     * @throws IOException if there is an I/O problem.
    062     *
    063     * @see #endJSON
    064     */
    065    boolean startObject() throws ParseException, IOException;
    066
    067    /**
    068     * Receive notification of the end of a JSON object.
    069     *
    070     * @return false if the handler wants to stop parsing after return.
    071     * @throws ParseException if there is a parsing problem.
    072     * @throws IOException if there is an I/O problem.
    073     *
    074     * @see #startObject
    075     */
    076    boolean endObject() throws ParseException, IOException;
    077
    078    /**
    079     * Receive notification of the beginning of a JSON object entry.
    080     *
    081     * @param key  key of a JSON object entry.
    082     *
    083     * @return false if the handler wants to stop parsing after return.
    084     * @throws ParseException if there is a parsing problem.
    085     * @throws IOException if there is an I/O problem.
    086     *
    087     * @see #endObjectEntry
    088     */
    089    boolean startObjectEntry(String key) throws ParseException, IOException;
    090
    091    /**
    092     * Receive notification of the end of the value of previous object entry.
    093     *
    094     * @return false if the handler wants to stop parsing after return.
    095     * @throws ParseException if there is a parsing problem.
    096     * @throws IOException if there is an I/O problem.
    097     *
    098     * @see #startObjectEntry
    099     */
    100    boolean endObjectEntry() throws ParseException, IOException;
    101
    102    /**
    103     * Receive notification of the beginning of a JSON array.
    104     *
    105     * @return false if the handler wants to stop parsing after return.
    106     * @throws ParseException if there is a parsing problem.
    107     * @throws IOException if there is an I/O problem.
    108     *
    109     * @see #endArray
    110     */
    111    boolean startArray() throws ParseException, IOException;
    112
    113    /**
    114     * Receive notification of the end of a JSON array.
    115     *
    116     * @return false  if the handler wants to stop parsing after return.
    117     * @throws ParseException if there is a parsing problem.
    118     * @throws IOException if there is an I/O problem.
    119     *
    120     * @see #startArray
    121     */
    122    boolean endArray() throws ParseException, IOException;
    123
    124    /**
    125     * Receive notification of the JSON primitive values:
    126     *     java.lang.String,
    127     *     java.lang.Number,
    128     *     java.lang.Boolean
    129     *     null
    130     *
    131     * @param value  instance of the following:
    132     *             java.lang.String,
    133     *             java.lang.Number,
    134     *             java.lang.Boolean,
    135     *             null
    136     *
    137     * @return false if the handler wants to stop parsing after return.
    138     * @throws ParseException if there is a parsing problem.
    139     * @throws IOException if there is an I/O problem.
    140     */
    141    boolean primitive(Object value) throws ParseException, IOException;
    142
    143}
    144