ColumnFamilyConfig.java

/**
 *
 * Copyright (C) TidesDB
 *
 * Original Author: Alex Gaetano Padula
 *
 * Licensed under the Mozilla Public License, v. 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     https://www.mozilla.org/en-US/MPL/2.0/
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.tidesdb;

/**
 * Configuration for a column family.
 */
public class ColumnFamilyConfig {

    static {
        NativeLibrary.load();
    }

    private long writeBufferSize;
    private long levelSizeRatio;
    private int minLevels;
    private int dividingLevelOffset;
    private long klogValueThreshold;
    private CompressionAlgorithm compressionAlgorithm;
    private boolean enableBloomFilter;
    private double bloomFPR;
    private boolean enableBlockIndexes;
    private int indexSampleRatio;
    private int blockIndexPrefixLen;
    private SyncMode syncMode;
    private long syncIntervalUs;
    private String comparatorName;
    private int skipListMaxLevel;
    private float skipListProbability;
    private IsolationLevel defaultIsolationLevel;
    private long minDiskSpace;
    private int l1FileCountTrigger;
    private int l0QueueStallThreshold;
    private double tombstoneDensityTrigger;
    private long tombstoneDensityMinEntries;
    private boolean useBtree;
    private boolean objectLazyCompaction;
    private boolean objectPrefetchCompaction;

    private ColumnFamilyConfig(Builder builder) {
        this.writeBufferSize = builder.writeBufferSize;
        this.levelSizeRatio = builder.levelSizeRatio;
        this.minLevels = builder.minLevels;
        this.dividingLevelOffset = builder.dividingLevelOffset;
        this.klogValueThreshold = builder.klogValueThreshold;
        this.compressionAlgorithm = builder.compressionAlgorithm;
        this.enableBloomFilter = builder.enableBloomFilter;
        this.bloomFPR = builder.bloomFPR;
        this.enableBlockIndexes = builder.enableBlockIndexes;
        this.indexSampleRatio = builder.indexSampleRatio;
        this.blockIndexPrefixLen = builder.blockIndexPrefixLen;
        this.syncMode = builder.syncMode;
        this.syncIntervalUs = builder.syncIntervalUs;
        this.comparatorName = builder.comparatorName;
        this.skipListMaxLevel = builder.skipListMaxLevel;
        this.skipListProbability = builder.skipListProbability;
        this.defaultIsolationLevel = builder.defaultIsolationLevel;
        this.minDiskSpace = builder.minDiskSpace;
        this.l1FileCountTrigger = builder.l1FileCountTrigger;
        this.l0QueueStallThreshold = builder.l0QueueStallThreshold;
        this.tombstoneDensityTrigger = builder.tombstoneDensityTrigger;
        this.tombstoneDensityMinEntries = builder.tombstoneDensityMinEntries;
        this.useBtree = builder.useBtree;
        this.objectLazyCompaction = builder.objectLazyCompaction;
        this.objectPrefetchCompaction = builder.objectPrefetchCompaction;
    }

    /**
     * Creates a default column family configuration. The tombstone density defaults
     * are sourced from the underlying C library so that this binding tracks the
     * engine's defaults automatically.
     *
     * @return a new ColumnFamilyConfig with default values
     */
    public static ColumnFamilyConfig defaultConfig() {
        return new Builder()
            .writeBufferSize(128 * 1024 * 1024)
            .levelSizeRatio(10)
            .minLevels(5)
            .dividingLevelOffset(2)
            .klogValueThreshold(512)
            .compressionAlgorithm(CompressionAlgorithm.LZ4_COMPRESSION)
            .enableBloomFilter(true)
            .bloomFPR(0.01)
            .enableBlockIndexes(true)
            .indexSampleRatio(1)
            .blockIndexPrefixLen(16)
            .syncMode(SyncMode.SYNC_FULL)
            .syncIntervalUs(1000000)
            .comparatorName("")
            .skipListMaxLevel(12)
            .skipListProbability(0.25f)
            .defaultIsolationLevel(IsolationLevel.READ_COMMITTED)
            .minDiskSpace(100 * 1024 * 1024)
            .l1FileCountTrigger(4)
            .l0QueueStallThreshold(20)
            .tombstoneDensityTrigger(nativeDefaultTombstoneDensityTrigger())
            .tombstoneDensityMinEntries(nativeDefaultTombstoneDensityMinEntries())
            .useBtree(false)
            .objectLazyCompaction(false)
            .objectPrefetchCompaction(true)
            .build();
    }

