Add RestController method for deprecating in one step

This adds an extra method, registerWithDeprecatedHandler, to register both a normal handler and a deprecated handler at the same time. This helps with renaming methods as opposed to _just_ deprecated methods.

core/src/main/java/org/elasticsearch/rest/RestController.java

@@ -128,6 +128,42 @@ public class RestController extends AbstractLifecycleComponent {
         registerHandler(method, path, new DeprecationRestHandler(handler, deprecationMessage, logger));
     }
 
+    /**
+     * Registers a REST handler to be executed when the provided {@code method} and {@code path} match the request, or when provided
+     * with {@code deprecatedMethod} and {@code deprecatedPath}. Expected usage:
+     * <pre><code>
+     * // remove deprecation in next major release
+     * controller.registerWithDeprecatedHandler(POST, "/_forcemerge", this,
+     *                                          POST, "/_optimize", deprecationLogger);
+     * controller.registerWithDeprecatedHandler(POST, "/{index}/_forcemerge", this,
+     *                                          POST, "/{index}/_optimize", deprecationLogger);
+     * </code></pre>
+     * <p>
+     * The registered REST handler ({@code method} with {@code path}) is a normal REST handler that is not deprecated and it is
+     * replacing the deprecated REST handler ({@code deprecatedMethod} with {@code deprecatedPath}) that is using the <em>same</em>
+     * {@code handler}.
+     * <p>
+     * Deprecated REST handlers without a direct replacement should be deprecated directly using {@link #registerAsDeprecatedHandler}
+     * and a specific message.
+     *
+     * @param method GET, POST, etc.
+     * @param path Path to handle (e.g., "/_forcemerge")
+     * @param handler The handler to actually execute
+     * @param deprecatedMethod GET, POST, etc.
+     * @param deprecatedPath <em>Deprecated</em> path to handle (e.g., "/_optimize")
+     * @param logger The existing deprecation logger to use
+     */
+    public void registerWithDeprecatedHandler(RestRequest.Method method, String path, RestHandler handler,
+                                              RestRequest.Method deprecatedMethod, String deprecatedPath,
+                                              DeprecationLogger logger) {
+        // e.g., [POST /_optimize] is deprecated! Use [POST /_forcemerge] instead.
+        final String deprecationMessage =
+            "[" + deprecatedMethod.name() + " " + deprecatedPath + "] is deprecated! Use [" + method.name() + " " + path + "] instead.";
+
+        registerHandler(method, path, handler);
+        registerAsDeprecatedHandler(deprecatedMethod, deprecatedPath, handler, deprecationMessage, logger);
+    }
+
     /**
      * Registers a REST handler to be executed when the provided method and path match the request.
      *

core/src/test/java/org/elasticsearch/rest/RestControllerTests.java

@@ -116,7 +116,7 @@ public class RestControllerTests extends ESTestCase {
         assertFalse(controller.canTripCircuitBreaker(new FakeRestRequest.Builder().withPath("/do-not-trip").build()));
     }
 
-    public void testRegisterHandlerAsDeprecationHandler() {
+    public void testRegisterAsDeprecatedHandler() {
         RestController controller = mock(RestController.class);
 
         RestRequest.Method method = randomFrom(RestRequest.Method.values());
@@ -133,6 +133,28 @@ public class RestControllerTests extends ESTestCase {
         verify(controller).registerHandler(eq(method), eq(path), any(DeprecationRestHandler.class));
     }
 
+    public void testRegisterWithDeprecatedHandler() {
+        final RestController controller = mock(RestController.class);
+
+        final RestRequest.Method method = randomFrom(RestRequest.Method.values());
+        final String path = "/_" + randomAsciiOfLengthBetween(1, 6);
+        final RestHandler handler = mock(RestHandler.class);
+        final RestRequest.Method deprecatedMethod = randomFrom(RestRequest.Method.values());
+        final String deprecatedPath = "/_" + randomAsciiOfLengthBetween(1, 6);
+        final DeprecationLogger logger = mock(DeprecationLogger.class);
+
+        final String deprecationMessage = "[" + deprecatedMethod.name() + " " + deprecatedPath + "] is deprecated! Use [" +
+            method.name() + " " + path + "] instead.";
+
+        // don't want to test everything -- just that it actually wraps the handlers
+        doCallRealMethod().when(controller).registerWithDeprecatedHandler(method, path, handler, deprecatedMethod, deprecatedPath, logger);
+
+        controller.registerWithDeprecatedHandler(method, path, handler, deprecatedMethod, deprecatedPath, logger);
+
+        verify(controller).registerHandler(method, path, handler);
+        verify(controller).registerAsDeprecatedHandler(deprecatedMethod, deprecatedPath, handler, deprecationMessage, logger);
+    }
+
     /**
      * Useful for testing with deprecation handler.
      */