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.

PentaCodec is the only supported implementation of the symbol codec. Other implementations are deprecated and will not be supported in the future.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	SymbolCodec.Reader Stateful symbol reader.
static interface	SymbolCodec.Resolver Symbol resolver to reuse string symbol instances.
static class	SymbolCodec.Writer Stateful symbol writer.

Field Summary

Fields

Modifier and Type	Field and Description
static int	VALID_CIPHER VALID_CIPHER defines range of valid encoded ciphers.

Method Summary

Modifier and Type	Method and Description
SymbolCodec.Reader	createReader() Creates stateful symbol reader.
SymbolCodec.Writer	createWriter() Creates stateful symbol writer.
String	decode(int cipher) Returns decoded symbol for specified cipher.
String	decode(int cipher, 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.
long	decodeToLong(int cipher) Returns decoded symbol for specified cipher packed in the primitive long value.
int	encode(char[] chars, int offset, int length) Returns encoded cipher for specified symbol represented in a character array.
int	encode(String symbol) Returns encoded cipher for specified symbol.
int	getWildcardCipher() Returns cipher that is used by the "wildcard" symbol.
int	hashCode(int cipher) Returns a hash code for the specified cipher.

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(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:

NullPointerException - if specified array is null.

IndexOutOfBoundsException - if specified parameters refers to characters outside specified array.

decode

String decode(int cipher)

Returns decoded symbol for specified cipher. Returns null if specified cipher is 0.

Throws:

IllegalArgumentException - if specified cipher could not be decoded.

decode

String decode(int cipher,
              String symbol)

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

decodeToLong

long decodeToLong(int cipher)

Returns decoded symbol for specified cipher packed in the primitive long value. Each decoded character occupies exactly 8 bits started from highest bit of returned value. Unused (lowest) bits of returned value are filled with 0. Returns 0 if specified cipher is 0.

This is the same encoding as specified by ShortString class. The result of ShortString.decode(decodeToLong(cipher)) expression shall be the same as result of decode(cipher) call except for null vs empty string discrepancy. However this method always aligns bytes in returned value to the highest one rather than lowest one.

Throws:

IllegalArgumentException - if specified cipher could not be decoded.

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 character or -1 if i >= decode(cipher).length().

Throws:

IllegalArgumentException - if specified cipher could not be decoded or i < 0.

hashCode

int hashCode(int cipher)

Returns a hash code for the specified cipher. Returns 0 if specified cipher is 0. The hash code is the same as decode(cipher).hashCode() except it does not throw NullPointerException for 0 cipher.

getWildcardCipher

int getWildcardCipher()

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

createReader

SymbolCodec.Reader createReader()

Creates stateful symbol reader.

createWriter

SymbolCodec.Writer createWriter()

Creates stateful symbol writer.