Implementation:Apache Paimon OptionsUtils

Knowledge Sources	Apache_Paimon
Domains	Type Conversion, Configuration Utilities, Prefix Map Handling
Last Updated	2026-02-08 00:00 GMT

Overview

OptionsUtils is a utility class providing type conversion, prefix-map handling, and other helper functions for the Options configuration system.

Description

OptionsUtils provides the central method convertValue(Object, Class) which dispatches to type-specific converters for Integer, Long, Boolean, Float, Double, String, Enum, Duration, MemorySize, and Map types. Enum conversion is case-insensitive. Duration conversion delegates to TimeUtils.parseDuration(). String conversion handles special cases for Duration, List, and Map types. Map/properties conversion parses comma-separated key:value pairs.

The class also provides prefix-map utilities (canBePrefixMap(), containsPrefixMap(), convertToPropertiesPrefixed(), convertToPropertiesPrefixKey(), removePrefixMap()) for handling nested configuration namespaces. These utilities enable hierarchical configuration patterns used for per-column and per-index-type settings. The class defines the PAIMON_PREFIX constant ("paimon.") for system-level option prefixing.

This is a core infrastructure utility that enables Paimon's string-to-typed configuration resolution. Every Options.get(ConfigOption) call ultimately uses this utility to convert stored string values into their typed representations. The prefix-map support is critical for supporting complex configuration structures.

Usage

Use OptionsUtils internally when implementing configuration parsing or when working with Options objects that need type conversion or prefix-map handling.

Code Reference

Source Location

• Repository: Apache_Paimon
• File: paimon-api/src/main/java/org/apache/paimon/options/OptionsUtils.java
• Lines: 1-350

Signature

public class OptionsUtils {

    public static final String PAIMON_PREFIX = "paimon.";

    // Type conversion
    public static <T> T convertValue(Object rawValue, Class<?> clazz);
    static Integer convertToInt(Object o);
    static Long convertToLong(Object o);
    static Boolean convertToBoolean(Object o);
    static Float convertToFloat(Object o);
    static Double convertToDouble(Object o);
    static String convertToString(Object o);
    public static <E extends Enum<?>> E convertToEnum(Object o, Class<E> clazz);
    static Duration convertToDuration(Object o);
    static MemorySize convertToMemorySize(Object o);
    static Map<String, String> convertToProperties(Object o);

    // Prefix map handling
    public static boolean canBePrefixMap(ConfigOption<?> configOption);
    public static boolean filterPrefixMapKey(String key, String candidate);
    static Map<String, String> convertToPropertiesPrefixed(
        Map<String, String> confData, String key);
    public static Map<String, String> convertToPropertiesPrefixKey(
        Map<String, String> confData, String prefixKey);
    public static Map<String, String> convertToPropertiesPrefixKey(
        Iterable<Map.Entry<String, String>> confData,
        String prefixKey,
        Predicate<String> valuePredicate);
    public static Map<String, String> convertToDynamicTableProperties(
        Map<String, String> confData,
        String globalOptionKeyPrefix,
        Pattern tableOptionKeyPattern,
        int keyGroup);
    static boolean containsPrefixMap(Map<String, String> confData, String key);
    static boolean removePrefixMap(Map<String, String> confData, String key);

    private OptionsUtils() {}  // Prevent instantiation
}

Import

import org.apache.paimon.options.OptionsUtils;

I/O Contract

Inputs

Name	Type	Required	Description
rawValue	Object	yes	Value to be converted
clazz	Class<?>	yes	Target type for conversion
confData	Map<String, String>	no	Configuration data for prefix operations
key	String	no	Configuration key or prefix

Outputs

Name	Type	Description
convertedValue	T	Value converted to target type
properties	Map<String, String>	Extracted prefix-map properties
canBePrefixMap	boolean	Whether option supports prefix-map notation

Usage Examples

Type Conversion

import org.apache.paimon.options.OptionsUtils;
import org.apache.paimon.options.MemorySize;
import java.time.Duration;

// Convert to Integer
Integer intValue = OptionsUtils.convertValue("42", Integer.class);
System.out.println("Integer: " + intValue);

// Convert to Boolean
Boolean boolValue = OptionsUtils.convertValue("true", Boolean.class);
System.out.println("Boolean: " + boolValue);

// Convert to Duration
Duration duration = OptionsUtils.convertValue("30s", Duration.class);
System.out.println("Duration: " + duration);

// Convert to MemorySize
MemorySize memSize = OptionsUtils.convertValue("128mb", MemorySize.class);
System.out.println("Memory: " + memSize.getMebiBytes() + " MB");

// Convert to Enum
enum LogLevel { DEBUG, INFO, WARN, ERROR }
LogLevel level = OptionsUtils.convertValue("INFO", LogLevel.class);
System.out.println("Log level: " + level);

Prefix Map Handling

import org.apache.paimon.options.OptionsUtils;
import java.util.HashMap;
import java.util.Map;

// Configuration with prefix notation
Map<String, String> config = new HashMap<>();
config.put("fields.field1.nested-key", "value1");
config.put("fields.field2.nested-key", "value2");
config.put("fields.field3.ignore-retract", "true");
config.put("other.option", "other-value");

// Extract prefixed properties for "fields.field1"
Map<String, String> field1Props =
    OptionsUtils.convertToPropertiesPrefixKey(config, "fields.field1.");
System.out.println("Field1 properties: " + field1Props);
// Output: {nested-key=value1}

// Extract prefixed properties for "fields.field2"
Map<String, String> field2Props =
    OptionsUtils.convertToPropertiesPrefixKey(config, "fields.field2.");
System.out.println("Field2 properties: " + field2Props);
// Output: {nested-key=value2}

// Check if key has prefix map
boolean hasPrefix = OptionsUtils.containsPrefixMap(config, "fields");
System.out.println("Has prefix map: " + hasPrefix);  // true

Properties Conversion

import org.apache.paimon.options.OptionsUtils;
import java.util.Map;

// Parse map from string
String mapString = "key1:value1,key2:value2,key3:value3";
Map<String, String> map = OptionsUtils.convertToProperties(mapString);
System.out.println("Parsed map: " + map);

// Convert map to string
String result = OptionsUtils.convertToString(map);
System.out.println("Map as string: " + result);

// Parse with escaping
String escapedString = "'k:e:y':'v:a:l','key2':'val2'";
Map<String, String> escapedMap = OptionsUtils.convertToProperties(escapedString);
System.out.println("Escaped map: " + escapedMap);

Working with ConfigOption

import org.apache.paimon.options.OptionsUtils;
import org.apache.paimon.options.ConfigOption;
import org.apache.paimon.options.ConfigOptions;
import java.util.Map;

// Define a map-type option
ConfigOption<Map<String, String>> mapOption =
    ConfigOptions.key("fields")
        .mapType()
        .noDefaultValue()
        .withDescription("Per-field settings");

// Check if option can be a prefix map
boolean canBePrefix = OptionsUtils.canBePrefixMap(mapOption);
System.out.println("Can be prefix map: " + canBePrefix);  // true

// Configuration with both notations
Map<String, String> config = new HashMap<>();
// Compact notation
config.put("fields", "field1:value1,field2:value2");
// Prefix notation
config.put("fields.field3", "value3");

// Extract using appropriate method based on notation
if (OptionsUtils.containsPrefixMap(config, "fields")) {
    Map<String, String> prefixMap =
        OptionsUtils.convertToPropertiesPrefixKey(config, "fields.");
    System.out.println("From prefix notation: " + prefixMap);
}

Related Pages

• Principle:Apache_Paimon_Table_Configuration