The ccnb compressed binary XML codec. More...
Classes | |
class | TypeAndVal |
Class for managing the paired type/value representation used to encode tags and content lengths. More... | |
Static Public Member Functions | |
static String | codecName () |
The name of this codec. | |
static int | encodeTypeAndVal (int type, long val, byte[] buf, int offset) |
Encode a type identifier (from the set listed above) and an integer value together in a composite encoding. | |
static byte[] | encodeTypeAndVal (int type, long val) |
Convenience method. | |
static int | encodeTypeAndVal (int tag, long val, OutputStream ostream) throws IOException |
Convenience method. | |
static TypeAndVal | decodeTypeAndVal (InputStream istream) throws IOException |
Decodes a type and value pair from an InputStream. | |
static TypeAndVal | peekTypeAndVal (InputStream istream) throws IOException |
Decodes a type and value pair from an InputStream, and then resets that stream at its original position. | |
static int | numbits (long x) |
Helper method, return the number of significant bits of x. | |
static int | numEncodingBytes (long x) |
static byte[] | decodeBlob (InputStream istream) throws IOException |
Decodes a binary blob (encoded binary content) from an InputStream. | |
static byte[] | decodeBlob (InputStream istream, int blobLength) throws IOException |
Decodes a binary blob (encoded binary content) from an InputStream when we have already read the BLOB tag and length, and just need to read the content. | |
static void | encodeBlob (OutputStream ostream, byte[] blob) throws IOException |
Encodes a binary BLOB (binary content) to an output stream. | |
static void | encodeBlob (OutputStream ostream, byte[] blob, int offset, int length) throws IOException |
Encodes a binary BLOB (binary content) to an output stream. | |
static String | decodeUString (InputStream istream) throws IOException |
Decodes a UTF-8 string element's content from an InputStream. | |
static String | decodeUString (InputStream istream, int byteLength) throws IOException |
Decodes a UTF-8 string element's content from an InputStream when we've read the type indicator (which could be UDATA, or TAG, or ATTR) and just need to get the data. | |
static void | encodeUString (OutputStream ostream, String ustring) throws IOException |
Encode a non-TAG, non-ATTR UString (UTF-8 String). | |
static void | encodeUString (OutputStream ostream, String ustring, byte type) throws IOException |
Encode the special case the UStrings that represent TAG and ATTR. | |
Static Public Attributes | |
static final String | CODEC_NAME = "Binary" |
static byte | XML_EXT = 0x00 |
Values encoded in type and value composites. | |
static byte | XML_TAG = 0x01 |
// starts composite - value is tagnamelen-1 | |
static byte | XML_DTAG = 0x02 |
// starts composite - value is tagdict index | |
static byte | XML_ATTR = 0x03 |
// attribute - value is attrnamelen-1, attribute value follows | |
static byte | XML_DATTR = 0x04 |
// attribute value is attrdict index | |
static byte | XML_BLOB = 0x05 |
// opaque binary data - value is byte count | |
static byte | XML_UDATA = 0x06 |
// UTF-8 encoded character data - value is byte count | |
static byte | XML_CLOSE = 0x0 |
// end element | |
static byte | XML_SUBTYPE_PROCESSING_INSTRUCTIONS = 16 |
// <?name:U value:U?> | |
static int | XML_TT_BITS = 3 |
Masks for bitwise processing. | |
static int | XML_TT_MASK = ((1 << XML_TT_BITS) - 1) |
static int | XML_TT_VAL_BITS = XML_TT_BITS + 1 |
static int | XML_TT_VAL_MASK = ((1 << (XML_TT_VAL_BITS)) - 1) |
static int | XML_REG_VAL_BITS = 7 |
static int | XML_REG_VAL_MASK = ((1 << XML_REG_VAL_BITS) - 1) |
static int | XML_TT_NO_MORE = (1 << XML_REG_VAL_BITS) |
static int | BYTE_MASK = 0xFF |
static int | LONG_BYTES = 8 |
static int | LONG_BITS = 64 |
Static Package Attributes | |
static final int | ENCODING_LIMIT_1_BYTE = ((1 << (XML_TT_VAL_BITS)) - 1) |
static final int | ENCODING_LIMIT_2_BYTES = ((1 << (XML_TT_VAL_BITS + XML_REG_VAL_BITS)) - 1) |
static final int | ENCODING_LIMIT_3_BYTES = ((1 << (XML_TT_VAL_BITS + 2 * XML_REG_VAL_BITS)) - 1) |
The ccnb compressed binary XML codec.
This class contains utility functions used by BinaryXMLEncoder and BinaryXMLDecoder as well as setup to use this codec with XMLCodecFactory.
Ccnb encoding uses a dictionary to turn tag and attribute names into short binary identifiers, and uses a compressed encoding for those identifiers and the lengths of atomic UTF-8 and binary data. For easy encoding & decoding there are no lengths of elements; this means encoding can be done as a single pass because the length of an encoded child element does not need to be known in order to write the start of the parent element.
The possible type tags:
See the protocol documentation for more details of the ccnb format.
static String org.ccnx.ccn.impl.encoding.BinaryXMLCodec.codecName | ( | ) | [static] |
The name of this codec.
Used to generate XMLEncoder and XMLDecoder instances with XMLCodecFactory.
static byte [] org.ccnx.ccn.impl.encoding.BinaryXMLCodec.decodeBlob | ( | InputStream | istream, | |
int | blobLength | |||
) | throws IOException [static] |
Decodes a binary blob (encoded binary content) from an InputStream when we have already read the BLOB tag and length, and just need to read the content.
istream | stream to read from | |
blobLength | the length of the binary content to read in bytes |
IOException | if stream cannot be read or decoded |
static byte [] org.ccnx.ccn.impl.encoding.BinaryXMLCodec.decodeBlob | ( | InputStream | istream | ) | throws IOException [static] |
Decodes a binary blob (encoded binary content) from an InputStream.
Expects to read a XML_BLOB type marker, and then the data. Has to peek to cope with 0-length blob. Inline the peek to avoid unneeded resets.
istream | stream to read from |
IOException | if stream cannot be read, decoded or reset |
static TypeAndVal org.ccnx.ccn.impl.encoding.BinaryXMLCodec.decodeTypeAndVal | ( | InputStream | istream | ) | throws IOException [static] |
Decodes a type and value pair from an InputStream.
istream | stream to read from |
IOException | if there is an error reading or decoding the type and value pair |
static String org.ccnx.ccn.impl.encoding.BinaryXMLCodec.decodeUString | ( | InputStream | istream, | |
int | byteLength | |||
) | throws IOException [static] |
Decodes a UTF-8 string element's content from an InputStream when we've read the type indicator (which could be UDATA, or TAG, or ATTR) and just need to get the data.
Assumes caller will cope with the fact that TAGs and ATTRs have encoded lengths that are one byte shorter than their actual data length, and that the length passed in here is actually the length of data we should read.
istream | stream to read from | |
byteLength | length of element to read |
IOException | if stream cannot be read or decoded |
static String org.ccnx.ccn.impl.encoding.BinaryXMLCodec.decodeUString | ( | InputStream | istream | ) | throws IOException [static] |
Decodes a UTF-8 string element's content from an InputStream.
Expects to read a XML_UDATA type marker, and then the data. Has to peek to cope with 0-length ustring. Inline the peek to avoid unneeded resets. This will not decode a TAG or ATTR ustring.
istream | stream to read from |
IOException | if stream cannot be read, decoded or reset |
static void org.ccnx.ccn.impl.encoding.BinaryXMLCodec.encodeBlob | ( | OutputStream | ostream, | |
byte[] | blob, | |||
int | offset, | |||
int | length | |||
) | throws IOException [static] |
Encodes a binary BLOB (binary content) to an output stream.
ostream | the stream to write to | |
blob | the binary content to write | |
offset | the offset into blob at which to start encoding data | |
length | the number of bytes of blob to encode |
IOException | if there is an error encoding or writing the data |
static void org.ccnx.ccn.impl.encoding.BinaryXMLCodec.encodeBlob | ( | OutputStream | ostream, | |
byte[] | blob | |||
) | throws IOException [static] |
Encodes a binary BLOB (binary content) to an output stream.
ostream | the stream to write to | |
blob | the binary content to write |
IOException | if there is an error encoding or writing the data |
static int org.ccnx.ccn.impl.encoding.BinaryXMLCodec.encodeTypeAndVal | ( | int | tag, | |
long | val, | |||
OutputStream | ostream | |||
) | throws IOException [static] |
Convenience method.
Encodes type and val into output stream using encodeTypeAndVal(int, long, byte [], int) and returns the number of bytes encoded.
tag | the type value to encode | |
val | Positive integer, potentially of any length, allow only longs here. | |
ostream | the stream to encode to |
static byte [] org.ccnx.ccn.impl.encoding.BinaryXMLCodec.encodeTypeAndVal | ( | int | type, | |
long | val | |||
) | [static] |
Convenience method.
Encodes type and val into fixed buffer using encodeTypeAndVal(int, long, byte [], int) and returns the result.
type | the type value to encode | |
val | Positive integer, potentially of any length, allow only longs here. |
static int org.ccnx.ccn.impl.encoding.BinaryXMLCodec.encodeTypeAndVal | ( | int | type, | |
long | val, | |||
byte[] | buf, | |||
int | offset | |||
) | [static] |
Encode a type identifier (from the set listed above) and an integer value together in a composite encoding.
Value is encoded in the first several bytes; with the tag encoded in the last three bits. The encoding of value is variable length in the bottom 7 bits of every byte except for the last one, where it is in the next to top 4 bits; the high order bit is set on every byte where there are more bytes to follow.
type | the type value to encode | |
val | Positive integer, potentially of any length, allow only longs here. | |
buf | the buffer to encode into | |
offset | the offset into buf at which to start encoding |
static void org.ccnx.ccn.impl.encoding.BinaryXMLCodec.encodeUString | ( | OutputStream | ostream, | |
String | ustring, | |||
byte | type | |||
) | throws IOException [static] |
Encode the special case the UStrings that represent TAG and ATTR.
The lengths of these strings are represented as length-1, as they can never be 0 length. The decrement is done here, rather than in encodeTypeAndVal.
ostream | the stream to encode to | |
ustring | the String containing the TAG or ATTR value. If null or a zero length string is passed in then nothing is written to the output. | |
type | the type to encode (XML_TAG or XML_ATTR) |
IOException | if there is an error encoding or writing the data |
static void org.ccnx.ccn.impl.encoding.BinaryXMLCodec.encodeUString | ( | OutputStream | ostream, | |
String | ustring | |||
) | throws IOException [static] |
Encode a non-TAG, non-ATTR UString (UTF-8 String).
ostream | stream to encode to | |
ustring | String to encode |
IOException | if there is an error encoding the data or writing to the stream |
static int org.ccnx.ccn.impl.encoding.BinaryXMLCodec.numbits | ( | long | x | ) | [static] |
Helper method, return the number of significant bits of x.
Deprecated; unused here, but left since it is public.
x | number we want to know bit length of |
static TypeAndVal org.ccnx.ccn.impl.encoding.BinaryXMLCodec.peekTypeAndVal | ( | InputStream | istream | ) | throws IOException [static] |
Decodes a type and value pair from an InputStream, and then resets that stream at its original position.
istream | stream to read from |
IOException | if there is an error reading or decoding the type and value pair |
byte org.ccnx.ccn.impl.encoding.BinaryXMLCodec.XML_EXT = 0x00 [static] |
Values encoded in type and value composites.
// starts composite extension - value is subtype
int org.ccnx.ccn.impl.encoding.BinaryXMLCodec.XML_TT_BITS = 3 [static] |
Masks for bitwise processing.
Java's bitwise operations operate on ints, so save effort of promotion.