Module methanol
Package com.github.mizosoft.methanol.internal.cache

Class DiskStore

  • All Implemented Interfaces:
    Store, TestableStore, java.io.Closeable, java.io.Flushable, java.lang.AutoCloseable
    public final class DiskStore
extends java.lang.Object
implements Store, TestableStore
    A persistent Store implementation that saves entries on disk under a specified directory. A DiskStore instance assumes exclusive ownership of its directory; only a single DiskStore from a single JVM process can safely operate on a given directory. This assumption is cooperatively enforced among DiskStore instances such that attempting to initialize a store with a directory that is in use by another store in the same or a different JVM process will cause an IOException to be thrown.

    The store keeps track of entries known to it across sessions by maintaining an on-disk hashtable called the index. As changes are made to the store by adding, accessing or removing entries, the index is transparently updated in a time-limited manner. By default, there's at most one index update every 2 seconds. This rate can be changed by setting the system property: com.github.mizosoft.methanol.internal.cache.DiskStore.indexUpdateDelayMillis. Setting a small delay can result in too often index updates, which extracts a noticeable toll on IO and CPU, especially if there's a relatively large number of entries (updating entails reconstructing then rewriting the whole index). On the other hand, scarcely updating the index affords less durability against crashes as entries that aren't indexed are dropped on initialization. Calling the flush method forces an index update, regardless of the time limit.

    To ensure entries are not lost across sessions, a store must be closed after it has been done with. The dispose() method can be called to atomically close the store and clear its directory if persistence isn't needed (e.g. using temp directories for storage). A closed store usually throws an IllegalStateException when used.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void clear()
      Removes all entries from this store.
      void close()
      Closes this store.
      java.nio.file.Path directory()  
      void dispose()
      Atomically clears and closes this store.
      java.util.Optional<Store.Editor> edit​(java.lang.String key)
      Synchronous variant of Store.edit(String, Executor).
      java.util.concurrent.CompletableFuture<java.util.Optional<Store.Editor>> edit​(java.lang.String key, java.util.concurrent.Executor executor)
      Opens an editor for the entry associated with the given key.
      java.util.List<java.lang.String> entriesOnUnderlyingStorageForTesting​(java.lang.String key)
      Returns string representations for the resources an entry with the given key occupies on the underlying store.
      void flush()
      Flushes any indexing data buffered by this store.
      java.util.Iterator<Store.Viewer> iterator()
      Returns an iterator of Viewers over the entries in this store.
      long maxSize()
      Returns this store's max size in bytes.
      static DiskStore.Builder newBuilder()  
      boolean remove​(java.lang.String key)
      Removes the entry associated with the given key.
      long size()
      Returns the size in bytes of all entries in this store.
      java.lang.String toString()  
      java.util.Optional<Store.Viewer> view​(java.lang.String key)
      Synchronous variant of Store.view(String, Executor).
      java.util.concurrent.CompletableFuture<java.util.Optional<Store.Viewer>> view​(java.lang.String key, java.util.concurrent.Executor executor)
      Opens a viewer for the entry associated with the given key.

      • Methods inherited from class java.lang.Object

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

      • Methods inherited from interface com.github.mizosoft.methanol.internal.cache.Store

        removeAll

    • Method Detail

      • directory

        public java.nio.file.Path directory()

      • maxSize

        public long maxSize()
        Description copied from interface: Store
        Returns this store's max size in bytes.
        Specified by:
        maxSize in interface Store

      • view

        public java.util.concurrent.CompletableFuture<java.util.Optional<Store.Viewer>> view​(java.lang.String key,
                                                                                     java.util.concurrent.Executor executor)
        Description copied from interface: Store
        Opens a viewer for the entry associated with the given key. An empty optional is returned if there's no such entry.
        Specified by:
        view in interface Store

      • edit

        public java.util.concurrent.CompletableFuture<java.util.Optional<Store.Editor>> edit​(java.lang.String key,
                                                                                     java.util.concurrent.Executor executor)
        Description copied from interface: Store
        Opens an editor for the entry associated with the given key. An empty optional is returned either if there's no such entry, or such entry cannot be edited at the moment.
        Specified by:
        edit in interface Store

      • iterator

        public java.util.Iterator<Store.Viewer> iterator()
        Description copied from interface: Store
        Returns an iterator of Viewers over the entries in this store. The iterator doesn't throw ConcurrentModificationException when the store is asynchronously modified, but there's no guarantee such changes are reflected.
        Specified by:
        iterator in interface Store

      • remove

        public boolean remove​(java.lang.String key)
               throws java.io.IOException
        Description copied from interface: Store
        Removes the entry associated with the given key.
        Specified by:
        remove in interface Store
        Throws:
        java.io.IOException

      • clear

        public void clear()
           throws java.io.IOException
        Description copied from interface: Store
        Removes all entries from this store.
        Specified by:
        clear in interface Store
        Throws:
        java.io.IOException

      • size

        public long size()
        Description copied from interface: Store
        Returns the size in bytes of all entries in this store.
        Specified by:
        size in interface Store

      • dispose

        public void dispose()
             throws java.io.IOException
        Description copied from interface: Store
        Atomically clears and closes this store.
        Specified by:
        dispose in interface Store
        Throws:
        java.io.IOException

      • close

        public void close()
           throws java.io.IOException
        Description copied from interface: Store
        Closes this store. Once the store is closed, all ongoing edits fail, either silently or by throwing an exception, to write or commit anything.
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Specified by:
        close in interface Store
        Throws:
        java.io.IOException

      • flush

        public void flush()
           throws java.io.IOException
        Description copied from interface: Store
        Flushes any indexing data buffered by this store.
        Specified by:
        flush in interface java.io.Flushable
        Specified by:
        flush in interface Store
        Throws:
        java.io.IOException

      • toString

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

      • entriesOnUnderlyingStorageForTesting

        public java.util.List<java.lang.String> entriesOnUnderlyingStorageForTesting​(java.lang.String key)
        Description copied from interface: TestableStore
        Returns string representations for the resources an entry with the given key occupies on the underlying store. Implementation must skip intermediary data structures and directly interact with the underlying store (e.g. filesystem).
        Specified by:
        entriesOnUnderlyingStorageForTesting in interface TestableStore