SONAR-6948 Ability for Java server extensions to call web services

7 files changed, 152 insertions, 22 deletions

diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/LocalConnector.java b/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/LocalConnector.java
new file mode 100644
index 00000000000..cf4075d61d8
--- /dev/null
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/LocalConnector.java
@@ -0,0 +1,113 @@
+/*
+ * SonarQube
+ * Copyright (C) 2009-2016 SonarSource SA
+ * mailto:contact AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3 of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ */
+package org.sonar.api.server.ws;
+
+import com.google.common.annotations.Beta;
+import java.util.Collection;
+import javax.annotation.CheckForNull;
+
+/**
+ * This class allows a web service to call another web service through the sonar-ws library.
+ * The call is in-process, synchronous and does not involve the HTTP stack.
+ * <p>
+ * Example of a web service that uses sonar-ws 5.5 to get some issues:
+ * <pre>
+ * import org.sonar.api.server.ws.RequestHandler;
+ * import org.sonarqube.ws.client.WsClientFactories;
+ *
+ * public class MyRequestHandler implements RequestHandler {
+ *   {@literal @}Override
+ *   public void handle(Request request, Response response) {
+ *     WsClient wsClient = WsClientFactories.getLocal().newClient(request.getLocalConnector());
+ *     SearchWsResponse issues = wsClient.issues().search(new SearchWsRequest());
+ *     // ...
+ *   }
+ * }
+ * </pre>
+ * </p>
+ * @since 5.5
+ */
+@Beta
+public interface LocalConnector {
+
+  LocalResponse call(LocalRequest request);
+
+  interface LocalRequest {
+    /**
+     * URL path, which is the concatenation of controller path and action key, for example "api/issues/search"
+     * @see org.sonar.api.server.ws.WebService.Controller#path
+     * @see org.sonar.api.server.ws.WebService.Action#key
+     */
+    String getPath();
+
+    /**
+     * @see Request#getMediaType()
+     */
+    String getMediaType();
+
+    /**
+     * HTTP method. Possible values are "GET" and "POST"
+     * @see Request#method()
+     */
+    String getMethod();
+
+    /**
+     * @see Request#hasParam(String)
+     */
+    boolean hasParam(String key);
+
+    /**
+     * @see Request#param(String)
+     */
+    @CheckForNull
+    String getParam(String key);
+  }
+
+  interface LocalResponse {
+    /**
+     * @see org.sonar.api.server.ws.Response.Stream#setStatus(int)
+     */
+    int getStatus();
+
+    /**
+     * @see org.sonar.api.server.ws.Response.Stream#setMediaType(String)
+     */
+    String getMediaType();
+
+    /**
+     * Response body
+     */
+    byte[] getBytes();
+
+    /**
+     * HTTP headers
+     * @see Response#setHeader(String, String)
+     */
+    Collection<String> getHeaderNames();
+
+    /**
+     * @see Response#setHeader(String, String)
+     * @return
+     */
+    @CheckForNull
+    String getHeader(String name);
+  }
+
+}
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/Request.java b/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/Request.java
index 52d6c06003c..fdc54cee2b0 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/Request.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/Request.java
@@ -19,6 +19,7 @@
  */
 package org.sonar.api.server.ws;
 
+import com.google.common.annotations.Beta;
 import com.google.common.base.Splitter;
 import com.google.common.collect.Lists;
 import java.io.InputStream;
@@ -234,4 +235,12 @@ public abstract class Request {
     }
     throw new IllegalArgumentException(String.format("Property %s is not a boolean value: %s", key, value));
   }