    /**
     * Creates a new builder for ColumnFamilyConfig.
     *
     * @return a new Builder
     */
    public static Builder builder() {
        return new Builder();
    }

    /**
     * Constructs a ColumnFamilyConfig from raw native primitives. Used by the JNI
     * layer when reading back the configuration embedded in tidesdb_stats_t.
     */
    static ColumnFamilyConfig fromNative(long writeBufferSize, long levelSizeRatio, int minLevels,
                                         int dividingLevelOffset, long klogValueThreshold,
                                         int compressionAlgorithm, boolean enableBloomFilter,
                                         double bloomFPR, boolean enableBlockIndexes,
                                         int indexSampleRatio, int blockIndexPrefixLen,
                                         int syncMode, long syncIntervalUs, String comparatorName,
                                         int skipListMaxLevel, float skipListProbability,
                                         int defaultIsolationLevel, long minDiskSpace,
                                         int l1FileCountTrigger, int l0QueueStallThreshold,
                                         double tombstoneDensityTrigger,
                                         long tombstoneDensityMinEntries, boolean useBtree,
                                         boolean objectLazyCompaction,
                                         boolean objectPrefetchCompaction) {
        return new Builder()
            .writeBufferSize(writeBufferSize)
            .levelSizeRatio(levelSizeRatio)
            .minLevels(minLevels)
            .dividingLevelOffset(dividingLevelOffset)
            .klogValueThreshold(klogValueThreshold)
            .compressionAlgorithm(CompressionAlgorithm.fromValue(compressionAlgorithm))
            .enableBloomFilter(enableBloomFilter)
            .bloomFPR(bloomFPR)
            .enableBlockIndexes(enableBlockIndexes)
            .indexSampleRatio(indexSampleRatio)
            .blockIndexPrefixLen(blockIndexPrefixLen)
            .syncMode(SyncMode.fromValue(syncMode))
            .syncIntervalUs(syncIntervalUs)
            .comparatorName(comparatorName == null ? "" : comparatorName)
            .skipListMaxLevel(skipListMaxLevel)
            .skipListProbability(skipListProbability)
            .defaultIsolationLevel(IsolationLevel.fromValue(defaultIsolationLevel))
            .minDiskSpace(minDiskSpace)
            .l1FileCountTrigger(l1FileCountTrigger)
            .l0QueueStallThreshold(l0QueueStallThreshold)
            .tombstoneDensityTrigger(tombstoneDensityTrigger)
            .tombstoneDensityMinEntries(tombstoneDensityMinEntries)
            .useBtree(useBtree)
            .objectLazyCompaction(objectLazyCompaction)
            .objectPrefetchCompaction(objectPrefetchCompaction)
            .build();
    }

    public long getWriteBufferSize() { return writeBufferSize; }
    public long getLevelSizeRatio() { return levelSizeRatio; }
    public int getMinLevels() { return minLevels; }
    public int getDividingLevelOffset() { return dividingLevelOffset; }
    public long getKlogValueThreshold() { return klogValueThreshold; }
    public CompressionAlgorithm getCompressionAlgorithm() { return compressionAlgorithm; }
    public boolean isEnableBloomFilter() { return enableBloomFilter; }
    public double getBloomFPR() { return bloomFPR; }
    public boolean isEnableBlockIndexes() { return enableBlockIndexes; }
    public int getIndexSampleRatio() { return indexSampleRatio; }
    public int getBlockIndexPrefixLen() { return blockIndexPrefixLen; }
    public SyncMode getSyncMode() { return syncMode; }
    public long getSyncIntervalUs() { return syncIntervalUs; }
    public String getComparatorName() { return comparatorName; }
    public int getSkipListMaxLevel() { return skipListMaxLevel; }
    public float getSkipListProbability() { return skipListProbability; }
    public IsolationLevel getDefaultIsolationLevel() { return defaultIsolationLevel; }
    public long getMinDiskSpace() { return minDiskSpace; }
    public int getL1FileCountTrigger() { return l1FileCountTrigger; }
    public int getL0QueueStallThreshold() { return l0QueueStallThreshold; }
    public double getTombstoneDensityTrigger() { return tombstoneDensityTrigger; }
    public long getTombstoneDensityMinEntries() { return tombstoneDensityMinEntries; }
    public boolean isUseBtree() { return useBtree; }
    public boolean isObjectLazyCompaction() { return objectLazyCompaction; }
    public boolean isObjectPrefetchCompaction() { return objectPrefetchCompaction; }

