com.opendxl.streaming.client

Interface Consumer

All Superinterfaces:

java.lang.AutoCloseable

All Known Implementing Classes:

Channel

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:

- a simplified instance creation because it is not necessary to provide parameters required by 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.

Method Summary

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

Method Detail

create

void create()
     throws PermanentError,
            TemporaryError

Creates a new consumer on the consumer group specified by ConsumerBuilder.ConsumerBuilder(String, ChannelAuth, String)} at construction time.

Throws:

PermanentError - if no consumer group was specified.

TemporaryError - if the creation attempt fails.

subscribe

void subscribe(java.util.List<java.lang.String> topics)
        throws ConsumerError,
               PermanentError,
               TemporaryError

Subscribes the consumer to a list of topics

Parameters:

topics - Topic list.

Throws:

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.

subscriptions

java.util.List<java.lang.String> subscriptions()
                                        throws ConsumerError,
                                               PermanentError,
                                               TemporaryError

List the topic names to which the consumer is subscribed

Returns:

List of topic names

Throws:

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.

delete

void delete()
     throws TemporaryError,
            PermanentError

Deletes the consumer from the consumer group

Throws:

TemporaryError - if the delete attempt fails.

PermanentError - if request was malformed.

consume

ConsumerRecords consume()
                 throws ConsumerError,
                        PermanentError,
                        TemporaryError

Consumes records from all the subscribed topics

Returns:

ConsumerRecords a list of the consumer record objects from the records returned by the server.

Throws:

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.

consume

ConsumerRecords consume(int timeout)
                 throws ConsumerError,
                        PermanentError,
                        TemporaryError

Consumes records from all the subscribed topics

Parameters:

timeout - Timeout in milliseconds to wait for records before returning

Returns:

ConsumerRecords a list of the consumer record objects from the records returned by the server.

Throws:

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.

commit

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.

Throws:

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.

run

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.

Parameters:

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.

Throws:

PermanentError - if a prior run is already in progress or no consumer group value was specified or callback to deliver records was not specified

TemporaryError - consume or commit attempts failed with errors other than ConsumerError.

run

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.

Parameters:

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 returning

Throws:

PermanentError - if a prior run is already in progress or no consumer group value was specified or callback to deliver records was not specified

TemporaryError - consume or commit attempts failed with errors other than ConsumerError.

run

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.

Parameters:

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.

Throws:

PermanentError - if a prior run is already in progress or no consumer group value was specified or callback to deliver records was not specified

TemporaryError - consume or commit attempts failed with errors other than ConsumerError.

run

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.

Parameters:

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 returning

Throws:

PermanentError - if a prior run is already in progress or no consumer group value was specified or callback to deliver records was not specified

TemporaryError - consume or commit attempts failed with errors other than ConsumerError.

stop

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.

Throws:

StopError - an error occurred while waiting for channel to be stopped

close

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

Specified by:

close in interface java.lang.AutoCloseable

Throws:

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