org.hd.d.pg2k.svrCore
Class TextUtils

java.lang.Object
  org.hd.d.pg2k.svrCore.TextUtils

public final class TextUtils
extends java.lang.Object

Some simple common text utilities of scope throughout the application.

sizeSuffixes

private static final java.lang.String[] sizeSuffixes

Suffixes used by sizeAsText.

XML_LINE_TERM

private static final java.lang.String XML_LINE_TERM

String to write as line terminator when converting to XML. A simple LF would suit UNIX-like systems though would probably be accepted by most. A bulkier CRLF is more like the Internet "standard".

See Also:

Constant Field Values

CASE_SENSITIVE_ORDER

public static final java.util.Comparator<java.lang.CharSequence> CASE_SENSITIVE_ORDER

Orders CharSequence objects as if by String.compareTo(); not null. If both arguments to compare() are the same reference (even null) this returns 0 immediately.

CASE_INSENSITIVE_ORDER

public static final java.util.Comparator<java.lang.CharSequence> CASE_INSENSITIVE_ORDER

Orders CharSequence objects as if by String.compareToIgnoreCase(); not null. If both arguments to compare() are the same reference (even null) this returns 0 immediately.

TextUtils

private TextUtils()

Prevent construction of an instance.

sizeAsText

public static final java.lang.String sizeAsText(long size,
                                                boolean abbrev)

Renders size in bytes as text, abbreviated if requested. Can produce normal or abbreviated output.

isASCII7

public static boolean isASCII7(java.lang.String s)

Returns true if given String is 7-bit clean, is is pure ASCII, or is null.

importCopy

public static final void importCopy(org.w3c.dom.Node dest,
                                    org.w3c.dom.Node src)

Recursively copy second Node and contents into first node. This works even when the second Node is from a different Document to the first and importNode() does not work (eg due to JDK1.5 impl bug).

toXML

public static final java.lang.String toXML(org.w3c.dom.Node node,
                                           boolean toXHTML,
                                           boolean terse)

Write DOM tree as XML/XHTML String; never "" nor null. Can write as terse/efficient single-line form or longer more human-friendly format.

When writing XHTML we make text nodes XML/HTML-safe, though allow embedded entities.

Parameters:

node - DOM tree root; never null

toXHTML - if true write with formatting suitable to include directly in HTML/XHTML for human consumption (eg using dl/ul/ol nested lists to produce formatted text representing the structure) rather than a pure XML representation of the Node tree itself

terse - if true write as compactly as possible, else make more human-readable if possible

toXML

public static final void toXML(java.lang.StringBuilder result,
                               org.w3c.dom.Node node,
                               boolean toXHTML,
                               boolean terse)

Write DOM tree as XML/XHTML String; appends to supplied StringBuilder. Can write as terse/efficient single-line form or longer more human-friendly format.

When writing XHTML we make text nodes XML/HTML-safe, though allow embedded entities.

Parameters:

node - DOM tree root; never null

toXHTML - if true write with formatting suitable to include directly in HTML/XHTML for human consumption (eg using dl/ul/ol nested lists to produce formatted text representing the structure) rather than a pure XML representation of the Node tree itself

terse - if true write as compactly as possible, else make more human-readable if possible

escapeHTMLMetaChars

public static java.lang.String escapeHTMLMetaChars(java.lang.String in)

