Package convex.core.data

Class Format

java.lang.Object

convex.core.data.Format

public class Format
extends Object

Static utility class for message format encoding "Standards are always out of date. That's what makes them standards." - Alan Bennett

Field Summary

Fields

Modifier and Type	Field	Description
static int	LIMIT_ENCODING_LENGTH	8191 byte system-wide limit on the legal length of a data object encoding.
static int	MAX_EMBEDDED_LENGTH	Maximum size in bytes of an embedded value, including tag
static int	MAX_REF_LENGTH	Maximum length in bytes of a Ref encoding (may be an embedded data object)
static int	MAX_VLC_LONG_LENGTH	Maximum length for a VLC encoded Long
static int	NULL_ENCODING_LENGTH	Encoded length of a null value

Constructor Summary

Constructors

Constructor	Description
Format()

Method Summary

Modifier and Type	Method	Description
static Blob	encodedBlob(ACell o)	Gets the encoded Blob for an object in canonical message format
static ByteBuffer	encodedBuffer(ACell cell)	Gets an new encoded ByteBuffer for an Cell in wire format
static String	encodedString(ACell cell)	Gets a hex String representing an object's encoding
static String	encodedString(Object o)	Gets a hex String representing an object's encoding.
static int	estimateSize(ACell cell)
static int	getVLCLength(long x)	Gets the length in bytes of VLC encoding for the given long value
static boolean	isCanonical(ACell o)	Returns true if the object is a canonical data object.
static boolean	isEmbedded(ACell cell)	Determines if an object should be embedded directly in the encoding rather than referenced with a Ref / hash.
static int	peekMessageLength(ByteBuffer bb)	Peeks for a VLC encoded message length at the start of a ByteBuffer, which must contain at least 1 byte, maximum 2.
static <T extends ACell> T	read(byte tag, Blob blob)	Read from a Blob with the specified tag
static <T extends ACell> T	read(Blob blob)	Decodes a single Value from a Blob.
static <T extends ACell> T	read(String hexString)	Read a value encoded as a hex string
static <T extends ACell> T	read(ByteBuffer bb)	Reads one complete Cell from a ByteBuffer.
static byte[]	readHexDigits(ByteBuffer bb, long start, long length)	Reads hex digits from ByteBuffer into the specified range of a new byte array.
static int	readLength(ByteBuffer bb)	Read an int length field (used for Strings etc.)
static long	readLong(ByteBuffer bb)	Reads a 64-bit long as 8 bytes from the ByteBuffer provided
static <T extends ACell> Ref<T>	readRef(ByteBuffer bb)	Reads a Ref from the ByteBuffer.
static Symbol	readSymbol(ByteBuffer bb)	Reads a Symbol from a ByteBuffer.
static String	readUTF8String(ByteBuffer bb)	Reads a UTF-8 String from a ByteBuffer.
static BigDecimal	readVLCBigDecimal(ByteBuffer bb)
static BigInteger	readVLCBigInteger(ByteBuffer bb)	Reads a BigInteger from the ByteBuffer.
static long	readVLCLong(byte[] data, int pos)	Reads a VLC encoded long as a long from the given location in a byte byte array.
static long	readVLCLong(ByteBuffer bb)	Reads a VLC encoded long from the given ByteBuffer.
static long	vlcSignExtend(byte b)	Sign extend 7th bit (sign) of a byte to all bits in a long
static int	write(byte[] bs, int pos, ACell cell)	Writes a canonical object to a byte array, preceded by the appropriate tag
static ByteBuffer	write(ByteBuffer bb, ACell cell)	Writes a canonical object to a ByteBuffer, preceded by the appropriate tag
static int	writeHexDigits(byte[] bs, int pos, ABlob src, long start, long length)	Writes hex digits from digit position start, total length.
static ByteBuffer	writeLength(ByteBuffer bb, int i)
static ByteBuffer	writeLong(ByteBuffer bb, long value)	Writes a 64-bit long as 8 bytes to the ByteBuffer provided
static ByteBuffer	writeMessageLength(ByteBuffer bb, int len)	Writes a message length as a VLC encoded long
static int	writeRawUTF8String(byte[] bs, int pos, String s)	Writes a raw string without tag to the byte array.
static ByteBuffer	writeRawUTF8String(ByteBuffer bb, String s)	Writes a raw string without tag to the byteBuffer.
static ByteBuffer	writeUTF8String(ByteBuffer bb, String s)	Writes a UTF-8 String to the byteBuffer.
static ByteBuffer	writeVLCBigDecimal(ByteBuffer bb, BigDecimal value)
static ByteBuffer	writeVLCBigInteger(ByteBuffer bb, BigInteger value)
static int	writeVLCLong(byte[] bs, int pos, long x)	Puts a variable length integer into the specified byte array (with no tag) Format: MSB of each byte 0=last octet, 1=more octets Following MSB, 7 bits of integer representation for each octet Second highest bit of first byte is interpreted as the sign
static ByteBuffer	writeVLCLong(ByteBuffer bb, long x)	Puts a VLC encoded long into the specified bytebuffer (with no tag) Format: MSB of each byte 0=last octet, 1=more octets Following MSB, 7 bits of integer representation for each octet Second highest bit of first byte is interpreted as the sign

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

