org.opencms.util
Class CmsStringUtil

java.lang.Object
  extended by org.opencms.util.CmsStringUtil

public final class CmsStringUtil
extends java.lang.Object

Provides String utility functions.

Since:
6.0.0
Version:
$Revision: 1.55 $
Author:
Andreas Zahner, Alexander Kandzior, Thomas Weckert

Field Summary
static java.lang.String BODY_END_REGEX
          Regular expression that matches the HTML body end tag.
static java.lang.String BODY_START_REGEX
          Regular expression that matches the HTML body start tag.
static java.lang.String FALSE
          Constant for "false".
static java.lang.String LINE_SEPARATOR
          a convenient shorthand to the line separator constant.
static java.lang.String MACRO_OPENCMS_CONTEXT
          Context macro.
static java.lang.String PLACEHOLDER_END
          The place holder end sign in the pattern.
static java.lang.String PLACEHOLDER_START
          The place holder start sign in the pattern.
static char[] SENTENCE_ENDING_CHARS
          Contains all chars that end a sentence in the trimToSize(String, int, int, String) method.
static java.lang.String TABULATOR
          a convenient shorthand for tabulations.
static java.lang.String TRUE
          Constant for "true".
 
Method Summary
static java.lang.String arrayAsString(java.lang.String[] arg, java.lang.String separator)
          Returns a string representation for the given array using the given separator.
static java.lang.String changeFileNameSuffixTo(java.lang.String filename, java.lang.String suffix)
          Changes the filename suffix.
static void checkName(java.lang.String name, java.lang.String contraints, java.lang.String key, I_CmsMessageBundle bundle)
          Checks if a given name is composed only of the characters a...z,A...Z,0...9 and the provided constraints.
static java.lang.String collectionAsString(java.util.Collection<?> collection, java.lang.String separator)
          Returns a string representation for the given collection using the given separator.
static java.lang.String escapeHtml(java.lang.String source)
          Replaces occurrences of special control characters in the given input with a HTML representation.
static java.lang.String escapeJavaScript(java.lang.String source)
          Escapes a String so it may be used in JavaScript String definitions.
static java.lang.String escapePattern(java.lang.String source)
          Escapes a String so it may be used as a Perl5 regular expression.
static java.util.Map<java.lang.String,java.lang.String> extendAttribute(java.lang.String text, java.lang.String attribute, java.lang.String defValue)
          This method takes a part of a html tag definition, an attribute to extend within the given text and a default value for this attribute; and returns a Map with 2 values: a String with key "text" with the new text without the given attribute, and another String with key "value" with the new extended value for the given attribute, this value is surrounded by the same type of quotation marks as in the given text.
static java.lang.String extractHtmlBody(java.lang.String content)
          Extracts the content of a <body> tag in a HTML page.
static java.lang.String extractXmlEncoding(java.lang.String content)
          Extracts the xml encoding setting from an xml file that is contained in a String by parsing the xml head.
static java.lang.String formatResourceName(java.lang.String name, int maxLength)
          Formats a resource name that it is displayed with the maximum length and path information is adjusted.
static java.lang.String formatRuntime(long runtime)
          Formats a runtime in the format hh:mm:ss, to be used e.g. in reports.
static java.awt.Color getColorValue(java.lang.String value, java.awt.Color defaultValue, java.lang.String key)
          Returns the color value (Color) for the given String value.
static int getIntValue(java.lang.String value, int defaultValue, java.lang.String key)
          Returns the Integer (int) value for the given String value.
static boolean isEmpty(java.lang.String value)
          Returns true if the provided String is either null or the empty String "".
static boolean isEmptyOrWhitespaceOnly(java.lang.String value)
          Returns true if the provided String is either null or contains only white spaces.
static boolean isEqual(java.lang.Object value1, java.lang.Object value2)
          Returns true if the provided Objects are either both null or equal according to Object.equals(Object).
static boolean isNotEmpty(java.lang.String value)
          Returns true if the provided String is neither null nor the empty String "".
static boolean isNotEmptyOrWhitespaceOnly(java.lang.String value)
          Returns true if the provided String is neither null nor contains only white spaces.
