Package org.rocksdb

Class AbstractEventListener

java.lang.Object
org.rocksdb.AbstractNativeReference
org.rocksdb.AbstractImmutableNativeReference
org.rocksdb.RocksCallbackObject
org.rocksdb.AbstractEventListener
All Implemented Interfaces:
AutoCloseable, EventListener
public abstract class AbstractEventListener extends RocksCallbackObject implements EventListener
Base class for Event Listeners.

  • Constructor Details

    • AbstractEventListener

      protected AbstractEventListener()
      Creates an Event Listener that will receive all callbacks from C++.

      If you don't need all callbacks, it is much more efficient to just register for the ones you need by calling AbstractEventListener(EnabledEventCallback...) instead.

    • AbstractEventListener

      protected AbstractEventListener(AbstractEventListener.EnabledEventCallback... enabledEventCallbacks)
      Creates an Event Listener that will receive only certain callbacks from C++.
      Parameters:
      enabledEventCallbacks - callbacks to enable in Java.

  • Method Details

    • onFlushCompleted

      public void onFlushCompleted(RocksDB db, FlushJobInfo flushJobInfo)
      Description copied from interface: EventListener
      callback function to RocksDB which will be called whenever a registered RocksDB flushes a file.

      Note that the this function must be implemented in a way such that it should not run for an extended period of time before the function returns. Otherwise, RocksDB may be blocked.

      Specified by:
      onFlushCompleted in interface EventListener
      Parameters:
      db - the database
      flushJobInfo - the flush job info, contains data copied from respective native structure.

    • onFlushBegin

      public void onFlushBegin(RocksDB db, FlushJobInfo flushJobInfo)
      Description copied from interface: EventListener
      A callback function to RocksDB which will be called before a RocksDB starts to flush memtables.

      Note that the this function must be implemented in a way such that it should not run for an extended period of time before the function returns. Otherwise, RocksDB may be blocked.

      Specified by:
      onFlushBegin in interface EventListener
      Parameters:
      db - the database
      flushJobInfo - the flush job info, contains data copied from respective native structure.

    • onTableFileDeleted

      public void onTableFileDeleted(TableFileDeletionInfo tableFileDeletionInfo)
      Description copied from interface: EventListener
      A callback function for RocksDB which will be called whenever a SST file is deleted. Different from EventListener.onCompactionCompleted(RocksDB, CompactionJobInfo) and EventListener.onFlushCompleted(RocksDB, FlushJobInfo), this callback is designed for external logging service and thus only provide string parameters instead of a pointer to DB. Applications that build logic basic based on file creations and deletions is suggested to implement EventListener.onFlushCompleted(RocksDB, FlushJobInfo) and EventListener.onCompactionCompleted(RocksDB, CompactionJobInfo).

      Note that if applications would like to use the passed reference outside this function call, they should make copies from the returned value.

      Specified by:
      onTableFileDeleted in interface EventListener
      Parameters:
      tableFileDeletionInfo - the table file deletion info, contains data copied from respective native structure.

    • onCompactionBegin

      public void onCompactionBegin(RocksDB db, CompactionJobInfo compactionJobInfo)
      Description copied from interface: EventListener
      A callback function to RocksDB which will be called before a RocksDB starts to compact. The default implementation is no-op.

      Note that the this function must be implemented in a way such that it should not run for an extended period of time before the function returns. Otherwise, RocksDB may be blocked.

      Specified by:
      onCompactionBegin in interface EventListener
      Parameters:
      db - a pointer to the rocksdb instance which just compacted a file.
      compactionJobInfo - a reference to a native CompactionJobInfo struct, which is released after this function is returned, and must be copied if it is needed outside of this function.

    • onCompactionCompleted

      public void onCompactionCompleted(RocksDB db, CompactionJobInfo compactionJobInfo)
      Description copied from interface: EventListener
      A callback function for RocksDB which will be called whenever a registered RocksDB compacts a file. The default implementation is a no-op.

      Note that this function must be implemented in a way such that it should not run for an extended period of time before the function returns. Otherwise, RocksDB may be blocked.

      Specified by:
      onCompactionCompleted in interface EventListener
      Parameters:
      db - a pointer to the rocksdb instance which just compacted a file.
      compactionJobInfo - a reference to a native CompactionJobInfo struct, which is released after this function is returned, and must be copied if it is needed outside of this function.

    • onTableFileCreated

      public void onTableFileCreated(TableFileCreationInfo tableFileCreationInfo)
      Description copied from interface: EventListener
      A callback function for RocksDB which will be called whenever a SST file is created. Different from OnCompactionCompleted and OnFlushCompleted, this callback is designed for external logging service and thus only provide string parameters instead of a pointer to DB. Applications that build logic basic based on file creations and deletions is suggested to implement OnFlushCompleted and OnCompactionCompleted.

      Historically it will only be called if the file is successfully created. Now it will also be called on failure case. User can check info.status to see if it succeeded or not.

      Note that if applications would like to use the passed reference outside this function call, they should make copies from these returned value.

      Specified by:
      onTableFileCreated in interface EventListener
      Parameters:
      tableFileCreationInfo - the table file creation info, contains data copied from respective native structure.

    • onTableFileCreationStarted

      public void onTableFileCreationStarted(TableFileCreationBriefInfo tableFileCreationBriefInfo)
      Description copied from interface: EventListener
      A callback function for RocksDB which will be called before a SST file is being created. It will follow by OnTableFileCreated after the creation finishes.

      Note that if applications would like to use the passed reference outside this function call, they should make copies from these returned value.

      Specified by:
      onTableFileCreationStarted in interface EventListener
      Parameters:
      tableFileCreationBriefInfo - the table file creation brief info, contains data copied from respective native structure.

    • onMemTableSealed

      public void onMemTableSealed(MemTableInfo memTableInfo)
      Description copied from interface: EventListener
      A callback function for RocksDB which will be called before a memtable is made immutable.

      Note that the this function must be implemented in a way such that it should not run for an extended period of time before the function returns. Otherwise, RocksDB may be blocked.

      Note that if applications would like to use the passed reference outside this function call, they should make copies from these returned value.

      Specified by:
      onMemTableSealed in interface EventListener
      Parameters:
      memTableInfo - the mem table info, contains data copied from respective native structure.

    • onColumnFamilyHandleDeletionStarted

      public void onColumnFamilyHandleDeletionStarted(ColumnFamilyHandle columnFamilyHandle)
      Description copied from interface: EventListener
      A callback function for RocksDB which will be called before a column family handle is deleted.

      Note that the this function must be implemented in a way such that it should not run for an extended period of time before the function returns. Otherwise, RocksDB may be blocked.

      Specified by:
      onColumnFamilyHandleDeletionStarted in interface EventListener
      Parameters:
      columnFamilyHandle - is a pointer to the column family handle to be deleted which will become a dangling pointer after the deletion.

    • onExternalFileIngested

      public void onExternalFileIngested(RocksDB db, ExternalFileIngestionInfo externalFileIngestionInfo)
      Description copied from interface: EventListener
      A callback function for RocksDB which will be called after an external file is ingested using IngestExternalFile.

      Note that the this function will run on the same thread as IngestExternalFile(), if this function is blocked, IngestExternalFile() will be blocked from finishing.

      Specified by:
      onExternalFileIngested in interface EventListener
      Parameters:
      db - the database
      externalFileIngestionInfo - the external file ingestion info, contains data copied from respective native structure.

    • onBackgroundError

      public void onBackgroundError(BackgroundErrorReason backgroundErrorReason, Status backgroundError)
      Description copied from interface: EventListener
      A callback function for RocksDB which will be called before setting the background error status to a non-OK value. The new background error status is provided in `bg_error` and can be modified by the callback. E.g., a callback can suppress errors by resetting it to Status::OK(), thus preventing the database from entering read-only mode. We do not provide any guarantee when failed flushes/compactions will be rescheduled if the user suppresses an error.

      Note that this function can run on the same threads as flush, compaction, and user writes. So, it is extremely important not to perform heavy computations or blocking calls in this function.

      Specified by:
      onBackgroundError in interface EventListener
      Parameters:
      backgroundErrorReason - background error reason code
      backgroundError - background error codes

    • onStallConditionsChanged

      public void onStallConditionsChanged(WriteStallInfo writeStallInfo)
      Description copied from interface: EventListener
      A callback function for RocksDB which will be called whenever a change of superversion triggers a change of the stall conditions.

      Note that the this function must be implemented in a way such that it should not run for an extended period of time before the function returns. Otherwise, RocksDB may be blocked.

      Specified by:
      onStallConditionsChanged in interface EventListener
      Parameters:
      writeStallInfo - write stall info, contains data copied from respective native structure.

    • onFileReadFinish

      public void onFileReadFinish(FileOperationInfo fileOperationInfo)
      Description copied from interface: EventListener
      A callback function for RocksDB which will be called whenever a file read operation finishes.
      Specified by:
      onFileReadFinish in interface EventListener
      Parameters:
      fileOperationInfo - file operation info, contains data copied from respective native structure.

    • onFileWriteFinish

      public void onFileWriteFinish(FileOperationInfo fileOperationInfo)
      Description copied from interface: EventListener
      A callback function for RocksDB which will be called whenever a file write operation finishes.
      Specified by:
      onFileWriteFinish in interface EventListener
      Parameters:
      fileOperationInfo - file operation info, contains data copied from respective native structure.

    • onFileFlushFinish

      public void onFileFlushFinish(FileOperationInfo fileOperationInfo)
      Description copied from interface: EventListener
      A callback function for RocksDB which will be called whenever a file flush operation finishes.
      Specified by:
      onFileFlushFinish in interface EventListener
      Parameters:
      fileOperationInfo - file operation info, contains data copied from respective native structure.

    • onFileSyncFinish

      public void onFileSyncFinish(FileOperationInfo fileOperationInfo)
      Description copied from interface: EventListener
      A callback function for RocksDB which will be called whenever a file sync operation finishes.
      Specified by:
      onFileSyncFinish in interface EventListener
      Parameters:
      fileOperationInfo - file operation info, contains data copied from respective native structure.

    • onFileRangeSyncFinish

      public void onFileRangeSyncFinish(FileOperationInfo fileOperationInfo)
      Description copied from interface: EventListener
      A callback function for RocksDB which will be called whenever a file rangeSync operation finishes.
      Specified by:
      onFileRangeSyncFinish in interface EventListener
      Parameters:
      fileOperationInfo - file operation info, contains data copied from respective native structure.

    • onFileTruncateFinish

      public void onFileTruncateFinish(FileOperationInfo fileOperationInfo)
      Description copied from interface: EventListener
      A callback function for RocksDB which will be called whenever a file truncate operation finishes.
      Specified by:
      onFileTruncateFinish in interface EventListener
      Parameters:
      fileOperationInfo - file operation info, contains data copied from respective native structure.

    • onFileCloseFinish

      public void onFileCloseFinish(FileOperationInfo fileOperationInfo)
      Description copied from interface: EventListener
      A callback function for RocksDB which will be called whenever a file close operation finishes.
      Specified by:
      onFileCloseFinish in interface EventListener
      Parameters:
      fileOperationInfo - file operation info, contains data copied from respective native structure.

    • shouldBeNotifiedOnFileIO

      public boolean shouldBeNotifiedOnFileIO()
      Description copied from interface: EventListener
      If true, the EventListener.onFileReadFinish(FileOperationInfo) and EventListener.onFileWriteFinish(FileOperationInfo) will be called. If false, then they won't be called.

      Default: false

      Specified by:
      shouldBeNotifiedOnFileIO in interface EventListener
      Returns:
      whether to callback when file read/write is finished

    • onErrorRecoveryBegin

      public boolean onErrorRecoveryBegin(BackgroundErrorReason backgroundErrorReason, Status backgroundError)
      Description copied from interface: EventListener
      A callback function for RocksDB which will be called just before starting the automatic recovery process for recoverable background errors, such as NoSpace(). The callback can suppress the automatic recovery by setting returning false. The database will then have to be transitioned out of read-only mode by calling RocksDB#resume().
      Specified by:
      onErrorRecoveryBegin in interface EventListener
      Parameters:
      backgroundErrorReason - background error reason code
      backgroundError - background error codes
      Returns:
      return false if the automatic recovery should be suppressed

    • onErrorRecoveryCompleted

      public void onErrorRecoveryCompleted(Status oldBackgroundError)
      Description copied from interface: EventListener
      A callback function for RocksDB which will be called once the database is recovered from read-only mode after an error. When this is called, it means normal writes to the database can be issued and the user can initiate any further recovery actions needed
      Specified by:
      onErrorRecoveryCompleted in interface EventListener
      Parameters:
      oldBackgroundError - old background error codes

    • initializeNative

      protected long initializeNative(long... nativeParameterHandles)
      Description copied from class: RocksCallbackObject
      Construct the Native C++ object which will callback to our object methods
      Specified by:
      initializeNative in class RocksCallbackObject
      Parameters:
      nativeParameterHandles - An array of native handles for any parameter objects that are needed during construction
      Returns:
      The native handle of the C++ object which will callback to us

    • disposeInternal

      protected void disposeInternal()
      Deletes underlying C++ native callback object pointer
      Overrides:
      disposeInternal in class RocksCallbackObject