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, compressing consecutive common prefixes.

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

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

The first length (total-length or negative prefix-length) is encoded using LongEncoder. The suffix-length, if present, is encoded using UnsignedIntEncoder.

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

Method Summary

Modifier and Type	Method and Description
static byte[]	read(InputStream input, byte[] 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, byte[] key, byte[] prev) Write the next key, compressing its common prefix with the previous key (if any).
static int	writeLength(byte[] key, byte[] 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 Detail

write

public static void write(OutputStream out,
                         byte[] key,
                         byte[] 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(byte[] key,
                              byte[] 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 byte[] read(InputStream input,
                          byte[] 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.

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

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.

Parameters:

input - encoded input

Returns:

iteration of key/value pairs

Throws:

IllegalArgumentException - if input is null