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).