Package org.apache.bookkeeper.mledger

Interface ManagedCursor

All Known Implementing Classes:
ManagedCursorImpl, NonDurableCursorImpl, ReadOnlyCursorImpl
@LimitedPrivate @Stable public interface ManagedCursor
A ManagedCursor is a persisted cursor inside a ManagedLedger.

The ManagedCursor is used to read from the ManagedLedger and to signal when the consumer is done with the messages that it has read before.

  • Method Details

    • getName

      String getName()
      Get the unique cursor name.
      Returns:
      the cursor name

    • getLastActive

      long getLastActive()
      Get the last active time of the cursor.
      Returns:
      the last active time of the cursor

    • updateLastActive

      void updateLastActive()
      Update the last active time of the cursor.

    • getProperties

      Map<String,Long> getProperties()
      Return any properties that were associated with the last stored position.

    • getCursorProperties

      Map<String,String> getCursorProperties()
      Return any properties that were associated with the cursor.

    • putCursorProperty

      CompletableFuture<Void> putCursorProperty(String key, String value)
      Add a property associated with the cursor. Note: ManagedLedgerException.BadVersionException will be set in this CompletableFuture, if there are concurrent modification and store data has changed.
      Returns:
      a handle to the result of the operation

    • setCursorProperties

      CompletableFuture<Void> setCursorProperties(Map<String,String> cursorProperties)
      Set all properties associated with the cursor, but internal properties(start with '#pulsar_internal.') are still preserved and prohibit setting of internal properties by this method. Note: ManagedLedgerException.BadVersionException will be set in this CompletableFuture, if there are concurrent modification and store data has changed.
      Returns:
      a handle to the result of the operation

    • removeCursorProperty

      CompletableFuture<Void> removeCursorProperty(String key)
      Remove a property associated with the cursor. Note: ManagedLedgerException.BadVersionException will be set in this CompletableFuture, if there are concurrent modification and store data has changed.
      Returns:
      a handle to the result of the operation

    • putProperty

      boolean putProperty(String key, Long value)
      Add a property associated with the last stored position.

    • removeProperty

      boolean removeProperty(String key)
      Remove a property associated with the last stored position.

    • readEntries

      List<Entry> readEntries(int numberOfEntriesToRead) throws InterruptedException, ManagedLedgerException
      Read entries from the ManagedLedger, up to the specified number. The returned list can be smaller.
      Parameters:
      numberOfEntriesToRead - maximum number of entries to return
      Returns:
      the list of entries
      Throws:
      ManagedLedgerException
      InterruptedException

    • asyncReadEntries

      void asyncReadEntries(int numberOfEntriesToRead, AsyncCallbacks.ReadEntriesCallback callback, Object ctx, PositionImpl maxPosition)
      Asynchronously read entries from the ManagedLedger.
      Parameters:
      numberOfEntriesToRead - maximum number of entries to return
      callback - callback object
      ctx - opaque context
      maxPosition - max position can read
      See Also:

    • asyncReadEntries

      void asyncReadEntries(int numberOfEntriesToRead, long maxSizeBytes, AsyncCallbacks.ReadEntriesCallback callback, Object ctx, PositionImpl maxPosition)
      Asynchronously read entries from the ManagedLedger.
      Parameters:
      numberOfEntriesToRead - maximum number of entries to return
      maxSizeBytes - max size in bytes of the entries to return
      callback - callback object
      ctx - opaque context
      maxPosition - max position can read

    • asyncReadEntriesWithSkip

      default void asyncReadEntriesWithSkip(int numberOfEntriesToRead, long maxSizeBytes, AsyncCallbacks.ReadEntriesCallback callback, Object ctx, PositionImpl maxPosition, Predicate<PositionImpl> skipCondition)
      Asynchronously read entries from the ManagedLedger.
      Parameters:
      numberOfEntriesToRead - maximum number of entries to return
      maxSizeBytes - max size in bytes of the entries to return
      callback - callback object
      ctx - opaque context
      maxPosition - max position can read
      skipCondition - predicate of read filter out

    • getNthEntry

      Entry getNthEntry(int n, ManagedCursor.IndividualDeletedEntries deletedEntries) throws InterruptedException, ManagedLedgerException
      Get 'N'th entry from the mark delete position in the cursor without updating any cursor positions.
      Parameters:
      n - entry position
      deletedEntries - skip individual deleted entries
      Returns:
      the entry
      Throws:
      InterruptedException
      ManagedLedgerException

    • asyncGetNthEntry

      void asyncGetNthEntry(int n, ManagedCursor.IndividualDeletedEntries deletedEntries, AsyncCallbacks.ReadEntryCallback callback, Object ctx)
      Asynchronously get 'N'th entry from the mark delete position in the cursor without updating any cursor positions.
      Parameters:
      n - entry position
      deletedEntries - skip individual deleted entries
      callback -
      ctx -

    • readEntriesOrWait

      List<Entry> readEntriesOrWait(int numberOfEntriesToRead) throws InterruptedException, ManagedLedgerException
      Read entries from the ManagedLedger, up to the specified number. The returned list can be smaller.

      If no entries are available, the method will block until at least a new message will be persisted.

      Parameters:
      numberOfEntriesToRead - maximum number of entries to return
      Returns:
      the list of entries
      Throws:
      ManagedLedgerException
      InterruptedException

    • readEntriesOrWait

      List<Entry> readEntriesOrWait(int maxEntries, long maxSizeBytes) throws InterruptedException, ManagedLedgerException
      Read entries from the ManagedLedger, up to the specified number and size.

      If no entries are available, the method will block until at least a new message will be persisted.

      Parameters:
      maxEntries - maximum number of entries to return
      maxSizeBytes - max size in bytes of the entries to return
      Returns:
      the list of entries
      Throws:
      ManagedLedgerException
      InterruptedException

    • asyncReadEntriesOrWait

      void asyncReadEntriesOrWait(int numberOfEntriesToRead, AsyncCallbacks.ReadEntriesCallback callback, Object ctx, PositionImpl maxPosition)
      Asynchronously read entries from the ManagedLedger.

      If no entries are available, the callback will not be triggered. Instead it will be registered to wait until a new message will be persisted into the managed ledger

      Parameters:
      numberOfEntriesToRead - maximum number of entries to return
      callback - callback object
      ctx - opaque context
      maxPosition - max position can read
      See Also:

    • asyncReadEntriesOrWait

      void asyncReadEntriesOrWait(int maxEntries, long maxSizeBytes, AsyncCallbacks.ReadEntriesCallback callback, Object ctx, PositionImpl maxPosition)
      Asynchronously read entries from the ManagedLedger, up to the specified number and size.

      If no entries are available, the callback will not be triggered. Instead it will be registered to wait until a new message will be persisted into the managed ledger

      Parameters:
      maxEntries - maximum number of entries to return
      maxSizeBytes - max size in bytes of the entries to return
      callback - callback object
      ctx - opaque context
      maxPosition - max position can read
      See Also:

    • asyncReadEntriesWithSkipOrWait

      default void asyncReadEntriesWithSkipOrWait(int maxEntries, AsyncCallbacks.ReadEntriesCallback callback, Object ctx, PositionImpl maxPosition, Predicate<PositionImpl> skipCondition)
      Asynchronously read entries from the ManagedLedger, up to the specified number and size.

      If no entries are available, the callback will not be triggered. Instead it will be registered to wait until a new message will be persisted into the managed ledger

      Parameters:
      maxEntries - maximum number of entries to return
      callback - callback object
      ctx - opaque context
      maxPosition - max position can read
      skipCondition - predicate of read filter out
      See Also:

    • asyncReadEntriesWithSkipOrWait

      default void asyncReadEntriesWithSkipOrWait(int maxEntries, long maxSizeBytes, AsyncCallbacks.ReadEntriesCallback callback, Object ctx, PositionImpl maxPosition, Predicate<PositionImpl> skipCondition)
      Asynchronously read entries from the ManagedLedger, up to the specified number and size.

      If no entries are available, the callback will not be triggered. Instead it will be registered to wait until a new message will be persisted into the managed ledger

      Parameters:
      maxEntries - maximum number of entries to return
      maxSizeBytes - max size in bytes of the entries to return
      callback - callback object
      ctx - opaque context
      maxPosition - max position can read
      skipCondition - predicate of read filter out
      See Also:

    • cancelPendingReadRequest

      boolean cancelPendingReadRequest()
      Cancel a previously scheduled asyncReadEntriesOrWait operation.
      Returns:
      true if the read operation was canceled or false if there was no pending operation
      See Also:

    • hasMoreEntries

      boolean hasMoreEntries()
      Tells whether this cursor has already consumed all the available entries.

      This method is not blocking.

      Returns:
      true if there are pending entries to read, false otherwise

    • getNumberOfEntries

      long getNumberOfEntries()
      Return the number of messages that this cursor still has to read.

      This method has linear time complexity on the number of ledgers included in the managed ledger.

      Returns:
      the number of entries

    • getNumberOfEntriesInBacklog

      long getNumberOfEntriesInBacklog(boolean isPrecise)
      Return the number of non-deleted messages on this cursor.

      This will also include messages that have already been read from the cursor but not deleted or mark-deleted yet.

      This method has linear time complexity on the number of ledgers included in the managed ledger.

      Parameters:
      isPrecise - set to true to get precise backlog count
      Returns:
      the number of entries

    • markDelete

      void markDelete(Position position) throws InterruptedException, ManagedLedgerException
      This signals that the reader is done with all the entries up to "position" (included). This can potentially trigger a ledger deletion, if all the other cursors are done too with the underlying ledger.
      Parameters:
      position - the last position that have been successfully consumed
      Throws:
      ManagedLedgerException
      InterruptedException

    • markDelete

      void markDelete(Position position, Map<String,Long> properties) throws InterruptedException, ManagedLedgerException
      This signals that the reader is done with all the entries up to "position" (included). This can potentially trigger a ledger deletion, if all the other cursors are done too with the underlying ledger.
      Parameters:
      position - the last position that have been successfully consumed
      properties - additional user-defined properties that can be associated with a particular cursor position
      Throws:
      ManagedLedgerException
      InterruptedException

    • asyncMarkDelete

      void asyncMarkDelete(Position position, AsyncCallbacks.MarkDeleteCallback callback, Object ctx)
      Asynchronous mark delete.
      Parameters:
      position - the last position that have been successfully consumed
      callback - callback object
      ctx - opaque context
      See Also:

    • asyncMarkDelete

      void asyncMarkDelete(Position position, Map<String,Long> properties, AsyncCallbacks.MarkDeleteCallback callback, Object ctx)
      Asynchronous mark delete.
      Parameters:
      position - the last position that have been successfully consumed
      properties - additional user-defined properties that can be associated with a particular cursor position
      callback - callback object
      ctx - opaque context
      See Also:

    • delete

      void delete(Position position) throws InterruptedException, ManagedLedgerException
      Delete a single message.

      Mark a single message for deletion. When all the previous messages are all deleted, then markDelete() will be called internally to advance the persistent acknowledged position.

      The deletion of the message is not persisted into the durable storage and cannot be recovered upon the reopening of the ManagedLedger

      Parameters:
      position - the position of the message to be deleted
      Throws:
      InterruptedException
      ManagedLedgerException

    • asyncDelete

      void asyncDelete(Position position, AsyncCallbacks.DeleteCallback callback, Object ctx)
      Delete a single message asynchronously

      Mark a single message for deletion. When all the previous messages are all deleted, then markDelete() will be called internally to advance the persistent acknowledged position.

      The deletion of the message is not persisted into the durable storage and cannot be recovered upon the reopening of the ManagedLedger

      Parameters:
      position - the position of the message to be deleted
      callback - callback object
      ctx - opaque context

    • delete

      void delete(Iterable<Position> positions) throws InterruptedException, ManagedLedgerException
      Delete a group of entries.

      Mark multiple single messages for deletion. When all the previous messages are all deleted, then markDelete() will be called internally to advance the persistent acknowledged position.

      The deletion of the message is not persisted into the durable storage and cannot be recovered upon the reopening of the ManagedLedger

      Parameters:
      positions - positions of the messages to be deleted
      Throws:
      InterruptedException
      ManagedLedgerException

    • asyncDelete

      void asyncDelete(Iterable<Position> position, AsyncCallbacks.DeleteCallback callback, Object ctx)
      Delete a group of messages asynchronously

      Mark a group of messages for deletion. When all the previous messages are all deleted, then markDelete() will be called internally to advance the persistent acknowledged position.

      The deletion of the messages is not persisted into the durable storage and cannot be recovered upon the reopening of the ManagedLedger

      Parameters:
      position - the positions of the messages to be deleted
      callback - callback object
      ctx - opaque context

    • getReadPosition

      Position getReadPosition()
      Get the read position. This points to the next message to be read from the cursor.
      Returns:
      the read position

    • getMarkDeletedPosition

      Position getMarkDeletedPosition()
      Get the newest mark deleted position on this cursor.
      Returns:
      the mark deleted position

    • getPersistentMarkDeletedPosition

      Position getPersistentMarkDeletedPosition()
      Get the persistent newest mark deleted position on this cursor.
      Returns:
      the persistent mark deleted position

    • rewind

      void rewind()
      Rewind the cursor to the mark deleted position to replay all the already read but not yet mark deleted messages.

      The next message to be read is the one after the current mark deleted message.

    • rewind

      default void rewind(boolean readCompacted)

    • seek

      default void seek(Position newReadPosition)
      Move the cursor to a different read position.

      If the new position happens to be before the already mark deleted position, it will be set to the mark deleted position instead.

      Parameters:
      newReadPosition - the position where to move the cursor

    • seek

      void seek(Position newReadPosition, boolean force)

    • clearBacklog

      void clearBacklog() throws InterruptedException, ManagedLedgerException
      Clear the cursor backlog.

      Consume all the entries for this cursor.

      Throws:
      InterruptedException
      ManagedLedgerException

    • asyncClearBacklog

      void asyncClearBacklog(AsyncCallbacks.ClearBacklogCallback callback, Object ctx)
      Clear the cursor backlog.

      Consume all the entries for this cursor.

      Parameters:
      callback - callback object
      ctx - opaque context

    • skipEntries

      void skipEntries(int numEntriesToSkip, ManagedCursor.IndividualDeletedEntries deletedEntries) throws InterruptedException, ManagedLedgerException
      Skip n entries from the read position of this cursor.
      Parameters:
      numEntriesToSkip - number of entries to skip
      deletedEntries - skip individual deleted entries
      Throws:
      InterruptedException
      ManagedLedgerException

    • asyncSkipEntries

      void asyncSkipEntries(int numEntriesToSkip, ManagedCursor.IndividualDeletedEntries deletedEntries, AsyncCallbacks.SkipEntriesCallback callback, Object ctx)
      Skip n entries from the read position of this cursor.
      Parameters:
      numEntriesToSkip - number of entries to skip
      deletedEntries - skip individual deleted entries
      callback - callback object
      ctx - opaque context

    • findNewestMatching

      Position findNewestMatching(Predicate<Entry> condition) throws InterruptedException, ManagedLedgerException
      Find the newest entry that matches the given predicate. Will only search among active entries
      Parameters:
      condition - predicate that reads an entry an applies a condition
      Returns:
      Position of the newest entry that matches the given predicate
      Throws:
      InterruptedException
      ManagedLedgerException

    • scan

      default CompletableFuture<ScanOutcome> scan(Optional<Position> startingPosition, Predicate<Entry> condition, int batchSize, long maxEntries, long timeOutMs)
      Scan the cursor from the current position up to the end. Please note that this is an expensive operation
      Parameters:
      startingPosition - the position to start from, if not provided the scan will start from the lastDeleteMarkPosition
      condition - a condition to continue the scan, the condition can access the entry
      batchSize - number of entries to process at each read
      maxEntries - maximum number of entries to scan
      timeOutMs - maximum time to spend on this operation
      Throws:
      InterruptedException
      ManagedLedgerException

    • findNewestMatching

      Position findNewestMatching(ManagedCursor.FindPositionConstraint constraint, Predicate<Entry> condition) throws InterruptedException, ManagedLedgerException
      Find the newest entry that matches the given predicate.
      Parameters:
      constraint - search only active entries or all entries
      condition - predicate that reads an entry an applies a condition
      Returns:
      Position of the newest entry that matches the given predicate
      Throws:
      InterruptedException
      ManagedLedgerException

    • asyncFindNewestMatching

      void asyncFindNewestMatching(ManagedCursor.FindPositionConstraint constraint, Predicate<Entry> condition, AsyncCallbacks.FindEntryCallback callback, Object ctx)
      Find the newest entry that matches the given predicate.
      Parameters:
      constraint - search only active entries or all entries
      condition - predicate that reads an entry an applies a condition
      callback - callback object returning the resultant position
      ctx - opaque context

    • asyncFindNewestMatching

      void asyncFindNewestMatching(ManagedCursor.FindPositionConstraint constraint, Predicate<Entry> condition, AsyncCallbacks.FindEntryCallback callback, Object ctx, boolean isFindFromLedger)
      Find the newest entry that matches the given predicate.
      Parameters:
      constraint - search only active entries or all entries
      condition - predicate that reads an entry an applies a condition
      callback - callback object returning the resultant position
      ctx - opaque context
      isFindFromLedger - find the newest entry from ledger

    • resetCursor

      void resetCursor(Position position) throws InterruptedException, ManagedLedgerException
      reset the cursor to specified position to enable replay of messages.
      Parameters:
      position - position to move the cursor to
      Throws:
      InterruptedException
      ManagedLedgerException

    • asyncResetCursor

      void asyncResetCursor(Position position, boolean forceReset, AsyncCallbacks.ResetCursorCallback callback)
      reset the cursor to specified position to enable replay of messages.
      Parameters:
      position - position to move the cursor to
      forceReset - whether to force reset the position even if the position is no longer in the managed ledger, this is used by compacted topic which has data in the compacted ledger, to ensure the cursor can read data from the compacted ledger.
      callback - callback object

    • replayEntries

      List<Entry> replayEntries(Set<? extends Position> positions) throws InterruptedException, ManagedLedgerException
      Read the specified set of positions from ManagedLedger.
      Parameters:
      positions - set of positions to read
      Returns:
      the list of entries
      Throws:
      InterruptedException
      ManagedLedgerException

    • asyncReplayEntries

      Set<? extends Position> asyncReplayEntries(Set<? extends Position> positions, AsyncCallbacks.ReadEntriesCallback callback, Object ctx)
      Read the specified set of positions from ManagedLedger without ordering.
      Parameters:
      positions - set of positions to read
      callback - callback object returning the list of entries
      ctx - opaque context
      Returns:
      skipped positions set of positions which are already deleted/acknowledged and skipped while replaying them

    • asyncReplayEntries

      Set<? extends Position> asyncReplayEntries(Set<? extends Position> positions, AsyncCallbacks.ReadEntriesCallback callback, Object ctx, boolean sortEntries)
      Read the specified set of positions from ManagedLedger.
      Parameters:
      positions - set of positions to read
      callback - callback object returning the list of entries
      ctx - opaque context
      sortEntries - callback with sorted entry list.
      Returns:
      skipped positions set of positions which are already deleted/acknowledged and skipped while replaying them

    • close

      void close() throws InterruptedException, ManagedLedgerException
      Close the cursor and releases the associated resources.
      Throws:
      InterruptedException
      ManagedLedgerException

    • asyncClose

      void asyncClose(AsyncCallbacks.CloseCallback callback, Object ctx)
      Close the cursor asynchronously and release the associated resources.
      Parameters:
      callback - callback object
      ctx - opaque context

    • getFirstPosition

      Position getFirstPosition()
      Get the first position.
      Returns:
      the first position

    • setActive

      void setActive()
      Activate cursor: EntryCacheManager caches entries only for activated-cursors.

    • setInactive

      void setInactive()
      Deactivate cursor.

    • setAlwaysInactive

      void setAlwaysInactive()
      A cursor that is set as always-inactive will never trigger the caching of entries.

    • isActive

      boolean isActive()
      Checks if cursor is active or not.
      Returns:

    • isDurable

      boolean isDurable()
      Tells whether the cursor is durable or just kept in memory.

    • getNumberOfEntriesSinceFirstNotAckedMessage

      long getNumberOfEntriesSinceFirstNotAckedMessage()
      Returns total number of entries from the first not-acked message to current dispatching position.
      Returns:

    • getTotalNonContiguousDeletedMessagesRange

      int getTotalNonContiguousDeletedMessagesRange()
      Returns number of mark-Delete range.
      Returns:

    • getNonContiguousDeletedMessagesRangeSerializedSize

      int getNonContiguousDeletedMessagesRangeSerializedSize()
      Returns the serialized size of mark-Delete ranges.

    • getEstimatedSizeSinceMarkDeletePosition

      long getEstimatedSizeSinceMarkDeletePosition()
      Returns the estimated size of the unacknowledged backlog for this cursor.
      Returns:
      the estimated size from the mark delete position of the cursor

    • skipNonRecoverableLedger

      default void skipNonRecoverableLedger(long ledgerId)
      If a ledger is lost, this ledger will be skipped after enabled "autoSkipNonRecoverableData", and the method is used to delete information about this ledger in the ManagedCursor.

    • getThrottleMarkDelete

      double getThrottleMarkDelete()
      Returns cursor throttle mark-delete rate.
      Returns:

    • setThrottleMarkDelete

      void setThrottleMarkDelete(double throttleMarkDelete)
      Update throttle mark delete rate.

    • getManagedLedger

      ManagedLedger getManagedLedger()
      Get ManagedLedger attached with cursor.
      Returns:
      ManagedLedger

    • getLastIndividualDeletedRange

      com.google.common.collect.Range<PositionImpl> getLastIndividualDeletedRange()
      Get last individual deleted range.
      Returns:
      range

    • trimDeletedEntries

      void trimDeletedEntries(List<Entry> entries)
      Trim delete entries for the given entries.

    • getDeletedBatchIndexesAsLongArray

      long[] getDeletedBatchIndexesAsLongArray(PositionImpl position)
      Get deleted batch indexes list for a batch message.

    • getStats

      ManagedCursorMXBean getStats()
      Returns:
      the managed cursor stats MBean

    • checkAndUpdateReadPositionChanged

      boolean checkAndUpdateReadPositionChanged()
      Checks if read position changed since this method was called last time.
      Returns:
      if read position changed

    • isClosed

      boolean isClosed()
      Checks if the cursor is closed.
      Returns:
      whether this cursor is closed.