nu.validator.json.JsonHandler Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of validator Show documentation
An HTML-checking library (used by https://html5.validator.nu and the HTML5 facet of the W3C Validator)
There is a newer version: 20.7.2
/*
 * Copyright (c) 2007 Mozilla Foundation
 *
 * Permission is hereby granted, free of charge, to any person obtaining a 
 * copy of this software and associated documentation files (the "Software"), 
 * to deal in the Software without restriction, including without limitation 
 * the rights to use, copy, modify, merge, publish, distribute, sublicense, 
 * and/or sell copies of the Software, and to permit persons to whom the 
 * Software is furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in 
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 
 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 
 * DEALINGS IN THE SOFTWARE.
 */

package nu.validator.json;

import org.xml.sax.SAXException;

/**
 * A SAX-inspired streaming interface for JSON. This interface is biased 
 * towards streaming writing whereas SAX is biased towards streaming 
 * parsing.
 * 
 * @version $Id$
 * @author hsivonen
 */
public interface JsonHandler {

    /**
     * Reports the start of the JSON file. When callback is
     * null, the file is a pure JSON file. With a non-null 
     * callback, a JSON value is wrapped in a function call named 
     * callback.
     * 
     * Note that the JSON null value is represented as 
     * string(null).
     * 
     * @param callback JavaScript callback function name or null for 
     * pure JSON.
     * @throws SAXException if bad things happen
     */
    public void startDocument(String callback) throws SAXException;

    /**
     * Reports the end of the JSON file. Must be called finally.
     * 
     * @throws SAXException if bad things happen
     */
    public void endDocument() throws SAXException;

    /**
     * Reports the start of an array.
     * 
     * @throws SAXException if bad things happen
     */
    public void startArray() throws SAXException;

    /**
     * Reports the end of an array.
     * 
     * @throws SAXException if bad things happen
     */
    public void endArray() throws SAXException;

    /**
     * Reports the start of an object.
     * 
     * @throws SAXException if bad things happen
     */    
    public void startObject() throws SAXException;

    /**
     * Starts a key-value pair inside an object. 
     * The parameter key gives the key and the next 
     * reported value is taken to be the value associated with 
     * the key. (Hence, there is no need for a corresponding 
     * end callback.)
     * 
     * @param key the key for the key-value pair (must not be null)
     * @throws SAXException if bad things happen
     */
    public void key(String key) throws SAXException;

    /**
     * Reports the end of an object.
     * 
     * @throws SAXException if bad things happen
     */    
    public void endObject() throws SAXException;

    /**
     * Reports the start of a string.
     * 
     * @throws SAXException if bad things happen
     */    
    public void startString() throws SAXException;

    /**
     * Adds characters to the current string started with 
     * startString().
     * 
     * @param ch a buffer of UTF-16 code units
     * @param start the first code unit to read
     * @param length the number of code units to read
     * @throws SAXException if bad things happen
     */
    public void characters(char[] ch, int start, int length) throws SAXException;

    /**
     * Reports the end of a string.
     * 
     * @throws SAXException if bad things happen
     */    
    public void endString() throws SAXException;    
    
    /**
     * Reports a JSON null on null and 
     * a string otherwise.
     * 
     * 
When the argument is not null, this method is 
     * shorthand for
     * 
startString();
     * characters(string.toCharArray(), 0, string.length());
     * endString();
     * 
     * @param string a string or null
     * @throws SAXException if bad things happen
     */
    public void string(String string) throws SAXException;    
    
    /**
     * Reports a number.
     * 
     * @param number the number
     * @throws SAXException if bad things happen
     */
    public void number(int number) throws SAXException;    
    
    /**
     * Reports a number.
     * 
     * @param number the number
     * @throws SAXException if bad things happen
     */
    public void number(long number) throws SAXException;    

    /**
     * Reports a number.
     * 
     * @param number the number
     * @throws SAXException if bad things happen
     */
    public void number(float number) throws SAXException;    

    /**
     * Reports a number.
     * 
     * @param number the number
     * @throws SAXException if bad things happen
     */
    public void number(double number) throws SAXException;    

    /**
     * Reports a boolean.
     * 
     * @param bool the boolean
     * @throws SAXException if bad things happen
     */
    public void bool(boolean bool) throws SAXException;    

}