View Javadoc

1   /*
2    *  This file is part of the Heritrix web crawler (crawler.archive.org).
3    *
4    *  Licensed to the Internet Archive (IA) by one or more individual 
5    *  contributors. 
6    *
7    *  The IA licenses this file to You under the Apache License, Version 2.0
8    *  (the "License"); you may not use this file except in compliance with
9    *  the License.  You may obtain a copy of the License at
10   *
11   *      http://www.apache.org/licenses/LICENSE-2.0
12   *
13   *  Unless required by applicable law or agreed to in writing, software
14   *  distributed under the License is distributed on an "AS IS" BASIS,
15   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16   *  See the License for the specific language governing permissions and
17   *  limitations under the License.
18   */
19  
20  package org.archive.util;
21  
22  import java.io.Closeable;
23  import java.util.Set;
24  
25  /***
26   * An object cache for create-once-by-name-and-then-reuse objects. 
27   * 
28   * Objects are added, but never removed. Subsequent get()s using the 
29   * same key will return the exact same object, UNLESS all such objects
30   * have been forgotten, in which case a new object MAY be returned. 
31   * 
32   * This allows implementors (such as ObjectIdentityBdbCache or 
33   * CachedBdbMap) to page out (aka 'expunge') instances to
34   * persistent storage while they're not being used. However, as long as
35   * they are used (referenced), all requests for the same-named object
36   * will share a reference to the same object, and the object may be
37   * mutated in place without concern for explicitly persisting its
38   * state to disk.  
39   * 
40   * @param <V>
41   */
42  public interface ObjectIdentityCache<K, V> extends Closeable {
43      /*** get the object under the given key/name */
44      public abstract V get(final K key);
45      
46      /*** get the object under the given key/name, using (and remembering)
47       * the object supplied by the supplier if no prior mapping exists */
48      public abstract V getOrUse(final K key, Supplier<V> supplierOrNull);
49  
50      /*** force the persistent backend, if any, to be updated with all 
51       * live object state */ 
52      public abstract void sync();
53      
54      /*** close/release any associated resources */ 
55      public abstract void close();
56      
57      /*** count of name-to-object contained */ 
58      public abstract int size();
59  
60      /*** set of all keys */ 
61      public abstract Set<K> keySet();
62  }