Refactoring Architecture for Plugins

Hello John,

In general, there is no specific architecture that you have to follow when
implementing a refactoring - you can provide your own action and UI and implement
the refactoring in any way you like. If the workflow used by BaseRefactoringProcessor
(find usages / show conflicts / process usages) is a good fit for your refactoring,
you're welcome to use it - generally this part of code is fairly stable and
not changing much between releases.

As for the dialogs, there's not much there that can be reused between different
refactorings, so most refactorings provide their own dialogs based on the
DialogWrapper class (which is the base class for most of the dialogs everywhere
in the IDEA UI).

Is there any documentation of the basic refactoring architecture for
writing refactorings through the Open API?  All that I can glean from
reading the forum is that the main interface is
RefactoringActionHandler, and that this interface is called when a
refactoring is invoked.  The invoke() method then has to do everything
from precondition checking, to showing dialogs, to previewing, to the
actual refactoring.  This sounds too high level.  I have been unable
to find any other documentation. (The forum posting that I found is
http://jetbrains.net/devnet/message/4919528#4919528)

RefactoringActionHandler contains two invoke() methods, one of which
is called when refactoring within the editor, and the other when
refactoring from other contexts (this is clear from the Javadoc in
that interface).

I have had a look at Remove Middleman refactoring in the idea.jar
library (which is the main part of IDEA, not part of the Open API) and
it uses the RefactoringDialog and BaseRefactoringProcessor
abstract classes but I understand these should preferably not be
reused as they are not in the Open API (see
http://jetbrains.net/devnet/message/5259142).  Perhaps I have
misunderstood.

It seems that some of the refactorings have been "opened" by moving
parts of them to openapi.jar.  The com.intellij.refactoring
package exists in both the idea.jar and the openapi.jar libraries
and there is a close relationship between them.  For example, in
openapi,jar, we have interface
com.intellij.refactoring.rename.RenameHandler which is then
implemented in idea.jar in different contexts, for example
*com.intellij.refactoring.rename.inplace.VariableInplaceRenameHandler.
*

In openapi.jar there is a
com.intellij.refactoring.util.RefactoringMessageDialog which seems
to be extended only by
com.intellij.refactoring.inline.InlineParameterDialog in idea.jar,
so all the other refactorings are using a different base for their
dialogs.

I'm not looking for a detailed discussion of how the refactorings
work, only the basic architecture that should be followed by plugins
for brand new refactorings (not for extensions of existing ones).

--
Dmitry Jemerov
Development Lead
JetBrains, Inc.
http://www.jetbrains.com/
"Develop with Pleasure!"

Thanks Dmitry.  Your answer is very helpful.