001    // Copyright 2004, 2005 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;
016    
017    /**
018     * Defines an object that can write markup (XML, HTML, XHTML) style output. A
019     * <code>IMarkupWriter</code> handles translation from unicode to the markup language (escaping
020     * characters such as '&lt;' and '&gt;' to their entity equivalents, '&amp;lt;' and '&amp;gt;') as
021     * well as assisting with nested elements, closing tags, etc.
022     * 
023     * @author Howard Ship, David Solis
024     */
025    
026    public interface IMarkupWriter
027    {
028        /**
029         * Writes an integer attribute into the currently open tag.
030         * 
031         * @throws IllegalStateException
032         *             if there is no open tag.
033         */
034    
035        public void attribute(String name, int value);
036    
037        /**
038         * Writes a boolean attribute into the currently open tag.
039         * 
040         * @throws IllegalStateException
041         *             if there is no open tag.
042         * @since 3.0
043         */
044    
045        public void attribute(String name, boolean value);
046    
047        /**
048         * Writes an attribute into the most recently opened tag. This must be called after
049         * {@link #begin(String)}and before any other kind of writing (which closes the tag).
050         * <p>
051         * The value may be null.
052         * 
053         * @throws IllegalStateException
054         *             if there is no open tag.
055         */
056    
057        public void attribute(String name, String value);
058    
059        /**
060         * Similar to {@link #attribute(String, String)}but no escaping of invalid elements is done for
061         * the value.
062         * 
063         * @throws IllegalStateException
064         *             if there is no open tag.
065         * @since 3.0
066         */
067    
068        public void attributeRaw(String name, String value);
069    
070        /**
071         * Closes any existing tag then starts a new element. The new element is pushed onto the active
072         * element stack.
073         */
074    
075        public void begin(String name);
076    
077        /**
078         * Starts an element that will not later be matched with an <code>end()</code> call. This is
079         * useful for elements that do not need closing tags.
080         */
081    
082        public void beginEmpty(String name);
083    
084        /**
085         * Invokes checkError() on the <code>PrintWriter</code> used to format output.
086         */
087    
088        public boolean checkError();
089    
090        /**
091         * Closes this <code>IMarkupWriter</code>. Close tags are written for any active elements.
092         * The <code>PrintWriter</code> is then sent <code>close()</code>. A nested writer will
093         * commit its buffer to its containing writer.
094         */
095    
096        public void close();
097    
098        /**
099         * Closes the most recently opened element by writing the '&gt;' that ends it. Once this is
100         * invoked, the <code>attribute()</code> methods may not be used until a new element is opened
101         * with {@link #begin(String)}or or {@link #beginEmpty(String)}.
102         */
103    
104        public void closeTag();
105    
106        /**
107         * Writes an XML/HTML comment. Any open tag is first closed. The method takes care of providing
108         * the <code>&lt;!--</code> and <code>--&gt;</code>, and provides a blank line after the
109         * close of the comment.
110         * <p>
111         * <em>Most</em> characters are valid inside a comment, so no check of the contents is made
112         * (much like {@link #printRaw(String)}.
113         */
114    
115        public void comment(String value);
116    
117        /**
118         * Ends the element most recently started by {@link#begin(String)}. The name of the tag is
119         * popped off of the active element stack and used to form an HTML close tag.
120         */
121    
122        public void end();
123    
124        /**
125         * Ends the most recently started element with the given name. This will also end any other
126         * intermediate elements. This is very useful for easily ending a table or even an entire page.
127         */
128    
129        public void end(String name);
130    
131        /**
132         * Forwards <code>flush()</code> to this <code>IMarkupWriter</code>'s
133         * <code>PrintWriter</code>.
134         */
135    
136        public void flush();
137    
138        /**
139         * Returns a nested writer, one that accumulates its changes in a buffer. When the nested writer
140         * is closed, it writes its buffer of markup into its containing <code>IMarkupWriter</code>
141         * using {@link #printRaw(String)}.
142         */
143    
144        public NestedMarkupWriter getNestedWriter();
145    
146        /**
147         * Version of {@link #print(char[], int, int, boolean)}&nbsp;that assumes filter is
148         * <em>enabled</em>.
149         */
150    
151        public void print(char[] data, int offset, int length);
152    
153        /**
154         * The primary <code>print()</code> method, used by most other methods.
155         * <p>
156         * Prints the character array, first closing any open tag. Problematic characters ('&lt;',
157         * '&gt;' and '&amp;') are converted to appropriate entities.
158         * <p>
159         * Does <em>nothing</em> if <code>data</code> is null.
160         * <p>
161         * Closes any open tag.
162         * 
163         * @param data
164         *            contains the characters to print, or null to not print anything
165         * @param offset
166         *            offset into the array to start printing from
167         * @param length
168         *            number of characters to print
169         * @param raw
170         *            if true, filtering is disabled
171         * @since 4.0
172         */
173    
174        public void print(char[] data, int offset, int length, boolean raw);
175    
176        /**
177         * Prints a single character, or its equivalent entity.
178         * <p>
179         * Closes any open tag.
180         */
181    
182        public void print(char value);
183    
184        /**
185         * Prints an integer.
186         * <p>
187         * Closes any open tag.
188         */
189    
190        public void print(int value);
191    
192        /**
193         * As with {@link #print(char[], int, int, boolean)}, but the data to print is defined by the
194         * String. Assumes filtering is <em>enabled</em>.
195         */
196    
197        public void print(String value);
198    
199        /**
200         * As with {@link #print(char[], int, int, boolean)}, but the data to print is defined by the
201         * String.
202         */
203    
204        public void print(String value, boolean raw);
205    
206        /**
207         * Closes the open tag (if any), then prints a line seperator to the output stream.
208         */
209    
210        public void println();
211    
212        /**
213         * Version of {@link #print(char[], int, int, boolean)}that assumes filter is <em>enabled</em>.
214         */
215    
216        public void printRaw(char[] buffer, int offset, int length);
217    
218        /**
219         * As with {@link #print(char[], int, int, boolean)}, but the data to print is defined by the
220         * String. Assumes filtering is <em>disabled</em>.
221         */
222    
223        public void printRaw(String value);
224    
225        /**
226         * Returns the type of content generated by this response writer, as a MIME type.
227         */
228    
229        public String getContentType();
230    }