ColumnFamily.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;

/**
 * Represents a column family in TidesDB.
 * Column families are isolated key-value stores with independent configuration.
 */
public class ColumnFamily {
    
    static {
        NativeLibrary.load();
    }
    
    private final long nativeHandle;
    private final String name;
    private long commitHookCtxHandle = 0;
    private final TidesDB owner;
    
    ColumnFamily(long nativeHandle, String name) {
        this(nativeHandle, name, null);
    }
    
    ColumnFamily(long nativeHandle, String name, TidesDB owner) {
        this.nativeHandle = nativeHandle;
        this.name = name;
        this.owner = owner;
    }
    
    /**
     * Checks that the owning database is open. Throws if the owner is closed.
     */
    void checkOwnerOpen() {
        if (owner != null && owner.isClosed()) {
            throw new IllegalStateException("TidesDB instance is closed");
        }
    }
    
    /**
     * Gets the name of this column family.
     *
     * @return the column family name
     */
    public String getName() {
        return name;
    }
    
    /**
     * Retrieves statistics about this column family.
     *
     * @return column family statistics
     * @throws TidesDBException if the stats cannot be retrieved
     */
    public Stats getStats() throws TidesDBException {
        checkOwnerOpen();
        return nativeGetStats(nativeHandle);
    }
    
    /**
     * Manually triggers compaction for this column family.
     *
     * @throws TidesDBException if compaction fails
     */
    public void compact() throws TidesDBException {
        checkOwnerOpen();
        nativeCompact(nativeHandle);
    }

    /**
     * Synchronously compacts every SSTable whose key range overlaps {@code [startKey, endKey)}.
     * Blocks the calling thread until the merge commits or fails - does not enqueue work
     * onto the compaction thread pool.
     *
     * <p>A {@code null} or empty endpoint means unbounded on that side. Both endpoints
     * being {@code null} or empty is rejected with {@link TidesDBException}; callers
     * wanting full-CF compaction must use {@link #compact()}.</p>
     *
     * @param startKey lower bound of the range, or {@code null}/empty for unbounded
     * @param endKey   upper bound (exclusive), or {@code null}/empty for unbounded
     * @throws TidesDBException if the range is invalid, another compaction is running,
     *                          or the merge fails
     */
    public void compactRange(byte[] startKey, byte[] endKey) throws TidesDBException {
        checkOwnerOpen();
        nativeCompactRange(nativeHandle, startKey, endKey);
    }
    
    /**
     * Manually triggers memtable flush for this column family.
     *
     * @throws TidesDBException if flush fails
     */
    public void flushMemtable() throws TidesDBException {
        checkOwnerOpen();
        nativeFlushMemtable(nativeHandle);
    }
    
    /**
     * Checks if a flush operation is currently in progress for this column family.
     *
     * @return true if flushing is in progress
     */
    public boolean isFlushing() {
        checkOwnerOpen();
        return nativeIsFlushing(nativeHandle);
    }
    
    /**
     * Checks if a compaction operation is currently in progress for this column family.
     *
     * @return true if compaction is in progress
     */
    public boolean isCompacting() {
        checkOwnerOpen();
        return nativeIsCompacting(nativeHandle);
    }
    
    /**
     * Updates runtime-safe configuration settings for this column family.
     * Configuration changes are applied to new operations only.
     * 
     * <p>Updatable settings (safe to change at runtime):</p>
     * <ul>
     *   <li>writeBufferSize - Memtable flush threshold</li>
     *   <li>skipListMaxLevel - Skip list level for new memtables</li>
     *   <li>skipListProbability - Skip list probability for new memtables</li>
     *   <li>bloomFPR - False positive rate for new SSTables</li>
     *   <li>indexSampleRatio - Index sampling ratio for new SSTables</li>
     *   <li>syncMode - Durability mode</li>
     *   <li>syncIntervalUs - Sync interval in microseconds</li>
     * </ul>
     *
     * @param config the new configuration
     * @param persistToDisk if true, saves changes to config.ini
     * @throws TidesDBException if the update fails
     */
    public void updateRuntimeConfig(ColumnFamilyConfig config, boolean persistToDisk) throws TidesDBException {
        checkOwnerOpen();
        if (config == null) {
            throw new IllegalArgumentException("Config cannot be null");
        }
        nativeUpdateRuntimeConfig(nativeHandle,
            config.getWriteBufferSize(),
            config.getSkipListMaxLevel(),
            config.getSkipListProbability(),
            config.getBloomFPR(),
            config.getIndexSampleRatio(),
            config.getSyncMode().getValue(),
            config.getSyncIntervalUs(),
            persistToDisk);
    }
    
