org.rocksdb

Class AbstractEventListener

java.lang.Object

org.rocksdb.AbstractNativeReference

org.rocksdb.AbstractImmutableNativeReference

org.rocksdb.RocksCallbackObject

org.rocksdb.AbstractEventListener

All Implemented Interfaces:

java.lang.AutoCloseable, EventListener

public abstract class AbstractEventListener
extends RocksCallbackObject
implements EventListener

Base class for Event Listeners.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AbstractEventListener.EnabledEventCallback

Field Summary

Fields inherited from class org.rocksdb.RocksCallbackObject

nativeHandle_

Fields inherited from class org.rocksdb.AbstractImmutableNativeReference

owningHandle_

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractEventListener() Creates an Event Listener that will receive all callbacks from C++.
protected	AbstractEventListener(AbstractEventListener.EnabledEventCallback... enabledEventCallbacks) Creates an Event Listener that will receive only certain callbacks from C++.

Method Summary

Modifier and Type	Method and Description
protected void	disposeInternal() Deletes underlying C++ native callback object pointer
protected long	initializeNative(long... nativeParameterHandles) Construct the Native C++ object which will callback to our object methods
void	onBackgroundError(BackgroundErrorReason backgroundErrorReason, Status backgroundError) A callback function for RocksDB which will be called before setting the background error status to a non-OK value.
void	onColumnFamilyHandleDeletionStarted(ColumnFamilyHandle columnFamilyHandle) A callback function for RocksDB which will be called before a column family handle is deleted.
void	onCompactionBegin(RocksDB db, CompactionJobInfo compactionJobInfo) A callback function to RocksDB which will be called before a RocksDB starts to compact.
void	onCompactionCompleted(RocksDB db, CompactionJobInfo compactionJobInfo) A callback function for RocksDB which will be called whenever a registered RocksDB compacts a file.
boolean	onErrorRecoveryBegin(BackgroundErrorReason backgroundErrorReason, Status backgroundError) A callback function for RocksDB which will be called just before starting the automatic recovery process for recoverable background errors, such as NoSpace().
void	onErrorRecoveryCompleted(Status oldBackgroundError) A callback function for RocksDB which will be called once the database is recovered from read-only mode after an error.
void	onExternalFileIngested(RocksDB db, ExternalFileIngestionInfo externalFileIngestionInfo) A callback function for RocksDB which will be called after an external file is ingested using IngestExternalFile.
void	onFileCloseFinish(FileOperationInfo fileOperationInfo) A callback function for RocksDB which will be called whenever a file close operation finishes.
void	onFileFlushFinish(FileOperationInfo fileOperationInfo) A callback function for RocksDB which will be called whenever a file flush operation finishes.
void	onFileRangeSyncFinish(FileOperationInfo fileOperationInfo) A callback function for RocksDB which will be called whenever a file rangeSync operation finishes.
void	onFileReadFinish(FileOperationInfo fileOperationInfo) A callback function for RocksDB which will be called whenever a file read operation finishes.
void	onFileSyncFinish(FileOperationInfo fileOperationInfo) A callback function for RocksDB which will be called whenever a file sync operation finishes.
void	onFileTruncateFinish(FileOperationInfo fileOperationInfo) A callback function for RocksDB which will be called whenever a file truncate operation finishes.
void	onFileWriteFinish(FileOperationInfo fileOperationInfo) A callback function for RocksDB which will be called whenever a file write operation finishes.
void	onFlushBegin(RocksDB db, FlushJobInfo flushJobInfo) A callback function to RocksDB which will be called before a RocksDB starts to flush memtables.
void	onFlushCompleted(RocksDB db, FlushJobInfo flushJobInfo) callback function to RocksDB which will be called whenever a registered RocksDB flushes a file.
void	onMemTableSealed(MemTableInfo memTableInfo) A callback function for RocksDB which will be called before a memtable is made immutable.
void	onStallConditionsChanged(WriteStallInfo writeStallInfo) A callback function for RocksDB which will be called whenever a change of superversion triggers a change of the stall conditions.
void	onTableFileCreated(TableFileCreationInfo tableFileCreationInfo) A callback function for RocksDB which will be called whenever a SST file is created.
void	onTableFileCreationStarted(TableFileCreationBriefInfo tableFileCreationBriefInfo) A callback function for RocksDB which will be called before a SST file is being created.
void	onTableFileDeleted(TableFileDeletionInfo tableFileDeletionInfo) A callback function for RocksDB which will be called whenever a SST file is deleted.
boolean	shouldBeNotifiedOnFileIO() If true, the EventListener.onFileReadFinish(FileOperationInfo) and EventListener.onFileWriteFinish(FileOperationInfo) will be called.

Methods inherited from class org.rocksdb.AbstractImmutableNativeReference

close, disOwnNativeHandle, isOwningHandle

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

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 Detail

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