Description Tobias Liefke 2011-10-20 10:17:55 EDT

Created attachment 205632 [details]
Example for the annotations, the processor and a test case.

(This is a "follow up" request for bug 331287)

Instead of removing all not supported methods and fields from the SWT API for RAP, I would propose to use NOOPs and mark these using annotations.

Here an example:

class org.eclipse.swt.widgets.Control {
  /** This method has no effect in RAP. */
  @Ineffective
  public void addMouseMoveListener (MouseMoveListener listener) {
    // Maybe log this call?
  }
}

That solution has many advantages:
1. We won't get NoSuchMethodErrors or similar for (closed) third party binaries that were compiled against SWT and that are using the unsupported (NOOP) methods.
2. We don't have to use "@Deprecated" (which is misleading).
3. We can supply an "annotation checker" which is configurable to either generate a compiler error or warning. That can be integrated in Eclipse (with the RAP tooling project).
4. We could explicitly suppress any compile problem for a specific usage already tested to be sufficient for the application - e.g. with @SuppressWarnings("rap.missing").
5. Using a second annotation "@Incomplete" we could even introduce a new level and describe existing implementations that are not fully equivalent to the SWT functionality.
6. The RWT team has a quick overview of open/incomplete implementations for every class (even a report could be created).

The attached ZIP contains two Eclipse projects for demonstrating the solution: org.eclipse.swt.annotation and org.eclipse.swt.annotation.processing.
I decided to use the SWT namespace for easier single sourcing (maybe we move the whole thing to SWT someday?).

In org.eclipse.swt.annotation you will find the proposed annotations @Ineffective and @Incomplete. Additionally there are two classes for demonstrating its usages (and for testing the annotation checker). Just import that project into a test workspace.

In org.eclipse.swt.annotation.processing you will find an example of an "annotation checker" plugin for Eclipse. I decided to use a "CompilationParticipant" instead of an "AnnotationProcessor", because its available in J2SE-1.5 and integrated automatically into the build process of JDT/PDE. Either compile it yourself or use the provided JAR file and deploy that plugin into your Eclipse IDE. If you recompile the imported project "org.eclipse.swt.annotation", you should see the "usage problems" marked in the example class org.eclipse.swt.annotation.test.User.

As it is just a proof of concept, the following limitations exist for the "annotation checker":
* No localization
* No checks during editing of the source file (only the saved file is checked)
* No configuration of the type of generated problems (using methods or fields that are marked @Ineffective is always an error and @Incomplete is always a warning)
* All classes in all Java projects are checked, no matter if they have a dependency on a annotated class
* No support for checks outside of eclipse (except when using the PDE-Build)

What are the next steps:
1. Include the annotation in RAP or SWT.
2. Mark the API methods where necessary.
3. Integrate the annotation checker into RAP Tooling (including localization).
4. Minimize the number of checked classes/projects.
5. Support configuration of generated problem type.
6. Create problem marker during source editing (not only after saving the file).

Steps 1 - 3 are the subject of this request, step 4 - 6 could result in follow up requests.