Package io.permazen.kv.util

Class KeyListEncoder

java.lang.Object

io.permazen.kv.util.KeyListEncoder

public final class KeyListEncoder
extends Object

Serializes a sequence of byte[] arrays, or byte[] key/value pairs, using a simple key prefix compression scheme.

Keys are encoded/decoded by read() and write() in one of two forms:

• total-length bytes...
• -prefix-length suffix-length suffix-bytes ...

In the first form, the total-length is encoded using LongEncoder as a positive number and is followed by that many bytes consituting the key. In the second form, the length of the key prefix that matches the previous key is encoded as a negative value using LongEncoder, followed by the number of suffix bytes encoded via UnsignedIntEncoder, followed by that many suffix bytes.

Support for encoding and decoding an entire iteration of key/value pairs is supported via readPairs() and writePairs().

Method Summary

Modifier and Type	Method	Description
static ByteData	read(InputStream input, ByteData prev)	Read the next key.
static Iterator<KVPair>	readPairs(InputStream input)	Decode an iteration of key/value pairs previously encoded by writePairs().
static void	write(OutputStream out, ByteData key, ByteData prev)	Write the next key, compressing its common prefix with the previous key (if any).
static int	writeLength(ByteData key, ByteData prev)	Calculate the number of bytes that would be required to write the next key via write().
static void	writePairs(Iterator<KVPair> kvpairs, OutputStream output)	Encode an iteration of key/value pairs.
static long	writePairsLength(Iterator<KVPair> kvpairs)	Determine the number of bytes that would be written by writePairs().

Methods inherited from class java.lang.Object

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

Method Details

write

public static void write(OutputStream out,
 ByteData key,
 ByteData prev)
                  throws IOException

Write the next key, compressing its common prefix with the previous key (if any).

Parameters:

out - output stream

key - key to write

prev - previous key, or null for none

Throws:

IOException - if an I/O error occurs

IllegalArgumentException - if out or key is null

writeLength

public static int writeLength(ByteData key,
 ByteData prev)

Calculate the number of bytes that would be required to write the next key via write().

Parameters:

key - key to write

prev - previous key, or null for none

Returns:

number of bytes to be written by write(out, key, prev)

Throws:

IllegalArgumentException - if key is null

read

public static ByteData read(InputStream input,
 ByteData prev)
                     throws IOException

Read the next key.

Parameters:

input - input stream

prev - previous key, or null for none

Returns:

next key

Throws:

IOException - if an I/O error occurs

EOFException - if an unexpected EOF is encountered

IllegalArgumentException - if input is null

IllegalArgumentException - if input contains invalid data

writePairs

public static void writePairs(Iterator<KVPair> kvpairs,
 OutputStream output)
                       throws IOException

Encode an iteration of key/value pairs.

Each key/value pair is encoded by encoding the key using prefix compression from the previous key, followed by the value with no prefix compression. A final 0xff byte terminates the sequence.

Parameters:

kvpairs - key/value pair iteration

output - encoded output

Throws:

IOException - if an I/O error occurs

IllegalArgumentException - if either parameter is null

writePairsLength

public static long writePairsLength(Iterator<KVPair> kvpairs)

Determine the number of bytes that would be written by writePairs().

Parameters:

kvpairs - key/value pair iteration

Returns:

encoded length of this instance

Throws:

IllegalArgumentException - if kvpairs is null

IllegalArgumentException - if the result is larger than Long.MAX_VALUE

readPairs

public static Iterator<KVPair> readPairs(InputStream input)

Decode an iteration of key/value pairs previously encoded by writePairs().

If an IOException occurs during iteration, the returned Iterator wraps it in a RuntimeException.

If invalid input is encountered during iteration, the returned Iterator will throw an IllegalArgumentException.

Decoding stops after reading the end of stream or a terminating 0xff byte.

Parameters:

input - encoded input

Returns:

iteration of key/value pairs

Throws:

IllegalArgumentException - if input is null