change_method_signature

Change method signature (parameters, return type, or name) and update all call sites.

Returns text edits for the method declaration and every place that must change. The caller should apply these edits to perform the change.

USAGE: Position on method declaration, provide changes OUTPUT: Edits for the declarations and every place updated

The method changes together with every method it overrides, every method that overrides it and every method a subtype inherits together with it, as rename_symbol renames them: one declaration edit each, each keeping its own parameter names and unchanged parameter types, and every call of any of them. A method related to a method of a class file is refused, naming that method: it cannot change. A place JDT's search reports but cannot confirm as a call, where a type or name does not resolve, is never rewritten: potentialMatches lists every one, to review by hand. An element of an annotation type is refused: it has no parameters; rename it with rename_symbol.

Every place JDT's change-signature refactoring updates is updated: calls, including the arguments of enum constants; Javadoc references (#method(Type) and Type#method(Type) links); a single static import of the method, renamed, or followed by an import of the new name when a member it names keeps the old name; the parameters of each lambda expression implementing the method; and, when a constructor without parameters is given some, its implicit super() calls: super(...) is added to each constructor of a direct subclass that calls it implicitly, and a constructor calling super(...) to each direct subclass that declares none. A call nested in another changed place, such as a chained call, changes within that place's edit.

Each edit replaces a span (type replace, with oldText and newText, or oldSignature and newSignature for a declaration, isDeclaration true) or inserts text (type insert, with line, column, offset and newText). A file's edits come in this order: declarations, the other places the search reports, in source order, lambda expressions, implicit super() calls, static imports.

PARAMETER OPERATIONS:

• Add new parameter with default value for existing calls

• Remove parameter (will remove from calls)

• Rename parameter: give it its new name and, as oldName, the name it has now. Each declaration and lambda expression that names it so takes the new name in its parameter list and every reference to it in its body, a declaration's @param tag naming it too, and a Javadoc reference naming it takes the new name; calls keep their arguments. A declaration or lambda expression that names it otherwise keeps its own name. An oldName that names no parameter of the method is INVALID_PARAMETER.

• Reorder parameters (specify all parameters in new order)

A renamed parameter's @param tag and references follow its declaration's or lambda expression's edit, in source order. The edits of the lambda expressions come in source order, file by file, as the other places do.

Every declaration keeps each kept parameter's modifiers and annotations as written. A changed type replaces only the type: the parameter is varargs when the new type ends in ..., and dimensions written after its name are dropped, as JDT does.

Refused as JDT refuses them (INVALID_PARAMETER 'newParameters', with JDT's messages): a blank parameter name or one that is no Java identifier; two parameters of one name; a name the change gives that a method changed with it already gives one of its parameters, naming that method; and a rename that changes what a name refers to: a renamed reference a local variable would capture (in the body, an anonymous class or a lambda expression), or a reference to a field or another variable the renamed parameter would capture. Each collision names the declaration it lies in and its place, as the file is now.

Compile errors that follow from the requested change (a changed return or parameter type breaking a caller, a removed parameter still used) do not refuse it. introducedProblems lists every compile error the applied edits introduce in each file the change edits or reports a place in, and JDT's note for each removed parameter a body still uses, at its first use, also where the code compiles because a field of that name captures it. Each entry gives filePath, line and column, as the file is now, and message, which names the method, field, initializer or type the error lies in ("a lambda expression in" it when it lies in one; an anonymous class by its number, as in Outer$1). Entries come by file, then line and column, then message. introducedProblems is present only when it has an entry.

warnings lists JDT's warnings on the new parameter names, in the order of the parameters, then one for each file holding a method reference that cannot be updated, in the order of methodReferences.

IMPORTANT: Uses ZERO-BASED coordinates.

potentialMatches, present only when there are any, holds the places JDT's search reports as possible matches but cannot confirm, because a type or name there does not resolve (a missing dependency or a compile error): count is their exact number, and locations lists them, as many as the results it stands beside may list. They are never counted or listed as results.

Requires load_project to be called first.