Rewrite HTML so that it displays as "raw" text and is safe to use in attribute values. Meta-characters (<, >, & " ') are rewritten to entity codes so that when shown on screen it looks like the raw HTML text when displayed in-line in HTML, and so as to avoid problems when embedded in XML and HTML.

If the input text does not contain these meta-characters then it is returned unchanged.

Additionally, all characters < 32 (ASCII control characters) are converted to spaces.

If null is passed in, then this returns null, to simplify its use in some cases where a null might be present.

Parameters:

in - String possibly containing HTML/XML meta-characters

decode8To6

public static byte[] decode8To6(java.lang.String base64Text)

Decode to a byte array (8 bit) from ASCII Base-64 (6 bit); never null. The input data must always be a multiple of 4 characters, and all character must come from the standard Base64 set [A-Za-z0-9+/=].

Parameters:

base64Text - data in base-46, eg as encoded by encode8To6(); never null

Returns:

binary data; never null

encode8To6

public static java.lang.String encode8To6(byte[] data8Bit)

Encode a byte array (8 bit) in ASCII Base-64 (6 bit); never null. With thanks to Apache.

Parameters:

data8Bit - binary input data; never null

Returns:

ASCII base-64 representation as String; never null

sanitiseForXML

public static java.lang.String sanitiseForXML(java.lang.String input,
                                              int maxLen,
                                              boolean allowEntities)

Sanitise text for XHTML/HTML/WML/XML use. The transformations are:

• A null argument is converted to an empty string.
• Whitespace is trimmed from the ends.
• Converts any ``<'' to ``{,'' ``>'' to ``}''.
• Unless in "allowEntities" modes, converts any ``&'' to ``+'', else leaves syntactically-correct entities intact and counts as a single character.
• Any non-ASCII characters are converted to a safe value; if entity codes are permitted then these values are converted to entity codes.
• The result is limited to at most the specified number of characters.

Our simple definition of a syntactically-correct entity is that it may contain any selection of ASCII digits and letters and optionally a leading hash (`#'), but certainly no whitespace. We may enforce a length limit.

If the input string is OK it is returned untouched.

TODO: Needs version with extra argument to allow entity sequences (of the form '&'xxx;) to be treated as single characters and to delete any '<'...'>' sequences, ie to do a more sophisticated job of sanitising XML/HTML that has some simple markup (primarily entity codes needed for i18n). TODO: jUnit tests

Parameters:

maxLen - if positive the output is limited to at most this number of characters; if >= 3 truncated text is marked with a trailing ``...'' in the last three prositions

allowEntities - if true, treats HTML/XML entity sequences as if single characters; the entities are vaguely tested for correct syntax and may not be allowed if invalid

indexOf

public static final int indexOf(java.lang.CharSequence cs,
                                char c)

First index of specified character in given (non-null) CharSequence as for String.

Returns:

index of first occurrence of c, else -1 if no occurrence of c

indexOf

public static final int indexOf(java.lang.CharSequence cs,
                                char c,
                                int fromIndex)

First index of specified character in given (non-null) CharSequence from/after specified index as for String.

Returns:

index of first occurrence of c, else -1 if no occurrence of c

lastIndexOf

public static final int lastIndexOf(java.lang.CharSequence cs,
                                    char c)

Last index of specified character in given (non-null) CharSequence as for String.

Returns:

index of last occurrence of c, else -1 if no occurrence of c

lastIndexOf

public static final int lastIndexOf(java.lang.CharSequence cs,
                                    char c,
                                    int fromIndex)

Last index of specified character in given (non-null) CharSequence from/before specified start index as for String.

Returns:

index of last occurrence of c, else -1 if no occurrence of c

regionMatches

public static boolean regionMatches(java.lang.CharSequence cs1,
                                    int start1,
                                    java.lang.CharSequence cs2,
                                    int start2,
                                    int len)

Checks that the specified region of two (non-null) CharSequences matches exactly (as for String).

contentEquals

public static boolean contentEquals(java.lang.CharSequence cs1,
                                    java.lang.CharSequence cs2)

Checks that two (non-null) CharSequences represent the same sequence of chars.

contentEqualsIgnoreCase

public static boolean contentEqualsIgnoreCase(java.lang.CharSequence cs1,
                                              java.lang.CharSequence cs2)

Checks that two (non-null) CharSequences represent the same sequence of chars, ignoring case.

compare

public static int compare(java.lang.CharSequence cs1,
                          java.lang.CharSequence cs2)

Compares two (non-null) CharSequences for lexical order.

startsWith

public static boolean startsWith(java.lang.CharSequence mainText,
                                 java.lang.CharSequence putativePrefix)

Returns true if the first sequence starts with the second, else false.

endsWith

public static boolean endsWith(java.lang.CharSequence mainText,
                               java.lang.CharSequence putativeSuffix)

Returns true if the first sequence ends with the second, else false.

createCharSequenceSortedSet

public static <T extends java.lang.CharSequence> java.util.SortedSet<T> createCharSequenceSortedSet(java.util.Collection<T> csc)

Create and populate a SortedSet of CharSequence in natural/total case-sensitive order that will work with any mix of immutable CharSequence keys; never null. This may not be consistent with equals() if keys are of mixed types.

The result is not thread-safe and is mutable.

Parameters:

csc - initial collection to populate from; can be null to avoid initial population

createCharSequenceSortedSet

public static <T extends java.lang.CharSequence> java.util.SortedSet<T> createCharSequenceSortedSet(java.util.Collection<T> csc,
                                                                                                    java.util.Comparator<java.lang.CharSequence> comparator)

Create and populate a SortedSet of CharSequence in specified order that will work with any mix of immutable CharSequence keys; never null. This may not be consistent with equals() if keys are of mixed types.

The result is not thread-safe and is mutable.

Parameters:

csc - initial collection to populate from; can be null to avoid initial population

comparator - used to order the items; never null