Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add warning about use of returnImmediately=true #354

Merged
merged 2 commits into from
Mar 5, 2021
Merged

Add warning about use of returnImmediately=true #354

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3285976
Add warning about use of `returnImmediately=true`
meltsufin Mar 5, 2021
a529149
reword warning
meltsufin Mar 5, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docs/src/main/asciidoc/pubsub.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -219,6 +219,10 @@ h|pullNext | Allows for a single message to be pulled and automatically acknowle
h|pullAndConvert | Works the same as the `pull` method and, additionally, converts the Pub/Sub binary payload to an object of the desired type, using the converter configured in the template.
|===

WARNING: We do not recommend setting `returnImmediately` to `true`, as it may result in delayed message delivery.
"Immediately" really means 1 second, and if Pub/Sub cannot retrieve any messages from the backend in that time, it will return 0 messages, despite having messages queue up on the topic.
Therefore, we recommend setting `returnImmediately` to `false`, or using `subscribe` methods from the previous section.

===== Acknowledging messages

There are two ways to acknowledge messages.
Expand Down
18 changes: 12 additions & 6 deletions .../main/java/com/google/cloud/spring/pubsub/core/subscriber/PubSubSubscriberOperations.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,8 @@ <T> Subscriber subscribeAndConvert(String subscription,
* @param maxMessages the maximum number of pulled messages. If this value is null then
* up to Integer.MAX_VALUE messages will be requested.
* @param returnImmediately returns immediately even if subscription doesn't contain enough
* messages to satisfy {@code maxMessages}
* messages to satisfy {@code maxMessages}.
* Setting this parameter to {@code true} is not recommended as it may result in long delays in message delivery.
* @return the list of received messages
*/
List<PubsubMessage> pullAndAck(String subscription, Integer maxMessages, Boolean returnImmediately);
Expand All @@ -88,7 +89,8 @@ <T> Subscriber subscribeAndConvert(String subscription,
* @param maxMessages the maximum number of pulled messages. If this value is null then
* up to Integer.MAX_VALUE messages will be requested.
* @param returnImmediately returns immediately even if subscription doesn't contain enough
* messages to satisfy {@code maxMessages}
* messages to satisfy {@code maxMessages}.
* Setting this parameter to {@code true} is not recommended as it may result in long delays in message delivery.
* @return the ListenableFuture for the asynchronous execution, returning the list of
* received acknowledgeable messages
* @since 1.2.3
Expand All @@ -102,7 +104,8 @@ <T> Subscriber subscribeAndConvert(String subscription,
* @param maxMessages the maximum number of pulled messages. If this value is null then
* up to Integer.MAX_VALUE messages will be requested.
* @param returnImmediately returns immediately even if subscription doesn't contain enough
* messages to satisfy {@code maxMessages}
* messages to satisfy {@code maxMessages}.
* Setting this parameter to {@code true} is not recommended as it may result in long delays in message delivery.
* @return the list of received acknowledgeable messages
*/
List<AcknowledgeablePubsubMessage> pull(String subscription, Integer maxMessages, Boolean returnImmediately);
Expand All @@ -114,7 +117,8 @@ <T> Subscriber subscribeAndConvert(String subscription,
* @param maxMessages the maximum number of pulled messages. If this value is null then
* up to Integer.MAX_VALUE messages will be requested.
* @param returnImmediately returns immediately even if subscription doesn't contain enough
* messages to satisfy {@code maxMessages}
* messages to satisfy {@code maxMessages}.
* Setting this parameter to {@code true} is not recommended as it may result in long delays in message delivery.
* @return the ListenableFuture for the asynchronous execution, returning the list of
* received acknowledgeable messages
* @since 1.2.3
Expand All @@ -129,7 +133,8 @@ <T> Subscriber subscribeAndConvert(String subscription,
* @param maxMessages the maximum number of pulled messages. If this value is null then
* up to Integer.MAX_VALUE messages will be requested.
* @param returnImmediately returns immediately even if subscription doesn't contain enough
* messages to satisfy {@code maxMessages}
* messages to satisfy {@code maxMessages}.
* Setting this parameter to {@code true} is not recommended as it may result in long delays in message delivery.
* @param payloadType the type to which the payload of the Pub/Sub messages should be converted
* @param <T> the type of the payload
* @return the list of received acknowledgeable messages
Expand All @@ -146,7 +151,8 @@ <T> List<ConvertedAcknowledgeablePubsubMessage<T>> pullAndConvert(String subscri
* @param maxMessages the maximum number of pulled messages. If this value is null then
* up to Integer.MAX_VALUE messages will be requested.
* @param returnImmediately returns immediately even if subscription doesn't contain enough
* messages to satisfy {@code maxMessages}
* messages to satisfy {@code maxMessages}.
* Setting this parameter to {@code true} is not recommended as it may result in long delays in message delivery.
* @param payloadType the type to which the payload of the Pub/Sub messages should be converted
* @param <T> the type of the payload
* @return the ListenableFuture for the asynchronous execution, returning the list of
Expand Down
3 changes: 2 additions & 1 deletion ...ud-gcp-pubsub/src/main/java/com/google/cloud/spring/pubsub/support/SubscriberFactory.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,8 @@ public interface SubscriberFactory {
* @param maxMessages the maximum number of pulled messages; must be greater than zero.
* If null is passed in, then up to Integer.MAX_VALUE messages will be requested.
* @param returnImmediately causes the pull request to return immediately even
* if subscription doesn't contain enough messages to satisfy {@code maxMessages}
* if subscription doesn't contain enough messages to satisfy {@code maxMessages}.
* Setting this parameter to {@code true} is not recommended as it may result in long delays in message delivery.
* @return the pull request that can be executed using a {@link SubscriberStub}
*/
PullRequest createPullRequest(String subscriptionName, Integer maxMessages,
Expand Down