[tigerstripe-dev] TAF update: Avoid Provider conflicts and resolve Annot

[Andrey Platov <andrey@xxxxxxxxx>]

Hi folks,

Below is an update on annotation framework. I'm sending update in several message to separate problems (since some are well understandable, other may require additional discussions).

During attempts to implement "Everything is EObject" POC, we understand that EObject approach do not addresses all the problems, so I'd like to raise discussion on best ways to finalize TAF architecture, to keep it simple and fulfilling all the requirements at the same time. Let me start from the beginning and comment according to past experience. 

Also let me fix terms, when I'm referring to implementations I will use:
* Current - what we have in HEAD
* New - attempts to solve existing problems with minimal architecture and API changes. This work has been started in CVS MULTIPLY_ANNOTATIONS branch. 
* POC - that's related to some experiments we did past days.

Problems:

I. Multiple providers conflict.

Currently TAF is based on IAnnotable idea (we can annotate anything we can adapt to this class). That is bad due to 

A) Potential adapters conflict: "N vendors supply adapters from, say IJavaElement to IAnnotable".
B) Responsibilty shared among AdapterFactory and AnnotationProvider: So one contributed stuff (Adapter) responsible to map POJOs to URIs, and another part (Provider) responsible for mapping URIs to POJO and everything else.

This clearly signaling that IAnnotable is not good idea.

So what we doing both in new implementation and I tried in POC is complete removal of IAnnotable and corresponding AdapterFactory. 

Instead we propose following approach (let's stay with URI for a while): 

First change in *new* code: IAnnotable removed, and String getURI(Object pojo) method added to the provider. This simple change resolves provider conflict problem and consolidate uri mapping code within provider boundaries. This change is done in the new code in the MULTIPLY_ANNOTATIONS branch.

II. Annotable object ambiguousness for selection.

Let's consider hypothetical situation when N providers claims to take control over some POJO. Such situation existence depends on how the framework will select provider for a POJO. Let's discuss several approaches to selecting provider:

No-adapt approach: Provider specifies class for which it is registered. TAF performs simple instanceof check on a POJO to select provider (No Adapting here). 

Pro: This aproach very likely will not result in any ambiguousness (IResource and IJavaElement are different POJOs, so selectin Java file in Java views will return JavaElement, other views will return Resource)
Con: In this case Annotable object selection is UI driven, which is not OK for some cases... Sometimes when I see .java resource I may want to annotate it keeping corresponding Java class in mind. Following is also very implortant: consider I have some special resources or JavaElements (e.g. Tigerstripe ones). Java UI do not know anything about my special elements, and will return just plain old resources/elements. If we do not employ adaptable => we not able to attach annotations to our special elements.

To eleminate cons, we need to add some intelligence when choosing providers.

At first stage let's collect all interested providers by adapting POJO (selection) to each of provider class of interest. A few approaches possbile to select required annotable object among the set of classes to which POJO can be adapted:

A) Explicitly selecting annotable object (either programmatically or with UI).
If ambiguouse case occured TAF will show all possible annotable objects in UI, allowing user to choose correct annotable object.

B) Adding knowledge to annotation classes: e.g. which Annotation object can be attached to which type of elements (uri). For example Stereotype annotation can be attached to TSElement only, Hibernate to JavaElement only, but there is no sense attaching them to Resource. At same time some licensing/authoring metadata may be attached to Resource and visible through dependency graph (Java and TS element must be interested to see this authoring data).

So information about annotable classes to which practicualar annotation can be applied looks to be important, and both A & B approaches do not mutually exclusive: some POJO can be adapted to completely independent classes and if existing annotations do not express their preferences => we may ask user to choose correct target).

(B) will also greatly help with "shorten list annotations type UI requirement" - only relevant annotation types will be listed into "Annotations -> Create" context menu according to this info.

Both A & B is simply doable without breaking existing API, just with UI improvements and adding "target" attribute to AnnotationType definition, like

  <extension point="org.eclipse.tigerstripe.annotation.core.annotationType">
     <definition
           id="org.eclipse.tigerstripe.annotation.example.person"
           name="Person"
           target="org.eclipse.resource.core.IResource"
...

target is an optional attribute, if missed then annotation can be attached to any pojo (of course with provider for its type).

C) This is questionable and we look forward for your comments on this:

For example 3 providers expressing interest in annotating the pojo: IResource, IJavaElement, and ITSElement.

In reality all these classes are not independent. For example Java CompilationUnit or High-level JavaType can't exist without corresponding resource. We can see some logical dependency among providers: Resource <- JavaElement <- TSElement. 

According to this "logical" inheritance we may want to see following behavior:

If user query for Annotations of TSElement, annotations for JavaElement and Resource shall be returned as well. For example Resource may be annotated with Author data, etc.

Do you think this is reasonable? If it is reasonable we propose to add new configuration attribute to provider ("base" or something like that), which will be used to specify dependencies between providers.

*** SUMMARY

Both I and II (A,B,C) changes have minimal impact on the API, at same time it resolves some conceptual TAF problems and fulfills some requests best way (showing only relevant annotation in the UI/Context Menu). This work has been started in MULTIPLY_ANNOTATIONS branch, and we'd be happy to hearing comments on proposed/implemented changes. If everything above is OK, we plan to finalize this in few days.

I'll post separate emails on another aspects of the framework.

Kind Regards,
Andrey & Yuri