net.openhft.chronicle.queue

Interface ExcerptTailer

All Superinterfaces:

AutoCloseable, Closeable, ExcerptCommon<ExcerptTailer>, net.openhft.chronicle.wire.MarshallableIn, net.openhft.chronicle.core.io.QueryCloseable, net.openhft.chronicle.core.io.SingleThreadedChecked, net.openhft.chronicle.wire.SourceContext

public interface ExcerptTailer
extends ExcerptCommon<ExcerptTailer>, net.openhft.chronicle.wire.MarshallableIn, net.openhft.chronicle.wire.SourceContext

The component that facilitates sequentially reading data from a ChronicleQueue.

NOTE: Tailers are NOT thread-safe, sharing a Tailer between threads will lead to errors and unpredictable behaviour.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	ExcerptTailer.AcknowledgedIndexReplicatedCheck

Field Summary

Fields inherited from interface net.openhft.chronicle.core.io.SingleThreadedChecked

DISABLE_SINGLE_THREADED_CHECK

Fields inherited from interface net.openhft.chronicle.wire.MarshallableIn

MARSHALLABLE_IN_INTERN_SIZE

Method Summary

Modifier and Type	Method and Description
default void	acknowledgedIndexReplicatedCheck(ExcerptTailer.AcknowledgedIndexReplicatedCheck acknowledgedIndexReplicatedCheck) Allows you to control the number of in flight messages that are allowed when setting acknowledgedIndexReplicatedCheck, By default, this is set to:
default @NotNull ExcerptTailer	afterLastWritten(ChronicleQueue queue) Winds this ExcerptTailer to after the last entry which wrote an entry to the queue.
default @NotNull ExcerptTailer	afterWrittenMessageAtIndex(@NotNull ChronicleQueue queue, long index) Winds this ExcerptTailer to the specified index of the provided queue and reads the history message, then moves this tailer to the message index in the history message.
default long	approximateExcerptsInCycle(int cycle) Deprecated. Use excerptsInCycle(int) instead
int	cycle() Returns the current cycle for this Tailer.
TailerDirection	direction() Returns the direction of this ExcerptTailer.
@NotNull ExcerptTailer	direction(@NotNull TailerDirection direction) Sets the direction of this ExcerptTailer.
default long	exactExcerptsInCycle(int cycle) Deprecated. Use excerptsInCycle(int) instead
default long	excerptsInCycle(int cycle) Return the exact number of excerpts in a cycle available for reading.
long	index() Returns the current index of this Tailer.
default long	lastReadIndex()
boolean	moveToCycle(int cycle) Tries to move to the start of a cycle for this Tailer to the provided cycle.
boolean	moveToIndex(long index) Tries to move the index for this Tailer to the provided index.
default boolean	readAfterReplicaAcknowledged() Returns the Read After Replica Acknowledged property of this Tailer.
default void	readAfterReplicaAcknowledged(boolean readAfterReplicaAcknowledged) Sets the Read After Replica Acknowledged property of this Tailer to the provided readAfterReplicaAcknowledged.
default @NotNull net.openhft.chronicle.wire.DocumentContext	readingDocument() Returns the DocumentContext for this ExcerptTailer.
@NotNull net.openhft.chronicle.wire.DocumentContext	readingDocument(boolean includeMetaData) Returns the DocumentContext for this ExcerptTailer.
@NotNull TailerState	state() Returns the TailerState of this Tailer.
boolean	striding() Returns the striding property of this Tailer.
ExcerptTailer	striding(boolean striding) Sets the striding property of this Tailer.
@NotNull ExcerptTailer	toEnd() Moves the index for this Tailer to the end of the queue.
@NotNull ExcerptTailer	toStart() Moves the index for this Tailer to the first existing excerpt in the queue.

Methods inherited from interface net.openhft.chronicle.queue.ExcerptCommon

currentFile, queue, sourceId, sync

Methods inherited from interface net.openhft.chronicle.core.io.Closeable

close, closeQuietly, closeQuietly

Methods inherited from interface net.openhft.chronicle.core.io.QueryCloseable

isClosed, isClosing

Methods inherited from interface net.openhft.chronicle.core.io.SingleThreadedChecked

singleThreadedCheckDisabled, singleThreadedCheckReset

Methods inherited from interface net.openhft.chronicle.wire.MarshallableIn

methodReader, methodReaderBuilder, readBytes, readBytes, readDocument, readMap, readText, readText

Methods inherited from interface net.openhft.chronicle.wire.SourceContext

sourceId

Method Detail

readingDocument

