org.ccnx.ccn.impl.encoding.BinaryXMLCodec Class Reference

The ccnb compressed binary XML codec. More...

Inheritance diagram for org.ccnx.ccn.impl.encoding.BinaryXMLCodec:

org.ccnx.ccn.impl.encoding.XMLCodec

List of all members.

Static Public Member Functions

static final 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 (final int type, final long value, final 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 final byte XML_EXT = 0x00
 Values encoded in type and value composites.
static final byte XML_TAG = 0x01
 // starts composite - value is tagnamelen-1
static final byte XML_DTAG = 0x02
 // starts composite - value is tagdict index
static final byte XML_ATTR = 0x03
 // attribute - value is attrnamelen-1, attribute value follows
static final byte XML_DATTR = 0x04
 // attribute value is attrdict index
static final byte XML_BLOB = 0x05
 // opaque binary data - value is byte count
static final byte XML_UDATA = 0x06
 // UTF-8 encoded character data - value is byte count
static final byte XML_CLOSE = 0x0
 // end element
static final byte XML_SUBTYPE_PROCESSING_INSTRUCTIONS = 16
 // <?name:U value:U?>
static final int XML_TT_BITS = 3
 Masks for bitwise processing.
static final int XML_TT_MASK = ((1 << XML_TT_BITS) - 1)
static final int XML_TT_VAL_BITS = XML_TT_BITS + 1
static final int XML_TT_VAL_MASK = ((1 << (XML_TT_VAL_BITS)) - 1)
static final int XML_REG_VAL_BITS = 7
static final int XML_REG_VAL_MASK = ((1 << XML_REG_VAL_BITS) - 1)
static final int XML_TT_NO_MORE = (1 << XML_REG_VAL_BITS)
static final int BYTE_MASK = 0xFF
static final int LONG_BYTES = 8
static final 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)

Classes

class  TypeAndVal
 Class for managing the paired type/value representation used to encode tags and content lengths. More...


Detailed Description

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.


Member Function Documentation

static final String org.ccnx.ccn.impl.encoding.BinaryXMLCodec.codecName (  )  [static]

The name of this codec.

Used to generate XMLEncoder and XMLDecoder instances with XMLCodecFactory.

Returns:
the codec name.

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.

Parameters:
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
Returns:
the number of bytes used to encode.
Deprecated:
Use encodeTypeAndVal(final int type, final long value, final OutputStream ostream)

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.

Parameters:
type the type value to encode
val Positive integer, potentially of any length, allow only longs here.
Returns:
the encoded type and value
Deprecated:
Use encodeTypeAndVal(final int type, final long value, final OutputStream ostream)

static int org.ccnx.ccn.impl.encoding.BinaryXMLCodec.encodeTypeAndVal ( final int  type,
final long  value,
final 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.

Parameters:
tag the type value to encode
val Positive integer, potentially of any length, allow only longs here.
ostream the stream to encode to
Returns:
the number of bytes encoded

static TypeAndVal org.ccnx.ccn.impl.encoding.BinaryXMLCodec.decodeTypeAndVal ( InputStream  istream  )  throws IOException [static]

Decodes a type and value pair from an InputStream.

Parameters:
istream stream to read from
Returns:
a decoded type and value
Exceptions:
IOException if there is an error reading or decoding the type and value pair

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.

Parameters:
istream stream to read from
Returns:
a decoded type and value
Exceptions:
IOException if there is an error reading or decoding the type and value pair

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.

Parameters:
x number we want to know bit length of
Returns:
bit length of x

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.

Parameters:
istream stream to read from
Returns:
returns decoded blob (binary content)
Exceptions:
IOException if stream cannot be read, decoded or reset

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.

Parameters:
istream stream to read from
blobLength the length of the binary content to read in bytes
Returns:
returns decoded blob (binary content)
Exceptions:
IOException if stream cannot be read or decoded

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.

Parameters:
ostream the stream to write to
blob the binary content to write
Exceptions:
IOException if there is an error encoding or writing the data

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.

Parameters:
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
Exceptions:
IOException if there is an error encoding or writing the data

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.

Parameters:
istream stream to read from
Returns:
returns decoded String
Exceptions:
IOException if stream cannot be read, decoded or reset

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.

Parameters:
istream stream to read from
byteLength length of element to read
Returns:
returns the decoded String
Exceptions:
IOException if stream cannot be read or decoded

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).

Parameters:
ostream stream to encode to
ustring String to encode
Exceptions:
IOException if there is an error encoding the data or writing to the stream

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.

Parameters:
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)
Exceptions:
IOException if there is an error encoding or writing the data


Member Data Documentation

Values encoded in type and value composites.

// starts composite extension - value is subtype

Masks for bitwise processing.

Java's bitwise operations operate on ints, so save effort of promotion.


The documentation for this class was generated from the following file:

Generated on Thu Feb 16 00:44:52 2012 for Content-Centric Networking in Java by  doxygen 1.5.6