Class HttpCache

java.lang.Object
com.github.mizosoft.methanol.HttpCache
All Implemented Interfaces:
Flushable, AutoCloseable
public final class HttpCache extends Object implements AutoCloseable, Flushable
An HTTP cache that resides between a Methanol client and its backend HttpClient.

An HttpCache instance is utilized by configuring it with Methanol.Builder.cache(HttpCache). The cache operates by inserting itself as an Interceptor that can short-circuit requests by serving responses from a specified storage.

See Also:

  • Method Details

    • directory

      public Optional<Path> directory()
      Returns the directory used by this cache if entries are being cached on disk.

    • maxSize

      public long maxSize()
      Returns this cache's max size in bytes.

    • executor

      public Optional<Executor> executor()
      Returns an Optional containing this cache's executor if one is explicitly set.

    • listener

      public Optional<HttpCache.Listener> listener()
      Returns the HttpCache.Listener set by the user.

    • size

      public long size() throws IOException
      Returns the size this cache occupies in bytes.
      Throws:
      IOException

    • stats

      public HttpCache.Stats stats()
      Returns a snapshot of statistics accumulated so far.

    • stats

      public HttpCache.Stats stats(URI uri)
      Returns a snapshot of statistics accumulated so far for the given URI.

    • initialize

      @Deprecated(since="1.8.0", forRemoval=true) public void initialize()
      Deprecated, for removal: This API element is subject to removal in a future version.
      As of 1.8.0, a cache is always initialized when created.
      Initializes this cache. A cache that operates on disk needs to initialize its in-memory data structures before usage to restore indexing data from previous sessions. Initialization entails reading index files, iterating over entries available on cache's directory and possibly creating new index files.

      The cache initializes itself automatically on first use. An application might choose to call this method (or initializeAsync()) during its startup sequence to allow the cache to operate directly when it's first used.

    • initializeAsync

      @Deprecated(since="1.8.0", forRemoval=true) public CompletableFuture<Void> initializeAsync()
      Deprecated, for removal: This API element is subject to removal in a future version.
      As of 1.8.0, a cache is always initialized when created.
      Asynchronously initializes this cache

    • uris

      public Iterator<URI> uris() throws IOException
      Returns an iterator over the URIs of responses known to this cache. The returned iterator supports removal.
      Throws:
      IOException

    • clear

      public void clear() throws IOException
      Removes all entries from this cache.
      Throws:
      IllegalStateException - if closed
      IOException

    • remove

      public boolean remove(URI uri) throws IOException
      Removes the entry associated with the given URI if one is present.
      Throws:
      IllegalStateException - if closed
      IOException

    • remove

      public boolean remove(HttpRequest request) throws IOException
      Removes the entry associated with the given request if one is present.
      Throws:
      IllegalStateException - if closed
      IOException

    • enable

      public void enable(boolean on)
      Sets whether this cache is enabled. A disabled cache neither reads from nor writes to underlying storage, just as if it was never installed. Caches start enabled, and can be later disabled and re-enabled any number of times.

      This function is intended to be used to disable the cache when underlying storage disconnects or becomes faulty, and consequently reading from or writing to the cache always fails. This can be detected when too many write and/or read failures occur.

    • isEnabled

      public boolean isEnabled()
      Returns whether this cache is enabled.

    • dispose

      public void dispose() throws IOException
      Atomically clears and closes this cache.
      Throws:
      IllegalStateException - if closed
      IOException

    • flush

      public void flush() throws IOException
      Specified by:
      flush in interface Flushable
      Throws:
      IOException

    • close

      public void close() throws IOException
      Closes this cache. Attempting to operate on a closed cache either directly (e.g. removing an entry) or indirectly (e.g. sending requests over a client that uses this cache) will likely cause an IllegalStateException (or perhaps some other exception) to be thrown.
      Specified by:
      close in interface AutoCloseable
      Throws:
      IOException

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • newBuilder

      public static HttpCache.Builder newBuilder()
      Returns a new HttpCache.Builder.