Refactor the Subscription API?

[chrisdutz]

Hi all,

since the beginning for me the Subscription API sort of felt sort of odd.

Currently you can create an execute a SubscriptionRequest and add multiple tags to that.
In the response you get one subscription handle per tag.
For each and every tag, you then can register handlers.
There is an alternative path where you can pre-register callbacks for each tag via the addPreRegisteredConsumer method.
While working with subscriptions for only one tag, this might not seem odd. However if you subscribe for multiple tags, things start getting strange, as you have to register handlers for each tag individually.

I would like to propose an alternative approach:
I would like to register only one handler for the entire subscription request. The SubscriptionEvent contains the names of the tags the event contains, so it's still easy to filter.
And while the synchronous requests all return CompletableFutures with the responses and you can register handlers to the completion of these, I would like to return Something similar, for which the user can register the callbacks there and these are then all called for any of the events coming in.

As soon as the user no longer wants to receive events, instead of "unsubscriging" I would like to call "cancel()" or "close()" on the object returned from the subscription request and that takes care of all the unsubscriptions.

[chrisdutz]

So one idea would have been to extend the CopmpletableFuture with the callback registration and cancel functions, but that sort of feels ugly.

Another one would be, that the PlcSubscriptionResponse, doesn't return a "handle", but a "handler" ... on this handler we could directly register callbacks and end the subscription.

[chrisdutz]

Test, if the "repository" is now omitted from the subject.

[chrisdutz]

Another tests after puppet must have deployed the changes

[sruehl]

One variant also would be to always use the tag names and utilize the unsubscription requests with it. Then add callbacks on the connection for tags and those get called not matter if it was a read or subscribe-event response.

[chrisdutz]

Wouldn't that generally be how it's done right now (At least the first part of your variant)?

I just sort of dislike this "each tag separately" concept. Not only do I think it's sort of confusing to write software for, but also is it more challenging to handle the subscriptions.

[chrisdutz]

So how about leaving most unchanged, but just having one Subscription handle per request and not per tag?

[chrisdutz]

I'll whip up an example in my branch.

[splatch]

In most of cases individual tags do not matter, subscription itself is usually a container for updates. Whether protocol handles it as one tag - one subscription, it is implementation detail which can be handled by driver itself. From user perspective, once he submits subscription request in single call cancelling it with one call seems to be consistent.

[chrisdutz]

So right now I think the process should look like this:

• A user issues a SubscriptionRequest
• He gets back a SubscriptionResponse
  • This SubscriptionResponse returns a map of return codes, that indicate for each tag of the subscription, if subscribing that tag worked
  • It also contains one SubscriptionHandle
• The user registers listeners to that handle
• All registered callbacks start receiving data
• As soon as the user no longer wants the subscription, he calls "unsubscribe()" or "close()" or whatever on the SubscriptionHandle

The API function "unsubscribe" would be removed from the connection API.

[sruehl]

yes

[splatch]

I think getting proposed way will clarify the API. In practice subscription token/identifier/key is anyhow buried in handle or somewhere in driver, so unsubscribe request is actually about finding that token and calling PLC with it to stop sending updates.

[sruehl]

I wonder if we should even name the result of the subscription SubscriptionToken or if handle says the same

[chrisdutz]

Oh ... that's something I care very little about ;-)
Didn't want to change eveything ... but I'm also happy with naming it differently.

[chrisdutz]

You could probably even call it "Subscription" ;-)