org.afcs.warts.util
Class HtmlUtils

java.lang.Object
  org.afcs.warts.util.HtmlUtils

public final class HtmlUtils

extends java.lang.Object

The HtmlUtils class contains utility methods for manipulating strings with HTML formatting that might be useful to servlets and JSPs.

REFACTOR: Much of the string replacement functionality could be made to re-use some generic routine. This is fairly problematic though, because in some cases we want to replace one character with another, in others one with many, and in others replace several characters in one sweep.

LICENSE: This code is released to the public domain and may be used for any purpose whatsoever without permission or acknowledgment.

Version:

Last Modified 21 August 2003

Author:

Warren Hedley ( whedley at sdsc dot edu )

Method Summary

static java.lang.String	breakUpContiguousNonWhitespace(java.lang.String input, int maxContiguousNonWhitespaceChars) This method ensures that there are at most maxContiguousNonWhitespaceChars continuous non-whitespace characters in the specified string, returning a string with extra whitespace if need be to ensure that the string will break nicely across multiple lines in a browser.
static boolean	containsHtmlSpecialCharacters(java.lang.String inputString) Returns true if the string received might contain HTML special characters that might cause problems in element content, i.e., ampersands or less-than signs.
static java.lang.String	escapeHtmlAttributeSpecialCharacters(java.lang.String inputString) Returns a copy of the input string where all HTML special characters that might cause problems in element attributes (such as ampersands, less-than signs, apostrophes and quotes) have been escaped with the appropriate HTML entities.
static char[]	escapeHtmlSpecialCharacter(char inputCharacter) Returns the array of characters that represents the HTML escaped version of the specified character.
static java.lang.String	escapeHtmlSpecialCharacters(java.lang.String inputString) Returns a copy of the input string where all HTML special characters that might cause problems in element content (such as ampersands and less-than signs) have been escaped with the appropriate HTML entities.
static java.lang.String	escapeHtmlSpecialCharacters(java.lang.String inputString, boolean contentOnlyChars) Returns a copy of the input string where all HTML special characters that might cause problems in element content or attributes have been escaped with the appropriate HTML entities.
static java.lang.String	hyperlinkEmailAddress(java.lang.String emailAddress) This method converts the specified email address into a hyperlink that contains the email address as the visible text, and uses the 'mailto:' protocol to open a mail application if a user clicks on the link.
static java.lang.String	insertHtmlLineBreaks(java.lang.String inputString) Returns a copy of the input string where all linebreaks have been replaced with the corresponding HTML linebreak tag (<br>).
static java.lang.String	insertNonBreakingSpaces(java.lang.String inputString) Returns a copy of the input string where all spaces (&#32) have been replaced with non-breaking spaces (&#160).
static java.lang.String	prepareTextForHtmlDisplay(java.lang.String inputString) Returns an HTML-formatted representation of the string received, where all special characters have been escaped, and all carriage returns have been converted to HTML line breaks.
static java.lang.String	stripTagsAndTrim(java.lang.String inputString) Given a string that may contain XML or HTML tags, which are bounded by a less-than and greater-than sign, this method removes the tags from the input string, and trims any whitespace from the end of the string.

Methods inherited from class java.lang.Object

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

Method Detail

breakUpContiguousNonWhitespace

public static java.lang.String breakUpContiguousNonWhitespace(java.lang.String input,
                                                              int maxContiguousNonWhitespaceChars)

This method ensures that there are at most maxContiguousNonWhitespaceChars continuous non-whitespace characters in the specified string, returning a string with extra whitespace if need be to ensure that the string will break nicely across multiple lines in a browser.

Parameters:

input - The string to check.

maxContiguousNonWhitespaceChars - The maximum number of contiguous non-whitespace characters to allow.

Returns:

The formatted string, or null if input is null.

Throws:

java.lang.IllegalArgumentException - If maxContiguousNonWhitespaceChars is less than 10 (which would be stupid).

containsHtmlSpecialCharacters

public static boolean containsHtmlSpecialCharacters(java.lang.String inputString)

Returns true if the string received might contain HTML special characters that might cause problems in element content, i.e., ampersands or less-than signs.

Parameters:

inputString - The string to scan for special characters.

Returns:

True if the string contains HTML special characters.

escapeHtmlAttributeSpecialCharacters

public static java.lang.String escapeHtmlAttributeSpecialCharacters(java.lang.String inputString)

Returns a copy of the input string where all HTML special characters that might cause problems in element attributes (such as ampersands, less-than signs, apostrophes and quotes) have been escaped with the appropriate HTML entities. This method is also useful for escaping content that appears in Javascript sections of an HTML document.

Parameters:

inputString - The string in which special characters should be escaped.

Returns:

The input string with all HTML content special characters escaped. If null is received, a null will be returned. If the string contains no HTML special characters, the input string will be returned.

escapeHtmlSpecialCharacters

public static java.lang.String escapeHtmlSpecialCharacters(java.lang.String inputString)

Returns a copy of the input string where all HTML special characters that might cause problems in element content (such as ampersands and less-than signs) have been escaped with the appropriate HTML entities.

Parameters:

inputString - The string in which special characters should be escaped.

Returns:

The input string with all HTML content special characters escaped. If null is received, a null will be returned. If the string contains no HTML special characters, the input string will be returned.

hyperlinkEmailAddress

public static java.lang.String hyperlinkEmailAddress(java.lang.String emailAddress)

This method converts the specified email address into a hyperlink that contains the email address as the visible text, and uses the 'mailto:' protocol to open a mail application if a user clicks on the link. If the email address recieved is null or 0-length, an empty string is returned.

Parameters:

emailAddress - The email address to convert to a hyperlink.

Returns:

A string containing a hyperlinked version of the email address received.

insertHtmlLineBreaks

public static java.lang.String insertHtmlLineBreaks(java.lang.String inputString)

Returns a copy of the input string where all linebreaks have been replaced with the corresponding HTML linebreak tag (<br>). A real linebreak is placed after each HTML line break. Note that only linebreaks of the form '\r\n' are caught and converted, because this is the format that multipart form submissions must take according to the HTML 4.0 specification, and hence what we expect to find in the database, or display.

Parameters:

inputString - The string to insert HTML linebreaks into.

Returns:

The input string with all linebreaks replaced with the HTML equivalent. If null is received, a null will be returned. If the string contains no linebreaks, the input string will be returned.

insertNonBreakingSpaces

public static java.lang.String insertNonBreakingSpaces(java.lang.String inputString)

Returns a copy of the input string where all spaces (&#32) have been replaced with non-breaking spaces (&#160).

Parameters:

inputString - The string to replace spaces with non-breaking spaces in.

Returns:

The input string with any spaces converted to non-breaking spaces. If null is received, a null will be returned. If the string contains no spaces, the input string will be returned.

prepareTextForHtmlDisplay

public static java.lang.String prepareTextForHtmlDisplay(java.lang.String inputString)

Returns an HTML-formatted representation of the string received, where all special characters have been escaped, and all carriage returns have been converted to HTML line breaks. This method should be called whenever servlets are displaying chunks of text that have been retreived from a text source, such as a database entry, to ensure correct display.

Parameters:

inputString - The string to process.

Returns:

The specified string, with HTML special characters escaped, and carriage returns converted to HTML line breaks.

stripTagsAndTrim

public static java.lang.String stripTagsAndTrim(java.lang.String inputString)

Given a string that may contain XML or HTML tags, which are bounded by a less-than and greater-than sign, this method removes the tags from the input string, and trims any whitespace from the end of the string. This is useful when, for instance, application servers insert formatting instructions into messages stored in request objects.

Parameters:

inputString - The string to process

Returns:

The specified string, with any XML or HTML tags escaped, and any trailing whitespace trimmed.

escapeHtmlSpecialCharacter

public static char[] escapeHtmlSpecialCharacter(char inputCharacter)

Returns the array of characters that represents the HTML escaped version of the specified character. If a character that doesn't require escaping is received, then it is returned in an array of length 1.

Parameters:

inputCharacter - The character to escape.

Returns:

An array of characters containing the HTML escaped version of the specified character.

escapeHtmlSpecialCharacters

public static java.lang.String escapeHtmlSpecialCharacters(java.lang.String inputString,
                                                           boolean contentOnlyChars)

Returns a copy of the input string where all HTML special characters that might cause problems in element content or attributes have been escaped with the appropriate HTML entities. Whether to escape just content problem characters or all attribute problem characters is controlled by the contentOnlyChars flag.

Parameters:

inputString - The string in which special characters should be escaped.

contentOnlyChars - Whether to just escape content problem characters, or attribute problem characters.

Returns:

The input string with all HTML content special characters escaped. If null is received, a null will be returned. If the string contains no HTML special characters, the input string will be returned.