IMarkupWriter


1   // Copyright 2004, 2005 The Apache Software Foundation
2   //
3   // Licensed under the Apache License, Version 2.0 (the "License");
4   // you may not use this file except in compliance with the License.
5   // You may obtain a copy of the License at
6   //
7   //     http://www.apache.org/licenses/LICENSE-2.0
8   //
9   // Unless required by applicable law or agreed to in writing, software
10  // distributed under the License is distributed on an "AS IS" BASIS,
11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  // See the License for the specific language governing permissions and
13  // limitations under the License.
14  
15  package org.apache.tapestry;
16  
17  /**
18   * Defines an object that can write markup (XML, HTML, XHTML) style output. A
19   * <code>IMarkupWriter</code> handles translation from unicode to the markup language (escaping
20   * characters such as '&lt;' and '&gt;' to their entity equivalents, '&amp;lt;' and '&amp;gt;') as
21   * well as assisting with nested elements, closing tags, etc.
22   * 
23   * @author Howard Ship, David Solis
24   */
25  
26  public interface IMarkupWriter
27  {
28      /**
29       * Writes an integer attribute into the currently open tag.
30       * 
31       * @throws IllegalStateException
32       *             if there is no open tag.
33       */
34  
35      public void attribute(String   name, int value);
36  
37      /**
38       * Writes a boolean attribute into the currently open tag.
39       * 
40       * @throws IllegalStateException
41       *             if there is no open tag.
42       * @since 3.0
43       */
44  
45      public void attribute(String   name, boolean value);
46  
47      /**
48       * Writes an attribute into the most recently opened tag. This must be called after
49       * {@link #begin(String)}and before any other kind of writing (which closes the tag).
50       * <p>
51       * The value may be null.
52       * 
53       * @throws IllegalStateException
54       *             if there is no open tag.
55       */
56  
57      public void attribute(String   name, String   value);
58  
59      /**
60       * Similar to {@link #attribute(String, String)}but no escaping of invalid elements is done for
61       * the value.
62       * 
63       * @throws IllegalStateException
64       *             if there is no open tag.
65       * @since 3.0
66       */
67  
68      public void attributeRaw(String   name, String   value);
69  
70      /**
71       * Closes any existing tag then starts a new element. The new element is pushed onto the active
72       * element stack.
73       */
74  
75      public void begin(String   name);
76  
77      /**
78       * Starts an element that will not later be matched with an <code>end()</code> call. This is
79       * useful for elements that do not need closing tags.
80       */
81  
82      public void beginEmpty(String   name);
83  
84      /**
85       * Invokes checkError() on the <code>PrintWriter</code> used to format output.
86       */
87  
88      public boolean checkError();
89  
90      /**
91       * Closes this <code>IMarkupWriter</code>. Close tags are written for any active elements.
92       * The <code>PrintWriter</code> is then sent <code>close()</code>. A nested writer will
93       * commit its buffer to its containing writer.
94       */
95  
96      public void close();
97  
98      /**
99       * 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 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags