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