ceph/src/rocksdb/java/src/main/java/org/rocksdb/AbstractNativeReference.java

   1 // Copyright (c) 2016, Facebook, Inc.  All rights reserved.
   2 // This source code is licensed under the BSD-style license found in the
   3 // LICENSE file in the root directory of this source tree. An additional grant
   4 // of patent rights can be found in the PATENTS file in the same 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    */
  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
  46   public abstract void close();
  47
  48   /**
  49    * @deprecated Instead use {@link AbstractNativeReference#close()}
  50    */
  51   @Deprecated
  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
  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 }