    /**
     * Forces a synchronous flush and aggressive compaction for this column family.
     * Unlike {@link #compact()} and {@link #flushMemtable()} (which are non-blocking),
     * purge blocks until all flush and compaction I/O is complete.
     *
     * @throws TidesDBException if the purge fails
     */
    public void purge() throws TidesDBException {
        checkOwnerOpen();
        nativePurge(nativeHandle);
    }
    
    /**
     * Forces an immediate fsync of the active write-ahead log for this column family.
     * Useful for explicit durability control when using SYNC_NONE or SYNC_INTERVAL modes.
     *
     * @throws TidesDBException if the WAL sync fails
     */
    public void syncWal() throws TidesDBException {
        checkOwnerOpen();
        nativeSyncWal(nativeHandle);
    }
    
    /**
     * Estimates the computational cost of iterating between two keys in this column family.
     * The returned value is an opaque double - meaningful only for comparison with other
     * values from the same method. Uses only in-memory metadata and performs no disk I/O.
     * Key order does not matter - the method normalizes the range internally.
     *
     * @param keyA first key (bound of range)
     * @param keyB second key (bound of range)
     * @return estimated traversal cost (higher = more expensive), 0.0 if no overlapping data
     * @throws TidesDBException if the estimation fails
     */
    public double rangeCost(byte[] keyA, byte[] keyB) throws TidesDBException {
        checkOwnerOpen();
        if (keyA == null || keyA.length == 0) {
            throw new IllegalArgumentException("keyA cannot be null or empty");
        }
        if (keyB == null || keyB.length == 0) {
            throw new IllegalArgumentException("keyB cannot be null or empty");
        }
        return nativeRangeCost(nativeHandle, keyA, keyB);
    }
    
    /**
     * Sets a commit hook (Change Data Capture) for this column family.
     * The hook fires synchronously after every transaction commit, receiving the full
     * batch of committed operations atomically. Keep the callback fast to avoid
     * stalling writers.
     *
     * <p>Hooks are runtime-only and not persisted. After a database restart,
     * hooks must be re-registered by the application.</p>
     *
     * @param hook the commit hook callback
     * @throws TidesDBException if the hook cannot be set
     */
    public void setCommitHook(CommitHook hook) throws TidesDBException {
        checkOwnerOpen();
        if (hook == null) {
            throw new IllegalArgumentException("Hook cannot be null, use clearCommitHook() instead");
        }
        boolean firstInstall = (commitHookCtxHandle == 0);
        commitHookCtxHandle = nativeSetCommitHook(nativeHandle, hook, commitHookCtxHandle);
        if (firstInstall && owner != null) {
            owner.registerHookColumnFamily(this);
        }
    }
    
    /**
     * Clears the commit hook for this column family.
     * After this call, no further commit callbacks will fire.
     *
     * @throws TidesDBException if the hook cannot be cleared
     */
    public void clearCommitHook() throws TidesDBException {
        checkOwnerOpen();
        commitHookCtxHandle = nativeSetCommitHook(nativeHandle, null, commitHookCtxHandle);
        if (owner != null) {
            owner.unregisterHookColumnFamily(this);
        }
    }
    
    /**
     * Best-effort hook detach during database close. The hook is removed from
     * the engine without caller interaction. Errors are swallowed.
     */
    void clearHookOnClose() {
        if (commitHookCtxHandle != 0) {
            try {
                nativeSetCommitHook(nativeHandle, null, commitHookCtxHandle);
            } catch (TidesDBException ignored) {
                // Best-effort during shutdown.
            }
            commitHookCtxHandle = 0;
        }
    }
    
    long getNativeHandle() {
        return nativeHandle;
    }
    
    private static native Stats nativeGetStats(long handle) throws TidesDBException;
    private static native void nativeCompact(long handle) throws TidesDBException;
    private static native void nativeCompactRange(long handle, byte[] startKey, byte[] endKey) throws TidesDBException;
    private static native void nativeFlushMemtable(long handle) throws TidesDBException;
    private static native boolean nativeIsFlushing(long handle);
    private static native boolean nativeIsCompacting(long handle);
    private static native void nativeUpdateRuntimeConfig(long handle, long writeBufferSize,
        int skipListMaxLevel, float skipListProbability, double bloomFPR, int indexSampleRatio,
        int syncMode, long syncIntervalUs, boolean persistToDisk) throws TidesDBException;
    private static native double nativeRangeCost(long handle, byte[] keyA, byte[] keyB) throws TidesDBException;
    private static native long nativeSetCommitHook(long handle, CommitHook hook, long oldCtxHandle) throws TidesDBException;
    private static native void nativePurge(long handle) throws TidesDBException;
    private static native void nativeSyncWal(long handle) throws TidesDBException;
}