    /**
     * Saves this column family configuration to an INI file under the given section.
     * If the file already exists it is overwritten. The written file can be read back
     * with {@link #loadFromIni(String, String)}.
     *
     * <p>Note: not every field round-trips. The persisted fields are the ones the engine
     * stores in a column family's {@code config.ini} (write buffer size, level ratios,
     * compression, bloom/index settings, sync mode, skip list parameters, isolation level,
     * compaction triggers, tombstone density, B+tree and object-store flags, and the
     * comparator name). Runtime-only fields such as commit hooks are not persisted.</p>
     *
     * @param iniFile     path to the INI file to write
     * @param sectionName section name to write the configuration under
     * @throws TidesDBException if the file cannot be written
     */
    public void saveToIni(String iniFile, String sectionName) throws TidesDBException {
        if (iniFile == null || iniFile.isEmpty()) {
            throw new IllegalArgumentException("INI file path cannot be null or empty");
        }
        if (sectionName == null || sectionName.isEmpty()) {
            throw new IllegalArgumentException("Section name cannot be null or empty");
        }
        nativeSaveToIni(iniFile, sectionName,
            writeBufferSize, levelSizeRatio, minLevels, dividingLevelOffset, klogValueThreshold,
            compressionAlgorithm.getValue(), enableBloomFilter, bloomFPR, enableBlockIndexes,
            indexSampleRatio, blockIndexPrefixLen, syncMode.getValue(), syncIntervalUs,
            comparatorName, skipListMaxLevel, skipListProbability,
            defaultIsolationLevel.getValue(), minDiskSpace, l1FileCountTrigger,
            l0QueueStallThreshold, tombstoneDensityTrigger, tombstoneDensityMinEntries,
            useBtree, objectLazyCompaction, objectPrefetchCompaction);
    }

    /**
     * Loads a column family configuration from an INI file section previously written by
     * {@link #saveToIni(String, String)} (or produced by the engine for an existing column
     * family). Fields absent from the section fall back to the engine defaults.
     *
     * @param iniFile     path to the INI file to read
     * @param sectionName section name to read the configuration from
     * @return the loaded configuration
     * @throws TidesDBException if the file cannot be read or the section is missing
     */
    public static ColumnFamilyConfig loadFromIni(String iniFile, String sectionName) throws TidesDBException {
        if (iniFile == null || iniFile.isEmpty()) {
            throw new IllegalArgumentException("INI file path cannot be null or empty");
        }
        if (sectionName == null || sectionName.isEmpty()) {
            throw new IllegalArgumentException("Section name cannot be null or empty");
        }
        return nativeLoadFromIni(iniFile, sectionName);
    }

    private static native double nativeDefaultTombstoneDensityTrigger();
    private static native long nativeDefaultTombstoneDensityMinEntries();
    private static native void nativeSaveToIni(String iniFile, String sectionName,
        long writeBufferSize, long levelSizeRatio, int minLevels, int dividingLevelOffset,
        long klogValueThreshold, int compressionAlgorithm, boolean enableBloomFilter,
        double bloomFPR, boolean enableBlockIndexes, int indexSampleRatio, int blockIndexPrefixLen,
        int syncMode, long syncIntervalUs, String comparatorName, int skipListMaxLevel,
        float skipListProbability, int defaultIsolationLevel, long minDiskSpace,
        int l1FileCountTrigger, int l0QueueStallThreshold, double tombstoneDensityTrigger,
        long tombstoneDensityMinEntries, boolean useBtree, boolean objectLazyCompaction,
        boolean objectPrefetchCompaction) throws TidesDBException;
    private static native ColumnFamilyConfig nativeLoadFromIni(String iniFile, String sectionName) throws TidesDBException;

