Package org.caffinitas.ohc

Interface OHCache<K,​V>

    • Method Detail

      • put

        boolean put​(K key,
            V value)
        Same as put(Object, Object, long) but uses the configured default TTL, if any.
        Parameters:
        key - key of the entry to be added. Must not be null.
        value - value of the entry to be added. Must not be null.
        Returns:
        true, if the entry has been added, false otherwise

      • put

        boolean put​(K key,
            V value,
            long expireAt)
        Adds the key/value. If the entry size of key/value exceeds the configured maximum entry length, any previously existing entry for the key is removed.
        Parameters:
        key - key of the entry to be added. Must not be null.
        value - value of the entry to be added. Must not be null.
        expireAt - timestamp in milliseconds since "epoch" (like System.currentTimeMillis()) when the entry shall expire. Pass USE_DEFAULT_EXPIRE_AT for the configured default time-to-live or NEVER_EXPIRE to let it never expire.
        Returns:
        true, if the entry has been added, false otherwise

      • addOrReplace

        boolean addOrReplace​(K key,
                     V old,
                     V value)
        Same as addOrReplace(Object, Object, Object, long) but uses the configured default TTL, if any.
        Parameters:
        key - key of the entry to be added or replaced. Must not be null.
        old - if the entry exists, it's serialized value is compared to the serialized value of old and only replaced, if it matches.
        value - value of the entry to be added. Must not be null.
        Returns:
        true on success or false if the existing value does not matcuh old

      • addOrReplace

        boolean addOrReplace​(K key,
                     V old,
                     V value,
                     long expireAt)
        Adds key/value if either the key is not present or the existing value matches parameter old. If the entry size of key/value exceeds the configured maximum entry length, the old value is removed.
        Parameters:
        key - key of the entry to be added or replaced. Must not be null.
        old - if the entry exists, it's serialized value is compared to the serialized value of old and only replaced, if it matches.
        value - value of the entry to be added. Must not be null.
        expireAt - timestamp in milliseconds since "epoch" (like System.currentTimeMillis()) when the entry shall expire. Pass USE_DEFAULT_EXPIRE_AT for the configured default time-to-live or NEVER_EXPIRE to let it never expire.
        Returns:
        true on success or false if the existing value does not matcuh old

      • putIfAbsent

        boolean putIfAbsent​(K key,
                    V value)
        Same as putIfAbsent(Object, Object, long) but uses the configured default TTL, if any.
        Parameters:
        key - key of the entry to be added. Must not be null.
        value - value of the entry to be added. Must not be null.
        Returns:
        true on success or false if the key is already present.

      • putIfAbsent

        boolean putIfAbsent​(K key,
                    V value,
                    long expireAt)
        Adds the key/value if the key is not present. If the entry size of key/value exceeds the configured maximum entry length, any previously existing entry for the key is removed.
        Parameters:
        key - key of the entry to be added. Must not be null.
        value - value of the entry to be added. Must not be null.
        expireAt - timestamp in milliseconds since "epoch" (like System.currentTimeMillis()) when the entry shall expire. Pass USE_DEFAULT_EXPIRE_AT for the configured default time-to-live or NEVER_EXPIRE to let it never expire.
        Returns:
        true on success or false if the key is already present.

      • putAll

        void putAll​(Map<? extends K,​? extends V> m)
        This is effectively a shortcut to add all entries in the given map m.
        Parameters:
        m - entries to be added

      • remove

        boolean remove​(K key)
        Remove a single entry for the given key.
        Parameters:
        key - key of the entry to be removed. Must not be null.
        Returns:
        true, if the entry has been removed, false otherwise

      • removeAll

        void removeAll​(Iterable<K> keys)
        This is effectively a shortcut to remove the entries for all keys given in the iterable keys.
        Parameters:
        keys - keys to be removed

      • clear

        void clear()
        Removes all entries from the cache.

      • get

        V get​(K key)
        Get the value for a given key.
        Parameters:
        key - key of the entry to be retrieved. Must not be null.
        Returns:
        either the non-null value or null if no entry for the requested key exists

      • containsKey

        boolean containsKey​(K key)
        Checks whether an entry for a given key exists. Usually, this is more efficient than testing for null via get(Object).
        Parameters:
        key - key of the entry to be retrieved. Must not be null.
        Returns:
        either true if an entry for the given key exists or false if no entry for the requested key exists

      • getDirect

        DirectValueAccess getDirect​(K key)
        Returns a closeable byte buffer. You must close the returned DirectValueAccess instance after use. After closing, you must not call any of the methods of the ByteBuffer returned by DirectValueAccess.buffer().
        Parameters:
        key - the key of the value to retrieve
        Returns:
        reference-counted byte buffer or null if key does not exist.

      • getDirect

        DirectValueAccess getDirect​(K key,
                            boolean updateLRU)
        Like getDirect(Object), but allows skipping the update of LRU stats when updateLRU is false.
        Parameters:
        key - the key to retrieve
        updateLRU - whether to update LRU stats
        Returns:
        reference-counted byte buffer or null if key does not exist.

      • getWithLoaderAsync

        Future<V> getWithLoaderAsync​(K key,
                             CacheLoader<K,​V> loader)
        Shortcut to call getWithLoader(Object, CacheLoader, long, TimeUnit) using the default entry time-to-live. Note that the cache has to be configured with an Executor to schedule the load process.

        Note that the future may indicate a failure via it's get methods if the CacheLoader.load(Object) implementation threw an error or a runtime exception occured due to not enough memory for example.

        Parameters:
        key - key of the value to load
        loader - loader implementation to use
        Returns:
        a future to process the load request asynchronously.

      • getWithLoaderAsync

        Future<V> getWithLoaderAsync​(K key,
                             CacheLoader<K,​V> loader,
                             long expireAt)
        Shortcut to call getWithLoader(Object, CacheLoader, long, TimeUnit) using the default entry time-to-live. Note that the cache has to be configured with an Executor to schedule the load process.

        Note that the future may indicate a failure via it's get methods if the CacheLoader.load(Object) implementation threw an error or a runtime exception occured due to not enough memory for example.

        Parameters:
        key - key of the value to load
        loader - loader implementation to use
        expireAt - optional timestamp (millis since epoch) at which the entry shall expire
        Returns:
        a future to process the load request asynchronously.

      • hotKeyIterator

        CloseableIterator<K> hotKeyIterator​(int n)
        Builds an iterator over the N most recently used keys returning deserialized objects. You must call close() on the returned iterator.

        Note: During a rehash, the implementation might return keys twice or not at all.

        Parameters:
        n - the N most recently used keys
        Returns:
        closeable iterator over the keys

      • keyIterator

        CloseableIterator<K> keyIterator()
        Builds an iterator over all keys returning deserialized objects. You must call close() on the returned iterator.

        Note: During a rehash, the implementation might return keys twice or not at all.

        Returns:
        closeable iterator over the keys

      • hotKeyBufferIterator

        CloseableIterator<ByteBuffer> hotKeyBufferIterator​(int n)
        Builds an iterator over all keys returning direct byte buffers. Do not use a returned ByteBuffer after calling any method on the iterator. You must call close() on the returned iterator.

        Note: During a rehash, the implementation might return keys twice or not at all.

        Parameters:
        n - the N most recently used keys
        Returns:
        closeable iterator over byte-buffers

      • keyBufferIterator

        CloseableIterator<ByteBuffer> keyBufferIterator()
        Builds an iterator over all keys returning direct byte buffers. Do not use a returned ByteBuffer after calling any method on the iterator. You must call close() on the returned iterator.

        Note: During a rehash, the implementation might return keys twice or not at all.

        Returns:
        closeable iterator over byte-buffers

      • deserializeEntry

        boolean deserializeEntry​(ReadableByteChannel channel)
                  throws IOException
        Deserialize a single entry.
        Parameters:
        channel - channel to read from
        Returns:
        whether the deserialization was successful
        Throws:
        IOException - indicates an IO error

      • serializeEntry

        boolean serializeEntry​(K key,
                       WritableByteChannel channel)
                throws IOException
        Serialize a cache entry.
        Parameters:
        key - Key of the cache entry to serialize
        channel - target channel to write to
        Returns:
        whether the serialization was successful
        Throws:
        IOException - indicates an IO error

      • deserializeEntries

        int deserializeEntries​(ReadableByteChannel channel)
                throws IOException
        Deserialize entries.
        Parameters:
        channel - channel to read from
        Returns:
        number of deserialized entries
        Throws:
        IOException - indicates an IO error

      • serializeHotNEntries

        int serializeHotNEntries​(int n,
                         WritableByteChannel channel)
                  throws IOException
        Serialize a the hottest cache entries.
        Parameters:
        n - number of cache entries to serialize
        channel - target channel to write to
        Returns:
        number of serialized entries
        Throws:
        IOException - indicates an IO error

      • serializeHotNKeys

        int serializeHotNKeys​(int n,
                      WritableByteChannel channel)
               throws IOException
        Serialize a the keys of the hottest cache entries.
        Parameters:
        n - number of cache entries to serialize
        channel - target channel to write to
        Returns:
        number of serialized entries
        Throws:
        IOException - indicates an IO error

      • resetStatistics

        void resetStatistics()

      • size

        long size()

      • hashTableSizes

        int[] hashTableSizes()

      • perSegmentSizes

        long[] perSegmentSizes()

      • segments

        int segments()

      • capacity

        long capacity()

      • memUsed

        long memUsed()

      • freeCapacity

        long freeCapacity()

      • loadFactor

        float loadFactor()

      • setCapacity

        void setCapacity​(long capacity)
        Modify the cache's capacity. Lowering the capacity will not immediately remove any entry nor will it immediately free allocated (off heap) memory.

        Future operations will even allocate in flight, temporary memory - i.e. setting capacity to 0 does not disable the cache, it will continue to work but cannot add more data.

        Parameters:
        capacity - the new capacity