oracle.apps.fnd.applcore.oaext.model
Class UTF8NameConverter

java.lang.Object
  oracle.apps.fnd.applcore.oaext.model.UTF8NameConverter

public final class UTF8NameConverter
extends java.lang.Object

Utility class for conversion between a UTF-8 string and the encoded string that conforms to the naming scheme specified by ISO 9660. Only names encoded by this class can be decoded by this class.

The encoding algorithm used by encode is essentially a modified version of URL encoding:

• The alpha-numeric characters "a" through "z", "A" through "Z" and "0" through "9" remain the same.
• The space character " " is converted into double underscores "__".
• All other characters are unsafe and are first converted into one or more bytes using UTF-8. Then each byte is represented by the 3-character string "_xy", where xy is the two-digit hexadecimal representation of the byte.

For example, the encoded string of "Test 8.3ext_3*6-5>=?" is "Test__8_2E3ext_5F3_2A6_2D5_3E_3D_3F".

Please note that although ISO 9660 allows ".", the encoded strings generated by this class do not have this character, mainly because "." is often reserved as a delimiter. In addition, the encoder/decoder in this class is case-sensitive. To generated a string only in upper case, convert the string to upper case before calling encode.

The method convert provides a convenient way to create a string suitable for being an identifier in ISO 9660 format. This method is optimized for strings that contain commonly used characters, including the underscore character "_". Please note that a string converted by this method cannot be restored (decoded) back to its original.

There is a possibility that two strings that are not equal before conversion will become equal after the conversion. For example, "5FStr_2A" and "Str*" will both be converted to "_5FStr_2A". In general, this collision can be prevented by avoiding the strings that start with "5F".
The following is how this method converts a string:

• The string remained unencoded if the string contains only characters from 'a' to 'z', 'A' to 'Z', '0' to '9', or '_'; otherwise it is encoded by method encode
• The string is prefixed with "_" if it has not been encoded by encode, with "_5F" if it has been encoded by encode

Nested Class Summary

static interface

UTF8NameConverter.IdentifierEncoder Encoder for encoding parts of the an identifier.

Method Summary

static java.lang.String	convert(java.lang.String s) Converts the given string to a string that can generally be used as a identifier for programmatic access.
static java.lang.String	convert(java.lang.String s, boolean alwaysPrefixedWithUnderscore) Converts the given string to a string that can generally be used as a identifier for programmatic access.
static java.lang.String	convertJaxbSafe(java.lang.String s) Converts a String to an identifier that won't cause JAXB compilation to fail when underscore is treated as a word separator.
static java.lang.String	decode(java.lang.String s) Decodes a string encoded by encode.
static java.lang.String	encode(java.lang.String s) Converts a string into ISO 9660 format with case preserved.
static java.lang.String	getIdentifier(java.lang.String head, java.lang.String tail, int maxNumberOfBytes, boolean insertHexHashCodeWhenNeeded, UTF8NameConverter.IdentifierEncoder encoder, java.lang.String... bodies) Gets an identifier that can generally be used as a file name.
static java.lang.String	makeJaxbSafe(java.lang.String r) Modifies a String returned by convert(String) to make it JAXB safe.

Methods inherited from class java.lang.Object

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

Method Detail

encode

public static java.lang.String encode(java.lang.String s)

Converts a string into ISO 9660 format with case preserved.

Parameters:

s - the string to be converted

Returns:

the converted string

Throws:

java.lang.NullPointerException - if the given string is null

java.lang.IllegalArgumentException - if the encoded string has more than 255 characters

java.lang.UnsupportedOperationException - if utf-8 is not supported in this platform

decode

public static java.lang.String decode(java.lang.String s)

Decodes a string encoded by encode.

Parameters:

s - the encoded string

Returns:

the decoded string

Throws:

java.lang.NullPointerException - if the given string is null

java.lang.UnsupportedOperationException - if UTF-8 is not supported in this platform

convert

public static java.lang.String convert(java.lang.String s)

Converts the given string to a string that can generally be used as a identifier for programmatic access. See class description for the algorithm used by this method.

Parameters:

s - the string to be converted

Returns:

the converted string which always starts with '_'

Throws:

java.lang.NullPointerException - if the given string is null

convert

public static java.lang.String convert(java.lang.String s,
                                       boolean alwaysPrefixedWithUnderscore)

Converts the given string to a string that can generally be used as a identifier for programmatic access. See class description for the algorithm used by this method.

Parameters:

s - the string to be converted

alwaysPrefixedWithUnderscore - true if the return String should always be prefixed with '_'; false if the String should be prefixed only when then first character is a numeric digit

Returns:

the converted string

Throws:

java.lang.NullPointerException - if the given string is null

convertJaxbSafe

public static java.lang.String convertJaxbSafe(java.lang.String s)

Converts a String to an identifier that won't cause JAXB compilation to fail when underscore is treated as a word separator. This method does not remove underscores from the given String, but it will ensure the return name does not start with an underscore followed by a number.

Parameters:

s - the String to be converted

Returns:

the converted String

Throws:

java.lang.NullPointerException - if the given String is null

getIdentifier

public static java.lang.String getIdentifier(java.lang.String head,
                                             java.lang.String tail,
                                             int maxNumberOfBytes,
                                             boolean insertHexHashCodeWhenNeeded,
                                             UTF8NameConverter.IdentifierEncoder encoder,
                                             java.lang.String... bodies)

Gets an identifier that can generally be used as a file name. The identifier may be constructed with a head, a tail and a list of text bodies. The head, tail and body text is encoded by the given encoder.

Depending on the maximum number of bytes given, the head, tail or body text may be shortened. The body text, if shortened, will be shortened before encoding. The shortening process involves removing the middle portion of a String until it is short enough. Since the head, tail and the body text are shortened individually, the head or tail can almost always remain intact if they are relatively short compared to the body.

When shortening is needed to reduce the length, the hash code (in base 16) may be inserted into the identifier to increase the likelihood of uniqueness. The hash code is based on the original head, body text and tail before encoding. If this option is on, the given maximum number of bytes is adjusted to accommodate the length of the hash code.

Parameters:

head - the head; null if there's none

tail - the tail; null if there's none

maxNumberOfBytes - the maximum number of bytes of the return String. The maximum number of bytes is based on the default character encoding of the platform.

insertHexHashCodeWhenNeeded - true if the hash code of (head + bodies + tail) should be inserted into the identifier to increase the likelihood of being unique when shortening is needed

encoder - the encoder

bodies - the list of Strings that will be concatenated together

Returns:

the identifier of the specified length in bytes

Throws:

java.lang.IllegalArgumentException - if the given body list is null or empty, , if the maximum number of bytes given is less than 28, or if the given encoder is null

makeJaxbSafe

public static java.lang.String makeJaxbSafe(java.lang.String r)

Modifies a String returned by convert(String) to make it JAXB safe.

Parameters:

r - the String to be modified

Returns:

the modified String