Package io.pravega.client.stream

Interface EventStreamWriter<Type>

Type Parameters:

Type - The type of events that go in this stream

All Superinterfaces:

java.lang.AutoCloseable

public interface EventStreamWriter<Type>
extends java.lang.AutoCloseable

A writer can write events to a stream. This class is safe to use across threads, but doing so will not increase performance.

Method Summary

Modifier and Type	Method	Description
void	close()	Calls flush and then closes the writer.
void	flush()	Block until all events that have been passed to writeEvent's corresponding futures have completed.
EventWriterConfig	getConfig()	Returns the configuration that this writer was create with.
void	noteTime(long timestamp)	Notes a time that can be seen by readers which read from this stream by EventStreamReader.getCurrentTimeWindow(Stream).
java.util.concurrent.CompletableFuture<java.lang.Void>	writeEvent(java.lang.String routingKey, Type event)	Write an event to the stream.
java.util.concurrent.CompletableFuture<java.lang.Void>	writeEvent(Type event)	Send an event to the stream.
java.util.concurrent.CompletableFuture<java.lang.Void>	writeEvents(java.lang.String routingKey, java.util.List<Type> events)	Write an ordered list of events to the stream atomically for a given routing key.

Method Detail

writeEvent

java.util.concurrent.CompletableFuture<java.lang.Void> writeEvent(Type event)

Send an event to the stream. Events that are written should appear in the stream exactly once. The maximum size of the serialized event supported is defined at Serializer.MAX_EVENT_SIZE. Note that the implementation provides retry logic to handle connection failures and service host failures. The number of retries is as specified in EventWriterConfig.getRetryAttempts(). Internal retries will not violate the exactly once semantic so it is better to rely on them than to wrap this with custom retry logic. If all the retries fail the returned completableFuture(s) will we completed with a RetriesExhaustedException post which no new writes can happen with this writer.

Parameters:

event - The event to be written to the stream (Null is disallowed)

Returns:

A completableFuture that will complete when the event has been durably stored on the configured number of replicas, and is available for readers to see. This future may complete exceptionally if this cannot happen, however these exceptions are not transient failures. Failures that occur as a result of connection drops or host death are handled internally with multiple retires and exponential backoff. So there is no need to attempt to retry in the event of an exception.

writeEvent

java.util.concurrent.CompletableFuture<java.lang.Void> writeEvent(java.lang.String routingKey,
                                                                  Type event)

Write an event to the stream. Similar to writeEvent(Object) but provides a routingKey which is used to specify ordering. Events written with the same routing key will be read by readers in exactly the same order they were written. The maximum size of the serialized event supported is defined at Serializer.MAX_EVENT_SIZE. Note that the implementation provides retry logic to handle connection failures and service host failures. The number of retries is as specified in EventWriterConfig.getRetryAttempts(). Internal retries will not violate the exactly once semantic so it is better to rely on this than to wrap this method with custom retry logic. If all the retries fail the returned completableFuture(s) will we completed with a RetriesExhaustedException post which no new writes can happen with this writer.

Parameters:

routingKey - A free form string that is used to route messages to readers. Two events written with the same routingKey are guaranteed to be read in order. Two events with different routing keys may be read in parallel.

event - The event to be written to the stream (Null is disallowed)

Returns:

A completableFuture that will complete when the event has been durably stored on the configured number of replicas, and is available for readers to see. This future may complete exceptionally if this cannot happen, however these exceptions are not transient failures. Failures that occur as a result of connection drops or host death are handled internally with multiple retires and exponential backoff. So there is no need to attempt to retry in the event of an exception.

writeEvents

java.util.concurrent.CompletableFuture<java.lang.Void> writeEvents(java.lang.String routingKey,
                                                                   java.util.List<Type> events)

Write an ordered list of events to the stream atomically for a given routing key. Events written with the same routing key will be read by readers in exactly the same order they were written. The maximum size of the serialized event individually should be Serializer.MAX_EVENT_SIZE and the collective batch should be less than twice the Serializer.MAX_EVENT_SIZE. Note that the implementation provides retry logic to handle connection failures and service host failures. The number of retries is as specified in EventWriterConfig.getRetryAttempts(). Internal retries will not violate the exactly once semantic so it is better to rely on this than to wrap this method with custom retry logic. If all the retries fail the returned completableFuture(s) will we completed with a RetriesExhaustedException post which no new writes can happen with this writer.

Parameters:

routingKey - A free form string that is used to route messages to readers. Two events written with the same routingKey are guaranteed to be read in order. Two events with different routing keys may be read in parallel.

events - The batch of events to be written to the stream (Null is disallowed)

Returns:

A completableFuture that will complete when the event has been durably stored on the configured number of replicas, and is available for readers to see. This future may complete exceptionally if this cannot happen, however these exceptions are not transient failures. Failures that occur as a result of connection drops or host death are handled internally with multiple retires and exponential backoff. So there is no need to attempt to retry in the event of an exception.

noteTime

void noteTime(long timestamp)

Notes a time that can be seen by readers which read from this stream by EventStreamReader.getCurrentTimeWindow(Stream). The semantics or meaning of the timestamp is left to the application. Readers might expect timestamps to be monotonic. So this is recommended but not enforced. There is no requirement to call this method. Never doing so will result in readers invoking EventStreamReader.getCurrentTimeWindow(Stream) receiving a null for both upper and lower times. Calling this method can be automated by setting EventWriterConfig.EventWriterConfigBuilder.automaticallyNoteTime(boolean) to true when creating a writer.

Parameters:

timestamp - a timestamp (in milliseconds) that represents the current location in the stream.

getConfig

EventWriterConfig getConfig()

Returns the configuration that this writer was create with.

Returns:

Writer configuration

flush

void flush()

Block until all events that have been passed to writeEvent's corresponding futures have completed. This method will throw a RetriesExhaustedException if all internal retries fail.

close

void close()

Calls flush and then closes the writer. (No further methods may be called)

Specified by:

close in interface java.lang.AutoCloseable