Interface ObjectCache<K,​V>


  • public interface ObjectCache<K,​V>
    A cache for arbitrary objects. Cache implementations are thread-safe and support concurrency. A cache entry can be locked when an object is in process of being created, but the locking / unlocking must be protected in a try ... finally block.

    To use as a reader:

     key = "EPSG:4326";
     CoordinateReferenceSystem crs = cache.get(key);
     
    To overwrite:
     cache.put(key, crs);
     
    To reserve the entry while figuring out what to write:
     try {
         cache.writeLock(key); // may block if another writer is working on this code.
         value = cache.peek(key);
         if (value == null) {
            // another writer got here first
         } else {
            value = figuringOutWhatToWrite(....);
            cache.put(key, value);
         }
     } finally {
         cache.writeUnLock(key);
     }
     
    To use as a proper cache:
     CylindricalCS cs = (CylindricalCS) cache.get(key);
     if (cs == null) {
         try {
             cache.writeLock(key);
             cs = (CylindricalCS) cache.test(key);
             if (cs == null) {
                 cs = csAuthority.createCylindricalCS(code);
                 cache.put(key, cs);
             }
         } finally {
             cache.writeUnLock(key);
         }
     }
     return cs;
     
    Since:
    2.5
    Author:
    Cory Horner (Refractions Research)
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void clear()
      Removes all entries from this cache.
      V get​(K key)
      Returns an object from the pool for the specified code.
      Set<K> getKeys()
      Returns a set of all the keys currently contained within the ObjectCache.
      V peek​(K key)
      Use the write lock to test the value for the provided key.
      void put​(K key, V object)
      Puts an element into the cache.
      void remove​(K key)
      Removes a given key from the cache.
      void writeLock​(K key)
      Acquire a write lock on the indicated key.
      void writeUnLock​(K key)
      Release write lock on the indicated key.
    • Method Detail

      • clear

        void clear()
        Removes all entries from this cache.
      • get

        V get​(K key)
        Returns an object from the pool for the specified code. If the object was retained as a weak reference, the referent is returned.
        Parameters:
        key - The key whose associated value is to be returned.
      • peek

        V peek​(K key)
        Use the write lock to test the value for the provided key.

        This method is used by a writer to test if someone (ie another writer) has provided the value for us (while we were blocked waiting for them).

        Returns:
        The value, may be null
      • put

        void put​(K key,
                 V object)
        Puts an element into the cache.

        You may simply use this method - it is threadsafe:

        
         cache.put("4326", crs);
         
        You may also consider reserving the entry while you work on the answer:
        
          try {
             cache.writeLock( "fred" );
             ...find fred
             cache.put( "fred", fred );
          }
          finally {
             cache.writeUnLock();
          }
         
        Parameters:
        key - the authority code.
        object - The referencing object to add in the pool.
      • writeLock

        void writeLock​(K key)
        Acquire a write lock on the indicated key.
      • writeUnLock

        void writeUnLock​(K key)
        Release write lock on the indicated key.
      • getKeys

        Set<K> getKeys()
        Returns a set of all the keys currently contained within the ObjectCache.

        This is a static copy of the keys in the cache at the point in time when the function is called.

        Returns:
        a set of keys currently contained within the cache.
      • remove

        void remove​(K key)
        Removes a given key from the cache.