package com.r35157.libs.objcache;

import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

/**
 * Stores objects under structured keys for a caller-supplied time to live.
 */
public interface ObjectCache {

    /**
     * Stores or replaces an object.
     *
     * <p>A time to live of zero makes the entry immediately expired.</p>
     *
     * @param key cache key
     * @param object object to cache
     * @param ttlMillis time to live in milliseconds
     * @throws NullPointerException if {@code key} or {@code object} is null
     * @throws IllegalArgumentException if {@code ttlMillis} is negative
     */
    void put(
            @NotNull ObjectCacheKey key,
            @NotNull Object object,
            long ttlMillis
    );

    /**
     * Returns the cached object when it exists and has not expired.
     *
     * <p>An expired entry is treated as absent and is removed lazily by
     * this operation.</p>
     *
     * @param key cache key
     * @return cached object, or {@code null} when absent or expired
     * @throws NullPointerException if {@code key} is null
     */
    @Nullable Object get(
            @NotNull ObjectCacheKey key
    );

    /**
     * Removes an entry when present.
     *
     * @param key cache key
     * @throws NullPointerException if {@code key} is null
     */
    void remove(
            @NotNull ObjectCacheKey key
    );

    /**
     * Removes all entries.
     */
    void clear();
}
