Add the documentation for ReliableMessageListener [API-2182]

[ihsandemir]

Added the documentation section to describe the ReliableTopic ReliableMessageListener interface and capabilities.

[netlify]

✅ Deploy Preview for hardcore-allen-f5257d ready!

Name	Link
🔨 Latest commit	76aadeb
🔍 Latest deploy log	https://app.netlify.com/sites/hardcore-allen-f5257d/deploys/65967cfc888a470008432c72
😎 Deploy Preview	https://deploy-preview-941--hardcore-allen-f5257d.netlify.app/hazelcast/5.4-snapshot/events/object-events
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[srknzl]

I feel like we should somehow give a link to the source code after all this nitty gritty details. (due to references of methods) You can even copy the interface and paste it in the documentation

[ihsandemir]

I feel like we should somehow give a link to the source code after all this nitty gritty details. (due to references of methods) You can even copy the interface and paste it in the documentation

Added link at commit 0efad8f

[Serdaro]

@ihsandemir , two things I'd like to get your opinion:

• When it comes to listeners, we are explaining them under https://docs.hazelcast.com/hazelcast/5.3/events/distributed-events. For example, for Topics you can see it at https://docs.hazelcast.com/hazelcast/5.3/events/object-events#listening-for-topic-messages. Do you think it'd be more convenient to move this section to the "Listening to Events" section, and mention about the reliable message listener under the Reliable Topic section with a link?
• As per the support ticket linked in API-2182, I get the feeling that "callback on canceling the listeners" topic should be highlighted. Do you think the new content in this PR covers this topic well?

[ihsandemir]

@ihsandemir , two things I'd like to get your opinion:

• When it comes to listeners, we are explaining them under https://docs.hazelcast.com/hazelcast/5.3/events/distributed-events. For example, for Topics you can see it at https://docs.hazelcast.com/hazelcast/5.3/events/object-events#listening-for-topic-messages. Do you think it'd be more convenient to move this section to the "Listening to Events" section, and mention about the reliable message listener under the Reliable Topic section with a link?
• As per the support ticket linked in API-2182, I get the feeling that "callback on canceling the listeners" topic should be highlighted. Do you think the new content in this PR covers this topic well?

@Serdaro Yes, definitely we can move the content to that section. Naturally, I was thinking that it needs to be under associated data structure but you probably made a choice to put them separately for some reason. Just for consistency, I can move it to that section.

The new callback onCancel is the answer to "callback on canceling the listeners" topic, well we can put more details if you think the current description is not enough.

[ihsandemir]

@ihsandemir , two things I'd like to get your opinion:

• When it comes to listeners, we are explaining them under https://docs.hazelcast.com/hazelcast/5.3/events/distributed-events. For example, for Topics you can see it at https://docs.hazelcast.com/hazelcast/5.3/events/object-events#listening-for-topic-messages. Do you think it'd be more convenient to move this section to the "Listening to Events" section, and mention about the reliable message listener under the Reliable Topic section with a link?
• As per the support ticket linked in API-2182, I get the feeling that "callback on canceling the listeners" topic should be highlighted. Do you think the new content in this PR covers this topic well?

@Serdaro Yes, definitely we can move the content to that section. Naturally, I was thinking that it needs to be under associated data structure but you probably made a choice to put them separately for some reason. Just for consistency, I can move it to that section.

The new callback onCancel is the answer to "callback on canceling the listeners" topic, well we can put more details if you think the current description is not enough.

Changed as requested. Can you review again @Serdaro ?

[rebekah-lawrence]

Suggested change

	If a regular MessageListener is registered on a reliable topic, the message listener works fine, but it can't do much more than listen to messages.
	If a `MessageListener` is registered on a reliable topic, it can listen to messages.

[ihsandemir]

Changed to :

If a regular MessageListener is registered on a reliable topic, it can't do much more than listening to new messages but the ReliableMessageListener gives you more capabilities on controlling the listener behaviour.

If a ReliableMessageListener is registered on a normal ITopic, only the methods inherited from MessageListener are called.

[rebekah-lawrence]

Suggested change

	The ReliableMessageListener allows you to control where you want to start processing a message when the listener is registered. This makes it possible to create a durable subscription by storing the sequence of the last message and using this sequenceId as the sequenceId to start from.
	You can use the `ReliableMessageListener` to control where you want to start processing a message when the listener is registered. This supports the creation of a durable subscription by storing the sequence of the last message and then starting from this `sequenceId`.

[ihsandemir]

Changed to:

You can use the ReliableMessageListener to control which message you want processing to start when the listener is registered. This supports the creation of a durable subscription by storing the sequence of the last message and then re-starting from this sequenceId.

[rebekah-lawrence]

Suggested change

	The ReliableMessageListener also gives the ability to deal with exceptions using the `isTerminal(Throwable)` method. This method allows you to control which exceptions should terminate the execution of the listener and cancel it. If a plain MessageListener is used, it won't terminate on exceptions and it will keep on running. But in some cases it is better to stop running.
	The `ReliableMessageListener` also copes with exceptions using the `isTerminal(Throwable)` method. This method allows you to control which exceptions can terminate and cancel the listener. If a `MessageListener` is used, it doesn't terminate following an exception and continues to run. In some situations, such as ????, it is better to cancel the listener following an exception.

[rebekah-lawrence]

you'll need to replace the ???? with a quick example of when this is the preferred behaviour

[ihsandemir]

Changed as:

The ReliableMessageListener also copes with exceptions using the isTerminal(Throwable) method. This method allows you to control which exceptions can terminate and cancel the listener. If a MessageListener is used, it doesn't terminate following an exception and continues to run. In some situations, such as cluster being stopped, it is better to cancel the listener following the exception.

[rebekah-lawrence]

One last suggestion - for consistency in the wording of the sections on this page - this section could be headed:

Listening for Reliable Messages