com.devexperts.qd
Interface SymbolCodec

All Known Implementing Classes:
PentaCodec

public interface SymbolCodec

The SymbolCodec defines coding and serialization of symbols. It is believed that most symbols can be effectively encoded into a single 32-bit value with full decoding capability. Taking into account that 32-bit values occupy much less memory and are processed much faster than strings, the symbol coding is used to achieve high performance.

The encoded representation of the symbol is called cipher; it uses Java int primitive data type for physical representation. The int cipher together with String symbol constitute cipher-symbol pair which is used throughout the system as a key to the symbol.

The table below defines allowed cipher-symbol pairs and their meaning:

 cipher == 0, symbol == null    - undefined, unknown, void, null
 cipher == 0, symbol != null    - unencodeable, defined by symbol
 cipher != 0, symbol == null    - encoded, defined by cipher
 cipher != 0, symbol != null    - encoded, defined by cipher, symbol must correspond to cipher
 
NOTE: it is prohibited not to encode symbol if it is encodeable, but it is allowed to omit raw symbol string (use null) for encoded ciphers.
NOTE: the range from 1 to 0x3FFFFFFF inclusive is reserved - no valid cipher is allowed to have value in this range. More precisely, for any valid encoded cipher the expression ((cipher & VALID_CIPHER) != 0) must be true. This range is reserved for private subsystem implementations - any subsystem may use this range internally as long as reserved values do not appear in its public API.

The SymbolCodec must be provided to QD by APS. It must perform coding and serialization on-the-fly without need to look into external resources each time. The PentaCodec gives a good example of generic symbol codec.


Field Summary
static int VALID_CIPHER
          VALID_CIPHER defines range of valid encoded ciphers.
 
Method Summary
 java.lang.String decode(int cipher)
          Returns decoded symbol for specified cipher.
 java.lang.String decode(int cipher, java.lang.String symbol)
          Returns decoded symbol for specified cipher-symbol pair.
 int decodeCharAt(int cipher, int i)
          Decodes one character from the given cipher at the given position.
 int encode(char[] chars, int offset, int length)
          Returns encoded cipher for specified symbol represented in a character array.
 int encode(java.lang.String symbol)
          Returns encoded cipher for specified symbol.
 int getWildcardCipher()
          Returns cipher that is used by the "wildcard" symbol.
 int readSymbol(com.devexperts.io.BufferedInput in, char[] buffer, java.lang.String[] result)
          Reads symbol from specified input stream and returns it in several ways depending on it's encodability and length.
 void readSymbol(java.io.DataInput in, SymbolReceiver receiver)
          Reads symbol from specified data intput and passes it into specified receiver.
 void writeSymbol(java.io.DataOutput out, int cipher, java.lang.String symbol)
          Writes specified symbol into specified data output.
 

Field Detail

VALID_CIPHER

static final int VALID_CIPHER
VALID_CIPHER defines range of valid encoded ciphers. See documentation of SymbolCodec for details.

See Also:
Constant Field Values
Method Detail

encode

int encode(java.lang.String symbol)
Returns encoded cipher for specified symbol. Returns 0 if specified symbol is null or is unencodeable.


encode

int encode(char[] chars,
           int offset,
           int length)
Returns encoded cipher for specified symbol represented in a character array. Returns 0 if specified symbol is unencodeable. This method must produce the same result as the following code:
encode(new String(chars, offset, length));.

Throws:
java.lang.NullPointerException - if specified array is null.
java.lang.IndexOutOfBoundsException - if specified parameters refers to characters outside specified array.

decode

java.lang.String decode(int cipher)
Returns decoded symbol for specified cipher. Returns null if specified cipher is 0.

Throws:
java.lang.IllegalArgumentException - if specified cipher could not be decoded.

decode

java.lang.String decode(int cipher,
                        java.lang.String symbol)
Returns decoded symbol for specified cipher-symbol pair. This is a shortcut with the following implementation:
return symbol != null ? symbol : decode(cipher);.


decodeCharAt

int decodeCharAt(int cipher,
                 int i)
Decodes one character from the given cipher at the given position. This method should be used only when few (one or two) characters are needed.

Returns:
Decoded characher or -1 if i >= decode(cipher).length().
Throws:
java.lang.IllegalArgumentException - if if specified cipher could not be decoded or i < 0.

getWildcardCipher

int getWildcardCipher()
Returns cipher that is used by the "wildcard" symbol. Wildcard symbol shall be chosen from a space of encodable symbols.


writeSymbol

void writeSymbol(java.io.DataOutput out,
                 int cipher,
                 java.lang.String symbol)
                 throws java.io.IOException
Writes specified symbol into specified data output.

Throws:
java.io.IOException - as specified data output does.

readSymbol

void readSymbol(java.io.DataInput in,
                SymbolReceiver receiver)
                throws java.io.IOException
Reads symbol from specified data intput and passes it into specified receiver.

Throws:
java.io.IOException - as specified data input does.

readSymbol

int readSymbol(com.devexperts.io.BufferedInput in,
               char[] buffer,
               java.lang.String[] result)
               throws java.io.IOException
Reads symbol from specified input stream and returns it in several ways depending on it's encodability and length. If this method returns: Both buffer and result parameters shall be local to the ongoing operation; they are used for local storage and to return result to the caller; they are not used by the codec after that. The buffer shall be large enough to accomodate common short symbols, for example 64 characters. The result shall have length 1 because only first element is ever used.

Parameters:
in - the source to read from
buffer - char buffer to use for reading operation and to return short non-encodable symbols
result - array used to return long non-encodable symbols
Returns:
result type code as described in the method above
Throws:
java.io.IOException - if an I/O error occurs