Principle:Apache Paimon Utility Infrastructure

Knowledge Sources	Apache_Paimon
Domains	Utility, Infrastructure
Last Updated	2026-02-08 00:00 GMT

Overview

Utility infrastructure provides foundational support libraries for common operations including string manipulation, mathematical computations, thread pool management, JSON serialization, and configuration handling.

Description

The utility infrastructure principle recognizes that complex systems require a stable foundation of reusable, well-tested utility functions that handle common operations consistently across the codebase. Rather than duplicating logic for string parsing, null checking, mathematical operations, or time conversions throughout the system, centralized utility modules provide canonical implementations that enforce consistent behavior and reduce error-prone code duplication.

String utilities handle common text processing tasks like null-safe comparison, trimming, splitting, and formatting. Array utilities provide operations for manipulating collections without forcing explicit null checks at every call site. Precondition checkers validate method arguments and invariants, failing fast with informative error messages when contracts are violated. Mathematical utilities implement specialized operations like safe integer arithmetic, rounding modes, and bit manipulation that appear frequently in data processing code.

Thread pool utilities standardize concurrent execution patterns, providing factory methods for creating thread pools with appropriate sizing, naming conventions, and error handling. Time utilities convert between different temporal representations and time zones, ensuring consistent timestamp handling across the system. JSON serialization utilities provide type-safe conversion between objects and JSON representations, handling edge cases like null values, nested structures, and type polymorphism. Compression utilities implement space-efficient encoding schemes like delta encoding and varint compression for numeric data. Configuration utilities define strongly-typed configuration options with validation rules, default values, and documentation, enabling type-safe access to system parameters.

Usage

Apply utility infrastructure when building any non-trivial system to avoid code duplication, enforce consistent patterns, and reduce common programming errors. These utilities serve as the building blocks for higher-level abstractions and should be leveraged throughout the codebase.

Theoretical Basis

Utility infrastructure follows principles of code reuse and defensive programming:

String Utilities

class StringUtils:
    function isNullOrEmpty(str) -> boolean:
        return str == null or str.length() == 0

    function isBlank(str) -> boolean:
        return str == null or str.trim().length() == 0

    function split(str, delimiter, limit) -> list<string>:
        if str == null:
            return emptyList()
        return str.split(delimiter, limit)

    function join(elements, delimiter) -> string:
        if elements == null or elements.isEmpty():
            return ""
        return elements.join(delimiter)

    function format(template, ...args) -> string:
        return String.format(template, args)

Array Utilities

class ArrayUtils:
    function isEmpty(array) -> boolean:
        return array == null or array.length == 0

    function contains(array, element) -> boolean:
        if array == null:
            return false
        for each item in array:
            if item.equals(element):
                return true
        return false

    function concat(array1, array2) -> array:
        if array1 == null:
            return array2
        if array2 == null:
            return array1
        return array1 + array2

Precondition Checking

class Preconditions:
    function checkNotNull(value, message) -> value:
        if value == null:
            throw NullPointerException(message)
        return value

    function checkArgument(condition, message):
        if not condition:
            throw IllegalArgumentException(message)

    function checkState(condition, message):
        if not condition:
            throw IllegalStateException(message)

    function checkElementIndex(index, size) -> index:
        if index < 0 or index >= size:
            throw IndexOutOfBoundsException(
                "Index " + index + " out of bounds for size " + size
            )
        return index

Mathematical Utilities

class MathUtils:
    function addExact(a, b) -> integer:
        result = a + b
        if ((a ^ result) & (b ^ result)) < 0:
            throw ArithmeticException("Integer overflow")
        return result

    function multiplyExact(a, b) -> long:
        result = a * b
        if result / b != a:
            throw ArithmeticException("Long overflow")
        return result

    function roundUp(value, multiple) -> integer:
        return ((value + multiple - 1) / multiple) * multiple

    function isPowerOfTwo(value) -> boolean:
        return value > 0 and (value & (value - 1)) == 0

Thread Pool Utilities