LIMIT_ENCODING_LENGTH

public static final int LIMIT_ENCODING_LENGTH

8191 byte system-wide limit on the legal length of a data object encoding. Technical reasons for this choice:

• This is the max length that can be VLC encoded in a 2 byte message header. This simplifies message encoding and decoding.
• It is big enough to include a 4096-byte Blob

See Also:

Constant Field Values

MAX_VLC_LONG_LENGTH

public static final int MAX_VLC_LONG_LENGTH

Maximum length for a VLC encoded Long

See Also:

Constant Field Values

MAX_EMBEDDED_LENGTH

public static final int MAX_EMBEDDED_LENGTH

Maximum size in bytes of an embedded value, including tag

See Also:

Constant Field Values

NULL_ENCODING_LENGTH

public static final int NULL_ENCODING_LENGTH

Encoded length of a null value

See Also:

Constant Field Values

MAX_REF_LENGTH

public static final int MAX_REF_LENGTH

Maximum length in bytes of a Ref encoding (may be an embedded data object)

Constructor Details

Format

public Format()

Method Details

getVLCLength

public static int getVLCLength(long x)

Gets the length in bytes of VLC encoding for the given long value

Parameters:

x - Long value to encode

Returns:

Length of VLC encoding

writeVLCLong

public static ByteBuffer writeVLCLong(ByteBuffer bb,
 long x)

Puts a VLC encoded long into the specified bytebuffer (with no tag) Format:

• MSB of each byte 0=last octet, 1=more octets
• Following MSB, 7 bits of integer representation for each octet
• Second highest bit of first byte is interpreted as the sign

Parameters:

bb - ByteBuffer to write to

x - Value to VLC encode

Returns:

Updated ByteBuffer

writeVLCLong

public static int writeVLCLong(byte[] bs,
 int pos,
 long x)

Puts a variable length integer into the specified byte array (with no tag) Format:

• MSB of each byte 0=last octet, 1=more octets
• Following MSB, 7 bits of integer representation for each octet
• Second highest bit of first byte is interpreted as the sign

Parameters:

bs - Byte array to write to

pos - Initial position in byte array

x - Long value to write

Returns:

end position in byte array after writing VLC long

readVLCLong

public static long readVLCLong(ByteBuffer bb)
                        throws BadFormatException

Reads a VLC encoded long from the given ByteBuffer. Assumes no tag

Parameters:

bb - ByteBuffer from which to read

Returns:

Long value from ByteBuffer

Throws:

BadFormatException - If encoding is invalid

vlcSignExtend

public static long vlcSignExtend(byte b)

Sign extend 7th bit (sign) of a byte to all bits in a long

Parameters:

b - Byte to extend

Returns:

The sign-extended byte as a long

readVLCLong

public static long readVLCLong(byte[] data,
 int pos)
                        throws BadFormatException

Reads a VLC encoded long as a long from the given location in a byte byte array. Assumes no tag

Parameters:

data - Byte array

pos - Position from which to read in byte array

Returns:

long value from byte array

Throws:

BadFormatException - If format is invalid, or reading beyond end of array

peekMessageLength