    /**
     * Builder for ColumnFamilyConfig.
     */
    public static class Builder {
        private long writeBufferSize = 128 * 1024 * 1024;
        private long levelSizeRatio = 10;
        private int minLevels = 5;
        private int dividingLevelOffset = 2;
        private long klogValueThreshold = 512;
        private CompressionAlgorithm compressionAlgorithm = CompressionAlgorithm.LZ4_COMPRESSION;
        private boolean enableBloomFilter = true;
        private double bloomFPR = 0.01;
        private boolean enableBlockIndexes = true;
        private int indexSampleRatio = 1;
        private int blockIndexPrefixLen = 16;
        private SyncMode syncMode = SyncMode.SYNC_FULL;
        private long syncIntervalUs = 1000000;
        private String comparatorName = "";
        private int skipListMaxLevel = 12;
        private float skipListProbability = 0.25f;
        private IsolationLevel defaultIsolationLevel = IsolationLevel.READ_COMMITTED;
        private long minDiskSpace = 100 * 1024 * 1024;
        private int l1FileCountTrigger = 4;
        private int l0QueueStallThreshold = 20;
        private double tombstoneDensityTrigger = 0.0;
        private long tombstoneDensityMinEntries = 1024;
        private boolean useBtree = false;
        private boolean objectLazyCompaction = false;
        private boolean objectPrefetchCompaction = true;

        public Builder writeBufferSize(long writeBufferSize) {
            this.writeBufferSize = writeBufferSize;
            return this;
        }

        public Builder levelSizeRatio(long levelSizeRatio) {
            this.levelSizeRatio = levelSizeRatio;
            return this;
        }

        public Builder minLevels(int minLevels) {
            this.minLevels = minLevels;
            return this;
        }

        public Builder dividingLevelOffset(int dividingLevelOffset) {
            this.dividingLevelOffset = dividingLevelOffset;
            return this;
        }

        public Builder klogValueThreshold(long klogValueThreshold) {
            this.klogValueThreshold = klogValueThreshold;
            return this;
        }

        public Builder compressionAlgorithm(CompressionAlgorithm compressionAlgorithm) {
            this.compressionAlgorithm = compressionAlgorithm;
            return this;
        }

        public Builder enableBloomFilter(boolean enableBloomFilter) {
            this.enableBloomFilter = enableBloomFilter;
            return this;
        }

        public Builder bloomFPR(double bloomFPR) {
            this.bloomFPR = bloomFPR;
            return this;
        }

        public Builder enableBlockIndexes(boolean enableBlockIndexes) {
            this.enableBlockIndexes = enableBlockIndexes;
            return this;
        }

        public Builder indexSampleRatio(int indexSampleRatio) {
            this.indexSampleRatio = indexSampleRatio;
            return this;
        }

        public Builder blockIndexPrefixLen(int blockIndexPrefixLen) {
            this.blockIndexPrefixLen = blockIndexPrefixLen;
            return this;
        }

        public Builder syncMode(SyncMode syncMode) {
            this.syncMode = syncMode;
            return this;
        }

        public Builder syncIntervalUs(long syncIntervalUs) {
            this.syncIntervalUs = syncIntervalUs;
            return this;
        }

        public Builder comparatorName(String comparatorName) {
            this.comparatorName = comparatorName;
            return this;
        }

        public Builder skipListMaxLevel(int skipListMaxLevel) {
            this.skipListMaxLevel = skipListMaxLevel;
            return this;
        }

        public Builder skipListProbability(float skipListProbability) {
            this.skipListProbability = skipListProbability;
            return this;
        }

        public Builder defaultIsolationLevel(IsolationLevel defaultIsolationLevel) {
            this.defaultIsolationLevel = defaultIsolationLevel;
            return this;
        }

        public Builder minDiskSpace(long minDiskSpace) {
            this.minDiskSpace = minDiskSpace;
            return this;
        }

        public Builder l1FileCountTrigger(int l1FileCountTrigger) {
            this.l1FileCountTrigger = l1FileCountTrigger;
            return this;
        }

        public Builder l0QueueStallThreshold(int l0QueueStallThreshold) {
            this.l0QueueStallThreshold = l0QueueStallThreshold;
            return this;
        }

        public Builder tombstoneDensityTrigger(double tombstoneDensityTrigger) {
            this.tombstoneDensityTrigger = tombstoneDensityTrigger;
            return this;
        }

