Package org.apache.ignite.internal.processors.query.stat.hll.serialization

## Class SerializationUtil

- java.lang.Object
- - org.apache.ignite.internal.processors.query.stat.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.

### Field Summary

Fields
`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
`SerializationUtil()`

### Method Summary

All Methods Static Methods Concrete Methods
`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.
`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 2n 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)`