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