{@link Codec CODEC} implementation
* whose encoding scheme uses separator sequences
* to separate distinct data elements
* and uses escape sequences to mask separator sequences
* and escape sequences at each level of recursion.
*
* This CODEC does not make use of data compression,
* and does not result in any data loss.
*
* This CODEC produces encoded data
* that is extremely readable at low levels of recursion,
* but is very difficult to read at high levels
* of recursion.
The unique three letter identifier
* for this CODEC is "ESC".
*
* This CODEC is automatically installed by the JPT.
String.
*/
private static final String SEPARATOR = ",";
/**
* The sequence of characters that escapes
* the following character or sequence
* from being considered an escape or separator sequence.
*/
private static final String ESCAPE = "\\";
/**
* The sequence of characters that represents null,
* or "no data".
*/
private static final String NULL = "" + (char)0;
//////////////////
// Constructors //
//////////////////
/**
* Constructs an object capable of encoding and decoding data
* using the "Escaped-separated" encoding scheme.
*/
public EscapedCodec() {}
///////////
// Codec //
///////////
/**
* Encodes the given array of data Strings
* into a single compound data String
* using the "Escaped-separated" encoding scheme.
*
* If the given array is null,
* a representation of null is returned.
*
* @param data an array of data Strings
* @return the resulting encoded String
* @see #decode(String)
* @see CodecUtilities#encode(String[])
* @see CodecUtilities#encode(Stringable[])
* @see Codec
*/
public String encode(String[] data) {
// encode null array as stored sequence
if (data == null)
return NULL;
// encode non-null array a
// as an escaped separated sequence
else {
String s = "";
for (int i = 0; i < data.length; i++)
s += escape(data[i]) + SEPARATOR;
return s;
}
}
/**
* Decodes the given compound data String
* into an array of data Strings
* using the "Escaped-separated" encoding scheme.
*
* If the given data is null
* or the representation of null,
* this method returns null.
*
* @param data an encoded data String
* @return the resulting array of data Strings
* @throws ParseException if the data was not encoded
* using this scheme
* @see #encode(String[])
* @see CodecUtilities#decode(String)
* @see Codec
*/
public String[] decode(String data) throws ParseException {
// return null for null data
if (data == null)
return null;
// return null for representation of null data
if (data.equals(NULL))
return null;
// create a vector to hold the individual elements,
// a flag to note escape sequences,
// and a buffer to hold the current element
Vector elements = new Vector();
boolean esc = false;
StringBuffer current = new StringBuffer();
// for each position in the input
for (int i = 0; i < data.length();) {
// if escape sequence starts at this position
if (data.indexOf(ESCAPE, i) == i) {
// if the last token was an escape sequence
if (esc) {
// note that this token does not escape the next
esc = false;
// add the escape character to the current element
current.append(ESCAPE);
}
// otherwise,
else {
// note the need to escape the next token
esc = true;
}
// always skip ahead the appropriate number of positions
i += ESCAPE.length();
}
// if separator sequence starts at this position
else if (data.indexOf(SEPARATOR, i) == i) {
// if the last token was an escape sequence
if (esc) {
// add the separator sequence to the current element
current.append(SEPARATOR);
}
// otherwise,
else {
// check for representation of null
if (current.toString().equals(NULL))
elements.add(null);
// otherwise add the current element to the collection
else
elements.add(current.toString());
// empty out the current element buffer
current.delete(0, current.length());
}
// note that this token does not escape the next
esc = false;
// skip ahead the appropriate number of positions
i += SEPARATOR.length();
}
// if other sequence starts at this position
else {
// check if escape sequence was skipped inappropriately
if (esc) {
// and add it back
current.append(ESCAPE);
}
// add the character at this position
current.append(data.charAt(i++));
// note that this token does not escape the next
esc = false;
}
}
// return an array of the appropriate type and length
return (String[])elements.toArray(new String[0]);
}
/**
* Returns the unique identifier for this encoding scheme:
* the String "ESC".
*
* @see CodecUtilities#installCodec(Codec)
* @see CodecUtilities#getDefaultCodec()
* @see Codec
*/
public String getPrefix() {
return "ESC";
}
/////////////////////
// Private methods //
/////////////////////
/**
* Prepares an individual element
* from the array of String data
* for encoding by preceding each separator
* and escape sequence with an escape sequence.
*
* If the given data is null,
* the representation for null data is returned.
*
* @param data the data String to escape
* @return the escaped data String
* @see #encode(String[])
*/
private String escape(String data) {
// return null representation for null data
if (data == null)
return NULL;
// create a buffer to hold the output
StringBuffer buffer = new StringBuffer(data.length());
// for each position in the input,
for (int i = 0; i < data.length();) {
// if separator sequence starts at this position
if (data.indexOf(SEPARATOR, i) == i) {
// add an escape character to the output
buffer.append(ESCAPE);
// add the found separator to the output
buffer.append(SEPARATOR);
// skip ahead the appropriate number of positions
i += SEPARATOR.length();
}
// if escape sequence starts at this position
else if (data.indexOf(ESCAPE, i) == i) {
// add an escape character to the output
buffer.append(ESCAPE);
// add the found escape character to the output
buffer.append(ESCAPE);
// skip ahead the appropriate number of positions
i += ESCAPE.length();
}
// otherwise add character at this position to the output
else buffer.append(data.charAt(i++));
}
// return the output as a String
return buffer.toString();
}
}