Module methanol
Package com.github.mizosoft.methanol

Class HttpCache

  • All Implemented Interfaces:
    java.io.Flushable, java.lang.AutoCloseable
    public final class HttpCache
extends java.lang.Object
implements java.lang.AutoCloseable, java.io.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:
    Caching with Methanol

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  HttpCache.Builder
      A builder of HttpCaches.
      static interface  HttpCache.Listener
      A listener to request/response & read/write events within the cache.
      static interface  HttpCache.Stats
      Statistics of an HttpCache.
      static interface  HttpCache.StatsRecorder
      Strategy for recoding HttpCache statistics.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      void clear()
      Removes all entries from this cache.
      void close()
      Closes this cache.
      java.util.Optional<java.nio.file.Path> directory()
      Returns the directory used by this cache if entries are being cached on disk.
      void dispose()
      Atomically clears and closes this cache.
      void enable​(boolean on)
      Sets whether this cache is enabled.
      java.util.Optional<java.util.concurrent.Executor> executor()
      Returns an Optional containing this cache's executor if one is explicitly set.
      void flush()  
      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.
      java.util.concurrent.CompletableFuture<java.lang.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.
      boolean isEnabled()
      Returns whether this cache is enabled.
      java.util.Optional<HttpCache.Listener> listener()
      Returns the HttpCache.Listener set by the user.
      long maxSize()
      Returns this cache's max size in bytes.
      static HttpCache.Builder newBuilder()
      Returns a new HttpCache.Builder.
      boolean remove​(java.net.http.HttpRequest request)
      Removes the entry associated with the given request if one is present.
      boolean remove​(java.net.URI uri)
      Removes the entry associated with the given URI if one is present.
      long size()
      Returns the size this cache occupies in bytes.
      HttpCache.Stats stats()
      Returns a snapshot of statistics accumulated so far.
      HttpCache.Stats stats​(java.net.URI uri)
      Returns a snapshot of statistics accumulated so far for the given URI.
      java.lang.String toString()  
      java.util.Iterator<java.net.URI> uris()
      Returns an iterator over the URIs of responses known to this cache.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Method Detail

      • directory

        public java.util.Optional<java.nio.file.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 java.util.Optional<java.util.concurrent.Executor> executor()
        Returns an Optional containing this cache's executor if one is explicitly set.

      • size

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

      • stats

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

      • stats

        public HttpCache.Stats stats​(java.net.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 java.util.concurrent.CompletableFuture<java.lang.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 java.util.Iterator<java.net.URI> uris()
                                      throws java.io.IOException
        Returns an iterator over the URIs of responses known to this cache. The returned iterator supports removal.
        Throws:
        java.io.IOException

      • clear

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

      • remove

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

      • remove

        public boolean remove​(java.net.http.HttpRequest request)
               throws java.io.IOException
        Removes the entry associated with the given request if one is present.
        Throws:
        java.lang.IllegalStateException - if closed
        java.io.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 java.io.IOException
        Atomically clears and closes this cache.
        Throws:
        java.lang.IllegalStateException - if closed
        java.io.IOException

      • flush

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

      • close

        public void close()
           throws java.io.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 java.lang.AutoCloseable
        Throws:
        java.io.IOException

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • newBuilder

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