This is an automated email from the ASF dual-hosted git repository.
liuyu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/pulsar.git
The following commit(s) were added to refs/heads/master by this push:
new 21adedc [Doc] Add descriptions for C++ Client API doc
(ClientConfiguration.h + ConsumerConfiguration.h + ReaderConfiguration.h)
(#10103)
21adedc is described below
commit 21adedc3f57eaab23d4bce1dfd733ae93d7db22a
Author: Yu Liu <[email protected]>
AuthorDate: Fri Apr 2 17:42:40 2021 +0800
[Doc] Add descriptions for C++ Client API doc (ClientConfiguration.h +
ConsumerConfiguration.h + ReaderConfiguration.h) (#10103)
* [Doc] Add descriptions for C++ Client API doc
* update
* update
* update
Co-authored-by: Anonymitaet <anonymitaet_hotmail.com>
---
.../include/pulsar/ClientConfiguration.h | 68 ++++++++++-
.../include/pulsar/ConsumerConfiguration.h | 124 ++++++++++++++++++---
.../include/pulsar/ReaderConfiguration.h | 105 +++++++++++++++--
3 files changed, 269 insertions(+), 28 deletions(-)
diff --git a/pulsar-client-cpp/include/pulsar/ClientConfiguration.h
b/pulsar-client-cpp/include/pulsar/ClientConfiguration.h
index 11b4cd0..71717c2 100644
--- a/pulsar-client-cpp/include/pulsar/ClientConfiguration.h
+++ b/pulsar-client-cpp/include/pulsar/ClientConfiguration.h
@@ -142,29 +142,87 @@ class PULSAR_PUBLIC ClientConfiguration {
*/
ClientConfiguration& setLogger(LoggerFactory* loggerFactory);
+ /**
+ * Configure whether to use the TLS encryption on the connections.
+ *
+ * The default value is false.
+ *
+ * @param useTls
+ */
ClientConfiguration& setUseTls(bool useTls);
+
+ /**
+ * @return whether the TLS encryption is used on the connections
+ */
bool isUseTls() const;
+ /**
+ * Set the path to the trusted TLS certificate file.
+ *
+ * @param tlsTrustCertsFilePath
+ */
ClientConfiguration& setTlsTrustCertsFilePath(const std::string&
tlsTrustCertsFilePath);
+
+ /**
+ * @return the path to the trusted TLS certificate file
+ */
std::string getTlsTrustCertsFilePath() const;
+ /**
+ * Configure whether the Pulsar client accepts untrusted TLS certificates
from brokers.
+ *
+ * The default value is false.
+ *
+ * @param tlsAllowInsecureConnection
+ */
ClientConfiguration& setTlsAllowInsecureConnection(bool allowInsecure);
+
+ /**
+ * @return whether the Pulsar client accepts untrusted TLS certificates
from brokers
+ */
bool isTlsAllowInsecureConnection() const;
+ /**
+ * Configure whether it allows validating hostname verification when a
client connects to a broker over
+ * TLS.
+ *
+ * It validates the incoming x509 certificate and matches the provided
hostname (CN/SAN) with the
+ * expected broker's hostname. It follows the server identity hostname
verification in RFC 2818.
+ *
+ * The default value is false.
+ *
+ * @see [RFC 2818](https://tools.ietf.org/html/rfc2818).
+ *
+ * @param validateHostName whether to enable the TLS hostname verification
+ */
ClientConfiguration& setValidateHostName(bool validateHostName);
+
+ /**
+ * @return true if the TLS hostname verification is enabled
+ */
bool isValidateHostName() const;
+ /**
+ * Configure the listener name that the broker returns the corresponding
`advertisedListener`.
+ *
+ * @param name the listener name
+ */
ClientConfiguration& setListenerName(const std::string& listenerName);
+
+ /**
+ * @return the listener name for the broker
+ */
const std::string& getListenerName() const;
- /*
- * Initialize stats interval in seconds. Stats are printed and reset after
every 'statsIntervalInSeconds'.
- * Set to 0 in order to disable stats collection.
+ /**
+ * Initialize stats interval in seconds. Stats are printed and reset after
every `statsIntervalInSeconds`.
+ *
+ * Set to 0 means disabling stats collection.
*/
ClientConfiguration& setStatsIntervalInSeconds(const unsigned int&);
- /*
- * Get the stats interval set in the client.
+ /**
+ * @return the stats interval configured for the client
*/
const unsigned int& getStatsIntervalInSeconds() const;
diff --git a/pulsar-client-cpp/include/pulsar/ConsumerConfiguration.h
b/pulsar-client-cpp/include/pulsar/ConsumerConfiguration.h
index d472b63..5dc42a9 100644
--- a/pulsar-client-cpp/include/pulsar/ConsumerConfiguration.h
+++ b/pulsar-client-cpp/include/pulsar/ConsumerConfiguration.h
@@ -89,17 +89,25 @@ class PULSAR_PUBLIC ConsumerConfiguration {
* consumers will be promoted to primary and will start getting messages.
*/
ConsumerConfiguration& setConsumerType(ConsumerType consumerType);
+
+ /**
+ * @return the consumer type
+ */
ConsumerType getConsumerType() const;
/**
* Set KeyShared subscription policy for consumer.
*
- * <p>By default, KeyShared subscription use auto split hash range to
maintain consumers. If you want to
+ * By default, KeyShared subscription use auto split hash range to
maintain consumers. If you want to
* set a different KeyShared policy, you can set by following example:
*
* @param keySharedPolicy The {@link KeySharedPolicy} want to specify
*/
ConsumerConfiguration& setKeySharedPolicy(KeySharedPolicy keySharedPolicy);
+
+ /**
+ * @return the KeyShared subscription policy
+ */
KeySharedPolicy getKeySharedPolicy() const;
/**
@@ -108,37 +116,49 @@ class PULSAR_PUBLIC ConsumerConfiguration {
* for every message received.
*/
ConsumerConfiguration& setMessageListener(MessageListener messageListener);
+
+ /**
+ * @return the message listener
+ */
MessageListener getMessageListener() const;
+
+ /**
+ * @return true if the message listener has been set
+ */
bool hasMessageListener() const;
/**
* Sets the size of the consumer receive queue.
*
- * The consumer receive queue controls how many messages can be
accumulated by the Consumer before the
- * application calls receive(). Using a higher value could potentially
increase the consumer throughput
+ * The consumer receive queue controls how many messages can be
accumulated by the consumer before the
+ * application calls receive(). Using a higher value may potentially
increase the consumer throughput
* at the expense of bigger memory utilization.
*
- * Setting the consumer queue size as zero decreases the throughput of the
consumer, by disabling
+ * Setting the consumer queue size to 0 decreases the throughput of the
consumer by disabling
* pre-fetching of
- * messages. This approach improves the message distribution on shared
subscription, by pushing messages
+ * messages. This approach improves the message distribution on shared
subscription by pushing messages
* only to
- * the consumers that are ready to process them. Neither receive with
timeout nor Partitioned Topics can
+ * the consumers that are ready to process them. Neither receive with
timeout nor partitioned topics can
* be
- * used if the consumer queue size is zero. The receive() function call
should not be interrupted when
- * the consumer queue size is zero.
+ * used if the consumer queue size is 0. The receive() function call
should not be interrupted when
+ * the consumer queue size is 0.
*
- * Default value is 1000 messages and should be good for most use cases.
+ * The default value is 1000 messages and it is appropriate for the most
use cases.
+ *
+ * @param size the new receiver queue size value
*
- * @param size
- * the new receiver queue size value
*/
void setReceiverQueueSize(int size);
+
+ /**
+ * @return the receiver queue size
+ */
int getReceiverQueueSize() const;
/**
* Set the max total receiver queue size across partitons.
- * <p>
- * This setting will be used to reduce the receiver queue size for
individual partitions
+ *
+ * This setting is used to reduce the receiver queue size for individual
partitions
* {@link #setReceiverQueueSize(int)} if the total exceeds this value
(default: 50000).
*
* @param maxTotalReceiverQueueSizeAcrossPartitions
@@ -150,7 +170,16 @@ class PULSAR_PUBLIC ConsumerConfiguration {
*/
int getMaxTotalReceiverQueueSizeAcrossPartitions() const;
- void setConsumerName(const std::string&);
+ /**
+ * Set the consumer name.
+ *
+ * @param consumerName
+ */
+ void setConsumerName(const std::string& consumerName);
+
+ /**
+ * @return the consumer name
+ */
const std::string& getConsumerName() const;
/**
@@ -167,13 +196,27 @@ class PULSAR_PUBLIC ConsumerConfiguration {
*/
long getUnAckedMessagesTimeoutMs() const;
+ /**
+ * Set the tick duration time that defines the granularity of the
ack-timeout redelivery (in
+ * milliseconds).
+ *
+ * The default value is 1000, which means 1 second.
+ *
+ * Using a higher tick time reduces
+ * the memory overhead to track messages when the ack-timeout is set to a
bigger value.
+ *
+ * @param milliSeconds the tick duration time (in milliseconds)
+ */
void setTickDurationInMs(const uint64_t milliSeconds);
+ /**
+ * @return the tick duration time (in milliseconds)
+ */
long getTickDurationInMs() const;
/**
* Set the delay to wait before re-delivering messages that have failed to
be process.
- * <p>
+ *
* When application uses {@link Consumer#negativeAcknowledge(Message)},
the failed message
* will be redelivered after a fixed timeout. The default is 1 min.
*
@@ -235,14 +278,51 @@ class PULSAR_PUBLIC ConsumerConfiguration {
*/
long getBrokerConsumerStatsCacheTimeInMs() const;
+ /**
+ * @return true if encryption keys are added
+ */
bool isEncryptionEnabled() const;
+
+ /**
+ * @return the shared pointer to CryptoKeyReader.
+ */
const CryptoKeyReaderPtr getCryptoKeyReader() const;
+
+ /**
+ * Set the shared pointer to CryptoKeyReader.
+ *
+ * @param the shared pointer to CryptoKeyReader
+ */
ConsumerConfiguration& setCryptoKeyReader(CryptoKeyReaderPtr
cryptoKeyReader);
+ /**
+ * @return the ConsumerCryptoFailureAction
+ */
ConsumerCryptoFailureAction getCryptoFailureAction() const;
+
+ /**
+ * Set the ConsumerCryptoFailureAction.
+ */
ConsumerConfiguration& setCryptoFailureAction(ConsumerCryptoFailureAction
action);
+ /**
+ * @return true if readCompacted is enabled
+ */
bool isReadCompacted() const;
+
+ /**
+ * If enabled, the consumer reads messages from the compacted topics
rather than reading the full message
+ * backlog of the topic. This means that if the topic has been compacted,
the consumer only sees the
+ * latest value for each key in the topic, up until the point in the topic
message backlog that has been
+ * compacted. Beyond that point, message is sent as normal.
+ *
+ * `readCompacted` can only be enabled subscriptions to persistent topics,
which have a single active
+ * consumer (for example, failure or exclusive subscriptions). Attempting
to enable it on subscriptions to
+ * a non-persistent topics or on a shared subscription leads to the
subscription call failure.
+ *
+ * @param readCompacted
+ * whether to read from the compacted topic
+ */
void setReadCompacted(bool compacted);
/**
@@ -253,9 +333,23 @@ class PULSAR_PUBLIC ConsumerConfiguration {
* @param periodInSeconds period in seconds to do an auto discovery
*/
void setPatternAutoDiscoveryPeriod(int periodInSeconds);
+
+ /**
+ * @return the time duration for the PatternMultiTopicsConsumer performs a
pattern auto discovery
+ */
int getPatternAutoDiscoveryPeriod() const;
+ /**
+ * The default value is `InitialPositionLatest`.
+ *
+ * @param subscriptionInitialPosition the initial position at which to set
+ * the cursor when subscribing to the topic for the first time
+ */
void setSubscriptionInitialPosition(InitialPosition
subscriptionInitialPosition);
+
+ /**
+ * @return the configured `InitialPosition` for the consumer
+ */
InitialPosition getSubscriptionInitialPosition() const;
/**
diff --git a/pulsar-client-cpp/include/pulsar/ReaderConfiguration.h
b/pulsar-client-cpp/include/pulsar/ReaderConfiguration.h
index 96b36b6..3d0af20 100644
--- a/pulsar-client-cpp/include/pulsar/ReaderConfiguration.h
+++ b/pulsar-client-cpp/include/pulsar/ReaderConfiguration.h
@@ -71,47 +71,101 @@ class PULSAR_PUBLIC ReaderConfiguration {
* messages. A listener will be called in order for every message received.
*/
ReaderConfiguration& setReaderListener(ReaderListener listener);
+
+ /**
+ * @return the configured {@link ReaderListener} for the reader
+ */
ReaderListener getReaderListener() const;
+
+ /**
+ * @return true if {@link ReaderListener} has been set
+ */
bool hasReaderListener() const;
/**
* Sets the size of the reader receive queue.
*
- * The consumer receive queue controls how many messages can be
accumulated by the Consumer before the
- * application calls receive(). Using a higher value could potentially
increase the consumer throughput
+ * The consumer receive queue controls how many messages can be
accumulated by the consumer before the
+ * application calls receive(). Using a higher value may potentially
increase the consumer throughput
* at the expense of bigger memory utilization.
*
- * Setting the consumer queue size as zero decreases the throughput of the
consumer, by disabling
+ * Setting the consumer queue size to 0 decreases the throughput of the
consumer by disabling
* pre-fetching of
- * messages. This approach improves the message distribution on shared
subscription, by pushing messages
+ * messages. This approach improves the message distribution on shared
subscription by pushing messages
* only to
- * the consumers that are ready to process them. Neither receive with
timeout nor Partitioned Topics can
+ * the consumers that are ready to process them. Neither receive with
timeout nor partitioned topics can
* be
- * used if the consumer queue size is zero. The receive() function call
should not be interrupted when
- * the consumer queue size is zero.
+ * used if the consumer queue size is 0. The receive() function call
should not be interrupted when
+ * the consumer queue size is 0.
*
- * Default value is 1000 messages and should be good for most use cases.
+ * The default value is 1000 messages and it is appropriate for most use
cases.
*
* @param size
* the new receiver queue size value
*/
void setReceiverQueueSize(int size);
+
+ /**
+ * @return the receiver queue size
+ */
int getReceiverQueueSize() const;
+ /**
+ * Set the reader name.
+ *
+ * @param readerName
+ */
void setReaderName(const std::string& readerName);
+
+ /**
+ * @return the reader name
+ */
const std::string& getReaderName() const;
+ /**
+ * Set the subscription role prefix.
+ *
+ * The default prefix is an empty string.
+ *
+ * @param subscriptionRolePrefix
+ */
void setSubscriptionRolePrefix(const std::string& subscriptionRolePrefix);
+
+ /**
+ * @return the subscription role prefix
+ */
const std::string& getSubscriptionRolePrefix() const;
+ /**
+ * If enabled, the consumer reads messages from the compacted topics
rather than reading the full message
+ * backlog of the topic. This means that if the topic has been compacted,
the consumer only sees the
+ * latest value for each key in the topic, up until the point in the topic
message backlog that has been
+ * compacted. Beyond that point, message is sent as normal.
+ *
+ * readCompacted can only be enabled subscriptions to persistent topics,
which have a single active
+ * consumer (for example, failure or exclusive subscriptions). Attempting
to enable it on subscriptions to
+ * a non-persistent topics or on a shared subscription leads to the
subscription call failure.
+ *
+ * @param readCompacted
+ * whether to read from the compacted topic
+ */
void setReadCompacted(bool compacted);
+
+ /**
+ * @return true if readCompacted is enabled
+ */
bool isReadCompacted() const;
/**
* Set the internal subscription name.
+ *
* @param internal subscriptionName
*/
void setInternalSubscriptionName(std::string internalSubscriptionName);
+
+ /**
+ * @return the internal subscription name
+ */
const std::string& getInternalSubscriptionName() const;
/**
@@ -128,8 +182,23 @@ class PULSAR_PUBLIC ReaderConfiguration {
*/
long getUnAckedMessagesTimeoutMs() const;
+ /**
+ * Set the tick duration time that defines the granularity of the
ack-timeout redelivery (in
+ * milliseconds).
+ *
+ * The default value is 1000, which means 1 second.
+ *
+ * Using a higher tick time
+ * reduces the memory overhead to track messages when the ack-timeout is
set to a bigger value.
+ *
+ * @param milliSeconds the tick duration time (in milliseconds)
+ *
+ */
void setTickDurationInMs(const uint64_t milliSeconds);
+ /**
+ * @return the tick duration time (in milliseconds)
+ */
long getTickDurationInMs() const;
/**
@@ -164,11 +233,31 @@ class PULSAR_PUBLIC ReaderConfiguration {
*/
long getAckGroupingMaxSize() const;
+ /**
+ * @return true if encryption keys are added
+ */
bool isEncryptionEnabled() const;
+
+ /**
+ * @return the shared pointer to CryptoKeyReader
+ */
const CryptoKeyReaderPtr getCryptoKeyReader() const;
+
+ /**
+ * Set the shared pointer to CryptoKeyReader.
+ *
+ * @param the shared pointer to CryptoKeyReader
+ */
ReaderConfiguration& setCryptoKeyReader(CryptoKeyReaderPtr
cryptoKeyReader);
+ /**
+ * @return the ConsumerCryptoFailureAction
+ */
ConsumerCryptoFailureAction getCryptoFailureAction() const;
+
+ /**
+ * Set the CryptoFailureAction for the reader.
+ */
ReaderConfiguration& setCryptoFailureAction(ConsumerCryptoFailureAction
action);
/**
