Difference between revisions of "Howto: Register Annotation Providers"

Latest revision as of 07:42, 27 May 2008

< To: Tigerstripe_APIs

Introduction

With an Annotation Framework you can annotate any object which can be identified with the URI (annotable objects). By default, framework provide two types of the annotable objects. There are resource (files, folders, etc.) and java elements (packages, classes, methods, etc.)

To contribute new annotable objects class you need to provide two operations:

• Get URI by annotated object.
• Get annotated object by URI.

We looks how annotable objects can be contributed by the example of resource annotable objects.

IAnnotationProvider

To provide mentioned information with the framework we need to use annotation provider. It can be contributed using "org.eclipse.tigerstripe.annotation.core.annotationProvider" extension point:

 <extension
      point="org.eclipse.tigerstripe.annotation.core.annotationProvider">
   <provider
        id="org.eclipse.tigerstripe.annotation.resource.provider"
        class="org.eclipse.tigerstripe.annotation.resource.ResourceAnnotationProvider"
        type="org.eclipse.core.resources.IResource"
        targetDescription="Resource"/>
 </extension>

The attributes are described as follows.

• id - a unique name that will be used to identify this annotation provider
• class - an annotation provider class
• type - class name of the annotable objects which will be annotated with this annotation provider
• targetDescription - human-readable description of the annotable object

This extension point provide a resource provider class which implements org.eclipse.tigerstripe.annotation.core.IAnnotationProvider interface:

 public class ResourceAnnotationProvider implements IAnnotationProvider {
     public Object getObject(URI uri) {
         return ResourceURIConverter.toResource(uri);
     }
     public URI getUri(Object object) {
         if (object instanceof IResource) {
             IResource resource = (IResource)object;
             return ResourceURIConverter.toURI(resource);
         }
         return null;
     }
 }

URI can be created from the IResource path and with the specific "resource" scheme:

 return URI.createHierarchicalURI("resource", null, null, resource.getFullPath().segments(), null, null);

To get IResource from the URI we can used following code:

 if ("resource".equals(uri.scheme())) {
     IPath path = new Path(uri.path());
     return ResourcesPlugin.getWorkspace().getRoot().findMember(path);
 }
 return null;

IAnnotationProvider may also delegate to other providers. Sometimes, annotations added to the IResource can be also used as annotations added to corresponding IJavaElement. In this case, annotation provider should describe all delegating information using delegate attribute. For example, JavaAnnotationProvider delegate to the ResourceAnnotationProvider using following declaration:

 <extension
      point="org.eclipse.tigerstripe.annotation.core.annotationProvider">
   <provider
        id="org.eclipse.tigerstripe.annotation.java.provider"
        class="org.eclipse.tigerstripe.annotation.java.JavaAnnotationProvider"
        type="org.eclipse.jdt.core.IJavaElement"
        targetDescription="Java Element"/>
      <delegate type="org.eclipse.core.resources.IResource"/>
   </provider>
 </extension>

To get all annotations by annotated object we can use IAnnotationManager.getAnnotations(Object object, boolean deepest) method. When deepest=false this method return annotations only for passed object. When deepest=true it return annotations for passed object and for all delegated objects.

Note: delegating is recursive. For example, if A delegate to B and B delegate to C. And we add 2 annotations for A, B and C objects we will see following picture:

 getAnnotations(A, false) return 2 annotations.
 getAnnotations(B, false) return 2 annotations.
 getAnnotations(C, false) return 2 annotations.
 getAnnotations(A, true) return 6 annotations.
 getAnnotations(B, true) return 4 annotations.
 getAnnotations(C, true) return 2 annotations.