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 '<' and '>' to their entity equivalents, '<' and '>') 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 '>' 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><!--</code> and <code>--></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)} 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 ('<', 157 * '>' and '&') 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 }