001/* Copyright 2006 FangYidong
002
003   Licensed under the Apache License, Version 2.0 (the "License");
004   you may not use this file except in compliance with the License.
005   You may obtain a copy of the License at
006
007       http://www.apache.org/licenses/LICENSE-2.0
008
009   Unless required by applicable law or agreed to in writing, software
010   distributed under the License is distributed on an "AS IS" BASIS,
011   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012   See the License for the specific language governing permissions and
013   limitations under the License. */
014package org.json.simple.parser;
015
016import java.io.IOException;
017
018/**
019 * A simplified and stoppable SAX-like content handler for stream processing of JSON text. 
020 * 
021 * 
022 * @see org.json.simple.parser.JSONParser#parse(java.io.Reader, ContentHandler, boolean)
023 * 
024 * @author FangYidong<fangyidong@yahoo.com.cn>
025 * @deprecated since 2.0.0 it doesn't extend the SAX ContentHandler promoting bad practices and incompatible code.
026 */
027@Deprecated
028public interface ContentHandler {
029        /**
030         * Receive notification of the beginning of JSON processing.
031         * The parser will invoke this method only once.
032     * 
033         * @throws ParseException 
034         *                      - JSONParser will stop and throw the same exception to the caller when receiving this exception.
035         * @throws IOException description omitted.
036         */
037        void startJSON() throws ParseException, IOException;
038        
039        /**
040         * Receive notification of the end of JSON processing.
041         * 
042         * @throws ParseException description omitted.
043         * @throws IOException description omitted.
044         */
045        void endJSON() throws ParseException, IOException;
046        
047        /**
048         * Receive notification of the beginning of a JSON object.
049         * 
050         * @return false if the handler wants to stop parsing after return.
051         * @throws ParseException
052     *          - JSONParser will stop and throw the same exception to the caller when receiving this exception.
053         * @throws IOException description omitted.
054     * @see #endJSON
055         */
056        boolean startObject() throws ParseException, IOException;
057        
058        /**
059         * Receive notification of the end of a JSON object.
060         * 
061         * @return false if the handler wants to stop parsing after return.
062         * @throws ParseException description omitted.
063         * @throws IOException description omitted.
064     * 
065     * @see #startObject
066         */
067        boolean endObject() throws ParseException, IOException;
068        
069        /**
070         * Receive notification of the beginning of a JSON object entry.
071         * 
072         * @param key - Key of a JSON object entry. 
073         * 
074         * @return false if the handler wants to stop parsing after return.
075         * @throws ParseException description omitted.
076         * @throws IOException description omitted.
077     * 
078     * @see #endObjectEntry
079         */
080        boolean startObjectEntry(String key) throws ParseException, IOException;
081        
082        /**
083         * Receive notification of the end of the value of previous object entry.
084         * 
085         * @return false if the handler wants to stop parsing after return.
086         * @throws ParseException description omitted.
087         * @throws IOException description omitted.
088     * 
089     * @see #startObjectEntry
090         */
091        boolean endObjectEntry() throws ParseException, IOException;
092        
093        /**
094         * Receive notification of the beginning of a JSON array.
095         * 
096         * @return false if the handler wants to stop parsing after return.
097         * @throws ParseException description omitted.
098         * @throws IOException description omitted.
099     * 
100     * @see #endArray
101         */
102        boolean startArray() throws ParseException, IOException;
103        
104        /**
105         * Receive notification of the end of a JSON array.
106         * 
107         * @return false if the handler wants to stop parsing after return.
108         * @throws ParseException description omitted.
109         * @throws IOException description omitted.
110     * 
111     * @see #startArray
112         */
113        boolean endArray() throws ParseException, IOException;
114        
115        /**
116         * Receive notification of the JSON primitive values:
117         *      java.lang.String,
118         *      java.lang.Number,
119         *      java.lang.Boolean
120         *      null
121         * 
122         * @param value - Instance of the following:
123         *                      java.lang.String,
124         *                      java.lang.Number,
125         *                      java.lang.Boolean
126         *                      null
127         * 
128         * @return false if the handler wants to stop parsing after return.
129         * @throws ParseException description omitted.
130         * @throws IOException description omitted.
131         */
132        boolean primitive(Object value) throws ParseException, IOException;
133                
134}