001/*
002 * SonarQube
003 * Copyright (C) 2009-2017 SonarSource SA
004 * mailto:info AT sonarsource DOT com
005 *
006 * This program is free software; you can redistribute it and/or
007 * modify it under the terms of the GNU Lesser General Public
008 * License as published by the Free Software Foundation; either
009 * version 3 of the License, or (at your option) any later version.
010 *
011 * This program is distributed in the hope that it will be useful,
012 * but WITHOUT ANY WARRANTY; without even the implied warranty of
013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014 * Lesser General Public License for more details.
015 *
016 * You should have received a copy of the GNU Lesser General Public License
017 * along with this program; if not, write to the Free Software Foundation,
018 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
019 */
020package org.sonar.api.server.ws;
021
022import com.google.common.annotations.Beta;
023import java.util.Collection;
024import java.util.List;
025import javax.annotation.CheckForNull;
026
027/**
028 * This class allows a web service to call another web service through the sonar-ws library.
029 * The call is in-process, synchronous and does not involve the HTTP stack.
030 * <p>
031 * Example of a web service that loads some issues:
032 * <pre>
033 * import org.sonar.api.server.ws.RequestHandler;
034 * import org.sonarqube.ws.client.WsClientFactories;
035 *
036 * public class MyRequestHandler implements RequestHandler {
037 *   {@literal @}Override
038 *   public void handle(Request request, Response response) {
039 *     WsClient wsClient = WsClientFactories.getLocal().newClient(request.localConnector());
040 *     SearchWsResponse issues = wsClient.issues().search(new SearchWsRequest());
041 *     // ...
042 *   }
043 * }
044 * </pre>
045 *
046 * It requires to use the sonar-ws library which Maven ids are:
047 * <pre>
048 *   &lt;dependency&gt;
049 *     &lt;groupId&gt;org.sonarsource.sonarqube&lt;/groupId&gt;
050 *     &lt;artifactId&gt;sonar-ws&lt;/artifactId&gt;
051 *   &lt;/dependency&gt;
052 * </pre>
053 * 
054 * @since 5.5
055 */
056@Beta
057public interface LocalConnector {
058
059  LocalResponse call(LocalRequest request);
060
061  interface LocalRequest {
062    /**
063     * URL path, which is the concatenation of controller path and action key, for example "api/issues/search"
064     * @see org.sonar.api.server.ws.WebService.Controller#path
065     * @see org.sonar.api.server.ws.WebService.Action#key
066     */
067    String getPath();
068
069    /**
070     * @see Request#getMediaType()
071     */
072    String getMediaType();
073
074    /**
075     * HTTP method. Possible values are "GET" and "POST"
076     * @see Request#method()
077     */
078    String getMethod();
079
080    /**
081     * @see Request#hasParam(String)
082     */
083    boolean hasParam(String key);
084
085    /**
086     * @see Request#param(String)
087     */
088    @CheckForNull
089    String getParam(String key);
090
091    /**
092     * @see Request#multiParam(String)
093     */
094    List<String> getMultiParam(String key);
095  }
096
097  interface LocalResponse {
098    /**
099     * @see org.sonar.api.server.ws.Response.Stream#setStatus(int)
100     */
101    int getStatus();
102
103    /**
104     * @see org.sonar.api.server.ws.Response.Stream#setMediaType(String)
105     */
106    String getMediaType();
107
108    /**
109     * Response body
110     */
111    byte[] getBytes();
112
113    /**
114     * HTTP headers
115     * @see Response#setHeader(String, String)
116     */
117    Collection<String> getHeaderNames();
118
119    /**
120     * @see Response#setHeader(String, String)
121     */
122    @CheckForNull
123    String getHeader(String name);
124  }
125
126}