[doc][broker]PIP-187 Make FilterResult#RESCHEDULE to deprecated

[poorbarcode]

Motivation

FilterResult.RESCHEDULE is a beta API, may be risky in the following scenarios:

• Use subscription type: Shared: consumer_1 can consume 60% of the messages, and consumer_2 can consume 60% of the messages, so there is 10% intersection between consumer_1 and consumer_2. If returns FilterResult.RESCHEDULE for more than 10% of messages, then it's possible: some message that can only be consumed by consumer_1 keeps redelivered to consumer_2, and some message that can only be consumed by consumer_2 keeps redelivered to consumer_1. Then these messages can not be consumed anymore for a long time.
  • [fix][broker]Can't consume messages for a long time due to Entry Filter #17782 fixed this problem.
• Use subscription type: Shared: consumer_1 can consume 40% of the messages, consumer_2 can consume 40% of the messages, and no consumer can consume the remaining 20%. If this 20% of the messages always return FilterResult.RESCHEDULE, this will cause that part of the message to always be redelivered and never consumed.
• Use subscription type: Key_Shared/Exclusive/Failover: This API cannot be used because there is no spare consumer to consume the redelivered message.

Modifications

Suggestion solution

Make FilterResult.RESCHEDULE to deprecated to avoid user use.

Other solution

Provide two strategies for messages that cannot be consumed:

• Drop the message or push it into DLQ
• Choose any consumer to receive

Why not choose this solution?

Because we can create a new subscription to achieve the same effect instead use FilterResult.RESCHEDULE.

Documentation

• doc-required
  (Your PR needs to update docs and you will update later)

• doc-not-needed
  (Please explain why)

• doc
  (Your PR contains doc changes)

• doc-complete
  (Docs have been already added)

Matching PR in forked repository

PR in forked repository:

• [run-ci][doc][broker]PIP-187 Make FilterResult#RESCHEDULE to deprecated poorbarcode/pulsar#9

[poorbarcode]

This PR should merge into the following branches:

• master
• brnach-2.11

[poorbarcode]

Hi @eolivelli could you take a look? Thanks

[eolivelli]

I don't agree.

RESCHEDULE has its own purpose and it works.
https://github.com/datastax/pulsar-jms/blob/master/pulsar-jms-filters/src/main/java/com/datastax/oss/pulsar/jms/selectors/JMSFilter.java#L91

it is also useful when the filter has a temporary error, like here

For instance I am using in on the JMS Filter
https://github.com/datastax/pulsar-jms/blob/master/pulsar-jms-filters/src/main/java/com/datastax/oss/pulsar/jms/selectors/JMSFilter.java#L111

this is not a BETA API.

if you want to deprecate it then please propose something else that covers these needs.

It would be great to have a mechanism to "select" the Consumers and do not let the message arrive to the filter in case that the "Wrong consumer" was picked up.

in any case we need some "TEMPORARY_ERROR" outcome for the filter, to allow the filter to postpone the processing when it cannot fail or accept a message

[poorbarcode]

Hi @eolivelli

in any case we need some "TEMPORARY_ERROR" outcome for the filter, to allow the filter to postpone the processing when it cannot fail or accept a message

make sense