1 // Copyright (c) 2016, Facebook, Inc.  All rights reserved.
2 //  This source code is licensed under both the GPLv2 (found in the
3 //  COPYING file in the root directory) and Apache 2.0 License
4 //  (found in the LICENSE.Apache file in the root directory).
5 
6 package org.rocksdb;
7 
8 /**
9  * AbstractNativeReference is the base-class of all RocksDB classes that have
10  * a pointer to a native C++ {@code rocksdb} object.
11  * <p>
12  * AbstractNativeReference has the {@link AbstractNativeReference#dispose()}
13  * method, which frees its associated C++ object.</p>
14  * <p>
15  * This function should be called manually, however, if required it will be
16  * called automatically during the regular Java GC process via
17  * {@link AbstractNativeReference#finalize()}.</p>
18  * <p>
19  * Note - Java can only see the long member variable (which is the C++ pointer
20  * value to the native object), as such it does not know the real size of the
21  * object and therefore may assign a low GC priority for it; So it is strongly
22  * suggested that you manually dispose of objects when you are finished with
23  * them.</p>
24  */
25 public abstract class AbstractNativeReference implements AutoCloseable {
26 
27   /**
28    * Returns true if we are responsible for freeing the underlying C++ object
29    *
30    * @return true if we are responsible to free the C++ object
31    * @see #dispose()
32    */
isOwningHandle()33   protected abstract boolean isOwningHandle();
34 
35   /**
36    * Frees the underlying C++ object
37    * <p>
38    * It is strong recommended that the developer calls this after they
39    * have finished using the object.</p>
40    * <p>
41    * Note, that once an instance of {@link AbstractNativeReference} has been
42    * disposed, calling any of its functions will lead to undefined
43    * behavior.</p>
44    */
45   @Override
close()46   public abstract void close();
47 
48   /**
49    * @deprecated Instead use {@link AbstractNativeReference#close()}
50    */
51   @Deprecated
dispose()52   public final void dispose() {
53     close();
54   }
55 
56   /**
57    * Simply calls {@link AbstractNativeReference#dispose()} to free
58    * any underlying C++ object reference which has not yet been manually
59    * released.
60    *
61    * @deprecated You should not rely on GC of Rocks objects, and instead should
62    * either call {@link AbstractNativeReference#close()} manually or make
63    * use of some sort of ARM (Automatic Resource Management) such as
64    * Java 7's <a href="https://docs.oracle.com/javase/tutorial/essential/exceptions/tryResourceClose.html">try-with-resources</a>
65    * statement
66    */
67   @Override
68   @Deprecated
finalize()69   protected void finalize() throws Throwable {
70     if(isOwningHandle()) {
71       //TODO(AR) log a warning message... developer should have called close()
72     }
73     dispose();
74     super.finalize();
75   }
76 }
77