static boolean isValidJavaClassName(java.lang.String className)
          Checks if the given class name is a valid Java class name.
static int lastIndexOf(java.lang.String source, char[] chars)
          Returns the last index of any of the given chars in the given source.
static int lastWhitespaceIn(java.lang.String source)
          Returns the last index a whitespace char the given source.
static java.lang.String mapAsString(java.util.Map<java.lang.String,java.lang.String> map, java.lang.String sepItem, java.lang.String sepKeyval)
          Returns a string representation for the given map using the given separators.
static java.lang.String padLeft(java.lang.String input, int size)
          Applies white space padding to the left of the given String.
static java.lang.String padRight(java.lang.String input, int size)
          Applies white space padding to the right of the given String.
static java.lang.String[] splitAsArray(java.lang.String source, char delimiter)
          Splits a String into substrings along the provided char delimiter and returns the result as an Array of Substrings.
static java.lang.String[] splitAsArray(java.lang.String source, java.lang.String delimiter)
          Splits a String into substrings along the provided String delimiter and returns the result as an Array of Substrings.
static java.util.List<java.lang.String> splitAsList(java.lang.String source, char delimiter)
          Splits a String into substrings along the provided char delimiter and returns the result as a List of Substrings.
static java.util.List<java.lang.String> splitAsList(java.lang.String source, char delimiter, boolean trim)
          Splits a String into substrings along the provided char delimiter and returns the result as a List of Substrings.
static java.util.List<java.lang.String> splitAsList(java.lang.String source, java.lang.String delimiter)
          Splits a String into substrings along the provided String delimiter and returns the result as List of Substrings.
static java.util.List<java.lang.String> splitAsList(java.lang.String source, java.lang.String delimiter, boolean trim)
          Splits a String into substrings along the provided String delimiter and returns the result as List of Substrings.
static java.util.Map<java.lang.String,java.lang.String> splitAsMap(java.lang.String source, java.lang.String paramDelim, java.lang.String keyValDelim)
          Splits a String into substrings along the provided paramDelim delimiter, then each substring is treat as a key-value pair delimited by keyValDelim.
static java.lang.String substitute(java.lang.String source, java.util.Map<java.lang.String,java.lang.String> substitions)
          Replaces a set of searchString and replaceString pairs, given by the substitutions Map parameter.
static java.lang.String substitute(java.lang.String source, java.lang.String searchString, java.lang.String replaceString)
          Substitutes searchString in the given source String with replaceString.
