Coverage Report - org.apache.tapestry.IMarkupWriter
 
Classes in this File Line Coverage Branch Coverage Complexity
IMarkupWriter
N/A
N/A
1
 
 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  
 import org.apache.tapestry.markup.Attribute;
 18  
 
 19  
 /**
 20  
  * Defines an object that can write markup (XML, HTML, XHTML) style output. A
 21  
  * <code>IMarkupWriter</code> handles translation from unicode to the markup language (escaping
 22  
  * characters such as '&lt;' and '&gt;' to their entity equivalents, '&amp;lt;' and '&amp;gt;') as
 23  
  * well as assisting with nested elements, closing tags, etc.
 24  
  * 
 25  
  * @author Howard Ship, David Solis
 26  
  */
 27  
 
 28  
 public interface IMarkupWriter
 29  
 {
 30  
     /**
 31  
      * Writes an integer attribute into the currently open tag.
 32  
      * 
 33  
      * @throws IllegalStateException
 34  
      *             if there is no open tag.
 35  
      */
 36  
 
 37  
     void attribute(String name, int value);
 38  
 
 39  
     /**
 40  
      * Writes a boolean attribute into the currently open tag.
 41  
      * 
 42  
      * @throws IllegalStateException
 43  
      *             if there is no open tag.
 44  
      * @since 3.0
 45  
      */
 46  
 
 47  
     void attribute(String name, boolean value);
 48  
 
 49  
     /**
 50  
      * Writes an attribute into the most recently opened tag. This must be called after
 51  
      * {@link #begin(String)}and before any other kind of writing (which closes the tag).
 52  
      * <p>
 53  
      * The value may be null.
 54  
      * 
 55  
      * @throws IllegalStateException
 56  
      *             if there is no open tag.
 57  
      */
 58  
 
 59  
     void attribute(String name, String value);
 60  
 
 61  
     /**
 62  
      * Similar to {@link #attribute(String, String)}but no escaping of invalid elements is done for
 63  
      * the value.
 64  
      * 
 65  
      * @throws IllegalStateException
 66  
      *             if there is no open tag.
 67  
      * @since 3.0
 68  
      */
 69  
 
 70  
     void attributeRaw(String name, String value);
 71  
     
 72  
     /**
 73  
      * Appends an integer attribute to the current attribute with a matching 
 74  
      * <code>name</code> key, if one exists. 
 75  
      * 
 76  
      * @throws IllegalStateException
 77  
      *             if there is no open tag.
 78  
      */
 79  
 
 80  
     void appendAttribute(String name, int value);
 81  
 
 82  
     /**
 83  
      * Appends a boolean attribute into the currently open tag.
 84  
      * 
 85  
      * @throws IllegalStateException
 86  
      *             if there is no open tag.
 87  
      * @since 3.0
 88  
      */
 89  
 
 90  
     void appendAttribute(String name, boolean value);
 91  
 
 92  
     /**
 93  
      * Appends an attribute into the most recently opened tag. This must be called after
 94  
      * {@link #begin(String)} and before any other kind of writing (which closes the tag).
 95  
      * <p>
 96  
      * The value may be null.
 97  
      * 
 98  
      * @throws IllegalStateException
 99  
      *             if there is no open tag.
 100  
      */
 101  
 
 102  
     void appendAttribute(String name, String value);
 103  
 
 104  
     /**
 105  
      * Similar to {@link #attribute(String, String)} but no escaping of invalid elements is done for
 106  
      * the value.
 107  
      * 
 108  
      * @throws IllegalStateException
 109  
      *             if there is no open tag.
 110  
      * @since 3.0
 111  
      */
 112  
 
 113  
     void appendAttributeRaw(String name, String value);
 114  
     
 115  
     /**
 116  
      * Checks if the current tag has an attribute keyed off of <code>name</code>.
 117  
      * 
 118  
      * @param name
 119  
      *          The name of the attribute to check for existance of.
 120  
      * @return 
 121  
      *          True if the attribute exists, false otherwise.
 122  
      * @throws IllegalStateException
 123  
      *             If there is no open tag.
 124  
      */
 125  
     boolean hasAttribute(String name);
 126  
     
 127  
     /**
 128  
      * Gets the attribute matching <code>name</code> from the current open
 129  
      * tag, if it exists.
 130  
      * 
 131  
      * @param name
 132  
      *          The attribute to get the value of by name.
 133  
      * @return 
 134  
      *          The attribute value, or null if it doesn't exist.
 135  
      * @throws IllegalStateException
 136  
      *             If there is no open tag.
 137  
      */
 138  
     Attribute getAttribute(String name);
 139  
     
 140  
     /**
 141  
      * Removes the attribute specified with a matching <code>name</code> if 
 142  
      * one exists.
 143  
      * 
 144  
      * @param name
 145  
      *          The attribute to remove.
 146  
      * @return
 147  
      *          The removed attribute, null if one didn't exist.
 148  
      * @throws IllegalStateException
 149  
      *             If there is no open tag.
 150  
      */
 151  
     Attribute removeAttribute(String name);
 152  
     
 153  
     /**
 154  
      * Removes all current attributes on the open tag, if any.
 155  
      * 
 156  
      * @throws IllegalStateException
 157  
      *             If there is no open tag.
 158  
      */
 159  
     void clearAttributes();
 160  
     
 161  
     /**
 162  
      * Closes any existing tag then starts a new element. The new element is pushed onto the active
 163  
      * element stack.
 164  
      */
 165  
 
 166  
     void begin(String name);
 167  
 
 168  
     /**
 169  
      * Starts an element that will not later be matched with an <code>end()</code> call. This is
 170  
      * useful for elements that do not need closing tags.
 171  
      */
 172  
 
 173  
     void beginEmpty(String name);
 174  
 
 175  
     /**
 176  
      * Invokes checkError() on the <code>PrintWriter</code> used to format output.
 177  
      */
 178  
 
 179  
     boolean checkError();
 180  
 
 181  
     /**
 182  
      * Closes this <code>IMarkupWriter</code>. Close tags are written for any active elements.
 183  
      * The <code>PrintWriter</code> is then sent <code>close()</code>. A nested writer will
 184  
      * commit its buffer to its containing writer.
 185  
      */
 186  
 
 187  
     void close();
 188  
 
 189  
     /**
 190  
      * Closes the most recently opened element by writing the '&gt;' that ends it. Once this is
 191  
      * invoked, the <code>attribute()</code> methods may not be used until a new element is opened
 192  
      * with {@link #begin(String)}or or {@link #beginEmpty(String)}.
 193  
      */
 194  
 
 195  
     void closeTag();
 196  
 
 197  
     /**
 198  
      * Writes an XML/HTML comment. Any open tag is first closed. The method takes care of providing
 199  
      * the <code>&lt;!--</code> and <code>--&gt;</code>, and provides a blank line after the
 200  
      * close of the comment.
 201  
      * <p>
 202  
      * <em>Most</em> characters are valid inside a comment, so no check of the contents is made
 203  
      * (much like {@link #printRaw(String)}.
 204  
      */
 205  
 
 206  
     void comment(String value);
 207  
 
 208  
     /**
 209  
      * Ends the element most recently started by {@link #begin(String)}. The name of the tag is
 210  
      * popped off of the active element stack and used to form an HTML close tag.
 211  
      */
 212  
 
 213  
     void end();
 214  
 
 215  
     /**
 216  
      * Ends the most recently started element with the given name. This will also end any other
 217  
      * intermediate elements. This is very useful for easily ending a table or even an entire page.
 218  
      */
 219  
 
 220  
     void end(String name);
 221  
 
 222  
     /**
 223  
      * Forwards <code>flush()</code> to this <code>IMarkupWriter</code>'s
 224  
      * <code>PrintWriter</code>.
 225  
      */
 226  
 
 227  
     void flush();
 228  
 
 229  
     /**
 230  
      * Returns a nested writer, one that accumulates its changes in a buffer. When the nested writer
 231  
      * is closed, it writes its buffer of markup into its containing <code>IMarkupWriter</code>
 232  
      * using {@link #printRaw(String)}.
 233  
      */
 234  
 
 235  
     NestedMarkupWriter getNestedWriter();
 236  
 
 237  
     /**
 238  
      * Version of {@link #print(char[], int, int, boolean)}&nbsp;that assumes filter is
 239  
      * <em>enabled</em>.
 240  
      */
 241  
 
 242  
     void print(char[] data, int offset, int length);
 243  
 
 244  
     /**
 245  
      * The primary <code>print()</code> method, used by most other methods.
 246  
      * <p>
 247  
      * Prints the character array, first closing any open tag. Problematic characters ('&lt;',
 248  
      * '&gt;' and '&amp;') are converted to appropriate entities.
 249  
      * <p>
 250  
      * Does <em>nothing</em> if <code>data</code> is null.
 251  
      * <p>
 252  
      * Closes any open tag.
 253  
      * 
 254  
      * @param data
 255  
      *            contains the characters to print, or null to not print anything
 256  
      * @param offset
 257  
      *            offset into the array to start printing from
 258  
      * @param length
 259  
      *            number of characters to print
 260  
      * @param raw
 261  
      *            if true, filtering is disabled
 262  
      * @since 4.0
 263  
      */
 264  
 
 265  
     void print(char[] data, int offset, int length, boolean raw);
 266  
 
 267  
     /**
 268  
      * Prints a single character, or its equivalent entity.
 269  
      * <p>
 270  
      * Closes any open tag.
 271  
      */
 272  
 
 273  
     void print(char value);
 274  
 
 275  
     /**
 276  
      * Prints an integer.
 277  
      * <p>
 278  
      * Closes any open tag.
 279  
      */
 280  
 
 281  
     void print(int value);
 282  
 
 283  
     /**
 284  
      * As with {@link #print(char[], int, int, boolean)}, but the data to print is defined by the
 285  
      * String. Assumes filtering is <em>enabled</em>.
 286  
      */
 287  
 
 288  
     void print(String value);
 289  
 
 290  
     /**
 291  
      * As with {@link #print(char[], int, int, boolean)}, but the data to print is defined by the
 292  
      * String.
 293  
      */
 294  
 
 295  
     void print(String value, boolean raw);
 296  
 
 297  
     /**
 298  
      * Closes the open tag (if any), then prints a line seperator to the output stream.
 299  
      */
 300  
 
 301  
     void println();
 302  
 
 303  
     /**
 304  
      * Version of {@link #print(char[], int, int, boolean)}that assumes filter is <em>enabled</em>.
 305  
      */
 306  
 
 307  
     void printRaw(char[] buffer, int offset, int length);
 308  
 
 309  
     /**
 310  
      * As with {@link #print(char[], int, int, boolean)}, but the data to print is defined by the
 311  
      * String. Assumes filtering is <em>disabled</em>.
 312  
      */
 313  
 
 314  
     void printRaw(String value);
 315  
 
 316  
     /**
 317  
      * Returns the type of content generated by this response writer, as a MIME type.
 318  
      */
 319  
 
 320  
     String getContentType();
 321  
 }