From 923d5953c9f8674b02b6df016e87ee8f47436c7e Mon Sep 17 00:00:00 2001 From: Bartek Pacia Date: Thu, 12 Jun 2025 16:37:14 +0000 Subject: [PATCH] RenamePsiElementProcessorBase: add Javadoc Drafted while working on IDEA-107390 Merge-request: IJ-MR-165236 Merged-by: Bartek Pacia GitOrigin-RevId: 7bae2c19691a5e10ec5101863e36ec8a5454f70d --- .../rename/RenamePsiElementProcessorBase.java | 64 +++++++++++++------ 1 file changed, 45 insertions(+), 19 deletions(-) diff --git a/platform/refactoring/src/com/intellij/refactoring/rename/RenamePsiElementProcessorBase.java b/platform/refactoring/src/com/intellij/refactoring/rename/RenamePsiElementProcessorBase.java index ba6e83731644..9ab41d773b67 100644 --- a/platform/refactoring/src/com/intellij/refactoring/rename/RenamePsiElementProcessorBase.java +++ b/platform/refactoring/src/com/intellij/refactoring/rename/RenamePsiElementProcessorBase.java @@ -1,7 +1,6 @@ // Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. package com.intellij.refactoring.rename; -import com.intellij.openapi.diagnostic.Logger; import com.intellij.openapi.editor.Editor; import com.intellij.openapi.extensions.ExtensionPointName; import com.intellij.openapi.project.Project; @@ -32,11 +31,32 @@ import java.util.Map; import static com.intellij.openapi.util.NlsContexts.DialogMessage; +/** + *

Lifecycle

+ *

+ * A simple implementation of this class might have the following lifecycle: + * + *

    + *
  1. {@link #canProcessElement(PsiElement)} is called to determine if this RenameProcessor can be used to rename the element
    2. + *
  2. If yes, {@link #findReferences} is called with on that element to find references to it that also should be renamed + * (it is what {@code usages} are in the next call) + *
    3. + *
  3. {@link #renameElement(PsiElement element, String newName, UsageInfo[] usages, RefactoringElementListener)} is called, with the new + * step name entered in the rename dialog and a list of usages. + *

    + * It has to rename the element and all its usages. Should not perform duplicate work that findReferences has already done. + *

    4. + *
+ *

+ * The class follows the Chain of Responsibility design pattern - when a rename operation is requested, the platform iterates through + * all registered processors and uses the first one that returns true from {@link #canProcessElement}. + * + * @see RenameHandler + * @see RenameProcessor + */ public abstract class RenamePsiElementProcessorBase { - private static final Logger LOG = Logger.getInstance(RenamePsiElementProcessorBase.class); - - public static final ExtensionPointName - EP_NAME = ExtensionPointName.create("com.intellij.renamePsiElementProcessor"); + public static final ExtensionPointName EP_NAME = + ExtensionPointName.create("com.intellij.renamePsiElementProcessor"); public abstract boolean canProcessElement(@NotNull PsiElement element); @@ -44,7 +64,7 @@ public abstract class RenamePsiElementProcessorBase { @NotNull PsiElement element, @Nullable PsiElement nameSuggestionContext, @Nullable Editor editor) { - for (RenameRefactoringDialogProvider dialogProvider: RenameRefactoringDialogProvider.EP_NAME.getExtensionList()) { + for (RenameRefactoringDialogProvider dialogProvider : RenameRefactoringDialogProvider.EP_NAME.getExtensionList()) { if (dialogProvider.isApplicable(this)) { return dialogProvider.createDialog(project, element, nameSuggestionContext, editor); } @@ -91,8 +111,8 @@ public abstract class RenamePsiElementProcessorBase { *

* Expected to be called from EDT. * - * @param element the base element for the refactoring. - * @param newName the name into which the element is being renamed. + * @param element the base element for the refactoring. + * @param newName the name into which the element is being renamed. * @param allRenames the map (from element to its new name) into which all additional elements to be renamed should be stored. */ public void prepareRenaming(@NotNull PsiElement element, @NotNull String newName, @NotNull Map allRenames) { @@ -113,9 +133,9 @@ public abstract class RenamePsiElementProcessorBase { /** * Entry point for finding conflicts. * - * @param element primary element being renamed - * @param newName new name of primary element - * @param conflicts map to put conflicts + * @param element primary element being renamed + * @param newName new name of the primary element + * @param conflicts map to put conflicts * @param allRenames other elements being renamed with their new names; not expected to be modified */ public void findExistingNameConflicts(@NotNull PsiElement element, @@ -190,7 +210,7 @@ public abstract class RenamePsiElementProcessorBase { } } - public boolean showRenamePreviewButton(@NotNull PsiElement psiElement){ + public boolean showRenamePreviewButton(@NotNull PsiElement psiElement) { return true; } @@ -199,7 +219,7 @@ public abstract class RenamePsiElementProcessorBase { * of an inherited method). * * @param element the element on which the refactoring was invoked. - * @param editor the editor in which the refactoring was invoked. + * @param editor the editor in which the refactoring was invoked. * @return the element to rename, or null if the rename refactoring should be canceled. */ public @Nullable PsiElement substituteElementToRename(@NotNull PsiElement element, @Nullable Editor editor) { @@ -207,12 +227,16 @@ public abstract class RenamePsiElementProcessorBase { } /** - * Substitutes element to be renamed and initiate rename procedure. Should be used in order to prevent modal dialogs to appear during inplace rename - * @param element the element on which refactoring was invoked - * @param editor the editor in which inplace refactoring was invoked - * @param renameCallback rename procedure which should be called on the chosen substitution + * Substitutes the element to be renamed and initiates the rename procedure. + * Should be used to prevent modal dialogs from appearing during inplace rename. + * + * @param element the element on which refactoring was invoked + * @param editor the editor in which inplace refactoring was invoked + * @param renameCallback the rename callback to be called on the chosen substitution */ - public void substituteElementToRename(final @NotNull PsiElement element, @NotNull Editor editor, @NotNull Pass renameCallback) { + public void substituteElementToRename(final @NotNull PsiElement element, + @NotNull Editor editor, + @NotNull Pass renameCallback) { final PsiElement psiElement = substituteElementToRename(element, editor); if (psiElement == null) return; if (!PsiElementRenameHandler.canRename(psiElement.getProject(), editor, psiElement)) return; @@ -228,6 +252,7 @@ public abstract class RenamePsiElementProcessorBase { /** * Use this method to force showing preview for custom processors. * This method is always called after prepareRenaming() + * * @return force show preview */ public boolean forcesShowPreview() { @@ -242,7 +267,8 @@ public abstract class RenamePsiElementProcessorBase { return RenameUtilBase.createMoveRenameUsageInfo(element, ref, referenceElement); } - public interface DefaultRenamePsiElementProcessor {} + public interface DefaultRenamePsiElementProcessor { + } private static class MyRenamePsiElementProcessorBase extends RenamePsiElementProcessorBase implements DefaultRenamePsiElementProcessor { @Override