001    // Copyright 2006 The Apache Software Foundation
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.
014    
015    package org.apache.tapestry.json;
016    
017    
018    /**
019     * JavaScript Object Notation writer which manages two core object response 
020     * types, {@link JSONObject} or {@link JSONArray}. It is up to the components
021     * participating in a particular response to decide how to cooperate and build
022     * a JSON structure that their client side will accept.
023     * 
024     * @see "http://www.json.org/"
025     * @author JSON.org, jkuhnert
026     */
027    public interface IJSONWriter
028    {   
029        /**
030         * Provides access to the core outer {@link JSONObject} being 
031         * rendered to a response. The object may not necessarily be instantiated
032         * until requested, for instances where a response should be a pure array
033         * or other.
034         * 
035         * @return The {@link JSONObject} being delegated to.
036         */
037        JSONObject object();
038        
039        /**
040         * Provides access to the core outer {@link JSONArray} being 
041         * rendered to a response. The object may not necessarily be instantiated
042         * until requested.
043         * 
044         * @return The {@link JSONArray} being delegated to.
045         */
046        JSONArray array();
047        
048        /**
049         * Causes any un-ended blocks to be closed, as well as 
050         * any reasources associated with writer to be flushed/written.
051         */
052        void close();
053        
054        /**
055         * Forwards <code>flush()</code> to this <code>IJSONWriter</code>'s
056         * <code>PrintWriter</code>.
057         */
058        void flush();
059    }