Get rid of @Programming annnotation

Hi devs,

A long time ago the support for a @Programming annotation was started as part of https://jira.xwiki.org/browse/XWIKI-2180 but never finished. We end up with a totally useless annotation but worst of all a very misleading annotation since we noticed people using it and assuming that it was actually protection their API automatically.

Since it’s currently in a very bad location, and we would like to have something more generic (any right check and not just programming) when we finally implement this I’m proposing to simply delete it completely. Deleting an annotation is not really a problem from a binary compatibility point of view (provided you don’t actually try to get this type of annotation from a method of course).

+1

+1

Some thoughts:

  • It’s not totally useless. It’s interesting to have it in the javadoc to express that a method requires PR. For example: http://nexus.xwiki.org/nexus/service/local/repositories/releases/archive/org/xwiki/platform/xwiki-platform-oldcore/6.4.2/xwiki-platform-oldcore-6.4.2-javadoc.jar/!/com/xpn/xwiki/api/Context.html#setDatabase(java.lang.String) (in this example the javadoc also mentions the need for PR but not all javadocs do)
  • I agree that it’s misleading to not use it everywhere since users could think that if the annotation is not present then it means the method doesn’t require PR.
  • “we noticed people using it and assuming that it was actually protection their API automatically.”. That could be fixed by improving the javadoc in the Programming annotation code which is currently misleading (Indicates that a method requires programming rights to be executed.), by saying that it’s informational only and doesn’t perform any check automatically. Similar to the ProgrammingRights xobject for wiki pages.
  • I agree that we should deprecated it, if only for the reason that the annotation is located in the com.xpn.xwiki.util package. We need such an annotation to be in org.xwiki.*.
  • I think I wouldn’t delete it (since it’ll make existing code fail) but move it legacy instead (and update its javadoc as mentioned above).

What kind of code do you have in mind ? Removing it won’t have any impact on the methods annotated with it and I really doubt any code really gather this kind of annotation on methods.

Note that there’s one occurence of this in wiki-editor-devtools: https://github.com/xwiki-contrib/wiki-editor-devtools/blob/master/editor-tool-autocomplete/editor-tool-autocomplete-api/src/main/java/org/xwiki/editor/tool/autocomplete/internal/velocity/AbstractAutoCompletionMethodFinder.java#L129.

Now it’s the only occurence we have in xwiki-contrib, AFAICS: https://github.com/search?q=org%3Axwiki-contrib+import+com.xpn.xwiki.util.Programming%3B&type=code

Note that the idea is to have a more generic way to express the rights needed (cf https://jira.xwiki.org/browse/XWIKI-18278), so IMO it makes sense to remove this one and to fix the places where it’s used to then provide the right one as part of XWIKI-18278.