class ThreadPoolUtils:
    function createThreadPool(name, coreSize, maxSize) -> ExecutorService:
        return new ThreadPoolExecutor(
            corePoolSize: coreSize,
            maxPoolSize: maxSize,
            keepAliveTime: 60 seconds,
            workQueue: new LinkedBlockingQueue(),
            threadFactory: createNamedThreadFactory(name),
            rejectedExecutionHandler: new AbortPolicy()
        )

    function createNamedThreadFactory(prefix) -> ThreadFactory:
        counter = new AtomicInteger(0)
        return thread => {
            thread.name = prefix + "-" + counter.incrementAndGet()
            thread.daemon = true
            return thread
        }

Time Utilities

class TimeUtils:
    function parseTimestamp(str, format) -> long:
        formatter = DateTimeFormatter.ofPattern(format)
        temporal = formatter.parse(str)
        return temporal.toEpochMilli()

    function formatTimestamp(millis, format, timezone) -> string:
        formatter = DateTimeFormatter.ofPattern(format)
            .withZone(timezone)
        return formatter.format(Instant.ofEpochMilli(millis))

    function toMillis(duration, unit) -> long:
        return unit.toMillis(duration)

JSON Serialization

class JsonSerdeUtil:
    function toJson(object) -> string:
        if object == null:
            return "null"

        if object is primitive:
            return object.toString()

        if object is list:
            return "[" + object.map(toJson).join(",") + "]"

        if object is map:
            entries = object.entries().map(e =>
                "\"" + e.key + "\":" + toJson(e.value)
            )
            return "{" + entries.join(",") + "}"

        // Use reflection or annotations for custom objects
        return serializeObject(object)

    function fromJson(json, targetType) -> object:
        parser = new JsonParser(json)
        return deserialize(parser, targetType)

Delta Varint Compression

class DeltaVarintCompressor:
    function compress(values) -> bytes:
        if values.isEmpty():
            return emptyBytes()

        output = new ByteArrayOutputStream()
        previous = 0

        for each value in values:
            delta = value - previous
            writeVarint(output, delta)
            previous = value

        return output.toByteArray()

    function decompress(bytes, count) -> list<long>:
        input = new ByteArrayInputStream(bytes)
        values = []
        previous = 0

        for i in 0 to count - 1:
            delta = readVarint(input)
            value = previous + delta
            values.add(value)
            previous = value

        return values

    function writeVarint(output, value):
        // Encode using variable-length format
        // 7 bits per byte, MSB indicates continuation
        while value > 127:
            output.write((value & 0x7F) | 0x80)
            value >>= 7
        output.write(value & 0x7F)

Configuration Options

class ConfigOption<T>:
    key: string
    defaultValue: T
    description: string
    validator: function(T) -> boolean

    function withDefault(value) -> ConfigOption<T>:
        return ConfigOption(key, value, description, validator)

    function withValidator(validatorFunc) -> ConfigOption<T>:
        return ConfigOption(key, defaultValue, description, validatorFunc)

class ConfigOptions:
    function intOption(key) -> ConfigOption<int>:
        return ConfigOption<int>(key)

    function stringOption(key) -> ConfigOption<string>:
        return ConfigOption<string>(key)

    function durationOption(key) -> ConfigOption<Duration>:
        return ConfigOption<Duration>(key)

class OptionsUtils:
    function get(config, option) -> value:
        if config.contains(option.key):
            rawValue = config.get(option.key)
            value = parseValue(rawValue, option.type)

            if option.validator != null:
                if not option.validator(value):
                    throw ValidationException(
                        "Invalid value for " + option.key + ": " + value
                    )

            return value
        else:
            return option.defaultValue

Predicate Abstraction

class Predicate:
    function alwaysTrue() -> Predicate:
        return value => true

    function alwaysFalse() -> Predicate:
        return value => false

    function and(pred1, pred2) -> Predicate:
        return value => pred1(value) and pred2(value)

    function or(pred1, pred2) -> Predicate:
        return value => pred1(value) or pred2(value)

    function not(pred) -> Predicate:
        return value => not pred(value)

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment