001 /*
002 * Copyright (c) 2007 Mozilla Foundation
003 *
004 * Permission is hereby granted, free of charge, to any person obtaining a
005 * copy of this software and associated documentation files (the "Software"),
006 * to deal in the Software without restriction, including without limitation
007 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
008 * and/or sell copies of the Software, and to permit persons to whom the
009 * Software is furnished to do so, subject to the following conditions:
010 *
011 * The above copyright notice and this permission notice shall be included in
012 * all copies or substantial portions of the Software.
013 *
014 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
015 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
016 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
017 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
018 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
019 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
020 * DEALINGS IN THE SOFTWARE.
021 */
022
023 package nu.validator.json;
024
025 import org.xml.sax.SAXException;
026
027 /**
028 * A SAX-inspired streaming interface for JSON. This interface is biased
029 * towards streaming writing whereas SAX is biased towards streaming
030 * parsing.
031 *
032 * @version $Id$
033 * @author hsivonen
034 */
035 public interface JsonHandler {
036
037 /**
038 * Reports the start of the JSON file. When <code>callback</code> is
039 * <code>null</code>, the file is a pure JSON file. With a non-<code>null</code>
040 * <code>callback</code>, a JSON value is wrapped in a function call named
041 * <var>callback</var>.
042 *
043 * <p>Note that the JSON <i>null</i> value is represented as
044 * <code>string(null)</code>.
045 *
046 * @param callback JavaScript callback function name or <code>null</code> for
047 * pure JSON.
048 * @throws SAXException if bad things happen
049 */
050 public void startDocument(String callback) throws SAXException;
051
052 /**
053 * Reports the end of the JSON file. Must be called <code>finally</code>.
054 *
055 * @throws SAXException if bad things happen
056 */
057 public void endDocument() throws SAXException;
058
059 /**
060 * Reports the start of an <i>array</i>.
061 *
062 * @throws SAXException if bad things happen
063 */
064 public void startArray() throws SAXException;
065
066 /**
067 * Reports the end of an <i>array</i>.
068 *
069 * @throws SAXException if bad things happen
070 */
071 public void endArray() throws SAXException;
072
073 /**
074 * Reports the start of an <i>object</i>.
075 *
076 * @throws SAXException if bad things happen
077 */
078 public void startObject() throws SAXException;
079
080 /**
081 * Starts a key-value pair inside an <i>object</i>.
082 * The parameter <code>key</code> gives the key and the next
083 * reported value is taken to be the value associated with
084 * the key. (Hence, there is no need for a corresponding
085 * <code>end</code> callback.)
086 *
087 * @param key the key for the key-value pair (must not be <code>null</code>)
088 * @throws SAXException if bad things happen
089 */
090 public void key(String key) throws SAXException;
091
092 /**
093 * Reports the end of an <i>object</i>.
094 *
095 * @throws SAXException if bad things happen
096 */
097 public void endObject() throws SAXException;
098
099 /**
100 * Reports the start of a <i>string</i>.
101 *
102 * @throws SAXException if bad things happen
103 */
104 public void startString() throws SAXException;
105
106 /**
107 * Adds characters to the current <i>string</i> started with
108 * <code>startString()</code>.
109 *
110 * @param ch a buffer of UTF-16 code units
111 * @param start the first code unit to read
112 * @param length the number of code units to read
113 * @throws SAXException if bad things happen
114 */
115 public void characters(char[] ch, int start, int length) throws SAXException;
116
117 /**
118 * Reports the end of a <i>string</i>.
119 *
120 * @throws SAXException if bad things happen
121 */
122 public void endString() throws SAXException;
123
124 /**
125 * Reports a JSON <i>null</i> on <code>null</code> and
126 * a <i>string</i> otherwise.
127 *
128 * <p>When the argument is not <code>null</code>, this method is
129 * shorthand for
130 * <pre>startString();
131 * characters(string.toCharArray(), 0, string.length());
132 * endString();</pre>
133 *
134 * @param string a string or <code>null</code>
135 * @throws SAXException if bad things happen
136 */
137 public void string(String string) throws SAXException;
138
139 /**
140 * Reports a <i>number</i>.
141 *
142 * @param number the number
143 * @throws SAXException if bad things happen
144 */
145 public void number(int number) throws SAXException;
146
147 /**
148 * Reports a <i>number</i>.
149 *
150 * @param number the number
151 * @throws SAXException if bad things happen
152 */
153 public void number(long number) throws SAXException;
154
155 /**
156 * Reports a <i>number</i>.
157 *
158 * @param number the number
159 * @throws SAXException if bad things happen
160 */
161 public void number(float number) throws SAXException;
162
163 /**
164 * Reports a <i>number</i>.
165 *
166 * @param number the number
167 * @throws SAXException if bad things happen
168 */
169 public void number(double number) throws SAXException;
170
171 /**
172 * Reports a <i>boolean</i>.
173 *
174 * @param bool the boolean
175 * @throws SAXException if bad things happen
176 */
177 public void bool(boolean bool) throws SAXException;
178
179 }