public static int peekMessageLength(ByteBuffer bb)
                             throws BadFormatException

Peeks for a VLC encoded message length at the start of a ByteBuffer, which must contain at least 1 byte, maximum 2. Does not move the buffer position.

Parameters:

bb - ByteBuffer containing a message length

Returns:

The message length

Throws:

BadFormatException - If the ByteBuffer does not start with a valid message length

writeMessageLength

public static ByteBuffer writeMessageLength(ByteBuffer bb,
 int len)

Writes a message length as a VLC encoded long

Parameters:

bb - ByteBuffer with capacity available for writing

len - Length of message to write

Returns:

The ByteBuffer after writing the message length

writeVLCBigInteger

public static ByteBuffer writeVLCBigInteger(ByteBuffer bb,
 BigInteger value)

readVLCBigInteger

public static BigInteger readVLCBigInteger(ByteBuffer bb)
                                    throws BadFormatException

Reads a BigInteger from the ByteBuffer. Assumes tag already read.

Parameters:

bb - ByteBuffer to read from

Returns:

A BigInteger

Throws:

BadFormatException - If format is invalid

write

public static ByteBuffer write(ByteBuffer bb,
 ACell cell)

Writes a canonical object to a ByteBuffer, preceded by the appropriate tag

Parameters:

bb - ByteBuffer to write to

cell - Cell to write (may be null)

Returns:

The ByteBuffer after writing the specified object

write

public static int write(byte[] bs,
 int pos,
 ACell cell)

Writes a canonical object to a byte array, preceded by the appropriate tag

Parameters:

bs - Byte array to write to

pos - Starting position to write in byte array

cell - Cell to write (may be null)

Returns:

Position in byte array after writing the specified object

writeVLCBigDecimal

public static ByteBuffer writeVLCBigDecimal(ByteBuffer bb,
 BigDecimal value)

readVLCBigDecimal

public static BigDecimal readVLCBigDecimal(ByteBuffer bb)
                                    throws BadFormatException

Throws:

BadFormatException

writeUTF8String

public static ByteBuffer writeUTF8String(ByteBuffer bb,
 String s)

Writes a UTF-8 String to the byteBuffer. Includes string tag and length

Parameters:

bb - ByteBuffer to write to

s - String to write

Returns:

ByteBuffer after writing

writeRawUTF8String

public static ByteBuffer writeRawUTF8String(ByteBuffer bb,
 String s)

Writes a raw string without tag to the byteBuffer. Includes length in bytes of UTF-8 representation

Parameters:

bb - ByteBuffer to write to

s - String to write

Returns:

ByteBuffer after writing

writeRawUTF8String

public static int writeRawUTF8String(byte[] bs,
 int pos,
 String s)

Writes a raw string without tag to the byte array. Includes length in bytes of UTF-8 representation

Parameters:

bs - Byte array

pos - Starting position to write in byte array

s - String to write

Returns:

Position in byte array after writing

readUTF8String

public static String readUTF8String(ByteBuffer bb)
                             throws BadFormatException

Reads a UTF-8 String from a ByteBuffer. Assumes the object tag has already been read

Parameters:

bb - ByteBuffer to read from

Returns:

String from ByteBuffer

Throws:

BadFormatException - If encoding is invalid

readSymbol

public static Symbol readSymbol(ByteBuffer bb)
                         throws BadFormatException

Reads a Symbol from a ByteBuffer. Assumes the object tag has already been read

Parameters:

bb - ByteBuffer from which to read a Symbol

Returns:

Symbol read from ByteBuffer

Throws:

BadFormatException - If encoding is invalid

writeLength

public static ByteBuffer writeLength(ByteBuffer bb,
 int i)

readLength

public static int readLength(ByteBuffer bb)
                      throws BadFormatException

Read an int length field (used for Strings etc.)

Parameters:

bb - ByteBuffer from which to read

Returns:

Length field

Throws:

BadFormatException - If encoding is invalid

writeLong

public static ByteBuffer writeLong(ByteBuffer bb,
 long value)

Writes a 64-bit long as 8 bytes to the ByteBuffer provided

Parameters:

bb - Destination ByteBuffer

value - Value to write

Returns:

ByteBuffer after writing

