michael@0: package org.json.simple.parser;
michael@0: 
michael@0: import java.io.IOException;
michael@0: 
michael@0: /**
michael@0:  * A simplified and stoppable SAX-like content handler for stream processing of JSON text. 
michael@0:  * 
michael@0:  * @see org.xml.sax.ContentHandler
michael@0:  * @see org.json.simple.parser.JSONParser#parse(java.io.Reader, ContentHandler, boolean)
michael@0:  * 
michael@0:  * @author FangYidong<fangyidong@yahoo.com.cn>
michael@0:  */
michael@0: public interface ContentHandler {
michael@0: 	/**
michael@0: 	 * Receive notification of the beginning of JSON processing.
michael@0: 	 * The parser will invoke this method only once.
michael@0:      * 
michael@0: 	 * @throws ParseException 
michael@0: 	 * 			- JSONParser will stop and throw the same exception to the caller when receiving this exception.
michael@0: 	 */
michael@0: 	void startJSON() throws ParseException, IOException;
michael@0: 	
michael@0: 	/**
michael@0: 	 * Receive notification of the end of JSON processing.
michael@0: 	 * 
michael@0: 	 * @throws ParseException
michael@0: 	 */
michael@0: 	void endJSON() throws ParseException, IOException;
michael@0: 	
michael@0: 	/**
michael@0: 	 * Receive notification of the beginning of a JSON object.
michael@0: 	 * 
michael@0: 	 * @return false if the handler wants to stop parsing after return.
michael@0: 	 * @throws ParseException
michael@0:      *          - JSONParser will stop and throw the same exception to the caller when receiving this exception.
michael@0:      * @see #endJSON
michael@0: 	 */
michael@0: 	boolean startObject() throws ParseException, IOException;
michael@0: 	
michael@0: 	/**
michael@0: 	 * Receive notification of the end of a JSON object.
michael@0: 	 * 
michael@0: 	 * @return false if the handler wants to stop parsing after return.
michael@0: 	 * @throws ParseException
michael@0:      * 
michael@0:      * @see #startObject
michael@0: 	 */
michael@0: 	boolean endObject() throws ParseException, IOException;
michael@0: 	
michael@0: 	/**
michael@0: 	 * Receive notification of the beginning of a JSON object entry.
michael@0: 	 * 
michael@0: 	 * @param key - Key of a JSON object entry. 
michael@0: 	 * 
michael@0: 	 * @return false if the handler wants to stop parsing after return.
michael@0: 	 * @throws ParseException
michael@0:      * 
michael@0:      * @see #endObjectEntry
michael@0: 	 */
michael@0: 	boolean startObjectEntry(String key) throws ParseException, IOException;
michael@0: 	
michael@0: 	/**
michael@0: 	 * Receive notification of the end of the value of previous object entry.
michael@0: 	 * 
michael@0: 	 * @return false if the handler wants to stop parsing after return.
michael@0: 	 * @throws ParseException
michael@0:      * 
michael@0:      * @see #startObjectEntry
michael@0: 	 */
michael@0: 	boolean endObjectEntry() throws ParseException, IOException;
michael@0: 	
michael@0: 	/**
michael@0: 	 * Receive notification of the beginning of a JSON array.
michael@0: 	 * 
michael@0: 	 * @return false if the handler wants to stop parsing after return.
michael@0: 	 * @throws ParseException
michael@0:      * 
michael@0:      * @see #endArray
michael@0: 	 */
michael@0: 	boolean startArray() throws ParseException, IOException;
michael@0: 	
michael@0: 	/**
michael@0: 	 * Receive notification of the end of a JSON array.
michael@0: 	 * 
michael@0: 	 * @return false if the handler wants to stop parsing after return.
michael@0: 	 * @throws ParseException
michael@0:      * 
michael@0:      * @see #startArray
michael@0: 	 */
michael@0: 	boolean endArray() throws ParseException, IOException;
michael@0: 	
michael@0: 	/**
michael@0: 	 * Receive notification of the JSON primitive values:
michael@0: 	 * 	java.lang.String,
michael@0: 	 * 	java.lang.Number,
michael@0: 	 * 	java.lang.Boolean
michael@0: 	 * 	null
michael@0: 	 * 
michael@0: 	 * @param value - Instance of the following:
michael@0: 	 * 			java.lang.String,
michael@0: 	 * 			java.lang.Number,
michael@0: 	 * 			java.lang.Boolean
michael@0: 	 * 			null
michael@0: 	 * 
michael@0: 	 * @return false if the handler wants to stop parsing after return.
michael@0: 	 * @throws ParseException
michael@0: 	 */
michael@0: 	boolean primitive(Object value) throws ParseException, IOException;
michael@0: 		
michael@0: }