com.purplehillsbooks.streams

Class HTMLWriter

java.lang.Object

java.io.Writer

com.purplehillsbooks.streams.HTMLWriter

All Implemented Interfaces:

java.io.Closeable, java.io.Flushable, java.lang.Appendable, java.lang.AutoCloseable

public class HTMLWriter
extends java.io.Writer

This class is for encoding values in order to make make text appear in an HTML page. This is not for creating HTML markeup. Instead you write text to this writer, and it properly encodes everything so that what is seen on the page is exactly what was written to this class. The example usage would be for a "comment" on a web page. A user writes a comment using any variety of characters, including quotes and angle-brackets which are characters that have a special meaning in HTML. What you want to do is to have the comment displayed on the page exactly as the user input it. But to do so, quote characters, and angle bracket characters must be properly converted so that they are not mistaken for HTML markup by the browser. There are two ways: a writer and a static encoding method. Both ways assume you are constructing your HTML by writing them to a Writer object. This is more efficient than concatenating strings together. 1. A Writer Instance. If you want to use a method that is prepared to write a raw value to a Writer, and you want that raw value to be HTML encoded, then you can construct a HTMLWriter on your existing writer, and pass HTMLWriter to the routine that will write the raw value. Every (raw) value written will be converted as it is passed on to the wrapped Writer. An example of this use is if you have a DOM tree (which can stream itself to a Writer) but you want the serialized DOM to be displayed on a HTML web page (and not interpreted as HTML by the browser). Passing the HTMLWriter to the DOM for serialization will mean that all the XML output will be properly encoded as HTML markup so that the resulting XML output will be displayed on the HTML page. 2. A Static Method. If the value you want to convert is a string (as is often the case) you don't need to construct a new writer object for this. Just call the static writeHtml method, passing a Writer and the string you want converted. The string will be converted as it is written to the Writer. the Java code to to create a HTML page with a sample XML within it:

 Writer w; // given as the place the page is being written
 String val = "<a><b>value of b</b><c>value of c</c></a>";
 w.write("<p>The sample XML expression is: ");
 HTMLWriter.writeHtml(w, val);
 w.write("</p></n>");
 

The val can be ANY legal String value, e.g. something a user typed in. The output stream of characters will accurately converted to HTML so that the value is displayed to the user. Author: Keith Swenson Copyright: Keith Swenson, all rights reserved License: This code is made available under the GNU Lesser GPL license.

Field Summary

Fields inherited from class java.io.Writer

lock

Constructor Summary

Constructors

Constructor and Description
HTMLWriter(java.io.Writer _wrapped)

Method Summary

Modifier and Type	Method and Description
void	close()
void	flush()
void	write(char[] chs, int start, int len)
void	write(int c)
static void	writeHtml(java.io.Writer w, java.lang.String val) Encodes a single String value to a HTML markup so that the HTML page will display the original passed in value exactly..
static void	writeHtmlWithLines(java.io.Writer w, java.lang.String val) writeHtmlWithLines is a special case routine for certain situations.

Methods inherited from class java.io.Writer

append, append, append, write, write, write

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HTMLWriter

public HTMLWriter(java.io.Writer _wrapped)

Method Detail

write

public void write(int c)
           throws java.io.IOException

Overrides:

write in class java.io.Writer

Throws:

java.io.IOException

write

public void write(char[] chs,
                  int start,
                  int len)
           throws java.io.IOException

Specified by:

write in class java.io.Writer

Throws:

java.io.IOException

close

public void close()
           throws java.io.IOException

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in class java.io.Writer

Throws:

java.io.IOException

flush

public void flush()
           throws java.io.IOException

Specified by:

flush in interface java.io.Flushable

Specified by:

flush in class java.io.Writer

Throws:

java.io.IOException

writeHtml

public static void writeHtml(java.io.Writer w,
                             java.lang.String val)
                      throws java.io.IOException

Encodes a single String value to a HTML markup so that the HTML page will display the original passed in value exactly..

If you are constructing an HTML page, and you have a String value that you want to be displayed on the page, and you do not want anything within that string value to be accidentally misinterpreted as markup, you must use this method to scan the String and convert any embedded problematic characters into their escaped equivalents. The result of the conversion is written into the stream that you pass in.

Parameters:

w - The Writer object to which the encoded String value is added.

val - The String value to encode.

Throws:

java.io.IOException

writeHtmlWithLines

public static void writeHtmlWithLines(java.io.Writer w,
                                      java.lang.String val)
                               throws java.io.IOException

writeHtmlWithLines is a special case routine for certain situations. In HTML a newline character is exactly equivalent to a space or tab character. This has the unfortunate effect of making the display of a normal text file to be wrapped into a single long, unreadable, paragraph. One solution is to use "PRE" tag to preserve the effect of newlines, but that also causes a fixed width font which is not always desirable. This method will convert raw text to equivalent HTML, so that the original text is displayed but with one embellishment: newline characters will be converted to a "BR" break tag, forcing the following text will start at the beginning of the next line. It is not a perfect solution, because not all text is formatted in this way that a newline always means the same as a break character, but for normal, casual blocks of text, like comments and short messages, this can work suitably.

Throws:

java.io.IOException