net.agkn.hll.serialization

Class SerializationUtil

java.lang.Object

net.agkn.hll.serialization.SerializationUtil

public class SerializationUtil
extends Object

A collection of constants and utilities for serializing and deserializing HLLs. NOTE: 'package' visibility is used for many methods that only need to be used by the ISchemaVersion implementations. The structure of a serialized HLL's metadata should be opaque to the rest of the library.

Author:

timon

Field Summary

Fields

Modifier and Type	Field and Description
static ISchemaVersion	DEFAULT_SCHEMA_VERSION The default schema version for serializing HLLs.
static ISchemaVersion[]	REGISTERED_SCHEMA_VERSIONS List of registered schema versions, indexed by their version numbers.
static ISchemaVersion	VERSION_ONE Schema version one (v1).

Constructor Summary

Constructors

Constructor and Description
SerializationUtil()

Method Summary

Modifier and Type	Method and Description
static int	explicitCutoff(byte cutoffByte) Extracts the explicit cutoff value from the cutoff byte of a serialized HLL.
static ISchemaVersion	getSchemaVersion(byte[] bytes) Get the appropriate schema version for the specified serialized HLL.
static ISchemaVersion	getSchemaVersion(int schemaVersionNumber)
static byte	packCutoffByte(int explicitCutoff, boolean sparseEnabled) Generates a byte that encodes the log-base-2 of the explicit cutoff or sentinel values for 'explicit-disabled' or 'auto', as well as the boolean indicating whether to use HLLType.SPARSE in the promotion hierarchy.
static byte	packParametersByte(int registerWidth, int registerCountLog2) Generates a byte that encodes the parameters of a HLLType.FULL or HLLType.SPARSE HLL. The top 3 bits are used to encode registerWidth - 1 (range of registerWidth is thus 1-9) and the bottom 5 bits are used to encode registerCountLog2 (range of registerCountLog2 is thus 0-31).
static byte	packVersionByte(int schemaVersion, int typeOrdinal) Generates a byte that encodes the schema version and the type ordinal of the HLL.
static int	registerCountLog2(byte parametersByte) Extracts the log2(registerCount) from the parameters byte of a serialized HLLType.FULL HLL.
static int	registerWidth(byte parametersByte) Extracts the register width from the parameters byte of a serialized HLLType.FULL HLL.
static int	schemaVersion(byte versionByte) Extracts the schema version from the version byte of a serialized HLL.
static boolean	sparseEnabled(byte cutoffByte) Extracts the 'sparse-enabled' boolean from the cutoff byte of a serialized HLL.
static int	typeOrdinal(byte versionByte) Extracts the type ordinal from the version byte of a serialized HLL.

Methods inherited from class java.lang.Object

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

Field Detail

VERSION_ONE

public static ISchemaVersion VERSION_ONE

Schema version one (v1).

DEFAULT_SCHEMA_VERSION

public static ISchemaVersion DEFAULT_SCHEMA_VERSION

The default schema version for serializing HLLs.

REGISTERED_SCHEMA_VERSIONS

public static ISchemaVersion[] REGISTERED_SCHEMA_VERSIONS

List of registered schema versions, indexed by their version numbers. If an entry is null, then no such schema version is registered. Similarly, registering a new schema version simply entails assigning an ISchemaVersion instance to the appropriate index of this array.

By default, only SchemaVersionOne is registered. Note that version zero will always be reserved for internal (e.g. proprietary, legacy) schema specifications/implementations and will never be assigned to in by this library.

Constructor Detail

SerializationUtil

public SerializationUtil()

Method Detail

getSchemaVersion

public static ISchemaVersion getSchemaVersion(int schemaVersionNumber)

Parameters:

schemaVersionNumber - the version number of the ISchemaVersion desired. This must be a registered schema version number.

Returns:

The ISchemaVersion for the given number. This will never be null.

getSchemaVersion

public static ISchemaVersion getSchemaVersion(byte[] bytes)

Get the appropriate schema version for the specified serialized HLL.

Parameters:

bytes - the serialized HLL whose schema version is desired.

Returns:

the schema version for the specified HLL. This will never be null.

packVersionByte

public static byte packVersionByte(int schemaVersion,
                                   int typeOrdinal)

Generates a byte that encodes the schema version and the type ordinal of the HLL. The top nibble is the schema version and the bottom nibble is the type ordinal.

Parameters:

schemaVersion - the schema version to encode.

typeOrdinal - the type ordinal of the HLL to encode.

Returns:

the packed version byte

packCutoffByte

public static byte packCutoffByte(int explicitCutoff,
                                  boolean sparseEnabled)

Generates a byte that encodes the log-base-2 of the explicit cutoff or sentinel values for 'explicit-disabled' or 'auto', as well as the boolean indicating whether to use HLLType.SPARSE in the promotion hierarchy. The top bit is always padding, the second highest bit indicates the 'sparse-enabled' boolean, and the lowest six bits encode the explicit cutoff value.

Parameters:

explicitCutoff - the explicit cutoff value to encode.

• If 'explicit-disabled' is chosen, this value should be 0.
• If 'auto' is chosen, this value should be 63.
• If a cutoff of 2ⁿ is desired, for 0 <= n < 31, this value should be n + 1.

sparseEnabled - whether HLLType.SPARSE should be used in the promotion hierarchy to improve HLL storage.

Returns:

the packed cutoff byte

packParametersByte

public static byte packParametersByte(int registerWidth,
                                      int registerCountLog2)

Generates a byte that encodes the parameters of a HLLType.FULL or HLLType.SPARSE HLL.

The top 3 bits are used to encode registerWidth - 1 (range of registerWidth is thus 1-9) and the bottom 5 bits are used to encode registerCountLog2 (range of registerCountLog2 is thus 0-31).

Parameters:

registerWidth - the register width (must be at least 1 and at most 9)

registerCountLog2 - the log-base-2 of the register count (must be at least 0 and at most 31)

Returns:

the packed parameters byte

sparseEnabled

public static boolean sparseEnabled(byte cutoffByte)

Extracts the 'sparse-enabled' boolean from the cutoff byte of a serialized HLL.

Parameters:

cutoffByte - the cutoff byte of the serialized HLL

Returns:

the 'sparse-enabled' boolean

explicitCutoff

public static int explicitCutoff(byte cutoffByte)

Extracts the explicit cutoff value from the cutoff byte of a serialized HLL.

Parameters:

cutoffByte - the cutoff byte of the serialized HLL

Returns:

the explicit cutoff value

schemaVersion

public static int schemaVersion(byte versionByte)

Extracts the schema version from the version byte of a serialized HLL.

Parameters:

versionByte - the version byte of the serialized HLL

Returns:

the schema version of the serialized HLL

typeOrdinal

public static int typeOrdinal(byte versionByte)

Extracts the type ordinal from the version byte of a serialized HLL.

Parameters:

versionByte - the version byte of the serialized HLL

Returns:

the type ordinal of the serialized HLL

registerWidth

public static int registerWidth(byte parametersByte)

Extracts the register width from the parameters byte of a serialized HLLType.FULL HLL.

Parameters:

parametersByte - the parameters byte of the serialized HLL

Returns:

the register width of the serialized HLL

See Also:

packParametersByte(int, int)

registerCountLog2

public static int registerCountLog2(byte parametersByte)

Extracts the log2(registerCount) from the parameters byte of a serialized HLLType.FULL HLL.

Parameters:

parametersByte - the parameters byte of the serialized HLL

Returns:

log2(registerCount) of the serialized HLL

See Also:

packParametersByte(int, int)