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

Field Summary

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

MARSHALLABLE_IN_INTERN_SIZE

Method Summary

Modifier and Type	Method and Description
@NotNull ExcerptTailer	afterLastWritten(ChronicleQueue queue) Winds this ExcerptTailer to after the last entry which wrote an entry to the queue.
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 @NotNull ExcerptTailer	disableThreadSafetyCheck(boolean disableThreadSafetyCheck) When set to true this Appender or Tailer can be shared between thread provided you ensure they used in a thread safe manner.
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	peekDocument() Deprecated.
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

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

close, closeQuietly, closeQuietly, notifyClosing, warnAndCloseIfNotClosed

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

isClosed, isClosing, throwExceptionIfClosed

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 meta data aware.

Returns:

the document context

peekDocument

@Deprecated
default boolean peekDocument()

Deprecated.

Returns true if readingDocument() would return a document which is present, in other words would return a DocumentContext where DocumentContext.isPresent() == true For the best performance you should only use this method once a message has been found by toStart() or readingDocument(). Otherwise readingDocument() is called and then rolled back, which is not optimal. For the same reason, this method should also be avoided when reading documents backwards. WARNING : THIS METHOD CAN NOT BE RELIED UPON, IT WILL SOMETIME WILL RETURN FALSE WHEN THERE ARE MESSAGES, YOU SHOULD ONLY CALL IT PERIODICALLY AND NOT RELY TO MUCH UPON ITS RESULTS INSTEAD CALL READING DOCUMENT ! ( FOR THIS REASON - WE HAVE DECIDED TO DEPRECATE IT ! )

Specified by:

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

Returns:

if readingDocument() would return a DocumentContext that provides excerpts to read.

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 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 provide 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
@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

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

state

@NotNull
@NotNull TailerState state()

Returns the TailerState of this Tailer.

Returns:

the TailerState of this Tailer

disableThreadSafetyCheck

@NotNull
default @NotNull ExcerptTailer disableThreadSafetyCheck(boolean disableThreadSafetyCheck)

Description copied from interface: ExcerptCommon

When set to true this Appender or Tailer can be shared between thread provided you ensure they used in a thread safe manner.

Specified by:

disableThreadSafetyCheck in interface ExcerptCommon<ExcerptTailer>

Parameters:

disableThreadSafetyCheck - true to turn off the thread safety check

Returns:

this.