• Share this article:

Discouraged Access

Tuesday, January 24, 2006 - 12:16 by Wayne Beaton

I recently got this question from a developer building Eclipse plug-ins:

What should I do about classes with discouraged access? For example IAntUIConstants is “internal”.

To start with, if you haven’t encountered this yourself already, here’s what it looks like in the Java editor when a class in your plug-in attempts to make use of the IAntUIConstants type:

Access to this class is discouraged and shows up as a warning in the editor (and in the “Problems” view). This warning does little to stop you, other than give you a creepy feeling that you’re doing something wrong. You can discourage the use of certain classes in your own plug-ins using the same mechanism, allowing you to share that creepy feeling among your friends and colleagues.

The answer to this question is simple: when you get a discouraged access warning, stop using the type that’s causing it. However, that may be a little too simplistic. What if you really, really, really need the functionality? In this case, the answer is still “don’t do it”. But what if you really, really, really, really need to use the class? In that case, you can use it, but you need to be aware of what it means (four really’s usually does it for me).

Discouraged access is provided for your protection (it’s for the plug-in provider’s protection as well since it gives them the ability to say “well… we warned you”). The idea is that you are discouraged from accessing things that are not part of the public API. The things that you are discouraged from accessing may change in future versions of Eclipse and break your code.

You will notice a couple of things about discouraged access code in Eclipse. First, you’ll very likely see the word “internal” somewhere in the package name (the Eclipse Platform Naming Conventions talks about this). The other thing you’ll notice is that the documentation is a lot less evolved in these types than in those that are part of the API.

If you really do need access to types that you are discouraged from accessing, you may be able to make a case for adding them to the public API through Bugzilla. Be prepared to make a pretty strong case as most teams take adding public APIs very seriously (they are a huge liability to them; once something is declared API, it must be supported and is hard to change).