+
+  /**
+   * Used by the sonar-ws library to allow a web service to call another web service.
+   * @see LocalConnector
+   * @since 5.5
+   */
+  @Beta
+  public abstract LocalConnector getLocalConnector();
 }
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/RequestHandler.java b/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/RequestHandler.java
index a100a9399e0..8b7db8953d8 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/RequestHandler.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/RequestHandler.java
@@ -23,7 +23,9 @@ import org.sonar.api.ExtensionPoint;
 import org.sonar.api.server.ServerSide;
 
 /**
+ * Extension point to execute a HTTP request.
  * @since 4.2
+ * @see WebService
  */
 @ServerSide
 @ExtensionPoint
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/Response.java b/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/Response.java
index fcd239bd16b..72aabd1d300 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/Response.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/Response.java
@@ -34,6 +34,11 @@ public interface Response {
 
   interface Stream {
     Stream setMediaType(String s);
+
+    /**
+     * HTTP status code. See https://en.wikipedia.org/wiki/List_of_HTTP_status_codes.
+     * By default value is set to 200.
+     */
     Stream setStatus(int httpStatus);
     OutputStream output();
   }
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/WebService.java b/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/WebService.java
index 260df6f9722..4dedab64d5a 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/WebService.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/WebService.java
@@ -87,28 +87,6 @@ import static java.lang.String.format;
  *   }
  * }
  * </pre>
- * <h3>How to test</h3>
- * <pre>
- * public class HelloWsTest {
- *   WebService ws = new HelloWs();
- *
- *   {@literal @}Test
- *   public void should_define_ws() throws Exception {
- *     // WsTester is available in the Maven artifact org.codehaus.sonar:sonar-testing-harness
- *     WsTester tester = new WsTester(ws);
- *     WebService.Controller controller = tester.controller("api/hello");
- *     assertThat(controller).isNotNull();
- *     assertThat(controller.path()).isEqualTo("api/hello");
- *     assertThat(controller.description()).isNotEmpty();
- *     assertThat(controller.actions()).hasSize(1);
- *
- *     WebService.Action show = controller.action("show");
- *     assertThat(show).isNotNull();
- *     assertThat(show.key()).isEqualTo("show");
- *     assertThat(index.handler()).isNotNull();
- *   }
- * }
- * </pre>
  *
  * @since 4.2
  */
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/internal/SimpleGetRequest.java b/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/internal/SimpleGetRequest.java
index adcf432f8fa..f08816d5bd7 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/internal/SimpleGetRequest.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/internal/SimpleGetRequest.java
@@ -24,6 +24,7 @@ import java.io.InputStream;
 import java.util.Map;
 import javax.annotation.Nullable;
 import org.apache.commons.io.IOUtils;
+import org.sonar.api.server.ws.LocalConnector;
 import org.sonar.api.server.ws.Request;
 
 import static com.google.common.base.Preconditions.checkNotNull;
@@ -76,4 +77,12 @@ public class SimpleGetRequest extends Request {
     return this;
   }
 
+  public Map<String, String> getParams() {
+    return params;
+  }
+
+  @Override
+  public LocalConnector getLocalConnector() {
+    throw new UnsupportedOperationException();
+  }
 }
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/internal/ValidatingRequest.java b/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/internal/ValidatingRequest.java
index 436d8b33032..f38a1bed2e2 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/internal/ValidatingRequest.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/internal/ValidatingRequest.java
@@ -29,16 +29,20 @@ import java.util.Set;
 import javax.annotation.CheckForNull;
 import javax.annotation.Nullable;
 import org.apache.commons.lang.StringUtils;
+import org.sonar.api.server.ws.LocalConnector;
 import org.sonar.api.server.ws.Request;
 import org.sonar.api.server.ws.WebService;
 import org.sonar.api.utils.log.Loggers;
 
+import static com.google.common.base.Preconditions.checkNotNull;
+
 /**
  * @since 4.2
  */
 public abstract class ValidatingRequest extends Request {
 
   private WebService.Action action;
+  private LocalConnector localConnector;
 
   public void setAction(WebService.Action action) {
     this.action = action;
@@ -49,6 +53,16 @@ public abstract class ValidatingRequest extends Request {
   }
 
   @Override
+  public LocalConnector getLocalConnector() {
+    checkNotNull(localConnector, "Local connector has not been set");
+    return localConnector;
+  }
+
+  public void setLocalConnector(LocalConnector lc) {
+    this.localConnector = lc;
+  }
+
+  @Override
   @CheckForNull
   public String param(String key) {
     return param(key, true);