Section 20.2. Accessing Internal Code

Eclipse separates classes into two categories: public API and "for internal use only." Any classes located in a package that has "internal" in its name (e.g.,org.eclipse.core.internal.boot) are internal to the plug-in, should not be referenced by any code outside the plug-in itself, and may change drastically between different versions of Eclipse. All other classes are considered public API, can be called from outside the plug-in, and follow strict Eclipse guidelines for how and when the class and method signatures can change. Needless to say, it is easier to stick to the public API when supporting multiple versions of Eclipse.

During the course of development, you may need to access classes and methods marked internal to a particular Eclipse plug-in. Every time you have such a need, the first thing you should do is double-check that there is not an existing public API that will do the trick instead. If no public API exists, then search the Eclipse.org archives or related sites (see Section A.2, Resources, on page 761) for a similar problem with a solution you can use. Failing that, post a message on the Eclipse newsgroup describing your situation and asking for suggestions (see the next section).

If you don't find a solution, then proceed to file a bug report or feature request in the Eclipse Bugzilla tracking system (see Section 20.2.2, BugzillaEclipse bug tracking system, on page 712). If needed, you can create a fragment (see Section 20.2.6, Using fragments, on page 714) to access the code necessary until a public API is made available.

20.2.1. Eclipse newsgroup

The Eclipse newsgroupwww.eclipse.org/newsgroups/provides novices and experts alike with an avenue for sharing knowledge. You'll need a username name and password, so if you do not have one, browse www.eclipse.org/, then go to Newsgroups > Request a Password. The more information you provide regarding what you are trying to accomplish and code showing what you have tried so far, the more likely you are to get a response and the information you need. A vague question will likely be ignored or bounced back to you for more information.

Do your homework, and above all, don't expect an answerthese are smart folks who will answer depending on their area of expertise, their interest in your question, and their available time. Nobody is being paid to help you. The Eclipse newsgroup is open to everyone, so don't be afraid to contribute to the community by offering help to others when you can.

20.2.2. BugzillaEclipse bug tracking system

Once you have double-checked that no public API exists and no one else on the newsgroup has a suggestion as to how your task can be accomplished, submit a bug report or feature request to the Eclipse Bugzilla tracking system:

Again, you'll need a username and password, so if you don't have one, browse www.eclipse.org/, and then select Bugs > Create a Bugzilla account. As with the newsgroup, the more information you provide regarding what you are trying to accomplish and code showing what you have tried so far, the more likely the Eclipse team will provide the public API you need in future versions of Eclipse. To increase your odds of success even further, be sure to include details concerning how you think Eclipse should be modified to suit your needs; or better yet, make and submit the modifications yourself (see Section 20.6.1, Modifying the Eclipse base, on page 727) along with test cases so that the Eclipse development team can simply install your changes, test them, and move on with the rest of their work. Your modifications may involve modifying existing Eclipse code, adding new code, or even adding a new extension point (see Section 17.2, Defining an Extension Point, on page 597).

Be sure to vote for the bugs that you want fixed so that the Eclipse team can get a better feel for which changes are important and which are not. As with the newsgroup, do your homework and don't expect to get everything you want. The Eclipse team is trying to satisfy a diverse community's needs and keep quite busy doing so.

20.2.3. Options for accessing internal code

Submitting a request to the Eclipse development team will help with future versions of Eclipse; but, what is to be done to support the current and prior versions? There are several techniques for accessing internal code, including:

Note

If you reference internal code, either directly or indirectly via a fragment, then the onus is on you to change your code if the internal code changes or goes away.

20.2.4. How Eclipse is different

Eclipse imposes more restrictions on plug-in interaction than in a typical Java application . Each plug-in has its own ClassLoader, restricting its visibility of the system to code in the plug-ins specified via the plug-in manifest (see Section 2.3.1, The Plug-in manifests, on page 71). This means that even though class A in one plug-in resides in a package with the same name as class B in a required plug-in, class A will not be able to access the protected and default methods in class B. The Eclipse Java development environment will correctly compile the code as if those methods can be accessed, but when the code is executed inside an Eclipse framework, the plug-in ClassLoader will restrict the access, throwing an IllegalAccessException.

This situation can also arise if the library is not exported by its plug-in manifest (see Section 3.3.2, Plug-in runtime, on page 110), even if the class and methods are all marked as public. Since you do not want to modify an existing Eclipse plug-in, you must be a bit more resourceful to work around these restrictions.

Tip

If a third party will be referencing and building on your plug-ins' code, then consider exporting all classes in your plug-in as shown in Section 3.3.2, Plug-in runtime, on page 110. Your classes may be used to build things not originally envisioned by you, and hiding classes prevents others from supporting different Eclipse versions and your code (see Section 19.2.6, Building against different versions of Eclipse, on page 693). Obviously, wherever you can, provide controlled third-party enhancements through the use of extension points (see Section 17.1, The Extension Point Mechanism, on page 595).

20.2.5. Related plug-ins

Eclipse 3.1 introduces a couple of enhanced package-level visibility directivesx-internal and x-friendsto more exactly define which plug-ins have access to which packages. When exporting packages using the Runtime page of the manifest editor (see Figure 2-11 on page 75), use the Package Visibility section to explicitly specify which plug-ins, if any, have access to the selected packages.

For example, in Section 2.8.1, Test preparation, on page 92, you could limit visibility of the exported packages to the test plug-in. This would result in an Export-Package declarations something like this.

Export-Package: com.qualityeclipse.favorites.actions
   ;x-friends:="com.qualityeclipse.favorites.test",
 com.qualityeclipse.favorites.model
   ;x-friends:="com.qualityeclipse.favorites.test",
 com.qualityeclipse.favorites.views
   ;x-friends:="com.qualityeclipse.favorites.test"

In this way, other plug-ins can be granted access to internal packages in a controlled manner.

20.2.6. Using fragments

When neither referencing the code directly nor copying the code into your own plug-in will work, you can try using fragments. Fragments are chunks of code defined in a plug-in-like structure that Eclipse automatically attaches to an existing plug-in (see Section 16.3, Using Fragments, on page 587).

As far as the Eclipse system is concerned, code contributed by a fragment is treated exactly the same as code that exists in the target plug-in. Originally, fragments were created to insert different National Language Support (NLS) code into a plug-in based on the intended audience, but you can exploit this mechanism to solve your own problems. Using this technique, you cannot override classes that already exist in the plug-in, but you can insert new utility classes used to access methods that were previously not accessible because they had default or protected visibility.