static java.lang.String substituteContextPath(java.lang.String htmlContent, java.lang.String context)
          Substitutes the OpenCms context path (e.g.
static java.lang.String substitutePerl(java.lang.String content, java.lang.String searchString, java.lang.String replaceItem, java.lang.String occurences)
          Substitutes searchString in content with replaceItem.
static java.lang.String toUnicodeLiteral(java.lang.String s)
          Returns the java String literal for the given String.
static java.lang.String transformValue(java.lang.String oldFormat, java.lang.String newFormat, java.lang.String value)
          This method transformes a string which matched a format with a place holder into another format.
static java.lang.String trimToSize(java.lang.String source, int length)
          Returns a substring of the source, which is at most length characters long.
static java.lang.String trimToSize(java.lang.String source, int length, int area, java.lang.String suffix)
          Returns a substring of the source, which is at most length characters long, cut in the last area chars in the source at a sentence ending char or whitespace.
static java.lang.String trimToSize(java.lang.String source, int length, java.lang.String suffix)
          Returns a substring of the source, which is at most length characters long.
static boolean validateRegex(java.lang.String value, java.lang.String regex, boolean allowEmpty)
          Validates a value against a regular expression.
static boolean validateResourceName(java.lang.String name)
          Deprecated. use CmsResource.checkResourceName(String) instead
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

BODY_END_REGEX

public static final java.lang.String BODY_END_REGEX
Regular expression that matches the HTML body end tag.

See Also:
Constant Field Values

BODY_START_REGEX

public static final java.lang.String BODY_START_REGEX
Regular expression that matches the HTML body start tag.

See Also:
Constant Field Values

FALSE

public static final java.lang.String FALSE
Constant for "false".


LINE_SEPARATOR

public static final java.lang.String LINE_SEPARATOR
a convenient shorthand to the line separator constant.


MACRO_OPENCMS_CONTEXT

public static final java.lang.String MACRO_OPENCMS_CONTEXT
Context macro.

See Also:
Constant Field Values

PLACEHOLDER_END

public static final java.lang.String PLACEHOLDER_END
The place holder end sign in the pattern.

See Also:
Constant Field Values

PLACEHOLDER_START

public static final java.lang.String PLACEHOLDER_START
The place holder start sign in the pattern.

See Also:
Constant Field Values

SENTENCE_ENDING_CHARS

public static final char[] SENTENCE_ENDING_CHARS
Contains all chars that end a sentence in the trimToSize(String, int, int, String) method.


TABULATOR

public static final java.lang.String TABULATOR
a convenient shorthand for tabulations.

See Also:
Constant Field Values

TRUE

public static final java.lang.String TRUE
Constant for "true".

Method Detail

arrayAsString

public static java.lang.String arrayAsString(java.lang.String[] arg,
                                             java.lang.String separator)
Returns a string representation for the given array using the given separator.

Parameters:
arg - the array to transform to a String
separator - the item separator
Returns:
the String of the given array

changeFileNameSuffixTo

public static java.lang.String changeFileNameSuffixTo(java.lang.String filename,
                                                      java.lang.String suffix)
Changes the filename suffix.

Parameters:
filename - the filename to be changed
suffix - the new suffix of the file
Returns:
the filename with the replaced suffix

checkName

public static void checkName(java.lang.String name,
                             java.lang.String contraints,
                             java.lang.String key,
                             I_CmsMessageBundle bundle)
                      throws CmsIllegalArgumentException
Checks if a given name is composed only of the characters a...z,A...Z,0...9 and the provided constraints.

If the check fails, an Exception is generated. The provided bundle and key is used to generate the Exception. 4 parameters are passed to the Exception:

  1. The name
  2. The first illegal character found
  3. The position where the illegal character was found
  4. The constraints

Parameters:
name - the name to check
contraints - the additional character constraints
key - the key to use for generating the Exception (if required)
bundle - the bundle to use for generating the Exception (if required)
Throws:
CmsIllegalArgumentException - if the check fails (generated from the given key and bundle)

collectionAsString

public static java.lang.String collectionAsString(java.util.Collection<?> collection,
                                                  java.lang.String separator)
Returns a string representation for the given collection using the given separator.

Parameters:
collection - the collection to print
separator - the item separator
Returns:
the string representation for the given collection

escapeHtml

public static java.lang.String escapeHtml(java.lang.String source)
Replaces occurrences of special control characters in the given input with a HTML representation.

This method currently replaces line breaks to <br/> and special HTML chars like < > & " with their HTML entity representation.

Parameters:
source - the String to escape
Returns:
the escaped String

escapeJavaScript

public static java.lang.String escapeJavaScript(java.lang.String source)
Escapes a String so it may be used in JavaScript String definitions.

This method replaces line breaks, quotation marks and \ characters.

Parameters:
source - the String to escape
Returns:
the escaped String

escapePattern

public static java.lang.String escapePattern(java.lang.String source)
Escapes a String so it may be used as a Perl5 regular expression.

This method replaces the following characters in a String:
{}[]()\$^.*+/

Parameters:
source - the string to escape
Returns:
the escaped string

extendAttribute

public static java.util.Map<java.lang.String,java.lang.String> extendAttribute(java.lang.String text,
                                                                               java.lang.String attribute,
                                                                               java.lang.String defValue)
This method takes a part of a html tag definition, an attribute to extend within the given text and a default value for this attribute; and returns a Map with 2 values: a String with key "text" with the new text without the given attribute, and another String with key "value" with the new extended value for the given attribute, this value is surrounded by the same type of quotation marks as in the given text.

Parameters:
text - the text to search in
attribute - the attribute to remove and extend from the text
defValue - a default value for the attribute, should not have any quotation mark
Returns:
a map with the new text and the new value for the given attribute

extractHtmlBody

public static java.lang.String extractHtmlBody(java.lang.String content)
Extracts the content of a <body> tag in a HTML page.

This method should be pretty robust and work even if the input HTML does not contains a valid body tag.

Parameters:
content - the content to extract the body from
Returns:
the extracted body tag content

extractXmlEncoding

public static java.lang.String extractXmlEncoding(java.lang.String content)
Extracts the xml encoding setting from an xml file that is contained in a String by parsing the xml head.

This is useful if you have a byte array that contains a xml String, but you do not know the xml encoding setting. Since the encoding setting in the xml head is usually encoded with standard US-ASCII, you usually just create a String of the byte array without encoding setting, and use this method to find the 'true' encoding. Then create a String of the byte array again, this time using the found encoding.

This method will return null in case no xml head or encoding information is contained in the input.

Parameters:
content - the xml content to extract the encoding from
Returns:
the extracted encoding, or null if no xml encoding setting was found in the input

formatResourceName

public static java.lang.String formatResourceName(java.lang.String name,
                                                  int maxLength)
Formats a resource name that it is displayed with the maximum length and path information is adjusted.

In order to reduce the length of the displayed names, single folder names are removed/replaced with ... successively, starting with the second! folder. The first folder is removed as last.

Example: formatResourceName("/myfolder/subfolder/index.html", 21) returns /myfolder/.../index.html.

Parameters:
name - the resource name to format
maxLength - the maximum length of the resource name (without leading /...)
Returns:
the formatted resource name

formatRuntime

public static java.lang.String formatRuntime(long runtime)
Formats a runtime in the format hh:mm:ss, to be used e.g. in reports.

If the runtime is greater then 24 hours, the format dd:hh:mm:ss is used.

Parameters:
runtime - the time to format
Returns:
the formatted runtime

getColorValue

public static java.awt.Color getColorValue(java.lang.String value,
                                           java.awt.Color defaultValue,
                                           java.lang.String key)
Returns the color value (Color) for the given String value.

All parse errors are caught and the given default value is returned in this case.

Parameters:
value - the value to parse as color
defaultValue - the default value in case of parsing errors
key - a key to be included in the debug output in case of parse errors
Returns:
the int value for the given parameter value String

getIntValue

public static int getIntValue(java.lang.String value,
                              int defaultValue,
                              java.lang.String key)
Returns the Integer (int) value for the given String value.

All parse errors are caught and the given default value is returned in this case.

Parameters:
value - the value to parse as int
defaultValue - the default value in case of parsing errors
key - a key to be included in the debug output in case of parse errors
Returns:
the int value for the given parameter value String

isEmpty

public static boolean isEmpty(java.lang.String value)
Returns true if the provided String is either null or the empty String "".

Parameters:
value - the value to check
Returns:
true, if the provided value is null or the empty String, false otherwise

isEmptyOrWhitespaceOnly

public static boolean isEmptyOrWhitespaceOnly(java.lang.String value)
Returns true if the provided String is either null or contains only white spaces.

Parameters:
value - the value to check
Returns:
true, if the provided value is null or contains only white spaces, false otherwise

isEqual

public static boolean isEqual(java.lang.Object value1,
                              java.lang.Object value2)
Returns true if the provided Objects are either both null or equal according to Object.equals(Object).

Parameters:
value1 - the first object to compare
value2 - the second object to compare
Returns:
true if the provided Objects are either both null or equal according to Object.equals(Object)

isNotEmpty

public static boolean isNotEmpty(java.lang.String value)
Returns true if the provided String is neither null nor the empty String "".

Parameters:
value - the value to check
Returns:
true, if the provided value is not null and not the empty String, false otherwise

isNotEmptyOrWhitespaceOnly

public static boolean isNotEmptyOrWhitespaceOnly(java.lang.String value)
Returns true if the provided String is neither null nor contains only white spaces.

Parameters:
value - the value to check
Returns:
true, if the provided value is null or contains only white spaces, false otherwise

isValidJavaClassName

public static boolean isValidJavaClassName(java.lang.String className)
Checks if the given class name is a valid Java class name.

Parameters:
className - the name to check
Returns:
true if the given class name is a valid Java class name

lastIndexOf

public static int lastIndexOf(java.lang.String source,
                              char[] chars)
Returns the last index of any of the given chars in the given source.

If no char is found, -1 is returned.

Parameters:
source - the source to check
chars - the chars to find
Returns:
the last index of any of the given chars in the given source, or -1

lastWhitespaceIn

public static int lastWhitespaceIn(java.lang.String source)
Returns the last index a whitespace char the given source.

If no whitespace char is found, -1 is returned.

Parameters:
source - the source to check
Returns:
the last index a whitespace char the given source, or -1

mapAsString

public static java.lang.String mapAsString(java.util.Map<java.lang.String,java.lang.String> map,
                                           java.lang.String sepItem,
                                           java.lang.String sepKeyval)
Returns a string representation for the given map using the given separators.

Parameters:
map - the map to write
sepItem - the item separator string
sepKeyval - the key-value pair separator string
Returns:
the string representation for the given map

padLeft

public static java.lang.String padLeft(java.lang.String input,
                                       int size)
Applies white space padding to the left of the given String.

Parameters:
input - the input to pad left
size - the size of the padding
Returns:
the input padded to the left

padRight

public static java.lang.String padRight(java.lang.String input,
                                        int size)
Applies white space padding to the right of the given String.

Parameters:
input - the input to pad right
size - the size of the padding
Returns:
the input padded to the right

splitAsArray

public static java.lang.String[] splitAsArray(java.lang.String source,
                                              char delimiter)
Splits a String into substrings along the provided char delimiter and returns the result as an Array of Substrings.

Parameters:
source - the String to split
delimiter - the delimiter to split at
Returns:
the Array of splitted Substrings

splitAsArray

public static java.lang.String[] splitAsArray(java.lang.String source,
                                              java.lang.String delimiter)
Splits a String into substrings along the provided String delimiter and returns the result as an Array of Substrings.

Parameters:
source - the String to split
delimiter - the delimiter to split at
Returns:
the Array of splitted Substrings

splitAsList

public static java.util.List<java.lang.String> splitAsList(java.lang.String source,
                                                           char delimiter)
Splits a String into substrings along the provided char delimiter and returns the result as a List of Substrings.

Parameters:
source - the String to split
delimiter - the delimiter to split at
Returns:
the List of splitted Substrings

splitAsList

public static java.util.List<java.lang.String> splitAsList(java.lang.String source,
                                                           char delimiter,
                                                           boolean trim)
Splits a String into substrings along the provided char delimiter and returns the result as a List of Substrings.

Parameters:
source - the String to split
delimiter - the delimiter to split at
trim - flag to indicate if leading and trailing white spaces should be omitted
Returns:
the List of splitted Substrings

splitAsList

public static java.util.List<java.lang.String> splitAsList(java.lang.String source,
                                                           java.lang.String delimiter)
Splits a String into substrings along the provided String delimiter and returns the result as List of Substrings.

Parameters:
source - the String to split
delimiter - the delimiter to split at
Returns:
the Array of splitted Substrings

splitAsList

public static java.util.List<java.lang.String> splitAsList(java.lang.String source,
                                                           java.lang.String delimiter,
                                                           boolean trim)
Splits a String into substrings along the provided String delimiter and returns the result as List of Substrings.

Parameters:
source - the String to split
delimiter - the delimiter to split at
trim - flag to indicate if leading and trailing white spaces should be omitted
Returns:
the Array of splitted Substrings

splitAsMap

public static java.util.Map<java.lang.String,java.lang.String> splitAsMap(java.lang.String source,
                                                                          java.lang.String paramDelim,
                                                                          java.lang.String keyValDelim)
Splits a String into substrings along the provided paramDelim delimiter, then each substring is treat as a key-value pair delimited by keyValDelim.

Parameters:
source - the string to split
paramDelim - the string to delimit each key-value pair
keyValDelim - the string to delimit key and value
Returns:
a map of splitted key-value pairs

substitute

public static java.lang.String substitute(java.lang.String source,
                                          java.util.Map<java.lang.String,java.lang.String> substitions)
Replaces a set of searchString and replaceString pairs, given by the substitutions Map parameter.

Parameters:
source - the string to scan
substitions - the map of substitutions
Returns:
the substituted String
See Also:
substitute(String, String, String)

substitute

public static java.lang.String substitute(java.lang.String source,
                                          java.lang.String searchString,
                                          java.lang.String replaceString)
Substitutes searchString in the given source String with replaceString.

This is a high-performance implementation which should be used as a replacement for String.replaceAll(java.lang.String, java.lang.String) in case no regular expression evaluation is required.

Parameters:
source - the content which is scanned
searchString - the String which is searched in content
replaceString - the String which replaces searchString
Returns:
the substituted String

substituteContextPath

public static java.lang.String substituteContextPath(java.lang.String htmlContent,
                                                     java.lang.String context)
Substitutes the OpenCms context path (e.g. /opencms/opencms/) in a HTML page with a special variable so that the content also runs if the context path of the server changes.

Parameters:
htmlContent - the HTML to replace the context path in
context - the context path of the server
Returns:
the HTML with the replaced context path

substitutePerl

public static java.lang.String substitutePerl(java.lang.String content,
                                              java.lang.String searchString,
                                              java.lang.String replaceItem,
                                              java.lang.String occurences)
Substitutes searchString in content with replaceItem.

Parameters:
content - the content which is scanned
searchString - the String which is searched in content
replaceItem - the new String which replaces searchString
occurences - must be a "g" if all occurrences of searchString shall be replaced
Returns:
String the substituted String

toUnicodeLiteral

public static java.lang.String toUnicodeLiteral(java.lang.String s)
Returns the java String literal for the given String.

This is the form of the String that had to be written into source code using the unicode escape sequence for special characters.

Example: "Ä" would be transformed to "\\u00C4".

Parameters:
s - a string that may contain non-ascii characters
Returns:
the java unicode escaped string Literal of the given input string

transformValue

public static java.lang.String transformValue(java.lang.String oldFormat,
                                              java.lang.String newFormat,
                                              java.lang.String value)
This method transformes a string which matched a format with a place holder into another format. The other format also includes place holders. Place holders start with PLACEHOLDER_START and end with PLACEHOLDER_END.

Parameters:
oldFormat - the original format
newFormat - the new format
value - the value which matched the original format and which shall be transformed into the new format
Returns:
the new value with the filled place holder with the information in the parameter value

trimToSize

public static java.lang.String trimToSize(java.lang.String source,
                                          int length)
Returns a substring of the source, which is at most length characters long.

This is the same as calling trimToSize(String, int, String) with the parameters (source, length, " ...").

Parameters:
source - the string to trim
length - the maximum length of the string to be returned
Returns:
a substring of the source, which is at most length characters long

trimToSize

public static java.lang.String trimToSize(java.lang.String source,
                                          int length,
                                          int area,
                                          java.lang.String suffix)
Returns a substring of the source, which is at most length characters long, cut in the last area chars in the source at a sentence ending char or whitespace.

If a char is cut, the given suffix is appended to the result.

Parameters:
source - the string to trim
length - the maximum length of the string to be returned
area - the area at the end of the string in which to find a sentence ender or whitespace
suffix - the suffix to append in case the String was trimmed
Returns:
a substring of the source, which is at most length characters long

trimToSize

public static java.lang.String trimToSize(java.lang.String source,
                                          int length,
                                          java.lang.String suffix)
Returns a substring of the source, which is at most length characters long.

If a char is cut, the given suffix is appended to the result.

This is almost the same as calling trimToSize(String, int, int, String) with the parameters (source, length, length*, suffix). If length if larger then 100, then length* = length / 2, otherwise length* = length.

Parameters:
source - the string to trim
length - the maximum length of the string to be returned
suffix - the suffix to append in case the String was trimmed
Returns:
a substring of the source, which is at most length characters long

validateRegex

public static boolean validateRegex(java.lang.String value,
                                    java.lang.String regex,
                                    boolean allowEmpty)
Validates a value against a regular expression.

Parameters:
value - the value to test
regex - the regular expression
allowEmpty - if an empty value is allowed
Returns:
true if the value satisfies the validation

validateResourceName

public static boolean validateResourceName(java.lang.String name)
Deprecated. use CmsResource.checkResourceName(String) instead

Checks if the provided name is a valid resource name, that is contains only valid characters.

Parameters:
name - the resource name to check
Returns:
true if the resource name is valid, false otherwise