[jdt-ui-dev] Adding refactorings - remarks - questions - HOWTO

["Sven Van Sighem" <sven_at_work@xxxxxxxxxxx>]

Hello,

My name is Sven Van Sighem, I'm in my last year of informatics
at the University of Antwerp in Belgium.

As a part of my thesis I have been studying the refactoring
engine of Eclipse. As was advised to several people via the
mailing list, I investigated the SEF refactoring, as wel as some
of the others.

From those I made up a sort of HOWTO on how to hook up a refactoring
to Eclipse. I added this to the end of my mail. Doing this, several
questions / remarks came up.

Before I start shooting, I would like to state that this is not ment
as a criticism, though some of it will probably sound like it. It is
just that for my thesis I must be critical. On top of that, part of
my thesis will also consist in creating refactorings and recording
the process for others to follow. As I have come to understand the
mechanisms used, these refactorings will either have to be adopted
by the PMC, or if we want to just use them internally will have to
be re-"hacked" into every new Eclipse version.

For the record, I think Eclipse is an excellent environment and have
allready reommended it to a lot of people, including my work place
(I'm taking these studies via my employer).

OK here I go:

* First, I found it odd that one has to sort of hack a refactoring into
the org.eclipse.jdt.ui project. If I follow the method used for e.g.
SEF I have to make quite a few changes to resources in this project
(both resource files and code files).
When I started off I expected to find an extension point enabling
me to hook up a refactoring plugin, but this does not appear to be
the case. Am I right in this assumption or did I miss something?

If this is the case, it also means that if I were to write a refactoring,
it would need to be added to the Eclipse Project via the PMC as it
would involve changes to the core of Eclipse rather than being
delivered as a plugin. I thought that maybe this was a conscious move
to prevent just any refactoring to be released. Is it?

* Second, I was surprised to see the property strings of the different
refactorings to be dispersed over several property files. I understand
that this is because the different string formatting methods in different
classes all have their own property file. However this seems like a
hard to maintain system. Personally I would give each refactoring its
own property file and pass a reference to it when calling the string
formatting method. Is there any specific reason why this is done the
way it is?

* Third adding the refactoring to the right button menu is done by "hacking"
it
into the org.eclipse.jdt.ui source code. Adding it to the Refactoring menu
in
the menu bar is done by defining an extension in the plugin.xml.
Is there a specific reason for this difference? Can this be diverted to an
extension point?


Greatings,

Sven Van Sighem



And here's the HOWTO

Creating an access point to your refactoring

1.	In org.eclipse.jdt.ui.actions create MyAction that extends
SelectionDispatchAction
		a)	Create MyAction(IworkbenchSite site) constructor containing
			super(site);
			setText(menu display text);
			WorkbenchHelp.setHelp(this, IJavaHelpContextIds.MY_ACTION);
		b)	In IjavaHelpContextIds add MY_ACTION constant
		c)	Create field private CompilationUnitEditor fEditor
		d)	Create a second constructor
			public MyAction(CompilationUnitEditor editor) {
				this(editor.getEditorSite());
				fEditor= editor;
				setEnabled(SelectionConverter.canOperateOn(fEditor));
			}
2.	In org.eclipse.jdt.ui.actions.RefactorActionGroup
		a)	add a field
			private SelectionDispatchAction fMyAction
		b)	In RefactorActionGroup(CompilationUnitEditor editor, String
groupName)constructor add:
			fMyAction= new MyAction(editor);
			fMyAction.setActionDefinitionId(IJavaEditorActionDefinitionIds.MY);
			fMyAction.update(selection);
			editor.setAction("My refactoring", fMyAction); //$NON-NLS-1$
		c)	In org.eclipse.jdt.ui.actions.IJavaEditorActionDefinitionIds add MY
constant
		d)	In RefactorActionGroup(IWorkbenchSite site) add:
			fMyAction= new MyAction(fSite);
			initAction(fMyAction, provider, selection);
		e)	In fillActionBars(IActionBars actionBars) add
			actionBars.setGlobalActionHandler(JdtActionConstants.MY, fMyAction);
		f)	In org.eclipse.jdt.ui.actions.JdtActionConstants add MY constant
		g)	In dispose() add
			disposeAction(fMyAction, provider)
		h)	In addRefactorSubmenu(IMenuManager menu) add
			addAction(refactorSubmenu, fMyAction)
3.	To add your refactoring to the Refactoring menu
		a)	Open plugin.xml of org.eclipse.jdt.ui with the plug-in manifest editor
		b)	Go to the Extensions tab
		c)	Make sure that “Show full extension hierarchy” is marked
		d)	Find the Java Coding actionSet extension (there are several actionSet
extensions)
		e)	Add an action by right clicking Java Coding and choosing new -> action
		f)	Give it the following properties:
				*	Id : org.eclipse.jdt.ui.actions.My
				*	Label : %Refactoring.myAction.label (For this to work you must add a
property Refactoring.myAction.label to the plugin.properties file, an
alternative is to directly write down the desired string. The properties
file can be used for translation.)
				*	MenubarPath : org.eclipse.jdt.ui.refactoring.menu/codingGroup
				*	Retarget : true

All this enables the hookup to the system. The different run methods of the
action can now be used to activate the actual refactoring.

The selectionChanged methods can be used to set the enabled status of the
action. You can do a check here to see if the connected refactoring is
applicable to the current selection or not. If it is not, you can have your
action greyed-out in the menu’s by setting enabled = false.