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 Detail

      • getName

        java.lang.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

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

      • readEntries

        java.util.List<Entry> readEntries​(int numberOfEntriesToRead)
                           throws java.lang.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
        java.lang.InterruptedException

      • asyncReadEntries

        void asyncReadEntries​(int numberOfEntriesToRead,
                      AsyncCallbacks.ReadEntriesCallback callback,
                      java.lang.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:
        readEntries(int)

      • asyncReadEntries

        void asyncReadEntries​(int numberOfEntriesToRead,
                      long maxSizeBytes,
                      AsyncCallbacks.ReadEntriesCallback callback,
                      java.lang.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

      • asyncGetNthEntry

        void asyncGetNthEntry​(int n,
                      ManagedCursor.IndividualDeletedEntries deletedEntries,
                      AsyncCallbacks.ReadEntryCallback callback,
                      java.lang.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

        java.util.List<Entry> readEntriesOrWait​(int numberOfEntriesToRead)
                                 throws java.lang.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
        java.lang.InterruptedException

      • readEntriesOrWait

        java.util.List<Entry> readEntriesOrWait​(int maxEntries,
                                        long maxSizeBytes)
                                 throws java.lang.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
        java.lang.InterruptedException

      • asyncReadEntriesOrWait

        void asyncReadEntriesOrWait​(int numberOfEntriesToRead,
                            AsyncCallbacks.ReadEntriesCallback callback,
                            java.lang.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:
        readEntriesOrWait(int)

      • asyncReadEntriesOrWait

        void asyncReadEntriesOrWait​(int maxEntries,
                            long maxSizeBytes,
                            AsyncCallbacks.ReadEntriesCallback callback,
                            java.lang.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:
        readEntriesOrWait(int, long)

      • 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 java.lang.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
        java.lang.InterruptedException

      • markDelete

        void markDelete​(Position position,
                java.util.Map<java.lang.String,​java.lang.Long> properties)
         throws java.lang.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
        java.lang.InterruptedException

      • asyncMarkDelete

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

      • asyncMarkDelete

        void asyncMarkDelete​(Position position,
                     java.util.Map<java.lang.String,​java.lang.Long> properties,
                     AsyncCallbacks.MarkDeleteCallback callback,
                     java.lang.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:
        markDelete(Position)

      • delete

        void delete​(Position position)
     throws java.lang.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:
        java.lang.InterruptedException
        ManagedLedgerException

      • asyncDelete

        void asyncDelete​(Position position,
                 AsyncCallbacks.DeleteCallback callback,
                 java.lang.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​(java.lang.Iterable<Position> positions)
     throws java.lang.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:
        java.lang.InterruptedException
        ManagedLedgerException

      • asyncDelete

        void asyncDelete​(java.lang.Iterable<Position> position,
                 AsyncCallbacks.DeleteCallback callback,
                 java.lang.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.

      • seek

        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

      • clearBacklog

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

        Consume all the entries for this cursor.

        Throws:
        java.lang.InterruptedException
        ManagedLedgerException

      • asyncClearBacklog

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

        Consume all the entries for this cursor.

        Parameters:
        callback - callback object
        ctx - opaque context

      • asyncSkipEntries

        void asyncSkipEntries​(int numEntriesToSkip,
                      ManagedCursor.IndividualDeletedEntries deletedEntries,
                      AsyncCallbacks.SkipEntriesCallback callback,
                      java.lang.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​(com.google.common.base.Predicate<Entry> condition)
                     throws java.lang.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:
        java.lang.InterruptedException
        ManagedLedgerException

      • findNewestMatching

        Position findNewestMatching​(ManagedCursor.FindPositionConstraint constraint,
                            com.google.common.base.Predicate<Entry> condition)
                     throws java.lang.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:
        java.lang.InterruptedException
        ManagedLedgerException

      • asyncFindNewestMatching

        void asyncFindNewestMatching​(ManagedCursor.FindPositionConstraint constraint,
                             com.google.common.base.Predicate<Entry> condition,
                             AsyncCallbacks.FindEntryCallback callback,
                             java.lang.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

      • resetCursor

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

      • asyncResetCursor

        void asyncResetCursor​(Position position,
                      AsyncCallbacks.ResetCursorCallback callback)
        reset the cursor to specified position to enable replay of messages.
        Parameters:
        position - position to move the cursor to
        callback - callback object

      • replayEntries

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

      • asyncReplayEntries

        java.util.Set<? extends Position> asyncReplayEntries​(java.util.Set<? extends Position> positions,
                                                     AsyncCallbacks.ReadEntriesCallback callback,
                                                     java.lang.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

        java.util.Set<? extends Position> asyncReplayEntries​(java.util.Set<? extends Position> positions,
                                                     AsyncCallbacks.ReadEntriesCallback callback,
                                                     java.lang.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

      • asyncClose

        void asyncClose​(AsyncCallbacks.CloseCallback callback,
                java.lang.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

      • getThrottleMarkDelete

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

      • setThrottleMarkDelete

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

      • getLastIndividualDeletedRange

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

      • trimDeletedEntries

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

      • getDeletedBatchIndexesAsLongArray

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

      • checkAndUpdateReadPositionChanged

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