readLong

public static long readLong(ByteBuffer bb)

Reads a 64-bit long as 8 bytes from the ByteBuffer provided

Parameters:

bb - Destination ByteBuffer

Returns:

long value

readRef

public static <T extends ACell> Ref<T> readRef(ByteBuffer bb)
                                        throws BadFormatException

Reads a Ref from the ByteBuffer. Converts Embedded objects to Refs automatically.

Type Parameters:

T - Type of referenced value

Parameters:

bb - ByteBuffer containing a ref to read

Returns:

Ref as read from ByteBuffer

Throws:

BadFormatException - If the data is badly formatted, or a non-embedded object is found.

read

public static <T extends ACell> T read(Blob blob)
                                throws BadFormatException

Decodes a single Value from a Blob. Assumes the presence of a tag. throws an exception if the Blob contents are not fully consumed

Parameters:

blob - Blob representing the Encoding of the Value

Returns:

Value read from the blob of encoded data

Throws:

BadFormatException - In case of encoding error

read

public static <T extends ACell> T read(byte tag,
 Blob blob)
                                throws BadFormatException

Read from a Blob with the specified tag

Type Parameters:

T - Type of value to read

Parameters:

tag - Tag to use for reading

blob - Blob to read from

Returns:

Value decoded

Throws:

BadFormatException - If encoding is invalid for the given tag

read

public static <T extends ACell> T read(String hexString)
                                throws BadFormatException

Read a value encoded as a hex string

Type Parameters:

T - Type of value to read

Parameters:

hexString - A valid hex String

Returns:

Value read

Throws:

BadFormatException - If encoding is invalid

read

public static <T extends ACell> T read(ByteBuffer bb)
                                throws BadFormatException

Reads one complete Cell from a ByteBuffer.

May return any valid Cell (including null)

Assumes the presence of an object tag.

Parameters:

bb - ByteBuffer from which to read

Returns:

Value read from the ByteBuffer

Throws:

BadFormatException - If encoding is invalid

isCanonical

public static boolean isCanonical(ACell o)

Returns true if the object is a canonical data object. Canonical data objects can be used as first class decentralised data objects.

Parameters:

o - Value to test

Returns:

true if object is canonical, false otherwise.

isEmbedded

public static boolean isEmbedded(ACell cell)

Determines if an object should be embedded directly in the encoding rather than referenced with a Ref / hash. Defined to be true for most small objects.

Parameters:

cell - Value to test

Returns:

true if object is embedded, false otherwise

encodedBlob

public static Blob encodedBlob(ACell o)

Gets the encoded Blob for an object in canonical message format

Parameters:

o - The object to encode

Returns:

Encoded data as a blob

encodedBuffer

public static ByteBuffer encodedBuffer(ACell cell)

Gets an new encoded ByteBuffer for an Cell in wire format

Parameters:

cell - The Cell to encode

Returns:

A ByteBuffer ready to read (i.e. already flipped)

writeHexDigits

public static int writeHexDigits(byte[] bs,
 int pos,
 ABlob src,
 long start,
 long length)

Writes hex digits from digit position start, total length. Fills final hex digit with 0 if length is odd.

Parameters:

bs - Byte array

pos - Position to write into byte array

src - Source Blob for hex digits

start - Start position in source blob (hex digit number from beginning)

length - Number of hex digits to write

Returns:

position after writing

readHexDigits

public static byte[] readHexDigits(ByteBuffer bb,
 long start,
 long length)
                            throws BadFormatException

Reads hex digits from ByteBuffer into the specified range of a new byte array. Needed for BlobMap encoding.

Parameters:

start - Start position (in hex digits)

length - Length (in hex digits)

bb - ByteBuffer to read from

Returns:

byte array containing hex digits

Throws:

BadFormatException - In case of bad Encoding format

encodedString

public static String encodedString(ACell cell)

Gets a hex String representing an object's encoding

Parameters:

cell - Any cell

Returns:

Hex String

encodedString

public static String encodedString(Object o)

Gets a hex String representing an object's encoding. Used in testing only.

Parameters:

o - Any object, will be cast to appropriate CVM type

Returns:

Hex String

estimateSize

public static int estimateSize(ACell cell)