        public Builder tombstoneDensityMinEntries(long tombstoneDensityMinEntries) {
            this.tombstoneDensityMinEntries = tombstoneDensityMinEntries;
            return this;
        }

        public Builder useBtree(boolean useBtree) {
            this.useBtree = useBtree;
            return this;
        }

        public Builder objectLazyCompaction(boolean objectLazyCompaction) {
            this.objectLazyCompaction = objectLazyCompaction;
            return this;
        }

        public Builder objectPrefetchCompaction(boolean objectPrefetchCompaction) {
            this.objectPrefetchCompaction = objectPrefetchCompaction;
            return this;
        }

        public ColumnFamilyConfig build() {
            validate();
            return new ColumnFamilyConfig(this);
        }

        private void validate() {
            // Nullable-enum checks (do first, before field-level checks)
            if (compressionAlgorithm == null) {
                throw new IllegalArgumentException("compressionAlgorithm must not be null");
            }
            if (syncMode == null) {
                throw new IllegalArgumentException("syncMode must not be null");
            }
            if (defaultIsolationLevel == null) {
                throw new IllegalArgumentException("defaultIsolationLevel must not be null");
            }

            // Non-negative (zero sentinel OK)
            if (klogValueThreshold < 0) {
                throw new IllegalArgumentException("klogValueThreshold must not be negative, was: " + klogValueThreshold);
            }
            if (syncIntervalUs < 0) {
                throw new IllegalArgumentException("syncIntervalUs must not be negative, was: " + syncIntervalUs);
            }
            if (minDiskSpace < 0) {
                throw new IllegalArgumentException("minDiskSpace must not be negative, was: " + minDiskSpace);
            }
            if (dividingLevelOffset < 0) {
                throw new IllegalArgumentException("dividingLevelOffset must not be negative, was: " + dividingLevelOffset);
            }
            if (blockIndexPrefixLen < 0) {
                throw new IllegalArgumentException("blockIndexPrefixLen must not be negative, was: " + blockIndexPrefixLen);
            }
            if (skipListMaxLevel < 0) {
                throw new IllegalArgumentException("skipListMaxLevel must not be negative, was: " + skipListMaxLevel);
            }

            // Positive-required (zero rejected)
            if (writeBufferSize <= 0) {
                throw new IllegalArgumentException("writeBufferSize must be positive, was: " + writeBufferSize);
            }
            if (levelSizeRatio <= 0) {
                throw new IllegalArgumentException("levelSizeRatio must be positive, was: " + levelSizeRatio);
            }
            if (minLevels <= 0) {
                throw new IllegalArgumentException("minLevels must be positive, was: " + minLevels);
            }
            if (indexSampleRatio <= 0) {
                throw new IllegalArgumentException("indexSampleRatio must be positive, was: " + indexSampleRatio);
            }
            if (l1FileCountTrigger <= 0) {
                throw new IllegalArgumentException("l1FileCountTrigger must be positive, was: " + l1FileCountTrigger);
            }
            if (l0QueueStallThreshold <= 0) {
                throw new IllegalArgumentException("l0QueueStallThreshold must be positive, was: " + l0QueueStallThreshold);
            }
            if (tombstoneDensityMinEntries <= 0) {
                throw new IllegalArgumentException("tombstoneDensityMinEntries must be positive, was: " + tombstoneDensityMinEntries);
            }

            // Float/double range and finiteness
            if (Double.isNaN(bloomFPR) || Double.isInfinite(bloomFPR) || bloomFPR < 0.0 || bloomFPR > 1.0) {
                throw new IllegalArgumentException("bloomFPR must be finite and in [0.0, 1.0], was: " + bloomFPR);
            }
            if (Float.isNaN(skipListProbability) || Float.isInfinite(skipListProbability) || skipListProbability < 0.0f || skipListProbability > 1.0f) {
                throw new IllegalArgumentException("skipListProbability must be finite and in [0.0, 1.0], was: " + skipListProbability);
            }
            if (Double.isNaN(tombstoneDensityTrigger) || Double.isInfinite(tombstoneDensityTrigger) || tombstoneDensityTrigger < 0.0 || tombstoneDensityTrigger > 1.0) {
                throw new IllegalArgumentException("tombstoneDensityTrigger must be finite and in [0.0, 1.0], was: " + tombstoneDensityTrigger);
            }
        }
    }
}