Bug 207085

Description Markus Kuppe 2007-10-22 16:18:20 EDT

From the consumer perspective it is of no interest, to receive notification about a partially resolved service. Services should be fully resolved before the IServiceListener is called. Hence plans for 2.0 are to simplify the IServiceListener interface. 

a) remove IServiceListener#serviceAdded(IServiceEvent)
b) rename IServiceListener#serviceResolved(IServiceEvent) to serviceDiscovered(IServiceEvent)
c) rename IServiceListener#serviceRemoved(IServiceEvent) to serviceUndiscovered(IServiceEvent)
c) remove IDiscoveryContainerAdapter#requestServiceInfo(IServiceID, int timeout);

requestServiceInfo isn't useful anymore, since discovery won't return partially resolved services.

This will be done chicken little by deprecating all three methods asap and adding the two new methods. After 2.0M4, the deprecated methods will be removed. It is worth to mention, that new providers  jslp/CompositeDiscovery/...  will not implement the old API and simply throw an UnsupportedOperationException if called. We hope this will be acceptable. Providing new and old API is simply to much of work.

The complete discussion leading to this decision can be found below.

------------ snip ------------

> (05:53:28 PM) Markus Kuppe: do you have a minute to discuss "Behavior of IDiscoveryContainerAdapter and service discovery" and my proposed API/SPI changes?
> (05:55:32 PM) Scott Lewis: ah...you mean no service type registration
> (05:55:35 PM) Scott Lewis: right?
> (05:55:49 PM) Markus Kuppe: exactly, at least to make it non required
> (05:56:16 PM) Markus Kuppe: addServiceListener(aServiceListener) without a IServiceTypeID
> (05:56:48 PM) Markus Kuppe: and just serviceAdded/serviceRemoved events and no serviceResolved event anymore.
> (05:57:32 PM) Scott Lewis: I'm for the simplification, but I don't initially see how all providers will support
> (05:58:34 PM) Markus Kuppe: you are talking about the first or the second simplification?
> (05:58:59 PM) Scott Lewis: the simplification of not having to register service types...just service listeners
> (06:29:32 PM) Scott Lewis: so I'm looking at your email to ecf-dev: "Behavior of IDiscoveryContainerAdapter and service" is that the right one to look at?
> (06:30:10 PM) Markus Kuppe: coming back to the API/SPI of discovery, the question is generally if we want an API which offers only common stuff or if we provide an API which forces providers to implement dummy methods.
> (06:30:16 PM) Markus Kuppe: yep
> (06:30:54 PM) Scott Lewis: well, I'm torn on that question (generally)
> (06:31:16 PM) Scott Lewis: in past, I've turned to adapters when faced with 'optional' api
> (06:31:44 PM) Scott Lewis: then providers can at least have a clear way to express that they don't support
> (06:31:55 PM) Scott Lewis: (returning null to getAdapter())
> (06:32:21 PM) Markus Kuppe: but for the current case I think we expose too much implementation of JMDNS
> (06:33:03 PM) Markus Kuppe: following the adapter it would rather make sense to have JMDNS implement some resolver adapter the consumer could get to resolve services.
> (06:33:05 PM) Scott Lewis: so you mean the service type and resolve process?
> (06:33:11 PM) Markus Kuppe: and not the other way around.
> (06:33:14 PM) Markus Kuppe: yep
> (06:33:58 PM) Markus Kuppe: but i do not see a reason why a consumer would be interested in partially resolved services anyway.
> (06:34:19 PM) Scott Lewis: well, I wouldn't be opposed to what you describe (moving some things on IDiscoveryContainerAdapter to an adapter interface)
> (06:35:37 PM) Scott Lewis: re: interested in partially resolved services...well, I don't know, but I suppose it would be for small/low bw devices...but in truth I don't know for sure
> (06:36:52 PM) Markus Kuppe: how do you envision the adapter interface to look like? If servicelisteners would only have to implement serviceAdded and serviceRemoved, how would serviceREsolved fit into this?
> (06:37:29 PM) Markus Kuppe: this would imply that a consumer still needs to know the specific provider
> (06:37:40 PM) Markus Kuppe: which makes CompositeDiscoveryContainer all the more compliated.
> (06:37:41 PM) Scott Lewis: interface with serviceResolved could be sub-interface of IServiceListener
> (06:39:26 PM) Scott Lewis: or IServiceListener could have just one method handleServiceEvent(IServiceEvent) and there could be more than one IServiceEvent types
> (06:40:02 PM) Scott Lewis: that would probably be better, as it's consistent with other ECF apis (file transfer, etc)
> (06:40:15 PM) Markus Kuppe: but we would need to define the event types upfront anyway, otherwise consumers wouldnt know how to handle them.
> (06:40:16 PM) Scott Lewis: but it adds some complexity
> (06:41:23 PM) Markus Kuppe: wouldnt know what to handle
> (06:41:27 PM) Scott Lewis: re: event types...yes...but rather than one IServiceEvent type, it would be necessary to have a (small) hierarchy
> (06:41:58 PM) Scott Lewis: IServiceEvent -> IServiceAddedEvent, IServiceEvent -> IServiceResolvedEvent, etc
> (06:42:48 PM) Markus Kuppe: i do not see a reason to make it so complex. the main use case/requirement for discovery is to inform a consumer about appearing and disappearing services.
> (06:43:23 PM) Markus Kuppe: so the listener interface should be simple
> (06:44:05 PM) Markus Kuppe: and maybe we could offer some optional service states
> (06:44:09 PM) Scott Lewis: IServiceListener would be simpler...i.e. IServiceListener.handleServiceEvent(IServiceEvent) would be the only method
> (06:44:24 PM) Markus Kuppe: but the impl would be more complex. ;)
> (06:46:03 PM) Scott Lewis: not necessarily...maybe IServiceEvent could be exactly as it is now, but have one additional method...e.g.
> (06:46:23 PM) Scott Lewis: boolean IServiceEvent.isAdded()
> (06:46:41 PM) Markus Kuppe: you would still have to check this method
> (06:46:53 PM) Scott Lewis: yes
> (06:47:09 PM) Markus Kuppe: if(event.isAdded) {
> doSomethingWithTheNewService;
> } else {
> removeService
> }
> (06:47:23 PM) Scott Lewis: true
> (06:47:28 PM) Markus Kuppe: i would like to get around this if/else by having two methods
> (06:48:17 PM) Scott Lewis: so you think that two methods is simpler?
> (06:48:30 PM) Markus Kuppe: from the consumer perspective i find it simpler
> (06:49:12 PM) Markus Kuppe: also it isnt a hard cut with the current interface. basically we remove one method and rename serviceResolved into serviceAdded
> (06:49:29 PM) Markus Kuppe: or we leave it as serviceResolved and life with the naming inconsistency.
> (06:50:23 PM) Scott Lewis: well IServiceListener has serviceAdded, serviceRemoved, and serviceResolved now...so do just mean removing serviceResolved?
> (06:50:25 PM) Markus Kuppe: or we rename it into discovered/undiscovered
> (06:50:51 PM) Markus Kuppe: technically i want to remove serviceAdded and rename serviceResolved into serviceAdded for naming consistency.
> (06:51:02 PM) Markus Kuppe: sorry for being not clear on this one
> (06:51:26 PM) Scott Lewis: yeah, I understand
> (06:51:51 PM) Markus Kuppe: i want to get rid of the partially discovered state
> (06:52:02 PM) Markus Kuppe: and the asynchronous calls requestServiceInfo
> (06:52:05 PM) Scott Lewis: well, we could just remove/deprecate serviceResolved from the interface
> (06:52:07 PM) Markus Kuppe: s/calls/call
> (06:52:52 PM) Markus Kuppe: but deprecating serviceResolved doesnt indicate that the behavior of serviceAdded has been changed in a way that it already returns fully resolved services.
> (06:54:10 PM) Scott Lewis: no, we would have to add docs to serviceAdded (at least)...for both providers and clients
> (06:55:00 PM) Markus Kuppe: javadoc might be missed by consumers, since they only get a warning about using deprecated api
> (06:55:38 PM) Markus Kuppe: and to not change behavior we would have to still call serviceResolved right after serviceAdded and ignore requestServiceInfo
> (06:56:04 PM) Markus Kuppe: imo this results in too much deprecated api in 2.0
> (06:57:17 PM) Scott Lewis: well, if it's too much deprecated API to remove then we should leave it?
> (06:57:41 PM) Markus Kuppe: nope, we should remove it entirely :)
> (06:57:55 PM) Markus Kuppe: 2.0 is allowed to break compatibility, isnt it?
> (06:58:23 PM) Scott Lewis: 2.0 is allowed to break compatibility...yes
> (06:59:18 PM) Scott Lewis: well, I'm assuming all the stuff that's deprecated now would be removed by 2.0
> (06:59:26 PM) Markus Kuppe: +1
> (06:59:39 PM) Markus Kuppe: will there be a 1.3?
> (06:59:47 PM) Scott Lewis: 1.3...I hope not
> (06:59:58 PM) Scott Lewis: not planned
> (07:00:42 PM) Scott Lewis: 'officially', we're now on 2.0 stream. If we need to do a 1.2.1 or 1.3 then well go back to friday's build and branch from there
> (07:01:14 PM) Scott Lewis: so I think we should begin removing methods
> (07:01:21 PM) Markus Kuppe: do we need to deprecate in at least one version before we would be allowed to remove methods?
> (07:01:37 PM) Scott Lewis: I don't think there is any such rule
> (07:01:52 PM) Scott Lewis: and we will have milestone versions
> (07:02:39 PM) Scott Lewis: I don't think there is a foundation rule to that effect
> (07:03:04 PM) Scott Lewis: but we might want to have 1 or 2 milestone releases deprecated
> (07:03:17 PM) Markus Kuppe: if we are allowed to simply remove methods, I am pretty much in favor of a complete rework of IServiceListener towards discovered/undisocvered
> (07:03:49 PM) Markus Kuppe: it is a clean break which all consumers will realize
> (07:04:00 PM) Markus Kuppe: because of compilation errors
> (07:04:22 PM) Scott Lewis: do you mean rename of methods...i.e. serviceDiscovered, serviceUndiscovered rather than serviceAdded, etc
> (07:04:33 PM) Markus Kuppe: yep
> (07:04:53 PM) Markus Kuppe: i would even remove "service" because the interface is called Iservicelistener
> (07:05:41 PM) Scott Lewis: well, repitition isn't necessarily bad :)
> (07:06:15 PM) Scott Lewis: ok...so let me summarize: IServiceListener
> (07:06:20 PM) Scott Lewis: a) all existing methods go away
> (07:06:45 PM) Scott Lewis: b) serviceDiscovered (or other name), serviceUndiscovered added (with appropriate semantics)
> (07:07:04 PM) Scott Lewis: for IDiscoveryContainerAdapter
> (07:07:38 PM) Scott Lewis: requestServiceInfo goes away
> (07:08:06 PM) Markus Kuppe: and while we are at it, we would remove all string based service type methods
> (07:08:29 PM) Markus Kuppe: and add addServiceListener(aServiceListener) without a IServiceTypeID
> (07:08:32 PM) Scott Lewis: you mean the ones already deprecated?
> (07:08:35 PM) Markus Kuppe: yep
> (07:09:20 PM) Scott Lewis: We probably should deprecate things for at least 1 milestone release (M4 in december)
> (07:09:41 PM) Scott Lewis: then remove
> (07:10:47 PM) Markus Kuppe: tbh it is getting a little bit hard for me keeping up with all the merging and the various (unapplied) patches so implementing the new api with the old one still present add a lot of additional work.
> (07:11:22 PM) Markus Kuppe: what do you think of branching the code and just deprecating without providing the new API. :o
> (07:12:11 PM) Markus Kuppe: this way people would be warned and i can work concentrate on the new api exclusively
> (07:12:32 PM) Markus Kuppe: certainly not the optimal solution.
> (07:12:46 PM) Scott Lewis: one sec...brb
> (07:14:29 PM) Scott Lewis: I would prefer a) making you committer; b) keeping all 2.0 work on HEAD
> (07:14:40 PM) Markus Kuppe: or at least dont implement deprecated API in newly written code like jslp, composite and simply let them throw UnsupportedOperationExceptions
> (07:15:10 PM) Scott Lewis: I'm OK with UnsupportedOperationExceptions
> (07:15:36 PM) Markus Kuppe: and after m4 we simply remove all deprecated methods
> (07:15:43 PM) Scott Lewis: right
> (07:16:25 PM) Markus Kuppe: committ rights would be a blessing, managing the code in two repositories with one being ro is a bitch. :o
> (07:17:10 PM) Scott Lewis: yes...let me nomiate you today, and start the vote
> (07:24:32 PM) Markus Kuppe: i will sum our ideas up and send them to the ml and bugzilla
> (07:25:10 PM) Scott Lewis: ok, thx. Might also be good to post to newsgroup also...just in case