org.opencms.i18n
Class CmsEncoder

java.lang.Object
  org.opencms.i18n.CmsEncoder

public final class CmsEncoder
extends 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() and java.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 replaxed with %hex where hex is a two digit hex number.

Note: On the client side (browser) instead of using corresponding escape and unescape JavaScript functions, better use encodeURIComponent and decodeURIComponent functions wich are work properly with unicode characters. These functions are supported in IE 5.5+ and NS 6+ only.

Since:

6.0.0

Version:

$Revision: 1.17 $

Author:

Alexander Kandzior

Field Summary

static String	ENCODING_ISO_8859_1 Constant for the standard ISO-8859-1 encoding.
static String	ENCODING_UTF_8 Default encoding for JavaScript decodeUriComponent methods is UTF-8 by w3c standard.

Method Summary

static String	adjustHtmlEncoding(String input, 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, String oldEncoding, String newEncoding) Changes the encoding of a byte array that represents a String.
static String	createString(byte[] bytes, 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 String	decode(String source) Decodes a String using UTF-8 encoding, which is the standard for http data transmission with GET ant POST requests.
static String	decode(String source, String encoding) This method is a substitute for URLDecoder.decode().
static String	decodeHtmlEntities(String input, String encoding) Decodes HTML entity references like € that are contained in the String to a regulat character, but only if that character is contained in the given encodings charset.
static String	encode(String source) Encodes a String using UTF-8 encoding, which is the standard for http data transmission with GET ant POST requests.
static String	encode(String source, String encoding) This method is a substitute for URLEncoder.encode().
static String	encodeHtmlEntities(String input, 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 String	escape(String source, String encoding) Encodes a String in a way that is compatible with the JavaScript escape function.
static String	escapeHtml(String source) Escapes special characters in a HTML-String with their number-based entity representation, for example & becomes &.
static String	escapeNonAscii(String source) Escapes non ASCII characters in a HTML-String with their number-based entity representation, for example & becomes &.
static String	escapeWBlanks(String source, String encoding) Encodes a String in a way that is compatible with the JavaScript escape function.
static String	escapeXml(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 String	lookupEncoding(String encoding, 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 String	redecodeUriComponent(String input) Re-decodes a String that has not been correctly decoded and thus has scrambled character bytes.
static String	unescape(String source, String encoding) Decodes a String in a way that is compatible with the JavaScript unescape function.

Methods inherited from class java.lang.Object

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

Field Detail

ENCODING_UTF_8

public static final String ENCODING_UTF_8

Default encoding for JavaScript decodeUriComponent methods is UTF-8 by w3c standard.

See Also:

Constant Field Values

ENCODING_ISO_8859_1

public static final String ENCODING_ISO_8859_1

Constant for the standard ISO-8859-1 encoding.

See Also:

Constant Field Values

Method Detail

adjustHtmlEncoding

public static String adjustHtmlEncoding(String input,
                                        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, String) first and feeds the result to encodeHtmlEntities(String, String).

Parameters:

input - the input to adjust the HTML encoding for

encoding - the charset to encode the result with

Returns:

the input with the decoded/encoded HTML entities

changeEncoding

public static byte[] changeEncoding(byte[] input,
                                    String oldEncoding,
                                    String newEncoding)

Changes the encoding of a byte array that represents a String.

Parameters:

input - the byte array to convert

oldEncoding - the current encoding of the byte array

newEncoding - the new encoding of the byte array

Returns:

byte[] the byte array encoded in the new encoding

createString

public static String createString(byte[] bytes,
                                  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 decode

encoding - the encoding scheme to use for decoding the bytes

Returns:

the bytes decoded to a String

decode

public static String decode(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 String decode(String source,
                            String encoding)

This method is a substitute for URLDecoder.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 to null. This method will then default to UTF-8 encoding, which is propably the right one.

Parameters:

source - The string to decode

encoding - The encoding to use (if null, the system default is used)

Returns:

The decoded source String

decodeHtmlEntities

public static String decodeHtmlEntities(String input,
                                        String encoding)

Decodes HTML entity references like € that are contained in the String to a regulat character, but only if that character is contained in the given encodings charset.

Parameters:

input - the input to decode the HTML enties in

encoding - the charset to decode the input for

Returns:

the input with the decoded HTML entities

See Also:

encodeHtmlEntities(String, String)

encode

public static String encode(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 String encode(String source,
                            String encoding)

This method is a substitute for URLEncoder.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 to null. This method will then default to UTF-8 encoding, which is propably the right one.

Parameters:

source - the String to encode

encoding - the encoding to use (if null, the system default is used)

Returns:

the encoded source String

encodeHtmlEntities

public static String encodeHtmlEntities(String input,
                                        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 HTML

encoding - the charset to encode the result with

Returns:

the input with the encoded HTML entities

See Also:

decodeHtmlEntities(String, String)

escape

public static String escape(String source,
                            String encoding)

Encodes a String in a way that is compatible with the JavaScript escape function.

Parameters:

source - The textstring to be encoded.

encoding - the encoding type

Returns:

The JavaScript escaped string.

escapeHtml

public static String escapeHtml(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 String escapeNonAscii(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)

escapeWBlanks

public static String escapeWBlanks(String source,
                                   String encoding)

Encodes a String in a way that is compatible with the JavaScript escape function. Muliple blanks are encoded _multiply _with %20.

Parameters:

source - The textstring to be encoded.

encoding - the encoding type

Returns:

The JavaScript escaped string.

escapeXml

public static String escapeXml(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 &lt;
• > with &gt;
• & with &amp;
• " with &quot;

Parameters:

source - the string to escape

Returns:

the escaped string

See Also:

escapeHtml(String)

lookupEncoding

public static String lookupEncoding(String encoding,
                                    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 resolve

fallback - the fallback encoding scheme

Returns:

the resolved encoding name, or the fallback value

redecodeUriComponent

public static String redecodeUriComponent(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 String unescape(String source,
                              String encoding)

Decodes a String in a way that is compatible with the JavaScript unescape function.

Parameters:

source - The String to be decoded.

encoding - the encoding type

Returns:

The JavaScript unescaped String.