Breaking API for WatchedLocationReference / WatchedUserReference

Hi everyone,

as part of my work on moving watch buttons, I need to break the constructors of two classes: WatchedLocationReference and WatchedUserReference both located in xwiki-platform-notifications-filters-watch. I need to break them because I’m adding new API using UserReference per our best practices, and those classes don’t take injection but instead get the components inserted in constructor.

IMO it’s a really bad design since we need to break them each time we want to inject new stuff…

So my initial plan - and what’s implemented so far in my pull request - was to break them to change their constructor to only give a ComponentManager as parameter and to deal with it for further injection. The advantage is that we wouldn’t need to break the constructor anymore. I need to check but I could also restrict the visibility of the constructor: we’re never supposed to call the constructors as we provide a WatchedEntityFactory specifically for that. Still those changes don’t make the design suddenly good.

Now fixing properly this design would need quite some time: it’s not an easy task especially since it involves breaking more stuff and I don’t want to start that right now.

Instead, I was starting to think about a middle ground: to move those classes to internal, and then to also make WatchedEntityFactory (located in same module) internal: right now those classes are exposed as APIs because the factory returns them.
But while writing this I’m realizing that it might not work at all: any code relying on old package would be broken right away.
My idea was that it would avoid breaking API multiple times: we would break the API now to move them to internal (and I can modify them the way I want as well for my needed changes), and we can then work on improving their design without causing a breakage. But it’s probably actually worst if it causes problems with existing code.

I performed a quick search on xwiki-contrib and so far it seems that only Change Request is using WatchedEntityFactory there, and same for WatchedLocationReference (no hit for WatchedUserReference).

So in the end I think I only got my first solution, wdyt? any better idea?