content: // Copyright (c) 2016, Facebook, Inc.  All rights reserved.
  //  This source code is licensed under both the GPLv2 (found in the
  //  COPYING file in the root directory) and Apache 2.0 License
  //  (found in the LICENSE.Apache file in the root directory).
  
  package org.rocksdb;
  
  /**
   * AbstractNativeReference is the base-class of all RocksDB classes that have
   * a pointer to a native C++ {@code rocksdb} object.
   * <p>
   * AbstractNativeReference has the {@link AbstractNativeReference#dispose()}
   * method, which frees its associated C++ object.</p>
   * <p>
   * This function should be called manually, however, if required it will be
   * called automatically during the regular Java GC process via
   * {@link AbstractNativeReference#finalize()}.</p>
   * <p>
   * Note - Java can only see the long member variable (which is the C++ pointer
   * value to the native object), as such it does not know the real size of the
   * object and therefore may assign a low GC priority for it; So it is strongly
   * suggested that you manually dispose of objects when you are finished with
   * them.</p>
   */
  public abstract class AbstractNativeReference implements AutoCloseable {
  
    /**
     * Returns true if we are responsible for freeing the underlying C++ object
     *
     * @return true if we are responsible to free the C++ object
     * @see #dispose()
     */
    protected abstract boolean isOwningHandle();
  
    /**
     * Frees the underlying C++ object
     * <p>
     * It is strong recommended that the developer calls this after they
     * have finished using the object.</p>
     * <p>
     * Note, that once an instance of {@link AbstractNativeReference} has been
     * disposed, calling any of its functions will lead to undefined
     * behavior.</p>
     */
    @Override
    public abstract void close();
  
    /**
     * @deprecated Instead use {@link AbstractNativeReference#close()}
     */
    @Deprecated
    public final void dispose() {
      close();
    }
  
    /**
     * Simply calls {@link AbstractNativeReference#dispose()} to free
     * any underlying C++ object reference which has not yet been manually
     * released.
     *
     * @deprecated You should not rely on GC of Rocks objects, and instead should
     * either call {@link AbstractNativeReference#close()} manually or make
     * use of some sort of ARM (Automatic Resource Management) such as
     * Java 7's <a href="https://docs.oracle.com/javase/tutorial/essential/exceptions/tryResourceClose.html">try-with-resources</a>
     * statement
     */
    @Override
    @Deprecated
    protected void finalize() throws Throwable {
      if(isOwningHandle()) {
        //TODO(AR) log a warning message... developer should have called close()
      }
      dispose();
      super.finalize();
    }
  }
  