public interface Consumer
extends java.lang.AutoCloseable
The Consumer interface only exposes the Channel methods to consume records. It does not expose
methods to produce records. Objects complying with Consumer interface are instantiated using
ConsumerBuilder which implements a build pattern for Consumer.
Consumer is easier to use than Channel when you only need to consume records and not to produce
them. Benefits are:
Channel
produce operations (e.g.: producerPathPrefix)
- a slim set of operations to consume only. Produce operations are not exposed, then it is not possible to call them
by accident.| Modifier and Type | Method and Description |
|---|---|
void |
close()
Closes the channel.
|
void |
commit()
Commits the record offsets to the channel.
|
ConsumerRecords |
consume()
Consumes records from all the subscribed topics
|
ConsumerRecords |
consume(int timeout)
Consumes records from all the subscribed topics
|
void |
create()
Creates a new consumer on the consumer group specified by
ConsumerBuilder.ConsumerBuilder(String, ChannelAuth, String)} at construction time. |
void |
delete()
Deletes the consumer from the consumer group
|
void |
run(ConsumerRecordProcessor processCallback,
java.util.List<java.lang.String> topics)
Repeatedly consume records from the subscribed topics.
|
void |
run(ConsumerRecordProcessor processCallback,
java.util.List<java.lang.String> topics,
int timeout)
Repeatedly consume records from the subscribed topics.
|
void |
run(ConsumerRecordProcessor processCallback,
java.lang.String topic)
Repeatedly consume records from the subscribed topic.
|
void |
run(ConsumerRecordProcessor processCallback,
java.lang.String topic,
int timeout)
Repeatedly consume records from the subscribed topic.
|
void |
stop()
Stop an active execution of the
Channel.run(ConsumerRecordProcessor, List) call. |
void |
subscribe(java.util.List<java.lang.String> topics)
Subscribes the consumer to a list of topics
|
java.util.List<java.lang.String> |
subscriptions()
List the topic names to which the consumer is subscribed
|
void create()
throws PermanentError,
TemporaryError
Creates a new consumer on the consumer group specified by
ConsumerBuilder.ConsumerBuilder(String, ChannelAuth, String)} at construction time.
PermanentError - if no consumer group was specified.TemporaryError - if the creation attempt fails.void subscribe(java.util.List<java.lang.String> topics)
throws ConsumerError,
PermanentError,
TemporaryError
Subscribes the consumer to a list of topics
topics - Topic list.ConsumerError - if the consumer associated with the channel does not exist on the server.PermanentError - if no topics were specified.TemporaryError - if the subscription attempt fails.java.util.List<java.lang.String> subscriptions()
throws ConsumerError,
PermanentError,
TemporaryError
List the topic names to which the consumer is subscribed
ConsumerError - if the consumer associated with the channel does not exist on the server.TemporaryError - if the retrieval of subscriptions fails.PermanentError - if request was malformed.void delete()
throws TemporaryError,
PermanentError
Deletes the consumer from the consumer group
TemporaryError - if the delete attempt fails.PermanentError - if request was malformed.ConsumerRecords consume() throws ConsumerError, PermanentError, TemporaryError
Consumes records from all the subscribed topics
ConsumerRecords a list of the consumer record objects from the records returned by the server.ConsumerError - if the consumer associated with the channel does not exist on the server.PermanentError - if the channel has not been subscribed to any topics.TemporaryError - if the consume attempt fails.ConsumerRecords consume(int timeout) throws ConsumerError, PermanentError, TemporaryError
Consumes records from all the subscribed topics
timeout - Timeout in milliseconds to wait for records before returningConsumerRecords a list of the consumer record objects from the records returned by the server.ConsumerError - if the consumer associated with the channel does not exist on the server.PermanentError - if the channel has not been subscribed to any topics.TemporaryError - if the consume attempt fails.void commit()
throws ConsumerError,
TemporaryError,
PermanentError
Commits the record offsets to the channel.
Committed offsets are the latest consumed ones on all consumed topics and partitions.
ConsumerError - if the consumer associated with the channel does not exist on the server.TemporaryError - if the commit attempt fails.PermanentError - if request was malformed.void run(ConsumerRecordProcessor processCallback, java.util.List<java.lang.String> topics) throws PermanentError, TemporaryError
Repeatedly consume records from the subscribed topics.
The supplied
ConsumerRecordProcessor.processCallback(ConsumerRecords, String) method is invoked with a list containing
each consumer record.
ConsumerRecordProcessor.processCallback(ConsumerRecords, String) return value is currently
ignored. It is reserved for future use.
The Channel.stop() method can also be called to halt an execution of this method.
processCallback - Callable which is invoked with a list of records which have been consumed.topics - If set to a non-empty value, the channel will be subscribed to the specified topics.
If set to an empty value, the channel will use topics previously subscribed via a call to the
subscribe method.PermanentError - if a prior run is already in progress or no consumer group value was specified or
callback to deliver records was not specifiedTemporaryError - consume or commit attempts failed with errors other than ConsumerError.void run(ConsumerRecordProcessor processCallback, java.util.List<java.lang.String> topics, int timeout) throws PermanentError, TemporaryError
Repeatedly consume records from the subscribed topics.
The supplied
ConsumerRecordProcessor.processCallback(ConsumerRecords, String) method is invoked with a list containing
each consumer record.
ConsumerRecordProcessor.processCallback(ConsumerRecords, String) return value is currently
ignored. It is reserved for future use.
The Channel.stop() method can also be called to halt an execution of this method.
processCallback - Callable which is invoked with a list of records which have been consumed.topics - If set to a non-empty value, the channel will be subscribed to the specified topics.
If set to an empty value, the channel will use topics previously subscribed via a call to the
subscribe method.timeout - Timeout in milliseconds to wait for records before returningPermanentError - if a prior run is already in progress or no consumer group value was specified or
callback to deliver records was not specifiedTemporaryError - consume or commit attempts failed with errors other than ConsumerError.void run(ConsumerRecordProcessor processCallback, java.lang.String topic) throws PermanentError, TemporaryError
Repeatedly consume records from the subscribed topic.
The supplied
ConsumerRecordProcessor.processCallback(ConsumerRecords, String) method is invoked with a list containing
each consumer record.
ConsumerRecordProcessor.processCallback(ConsumerRecords, String) return value is currently
ignored. It is reserved for future use.
The Channel.stop() method can also be called to halt an execution of this method.
processCallback - Callable which is invoked with a list of records which have been consumed.topic - If set to a non-empty value, the channel will be subscribed to the specified topic.
If set to an empty value, the channel will use topics previously subscribed via a call to the
subscribe method.PermanentError - if a prior run is already in progress or no consumer group value was specified or
callback to deliver records was not specifiedTemporaryError - consume or commit attempts failed with errors other than ConsumerError.void run(ConsumerRecordProcessor processCallback, java.lang.String topic, int timeout) throws PermanentError, TemporaryError
Repeatedly consume records from the subscribed topic.
The supplied
ConsumerRecordProcessor.processCallback(ConsumerRecords, String) method is invoked with a list containing
each consumer record.
ConsumerRecordProcessor.processCallback(ConsumerRecords, String) return value is currently
ignored. It is reserved for future use.
The Channel.stop() method can also be called to halt an execution of this method.
processCallback - Callable which is invoked with a list of records which have been consumed.topic - If set to a non-empty value, the channel will be subscribed to the specified topic.
If set to an empty value, the channel will use topics previously subscribed via a call to the
subscribe method.timeout - Timeout in milliseconds to wait for records before returningPermanentError - if a prior run is already in progress or no consumer group value was specified or
callback to deliver records was not specifiedTemporaryError - consume or commit attempts failed with errors other than ConsumerError.void stop() throws StopError
Stop an active execution of the Channel.run(ConsumerRecordProcessor, List) call.
If no Channel.run(ConsumerRecordProcessor, List) call is active, this function returns
immediately. If a Channel.run(ConsumerRecordProcessor, List) call is active, this function blocks
until the run has been completed.
StopError - an error occurred while waiting for channel to be stoppedvoid close()
throws TemporaryError,
StopError,
PermanentError
Closes the channel.
It calls Channel.destroy() to stop the channel and to release its resources.
This method is added to allow Channel to be used in conjunction with Java try-with-resources statement.
close in interface java.lang.AutoCloseableTemporaryError - if a consumer has previously been created for the channel but an attempt to delete the
consumer from the channel fails.StopError - if the attempt to stop the channel fails.PermanentError