Class CmsEncoder
- java.lang.Object
-
- org.opencms.i18n.CmsEncoder
-
public final class CmsEncoder extends java.lang.Object
The OpenCms CmsEncoder class provides static methods to decode and encode data.The methods in this class are substitutes for
java.net.URLEncoder.encode()
andjava.net.URLDecoder.decode()
. Use the methods from this class in all OpenCms core classes to ensure the encoding is always handled the same way.The de- and encoding uses the same coding mechanism as JavaScript, special characters are replaced with
%hex
where hex is a two digit hex number.Note: On the client side (browser) instead of using the deprecated
escape
andunescape
JavaScript functions, always the useencodeURIComponent
anddecodeURIComponent
functions. Only these work properly with unicode characters.- Since:
- 6.0.0
-
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
BASE64_EXTRA
Non-alphanumeric characters used for Base64 encoding.static java.lang.String
BASE64_EXTRA_REPLACEMENTS
Characters used as replacements for non-alphanumeric Base64 characters when using Base64 for request parameters.static java.lang.String
ENCODING_ISO_8859_1
Constant for the standardISO-8859-1
encoding.static java.lang.String
ENCODING_US_ASCII
Constant for the standardUS-ASCII
encoding.static java.lang.String
ENCODING_UTF_8
Constant for the standardUTF-8
encoding.
-
Method Summary
All Methods Static Methods Concrete Methods Deprecated Methods Modifier and Type Method Description static java.lang.String
adjustHtmlEncoding(java.lang.String input, java.lang.String encoding)
Adjusts the given String by making sure all characters that can be displayed in the given charset are contained as chars, whereas all other non-displayable characters are converted to HTML entities.static byte[]
changeEncoding(byte[] input, java.lang.String oldEncoding, java.lang.String newEncoding)
Changes the encoding of a byte array that represents a String.static java.lang.String
convertHostToPunycode(java.lang.String uriString)
Converts the host of an URI to Punycode.static java.lang.String
createString(byte[] bytes, java.lang.String encoding)
Creates a String out of a byte array with the specified encoding, falling back to the system default in case the encoding name is not valid.static java.lang.String
decode(java.lang.String source)
Decodes a String using UTF-8 encoding, which is the standard for http data transmission with GET ant POST requests.static java.lang.String
decode(java.lang.String source, java.lang.String encoding)
This method is a substitute forURLDecoder.decode()
.static java.lang.String
decodeHtmlEntities(java.lang.String input)
Decodes HTML entity references like€
.static java.lang.String
decodeHtmlEntities(java.lang.String input, java.lang.String encoding)
Deprecated.static java.lang.String
decodeParameter(java.lang.String input)
Decodes a string used as parameter in an uri in a way independent of other encodings/decodings applied before.static java.util.List<java.lang.String>
decodeStringsFromBase64Parameter(java.lang.String data)
Decodes a parameter which has been encoded from a string list using encodeStringsAsBase64Parameter.static java.lang.String
encode(java.lang.String source)
Encodes a String using UTF-8 encoding, which is the standard for http data transmission with GET ant POST requests.static java.lang.String
encode(java.lang.String source, java.lang.String encoding)
This method is a substitute forURLEncoder.encode()
.static java.lang.String
encodeHtmlEntities(java.lang.String input, java.lang.String encoding)
Encodes all characters that are contained in the String which can not displayed in the given encodings charset with HTML entity references like€
.static java.lang.String
encodeJavaEntities(java.lang.String input, java.lang.String encoding)
Encodes all characters that are contained in the String which can not displayed in the given encodings charset with Java escaping like€
.static java.lang.String
encodeParameter(java.lang.String input)
Encodes a string used as parameter in an uri in a way independent of other encodings/decodings applied later.static java.lang.String
encodeStringsAsBase64Parameter(java.util.List<java.lang.String> strings)
Encode a list of strings as base64 data to be used in a request parameter.static java.lang.String
escape(java.lang.String source)
Encodes a String in a way similar to the JavaScript "encodeURIcomponent" function, using "UTF-8" for character encoding encoding.static java.lang.String
escape(java.lang.String source, java.lang.String encoding)
Encodes a String in a way similar to the JavaScript "encodeURIcomponent" function.static java.lang.String
escapeHtml(java.lang.String source)
Escapes special characters in a HTML-String with their number-based entity representation, for example & becomes &.static java.lang.String
escapeNonAscii(java.lang.String source)
Escapes non ASCII characters in a HTML-String with their number-based entity representation, for example & becomes &.static java.lang.String
escapeSql(java.lang.String source)
A simple method to avoid injection.static java.lang.String
escapeSqlLikePattern(java.lang.String pattern, char escapeChar)
Escapes the wildcard characters in a string which will be used as the pattern for a SQL LIKE clause.static java.lang.String
escapeWBlanks(java.lang.String source, java.lang.String encoding)
Encodes a String in a way similar JavaScript "encodeURIcomponent" function.static java.lang.String
escapeXml(java.lang.String source)
Escapes a String so it may be printed as text content or attribute value in a HTML page or an XML file.static java.lang.String
escapeXml(java.lang.String source, boolean doubleEscape)
Escapes a String so it may be printed as text content or attribute value in a HTML page or an XML file.static java.lang.String
lookupEncoding(java.lang.String encoding, java.lang.String fallback)
Checks if a given encoding name is actually supported, and if so resolves it to it's canonical name, if not it returns the given fallback value.static java.lang.String
redecodeUriComponent(java.lang.String input)
Re-decodes a String that has not been correctly decoded and thus has scrambled character bytes.static java.lang.String
unescape(java.lang.String source)
Decodes a String in a way similar to the JavaScript "decodeURIcomponent" function, using "UTF-8" for character encoding.static java.lang.String
unescape(java.lang.String source, java.lang.String encoding)
Decodes a String in a way similar to the JavaScript "decodeURIcomponent" function.
-
-
-
Field Detail
-
BASE64_EXTRA
public static final java.lang.String BASE64_EXTRA
Non-alphanumeric characters used for Base64 encoding.- See Also:
- Constant Field Values
-
BASE64_EXTRA_REPLACEMENTS
public static final java.lang.String BASE64_EXTRA_REPLACEMENTS
Characters used as replacements for non-alphanumeric Base64 characters when using Base64 for request parameters.- See Also:
- Constant Field Values
-
ENCODING_ISO_8859_1
public static final java.lang.String ENCODING_ISO_8859_1
Constant for the standardISO-8859-1
encoding.- See Also:
- Constant Field Values
-
ENCODING_US_ASCII
public static final java.lang.String ENCODING_US_ASCII
Constant for the standardUS-ASCII
encoding.- See Also:
- Constant Field Values
-
ENCODING_UTF_8
public static final java.lang.String ENCODING_UTF_8
Constant for the standardUTF-8
encoding.Default encoding for JavaScript decodeUriComponent methods is
UTF-8
by w3c standard.- See Also:
- Constant Field Values
-
-
Method Detail
-
adjustHtmlEncoding
public static java.lang.String adjustHtmlEncoding(java.lang.String input, java.lang.String encoding)
Adjusts the given String by making sure all characters that can be displayed in the given charset are contained as chars, whereas all other non-displayable characters are converted to HTML entities.Just calls
decodeHtmlEntities(String)
first and feeds the result toencodeHtmlEntities(String, String)
.- Parameters:
input
- the input to adjust the HTML encoding forencoding
- the charset to encode the result with\- Returns:
- the input with the decoded/encoded HTML entities
-
changeEncoding
public static byte[] changeEncoding(byte[] input, java.lang.String oldEncoding, java.lang.String newEncoding)
Changes the encoding of a byte array that represents a String.- Parameters:
input
- the byte array to convertoldEncoding
- the current encoding of the byte arraynewEncoding
- the new encoding of the byte array- Returns:
- the byte array encoded in the new encoding
-
convertHostToPunycode
public static java.lang.String convertHostToPunycode(java.lang.String uriString)
Converts the host of an URI to Punycode.This is needed when we want to do redirects to hosts with host names containing international characters like umlauts.
- Parameters:
uriString
- the URI- Returns:
- the converted URI
-
createString
public static java.lang.String createString(byte[] bytes, java.lang.String encoding)
Creates a String out of a byte array with the specified encoding, falling back to the system default in case the encoding name is not valid.Use this method as a replacement for
new String(byte[], encoding)
to avoid possible encoding problems.- Parameters:
bytes
- the bytes to decodeencoding
- the encoding scheme to use for decoding the bytes- Returns:
- the bytes decoded to a String
-
decode
public static java.lang.String decode(java.lang.String source)
Decodes a String using UTF-8 encoding, which is the standard for http data transmission with GET ant POST requests.- Parameters:
source
- the String to decode- Returns:
- String the decoded source String
-
decode
public static java.lang.String decode(java.lang.String source, java.lang.String encoding)
This method is a substitute forURLDecoder.decode()
. Use this in all OpenCms core classes to ensure the encoding is always handled the same way.In case you don't know what encoding to use, set the value of the
encoding
parameter tonull
. This method will then default to UTF-8 encoding, which is probably the right one.- Parameters:
source
- The string to decodeencoding
- The encoding to use (if null, the system default is used)- Returns:
- The decoded source String
-
decodeHtmlEntities
public static java.lang.String decodeHtmlEntities(java.lang.String input)
Decodes HTML entity references like€
.- Parameters:
input
- the input to decode the HTML entities in- Returns:
- the input with the decoded HTML entities
- See Also:
encodeHtmlEntities(String, String)
-
decodeHtmlEntities
@Deprecated public static java.lang.String decodeHtmlEntities(java.lang.String input, java.lang.String encoding)
Deprecated.Decodes HTML entity references like€
that are contained in the String to a regular character, but only if that character is contained in the given encodings charset.- Parameters:
input
- the input to decode the HTML entities inencoding
- the charset to decode the input for- Returns:
- the input with the decoded HTML entities
- See Also:
encodeHtmlEntities(String, String)
-
decodeParameter
public static java.lang.String decodeParameter(java.lang.String input)
Decodes a string used as parameter in an uri in a way independent of other encodings/decodings applied before.- Parameters:
input
- the encoded parameter string- Returns:
- the decoded parameter string
- See Also:
encodeParameter(String)
-
decodeStringsFromBase64Parameter
public static java.util.List<java.lang.String> decodeStringsFromBase64Parameter(java.lang.String data)
Decodes a parameter which has been encoded from a string list using encodeStringsAsBase64Parameter.- Parameters:
data
- the data to decode- Returns:
- the list of strings
-
encode
public static java.lang.String encode(java.lang.String source)
Encodes a String using UTF-8 encoding, which is the standard for http data transmission with GET ant POST requests.- Parameters:
source
- the String to encode- Returns:
- String the encoded source String
-
encode
public static java.lang.String encode(java.lang.String source, java.lang.String encoding)
This method is a substitute forURLEncoder.encode()
. Use this in all OpenCms core classes to ensure the encoding is always handled the same way.In case you don't know what encoding to use, set the value of the
encoding
parameter tonull
. This method will then default to UTF-8 encoding, which is probably the right one.- Parameters:
source
- the String to encodeencoding
- the encoding to use (if null, the system default is used)- Returns:
- the encoded source String
-
encodeHtmlEntities
public static java.lang.String encodeHtmlEntities(java.lang.String input, java.lang.String encoding)
Encodes all characters that are contained in the String which can not displayed in the given encodings charset with HTML entity references like€
.This is required since a Java String is internally always stored as Unicode, meaning it can contain almost every character, but the HTML charset used might not support all such characters.
- Parameters:
input
- the input to encode for HTMLencoding
- the charset to encode the result with- Returns:
- the input with the encoded HTML entities
- See Also:
decodeHtmlEntities(String, String)
-
encodeJavaEntities
public static java.lang.String encodeJavaEntities(java.lang.String input, java.lang.String encoding)
Encodes all characters that are contained in the String which can not displayed in the given encodings charset with Java escaping like€
.This can be used to escape values used in Java property files.
- Parameters:
input
- the input to encode for Javaencoding
- the charset to encode the result with- Returns:
- the input with the encoded Java entities
-
encodeParameter
public static java.lang.String encodeParameter(java.lang.String input)
Encodes a string used as parameter in an uri in a way independent of other encodings/decodings applied later.Used to ensure that GET parameters are not wrecked by wrong or incompatible configuration settings. In order to ensure this, the String is first encoded with html entities for any character that cannot encoded in US-ASCII; additionally, the plus sign is also encoded to avoid problems with the white-space replacer. Finally, the entity prefix is replaced with characters not used as delimiters in urls.
- Parameters:
input
- the parameter string- Returns:
- the encoded parameter string
-
encodeStringsAsBase64Parameter
public static java.lang.String encodeStringsAsBase64Parameter(java.util.List<java.lang.String> strings)
Encode a list of strings as base64 data to be used in a request parameter.- Parameters:
strings
- the strings to encode- Returns:
- the resulting base64 data
-
escape
public static java.lang.String escape(java.lang.String source)
Encodes a String in a way similar to the JavaScript "encodeURIcomponent" function, using "UTF-8" for character encoding encoding.JavaScript "decodeURIcomponent" can decode Strings that have been encoded using this method.
Directly exposed for JSP EL, not through
CmsJspElFunctions
.- Parameters:
source
- The text to be encoded- Returns:
- The encoded string
- See Also:
escape(String, String)
-
escape
public static java.lang.String escape(java.lang.String source, java.lang.String encoding)
Encodes a String in a way similar to the JavaScript "encodeURIcomponent" function.JavaScript "decodeURIcomponent" can decode Strings that have been encoded using this method, provided "UTF-8" has been used as encoding.
Directly exposed for JSP EL, not through
CmsJspElFunctions
.- Parameters:
source
- The text to be encodedencoding
- the encoding type- Returns:
- The encoded string
-
escapeHtml
public static java.lang.String escapeHtml(java.lang.String source)
Escapes special characters in a HTML-String with their number-based entity representation, for example & becomes &.A character
num
is replaced if
((ch != 32) && ((ch > 122) || (ch < 48) || (ch == 60) || (ch == 62)))
- Parameters:
source
- the String to escape- Returns:
- String the escaped String
- See Also:
escapeXml(String)
-
escapeNonAscii
public static java.lang.String escapeNonAscii(java.lang.String source)
Escapes non ASCII characters in a HTML-String with their number-based entity representation, for example & becomes &.A character
num
is replaced if
(ch > 255)
- Parameters:
source
- the String to escape- Returns:
- String the escaped String
- See Also:
escapeXml(String)
-
escapeSql
public static java.lang.String escapeSql(java.lang.String source)
A simple method to avoid injection.Replaces all single quotes to double single quotes in the value parameter of the SQL statement.
- Parameters:
source
- the String to escape SQL from- Returns:
- the escaped value of the parameter source
-
escapeSqlLikePattern
public static java.lang.String escapeSqlLikePattern(java.lang.String pattern, char escapeChar)
Escapes the wildcard characters in a string which will be used as the pattern for a SQL LIKE clause.- Parameters:
pattern
- the patternescapeChar
- the character which should be used as the escape character- Returns:
- the escaped pattern
-
escapeWBlanks
public static java.lang.String escapeWBlanks(java.lang.String source, java.lang.String encoding)
Encodes a String in a way similar JavaScript "encodeURIcomponent" function.Multiple blanks are encoded _multiply_ with
%20
.- Parameters:
source
- The text to be encodedencoding
- the encoding type- Returns:
- The encoded String
-
escapeXml
public static java.lang.String escapeXml(java.lang.String source)
Escapes a String so it may be printed as text content or attribute value in a HTML page or an XML file.This method replaces the following characters in a String:
- < with <
- > with >
- & with &
- " with "
- Parameters:
source
- the string to escape- Returns:
- the escaped string
- See Also:
escapeHtml(String)
-
escapeXml
public static java.lang.String escapeXml(java.lang.String source, boolean doubleEscape)
Escapes a String so it may be printed as text content or attribute value in a HTML page or an XML file.This method replaces the following characters in a String:
- < with <
- > with >
- & with &
- " with "
- Parameters:
source
- the string to escapedoubleEscape
- iffalse
, all entities that already are escaped are left untouched- Returns:
- the escaped string
- See Also:
escapeHtml(String)
-
lookupEncoding
public static java.lang.String lookupEncoding(java.lang.String encoding, java.lang.String fallback)
Checks if a given encoding name is actually supported, and if so resolves it to it's canonical name, if not it returns the given fallback value.Charsets have a set of aliases. For example, valid aliases for "UTF-8" are "UTF8", "utf-8" or "utf8". This method resolves any given valid charset name to it's "canonical" form, so that simple String comparison can be used when checking charset names internally later.
Please see http://www.iana.org/assignments/character-sets for a list of valid charset alias names.
- Parameters:
encoding
- the encoding to check and resolvefallback
- the fallback encoding scheme- Returns:
- the resolved encoding name, or the fallback value
-
redecodeUriComponent
public static java.lang.String redecodeUriComponent(java.lang.String input)
Re-decodes a String that has not been correctly decoded and thus has scrambled character bytes.This is an equivalent to the JavaScript "decodeURIComponent" function. It converts from the default "UTF-8" to the currently selected system encoding.
- Parameters:
input
- the String to convert- Returns:
- String the converted String
-
unescape
public static java.lang.String unescape(java.lang.String source)
Decodes a String in a way similar to the JavaScript "decodeURIcomponent" function, using "UTF-8" for character encoding.This method can decode Strings that have been encoded in JavaScript with "encodeURIcomponent".
Directly exposed for JSP EL, not through
CmsJspElFunctions
.- Parameters:
source
- The String to be decoded- Returns:
- The decoded String
-
unescape
public static java.lang.String unescape(java.lang.String source, java.lang.String encoding)
Decodes a String in a way similar to the JavaScript "decodeURIcomponent" function.This method can decode Strings that have been encoded in JavaScript with "encodeURIcomponent", provided "UTF-8" is used as encoding.
Directly exposed for JSP EL, not through
CmsJspElFunctions
.- Parameters:
source
- The String to be decodedencoding
- the encoding type- Returns:
- The decoded String
-
-