Howto: Register Refactoring Support

< To: Tigerstripe_APIs

Introduction

URI of an annotated objects may be changed during object lifetime and annotations need to be updated. For this case Annotation Framework supports annotated object refactoring. From the Annotation Framework perspective - refactoring is an operation which change one URI to another.

Refactoring support for your own annotated object

TAF includes refactoring support for resources and java elements. If it's necessary to add refactoring support for a new type of annotated objects you should contribute a new extension of org.eclipse.tigerstripe.annotation.core.refactoringListeners. It requires implementing org.eclipse.tigerstripe.annotation.core.refactoring.IRefactoringChangesListener interface. This interface has following methods:

• deleted(IRefactoringDelegate delegate, ILazyObject object) - called when object is being deleted.
• changed(IRefactoringDelegate delegate, ILazyObject oldObject, ILazyObject newObject, int kind) - called when object is being changed. Parameter oldObject presents object before changes and newObject – after it. Parameter kind can take following values org.eclipse.tigerstripe.annotation.core.refactoring.IRefactoringChangesListener.ABOUT_TO_CHANGE (before refactoring) and org.eclipse.tigerstripe.annotation.core.refactoring.IRefactoringChangesListener.CHANGED (after refactoring performed)
• moved(IRefactoringDelegate delegate, ILazyObject[] objects, ILazyObject destination, int kind) - called when objects is being moved. Parameter destination presents object where objects are moving.
• copied(IRefactoringDelegate delegate, ILazyObject[] objects, ILazyObject destination, Map<ILazyObject, String> newNames, int kind) - called when object is being copied. Parameter destination presents object where objects are coping. Parameter newNames maps coping object to its new names.

ILazyObject is a proxy to annotated object that is being refactored. Its method getObject() returns real annotated object as soon as it can be available during refactoring. Interface org.eclipse.tigerstripe.annotation.core.refactoring.IRefactoringDelegate intends for reporting about URI changes. Please, see example below:

 public class MyRefactoringSupport implements IRefactoringChangesListener {
   public void changed(IRefactoringDelegate delegate, ILazyObject oldObject, ILazyObject newObject, int kind) {
     if (kind == ABOUT_TO_CHANGE) {
       // Lazy object oldObject is supposed to return real annotated object before refactoring 
       Object obj = oldObject.getObject(); 
       ...
     } else if (kind == CHANGED) {			
       // Lazy object newObject is supposed to return real annotated object after refactoring
       Object obj = newObject.getObject();
       ...
       // Evaluate URI changes using new object and report about URI changes to refactoring delegate
       delegate.changed(oldUri, newUri, false);
     }
   }
   ...
 }

Support for custom object changes

TAF provides support for standard refactoring (LTK). If you want TAF to update annotations automatically while custom object changes you should notify TAF using interface org.eclipse.tigerstripe.annotation.core.IRefactoringNotifier. This interface has following methods:

• fireDeleted(ILazyObject object) – notify about object deletion.
• fireChanged(ILazyObject oldObject, ILazyObject newObject, int kind) – notify about object changing. Parameter kind can take following values org.eclipse.tigerstripe.annotation.core.refactoring.IRefactoringChangesListener.ABOUT_TO_CHANGE (before refactoring) and org.eclipse.tigerstripe.annotation.core.refactoring.IRefactoringChangesListener.CHANGED (after refactoring performed)
• fireMoved(ILazyObject[] objects, ILazyObject destination, int kind) – notify about object moving.
• fireCopy(ILazyObject[] objects, ILazyObject destination, Map<ILazyObject, String> newNames, int kind) – notify about objects being copied.

IRefactoringNotifier instance can be retrieved from Annotation Manager as following:

 AnnotationPlugin.getManager().getRefactoringNotifier();