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
015package 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
026public 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}