Package org.opencms.util

Class CmsStringUtil

java.lang.Object
org.opencms.util.CmsStringUtil
public final class CmsStringUtil extends Object
Provides String utility functions.

Since:
6.0.0

  • Field Details

  • Method Details

    • addLeadingAndTrailingSlash

      public static String addLeadingAndTrailingSlash(String path)
      Adds leading and trailing slashes to a path, if the path does not already start or end with a slash.

      Directly exposed for JSP EL, not through CmsJspElFunctions.

      Parameters:
      path - the path to which add the slashes
      Returns:
      the path with added leading and trailing slashes

    • arrayAsString

      public static String arrayAsString(String[] arg, 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 String changeFileNameSuffixTo(String filename, String suffix)
      Changes the given filenames suffix from the current suffix to the provided suffix. Directly exposed for JSP EL, not through CmsJspElFunctions.

      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(String name, String constraints, 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
      constraints - 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 String collectionAsString(Collection<?> collection, 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

    • comparePaths

      public static boolean comparePaths(String path1, String path2)
      Compares two paths, ignoring leading and trailing slashes.

      Directly exposed for JSP EL, not through CmsJspElFunctions.

      Parameters:
      path1 - the first path
      path2 - the second path
      Returns:
      true if the paths are equal (ignoring leading and trailing slashes)

    • countChar

      public static int countChar(String s, char c)
      Counts the occurrence of a given char in a given String.

      Parameters:
      s - the string
      c - the char to count
      Returns:
      returns the count of occurrences of a given char in a given String

    • enumNameToStringArray

      public static <T extends Enum<T>> String[] enumNameToStringArray(T[] values)
      Returns a String array representation for the given enum.

      Type Parameters:
      T - the type of the enum
      Parameters:
      values - the enum values
      Returns:
      the representing String array

    • escapeHtml

      public static String escapeHtml(String source)
      Replaces line breaks to <br/> and HTML control characters like < > & " with their HTML entity representation.

      Directly exposed for JSP EL, not through CmsJspElFunctions.

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

    • escapeJavaScript

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

      This method escapes line breaks (\r\n,\n) quotation marks (".') and slash as well as backspace characters (\,/).

      Directly exposed for JSP EL, not through CmsJspElFunctions.

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

    • escapePattern

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

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

      Directly exposed for JSP EL, not through CmsJspElFunctions.

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

    • extendAttribute

      public static Map<String,String> extendAttribute(String text, String attribute, 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 String extractHtmlBody(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.

      Directly exposed for JSP EL, not through CmsJspElFunctions.

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

    • extractXmlEncoding

      public static String extractXmlEncoding(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 String formatResourceName(String name, int maxLength)
      Shortens a resource name or path so that it is not longer than the provided maximum length.

      In order to reduce the length of the resource name, only complete folder names are removed and replaced with ... successively, starting with the second folder. The first folder is removed only in case the result still does not fit if all subfolders have been removed.

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

      Directly exposed for JSP EL, not through CmsJspElFunctions.

      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 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 Color getColorValue(String value, Color defaultValue, 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

    • getCommonPrefixPath

      public static String getCommonPrefixPath(String first, String second)
      Returns the common parent path of two paths.

      Directly exposed for JSP EL, not through CmsJspElFunctions.

      Parameters:
      first - the first path
      second - the second path
      Returns:
      the common prefix path

    • getEthernetAddress

      public static String getEthernetAddress()
      Returns the Ethernet-Address of the locale host.

      A dummy ethernet address is returned, if the ip is representing the loopback address or in case of exceptions.

      Returns:
      the Ethernet-Address

    • getIntValue

      public static int getIntValue(String value, int defaultValue, 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

    • getIntValueRounded

      public static int getIntValueRounded(String value, int defaultValue, String key)
      Returns the closest 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, can also represent a float value
      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 closest int value for the given parameter value String

    • getLocaleForName

      public static Locale getLocaleForName(String name)
      Returns a Locale calculated from the suffix of the given String, or null if no locale suffix is found.

      The locale returned will include the optional country code if this was part of the suffix.

      Calls CmsResource.getName(String) first, so the given name can also be a resource root path.

      Directly exposed for JSP EL, not through CmsJspElFunctions.

      Parameters:
      name - the name to get the locale for
      Returns:
      the locale, or null
      See Also:

    • getLocaleForText

      public static Locale getLocaleForText(String text)
      Returns the locale for the given text based on the language detection library.

      The result will be null if the detection fails or the detected locale is not configured in the 'opencms-system.xml' as available locale.

      Parameters:
      text - the text to retrieve the locale for
      Returns:
      the detected locale for the given text

    • getLocaleSuffixForName

      public static String getLocaleSuffixForName(String name)
      Returns the locale suffix from the given String, or null if no locae suffix is found.

      Uses the the PATTERN_LOCALE_SUFFIX to find a language_country occurrence in the given name and returns the first group of the match.

      Examples:

      • rabbit_en_EN.html -> Locale[en_EN]
      • rabbit_en_EN      -> Locale[en_EN]
      • rabbit_en.html    -> Locale[en]
      • rabbit_en         -> Locale[en]
      • rabbit_en.        -> Locale[en]
      • rabbit_enr        -> null
      • rabbit_en.tar.gz  -> null
      Directly exposed for JSP EL, not through CmsJspElFunctions.

      Parameters:
      name - the resource name to get the locale suffix for
      Returns:
      the locale suffix if found, null otherwise

    • getLongValue

      public static long getLongValue(String value, long defaultValue, String key)
      Returns the Long (long) 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 long
      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 long value for the given parameter value String

    • getPathComponents

      public static List<String> getPathComponents(String path)
      Splits a path into its non-empty path components.

      If the path is the root path, an empty list will be returned.

      Directly exposed for JSP EL, not through CmsJspElFunctions.

      Parameters:
      path - the path to split
      Returns:
      the list of non-empty path components

    • getRelativeSubPath

      public static String getRelativeSubPath(String base, String path)
      Converts the given path to a path relative to a base folder, but only if it actually is a sub-path of the latter, otherwise null is returned.

      Directly exposed for JSP EL, not through CmsJspElFunctions.

      Parameters:
      base - the base path
      path - the path which should be converted to a relative path
      Returns:
      'path' converted to a path relative to 'base', or null if 'path' is not a sub-folder of 'base'

    • indentLines

      public static String indentLines(String text, int numSpaces)
      Inserts the given number of spaces at the start of each line in the given text.

      This is useful when writing toString() methods for complex nested objects.

      Parameters:
      text - the text to indent
      numSpaces - the number of spaces to insert before each line
      Returns:
      the indented text

    • isEmpty

      public static boolean isEmpty(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(String value)
      Returns true if the provided String is either null or contains only white spaces.

      Directly exposed for JSP EL, not through CmsJspElFunctions.

      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(Object value1, 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(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(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

    • isPrefixPath

      public static boolean isPrefixPath(String firstPath, String secondPath)
      Checks if the first path is a prefix of the second path.

      This method is different compared to String.startsWith(java.lang.String, int), because it considers /foo/bar to be a prefix path of /foo/bar/baz, but not of /foo/bar42. Directly exposed for JSP EL, not through CmsJspElFunctions.

      Parameters:
      firstPath - the first path
      secondPath - the second path
      Returns:
      true if the first path is a prefix path of the second path

    • isProperPrefixPath

      public static boolean isProperPrefixPath(String firstPath, String secondPath)
      Checks if the first path is a prefix of the second path, but not equivalent to it.

      Parameters:
      firstPath - the first path
      secondPath - the second path
      Returns:
      true if the first path is a prefix path of the second path, but not equivalent

    • isValidJavaClassName

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

      Directly exposed for JSP EL, not through CmsJspElFunctions.

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

    • joinPaths

      public static String joinPaths(List<String> paths)
      Concatenates multiple paths and separates them with '/'.

      Consecutive slashes will be reduced to a single slash in the resulting string. For example, joinPaths("/foo/", "/bar", "baz") will return "/foo/bar/baz".

      Parameters:
      paths - the list of paths
      Returns:
      the joined path

    • joinPaths

      public static String joinPaths(String... paths)
      Concatenates multiple paths and separates them with '/'.

      Consecutive slashes will be reduced to a single slash in the resulting string. For example joinPaths("/foo/", "/bar", "baz") will return "/foo/bar/baz".

      If one of the argument paths already contains a double "//" this will also be reduced to '/'. For example joinPaths("/foo//bar/", "/baz") will return "/foo/bar/baz".

      Parameters:
      paths - the array of paths
      Returns:
      the joined path

    • lastIndexOf

      public static int lastIndexOf(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(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

    • listAsString

      public static String listAsString(List<?> list, String separator)
      Returns a string representation for the given list using the given separator.

      Parameters:
      list - the list to write
      separator - the item separator string
      Returns:
      the string representation for the given map

    • mapAsJson

      public static String mapAsJson(Map<String,String> map)
      Encodes a map with string keys and values as a JSON string with the same keys/values.

      Parameters:
      map - the input map
      Returns:
      the JSON data containing the map entries

    • mapAsString

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

      Type Parameters:
      K - type of map keys
      V - type of map values
      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 String padLeft(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 String padRight(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

    • parseDuration

      public static final long parseDuration(String durationStr, long defaultValue)
      Parses a duration and returns the corresponding number of milliseconds. Durations consist of a space-separated list of components of the form {number}{time unit}, for example 1d 5m. The available units are d (days), h (hours), m (months), s (seconds), ms (milliseconds).

      Parameters:
      durationStr - the duration string
      defaultValue - the default value to return in case the pattern does not match
      Returns:
      the corresponding number of milliseconds

    • readStringTemplateGroup

      public static org.antlr.stringtemplate.StringTemplateGroup readStringTemplateGroup(InputStream stream)
      Reads a stringtemplate group from a stream. This will always return a group (empty if necessary), even if reading it from the stream fails.
      Parameters:
      stream - the stream to read from
      Returns:
      the string template group

    • removePrefixPath

      public static Optional<String> removePrefixPath(String prefix, String path)

    • replacePrefix

      public static com.google.common.base.Optional<String> replacePrefix(String text, String origPrefix, String newPrefix, boolean ignoreCase)
      Replaces a constant prefix with another string constant in a given text.

      If the input string does not start with the given prefix, Optional.absent() is returned.

      Parameters:
      text - the text for which to replace the prefix
      origPrefix - the original prefix
      newPrefix - the replacement prefix
      ignoreCase - if true, upper-/lower case differences will be ignored
      Returns:
      an Optional containing either the string with the replaced prefix, or an absent value if the prefix could not be replaced

    • splitAsArray

      public static String[] splitAsArray(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 String[] splitAsArray(String source, 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 List<String> splitAsList(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 List<String> splitAsList(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 List<String> splitAsList(String source, 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 List<String> splitAsList(String source, 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 Map<String,String> splitAsMap(String source, String paramDelim, 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

    • splitOptions

      public static Map<String,String> splitOptions(String optionsStr)
      Specialized version of splitAsMap used for splitting option lists for widgets.

      This used the separator characters (':' for key/value, '|' for entries), but also allows escaping of these characters with backslashes ('\'), to enable use of colons/pipes in keys and values. Backslashes themselves can also be escaped.

      Parameters:
      optionsStr - the string representing the option list
      Returns:
      the options map

    • substitute

      public static String substitute(Pattern pattern, String text, I_CmsRegexSubstitution sub)
      Substitutes a pattern in a string using a I_CmsRegexSubstitution.

      Parameters:
      pattern - the pattern to substitute
      text - the text in which the pattern should be substituted
      sub - the substitution handler
      Returns:
      the transformed string

    • substitute

      public static String substitute(String source, Map<String,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

      public static String substitute(String source, String searchString, 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 String substituteContextPath(String htmlContent, 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 String substitutePerl(String content, String searchString, String replaceItem, 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 String toUnicodeLiteral(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: "&Auml" 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

    • transformValues

      public static String transformValues(String oldFormat, String newFormat, String value)
      This method transformes a string which matched a format with one or more place holders into another format. The other format also includes the same number of 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

    • translatePathComponents

      public static String translatePathComponents(CmsResourceTranslator translator, String path)
      Translates all consecutive sequences of non-slash characters in a path using the given resource translator.
      Parameters:
      translator - the resource translator
      path - the path to translate
      Returns:
      the translated path

    • trimToSize

      public static String trimToSize(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 String trimToSize(String source, int length, int area, 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 String trimToSize(String source, int length, 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(String value, 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