|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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 cipherNOTE: 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.
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 |
---|
static final int VALID_CIPHER
SymbolCodec
for details.
Method Detail |
---|
int encode(java.lang.String symbol)
int encode(char[] chars, int offset, int length)
encode(new String(chars, offset, length));
.
java.lang.NullPointerException
- if specified array is null.
java.lang.IndexOutOfBoundsException
- if specified parameters refers to
characters outside specified array.java.lang.String decode(int cipher)
java.lang.IllegalArgumentException
- if specified cipher could not be decoded.java.lang.String decode(int cipher, java.lang.String symbol)
return symbol != null ? symbol : decode(cipher);
.
int decodeCharAt(int cipher, int i)
-1
if i >= decode(cipher).length()
.
java.lang.IllegalArgumentException
- if if specified cipher could not be decoded or i < 0
.int getWildcardCipher()
void writeSymbol(java.io.DataOutput out, int cipher, java.lang.String symbol) throws java.io.IOException
java.io.IOException
- as specified data output does.void readSymbol(java.io.DataInput in, SymbolReceiver receiver) throws java.io.IOException
java.io.IOException
- as specified data input does.int readSymbol(com.devexperts.io.BufferedInput in, char[] buffer, java.lang.String[] result) throws java.io.IOException
0
; result array is unchanged;
0
- symbol is stored in the result array at index 0
; buffer content is destroyed;
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.
in
- the source to read frombuffer
- char buffer to use for reading operation and to return short non-encodable symbolsresult
- array used to return long non-encodable symbols
java.io.IOException
- if an I/O error occurs
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |