com.aquenos.cassandra.pvarchiver.common

Class CustomUrlCodec

java.lang.Object

com.aquenos.cassandra.pvarchiver.common.CustomUrlCodec

public abstract class CustomUrlCodec
extends Object

Utility for encoding and decoding strings so that they can safely be used as part of a URL.

This utility can be used to encode a string that shall be used as part of a URL. After encoding, the string does not contain any characters that carry a special meaning in a URL path or query string.

When being encoded, a string is first converted to its byte representation. Then, only the letters A–Z and a –z, the digits 0–9, the minus sign (-), and the underscore (_) are kept as is.

All other bytes are encoded in the resulting string by a tilde character( ~) followed by two hexadecimal digits.

The encoding used by this class is very similar to the general encoding used for URLs, but there are a few important differences:

• Instead of the percent character (%), the tilde character ( ~) is used for escaping. This has the advantage that no double-escaping will occur if the encoded string is used as part of a URL that is then encoded again.
• It encodes characters that are valid in a URL path (or query string), but might carry a special meaning. In particular, forward slashes (/ ) and the semicolon (;) are encoded. This way, encoded strings can safely be used as part of a URL path.
• As the encoding scheme is incompatible with the regular URL encoding, string encoded using this encoding will never be interpreted or partially decoded by a web server. This way, it is possible to pass a string containing special characters between different applications without having any undesired conversions in between.

When decoding, this utility assumes that the encoded string only contains characters from the US-ASCII character set (like a correctly encoded string does). Other characters are mostly likely lost during the decoding process.

Author:

Sebastian Marsching

Constructor Summary

Constructors

Constructor and Description
CustomUrlCodec()

Method Summary

Modifier and Type	Method and Description
static String	decode(String encodedString) Decodes an encoded string using the UTF-8 character set.
static String	decode(String encodedString, Charset charset) Decodes an encoded string using the specified character set.
static String	decode(String encodedString, String encoding) Decodes an encoded string using the specified encoding.
static String	encode(String unencodedString) Encodes the specified string using the UTF-8 character set.
static String	encode(String unencodedString, Charset charset) Encoded the specified string using the specified character set.
static String	encode(String unencodedString, String encoding) Encodes the specified string using the specified encoding.

Methods inherited from class java.lang.Object

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

Constructor Detail

CustomUrlCodec

public CustomUrlCodec()

Method Detail

decode

public static String decode(String encodedString)

Decodes an encoded string using the UTF-8 character set. The decoding is performed according to the rules described in the documentation of this class.

Parameters:

encodedString - encoded string. Typically, this string will have been generated by calling the encode(String) method.

Returns:

decoded string.

Throws:

NullPointerException - if encodedString is null.

See Also:

decode(String, Charset), encode(String)

decode

public static String decode(String encodedString,
                            String encoding)

Decodes an encoded string using the specified encoding. The decoding is performed according to the rules described in the documentation of this class. The specified encoding is used to convert the byte array that is the result of the decoding process back to a string.

Parameters:

encodedString - encoded string. Typically, this string will have been generated by calling the encode(String, String) method, using the same encoding.

encoding - encoding that is used for converting the resulting byte array back to a string (e.g. "UTF-8").

Returns:

decoded string.

Throws:

IllegalArgumentException - if encoding is null.

IllegalCharsetNameException - if the specified encoding is not valid.

NullPointerException - if encodedString is null.

UnsupportedCharsetException - if the specified encoding is not supported by the JVM.

See Also:

decode(String, Charset), encode(String, String)

decode

public static String decode(String encodedString,
                            Charset charset)

Decodes an encoded string using the specified character set. The decoding is performed according to the rules described in the documentation of this class. The specified character set is used to convert the byte array that is the result of the decoding process back to a string.

Parameters:

encodedString - encoded string. Typically, this string will have been generated by calling the encode(String, Charset) method, using the same charset.

charset - character set that is used for converting the resulting byte array back to a string.

Returns:

decoded string.

Throws:

NullPointerException - if charset or encodedString is null.

See Also:

encode(String, Charset)

encode

public static String encode(String unencodedString)

Encodes the specified string using the UTF-8 character set. The encoding is performed according to the rules described in the documentation of this class.

Parameters:

unencodedString - string to be encoded.

Returns:

encoded string. The encoded string is suitable for decoding by decode(String).

Throws:

NullPointerException - if unencodedString is null.

See Also:

decode(String), encode(String, Charset)

encode

public static String encode(String unencodedString,
                            String encoding)

Encodes the specified string using the specified encoding. The encoding is performed according to the rules described in the documentation of this class. The specified encoding is used to convert the string to a byte array before encoding it.

Parameters:

unencodedString - string to be encoded.

encoding - encoding that is used for converting the string to a byte array (e.g. "UTF-8").

Returns:

encoded string. The encoded string is suitable for decoding by decode(String, String).

Throws:

IllegalArgumentException - if encoding is null.

IllegalCharsetNameException - if the specified encoding is not valid.

NullPointerException - if unencodedString is null.

UnsupportedCharsetException - if the specified encoding is not supported by the JVM.

See Also:

decode(String, String), encode(String, Charset)

encode

public static String encode(String unencodedString,
                            Charset charset)

Encoded the specified string using the specified character set. The encoding is performed according to the rules described in the documentation of this class. The specified character set is used to convert the string to byte array before encoding it.

Parameters:

unencodedString - string to be encoded.

charset - character set that is used for converting the string to a byte array.

Returns:

encoded string. The encoded string is suitable for decoding by decode(String, Charset).

Throws:

NullPointerException - if charset or unencodedString is null.

See Also:

decode(String, Charset)