@NotNull
default @NotNull net.openhft.chronicle.wire.DocumentContext readingDocument()

Returns the DocumentContext for this ExcerptTailer.

This is equivalent to MarshallableIn.readDocument(ReadMarshallable) but without the use of a lambda expression.

This method is the ExcerptTailer equivalent of WireIn.readingDocument()

Specified by:

readingDocument in interface net.openhft.chronicle.wire.MarshallableIn

Returns:

the document context

readingDocument

@NotNull
@NotNull net.openhft.chronicle.wire.DocumentContext readingDocument(boolean includeMetaData)

Returns the DocumentContext for this ExcerptTailer.

This is equivalent to MarshallableIn.readDocument(ReadMarshallable) but without the use of a lambda expression.

This method is the ExcerptTailer equivalent of WireIn.readingDocument()

Parameters:

includeMetaData - if the DocumentContext shall be metadata aware.

Returns:

the document context

index

long index()

Returns the current index of this Tailer.

If this method is invoked within a try (tailer.readingDocument(){ } block, returns the index of the current reading document. Otherwise, returns the next index to read.

The index includes the cycle and the sequence number within that cycle.

Specified by:

index in interface net.openhft.chronicle.wire.SourceContext

Returns:

the current index of this Tailer

lastReadIndex

default long lastReadIndex()

cycle

int cycle()

Returns the current cycle for this Tailer.

Usually, each cycle will have its own unique data file to store excerpts.

Returns:

Returns the current cycle for this Tailer

moveToIndex

boolean moveToIndex(long index)

Tries to move the index for this Tailer to the provided index.

The index contains both the cycle number and sequence number within the cycle.

In order for the operation to succeed, the roll file, corresponding to the cycle number in the index, must be present and the roll file must contain the sequence number contained in the index.

If the index is not a valid index, the operation is undefined.

Parameters:

index - to move to.

Returns:

if this is a valid index.

moveToCycle

boolean moveToCycle(int cycle)

Tries to move to the start of a cycle for this Tailer to the provided cycle.

In order for the operation to succeed, the roll file, corresponding to the cycle number, must be present.

If the cycle is not a valid cycle, the operation is undefined.

Parameters:

cycle - to move to.

Returns:

if this is a valid cycle.

toStart

@NotNull
@NotNull ExcerptTailer toStart()

Moves the index for this Tailer to the first existing excerpt in the queue.

Returns:

this ExcerptTailer

toEnd

@NotNull
@NotNull ExcerptTailer toEnd()

Moves the index for this Tailer to the end of the queue.

If the direction() == FORWARD, this will be the index position corresponding to one more than the last entry. Otherwise, the index will be the last excerpt.

This is not atomic with the appenders, in other words if a cycle has been added in the current millisecond, toEnd() may not see it, This is because for performance reasons, the queue.lastCycle() is cached, as finding the last cycle is expensive, it requires asking the directory for the Files.list() so, this cache is only refreshed if the call toEnd() is in a new millisecond. Hence, a whole milliseconds with of data could be added to the chronicle-queue that toEnd() won’t see. For appenders that are using the same queue instance ( and with then same JVM ), they can be informed that the last cycle has changed, this will yield better results, but atomicity can still not be guaranteed.

Returns:

this ExcerptTailer

striding

ExcerptTailer striding(boolean striding)

Sets the striding property of this Tailer.

When striding is enabled AND direction is BACKWARD, skip to the entries easiest to find, doesn't need to be every entry.

Parameters:

striding - skip to the indexStride if that is easy, doesn't always happen.

Returns:

this ExcerptTailer

striding

boolean striding()

Returns the striding property of this Tailer.

Returns:

the striding property of this Tailer

See Also:

striding(boolean)

direction

@NotNull
@NotNull ExcerptTailer direction(@NotNull
                                          @NotNull TailerDirection direction)

Sets the direction of this ExcerptTailer.

The direction determines the direction of movement upon reading an excerpt.

Parameters:

direction - which is either of NONE, FORWARD, BACKWARD

Returns:

this ExcerptTailer

Throws:

NullPointerException - if the provided direction is null

direction

TailerDirection direction()

Returns the direction of this ExcerptTailer.

The direction determines the direction of movement upon reading an excerpt.

Returns:

the direction of this ExcerptTailer

afterLastWritten

@NotNull
default @NotNull ExcerptTailer afterLastWritten(ChronicleQueue queue)

Winds this ExcerptTailer to after the last entry which wrote an entry to the queue.

Parameters:

queue - which was written to.

Returns:

this ExcerptTailer

Throws:

net.openhft.chronicle.core.io.IORuntimeException - if the provided queue couldn't be wound to the last index.

NullPointerException - if the provided queue is null

readAfterReplicaAcknowledged

default void readAfterReplicaAcknowledged(boolean readAfterReplicaAcknowledged)

Sets the Read After Replica Acknowledged property of this Tailer to the provided readAfterReplicaAcknowledged.

Enterprise Queue only: if replication enabled, setting this to true on a source queue ensures that this tailer will not read until at least one of the sinks has acknowledged receipt of the excerpt. This will block forever if no sinks acknowledge receipt.

Parameters:

readAfterReplicaAcknowledged - enable

acknowledgedIndexReplicatedCheck

default void acknowledgedIndexReplicatedCheck(ExcerptTailer.AcknowledgedIndexReplicatedCheck acknowledgedIndexReplicatedCheck)

Allows you to control the number of in flight messages that are allowed when setting acknowledgedIndexReplicatedCheck, By default, this is set to:

By providing a custom implementation of acknowledgedIndexReplicatedCheck you can control the number of in-flight messages that are allowed before the message is available to be read by the tailer. And in addition, then acknowledgedIndexReplicatedCheck will be set to true.

below is the default implementation:

 boolean acknowledgedIndexReplicatedCheck(long index, long lastSequenceAck) {
      return index == lastSequenceAck;
 }
 

With this default implementation it will ensure tailer will not be able to read a message until it has been acknowledged that it has been full replicated.

However, if you wish to tolerate a number of in-flight or pending messages before the message., You can set this to a different implementation. For example, if you wish to tolerate one unacknowledged message, set tolerateNumberOfUnAckedMessages to 1, as shown below:

 boolean acknowledgedIndexReplicatedCheck(long index, long lastSequenceAck) {
     int tolerateNumberOfUnAckedMessages = 1;
     return index <= lastSequenceAck + tolerateNumberOfUnAckedMessages;
 }
 

This feature is exclusive to Enterprise Queue and is disabled when accessing a queue file role. Specifically, it's unavailable when the in-flight message originated from a cycle other than the current one. For more information about cycles, see RollCycles and RollCycle.toCycle(long).

Parameters:

acknowledgedIndexReplicatedCheck - as a custom implementation of acknowledgedIndexReplicatedCheck

readAfterReplicaAcknowledged

default boolean readAfterReplicaAcknowledged()

Returns the Read After Replica Acknowledged property of this Tailer.

Enterprise Queue only: if replication enabled, setting this to true on a source queue ensures that this tailer will not read until at least one of the sinks has acknowledged receipt of the excerpt. This will block forever if no sinks acknowledge receipt.

Returns:

the Read After Replica Acknowledged property of this Tailer

approximateExcerptsInCycle

@Deprecated
default long approximateExcerptsInCycle(int cycle)

Deprecated. Use excerptsInCycle(int) instead

Returns a number of excerpts in a cycle. May use a fast path to return the cycle length cached in indexing, which is updated last during append operation so may be possible that a single entry is available for reading but not acknowledged by this method yet.

Calling this method may move ExcerptTailer to the specified cycle and release its store.

Returns:

the approximate number of excerpts in a cycle.

exactExcerptsInCycle

@Deprecated
default long exactExcerptsInCycle(int cycle)

Deprecated. Use excerptsInCycle(int) instead

Returns an exact number of excerpts in a cycle available for reading. This may be a computationally expensive operation.

Calling this method may move ExcerptTailer to the specified cycle and release its store.

Returns:

the exact number of excerpts in a cycle.

excerptsInCycle

default long excerptsInCycle(int cycle)

Return the exact number of excerpts in a cycle available for reading.

Calling this method may move ExcerptTailer to the specified cycle and release its store.

Returns:

the exact number of excerpts in a cycle.

state

@NotNull
@NotNull TailerState state()

Returns the TailerState of this Tailer.

Returns:

the TailerState of this Tailer

afterWrittenMessageAtIndex

@NotNull
default @NotNull ExcerptTailer afterWrittenMessageAtIndex(@NotNull
                                                                   @NotNull ChronicleQueue queue,
                                                                   long index)

Winds this ExcerptTailer to the specified index of the provided queue and reads the history message, then moves this tailer to the message index in the history message.

Parameters:

queue - The queue which was written to, and may contain a history message at the specified index. Must not be null.

index - The index to read the history message in the queue.

Returns:

This ExcerptTailer instance.

Throws:

net.openhft.chronicle.core.io.IORuntimeException - if the provided queue couldn't be wound to the last index.

NullPointerException - if the provided queue is null.