Package org.hawaiiframework.cache

Interface Cache<T>

  • Type Parameters:
    T - the type of objects to store.
    All Known Implementing Classes:
    RedisCache
    public interface Cache<T>
    Cache to store objects.

    The underlying cache implementation is free to expire objects before the configured (or requested) expiry time. Reasons for this can be memory pressure or (default) cache configuration.

    In other words, there is no guarantee that a cache.put(key, object) followed by a cache.get(key) will return the object stored. In case the key is not found null will be returned.

    Author:
    Richard Kohlen

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      T get​(@NotNull String key)
      Retrieve the object stored under the key.
      default Optional<T> optional​(@NotNull String key)
      Retrieve an optional for the object stored under the key.
      void put​(@NotNull String key, T value)
      Put the object in the cache with the given key.
      void put​(@NotNull String key, T value, @NotNull Duration duration)
      Put the object in the cache with the given key for the given duration.
      void put​(@NotNull String key, T value, @NotNull LocalDateTime expiresAt)
      Put the object in the cache with the given key for until expiresAt has come.
      void put​(@NotNull String key, T value, @NotNull ZonedDateTime expiresAt)
      Put the object in the cache with the given key for until expiresAt has come.
      default void putEternally​(@NotNull String key, T value)
      Put the object in the cache with the given key for ever.
      void remove​(@NotNull String key)
      Remove the value associate with the key.

    • Method Detail

      • put

        void put​(@NotNull
         @NotNull String key,
         @NotNull
         T value)
        Put the object in the cache with the given key.

        The object is stored for the default configured time, depending on the cache implementation. See general remarks about cache evictions.

        Parameters:
        key - The (not null) key to store the object under.
        value - The (not null) object to store.

      • put

        void put​(@NotNull
         @NotNull String key,
         @NotNull
         T value,
         @NotNull
         @NotNull Duration duration)
        Put the object in the cache with the given key for the given duration.

        The object is stored for the requested duration. See general remarks about cache evictions.

        Parameters:
        key - The (not null) key to store the object under.
        value - The (not null) object to store.
        duration - The (not null) duration to store the object for.

      • put

        void put​(@NotNull
         @NotNull String key,
         @NotNull
         T value,
         @NotNull
         @NotNull LocalDateTime expiresAt)
        Put the object in the cache with the given key for until expiresAt has come.

        The object is stored and should be removed when expiresAt had come.

        Parameters:
        key - The (not null) key to store the object under.
        value - The (not null) object to store.
        expiresAt - The (not null) expiry time.

      • put

        void put​(@NotNull
         @NotNull String key,
         @NotNull
         T value,
         @NotNull
         @NotNull ZonedDateTime expiresAt)
        Put the object in the cache with the given key for until expiresAt has come.

        The object is stored and should be removed when expiresAt had come.

        Parameters:
        key - The (not null) key to store the object under.
        value - The (not null) object to store.
        expiresAt - The (not null) expiry time.

      • putEternally

        default void putEternally​(@NotNull
                          @NotNull String key,
                          @NotNull
                          T value)
        Put the object in the cache with the given key for ever.

        The object is stored and should never be removed. This should overrule configured default expiry time for objects put in the cache. However, the object may still be evicted from the cache, for instance for memory reasons.

        This method calls Duration.ofMillis(Long.max()) and passes it to the put(key, value, Duration duration). So this method does not persist eternally, but rather persists for a long time.

        Parameters:
        key - The (not null) key to store the object under.
        value - The (not null) object to store.

      • get

        T get​(@NotNull
      @NotNull String key)
        Retrieve the object stored under the key.
        Parameters:
        key - The (never null) key to retrieve the value with.
        Returns:
        The value, or null if the object is not found.

      • optional

        default Optional<T> optional​(@NotNull
                             @NotNull String key)
        Retrieve an optional for the object stored under the key.
        Parameters:
        key - The (never null) key to retrieve the value with.
        Returns:
        The Optional for the value.

      • remove

        void remove​(@NotNull
            @NotNull String key)
        Remove the value associate with the key.
        Parameters:
        key - The key to remove.