How to use

WebService$Controller

in

org.sonar.api.server.ws

assertThat(controller.path()).isEqualTo("api/metric");
assertThat(controller.description()).isEqualTo("Metrics");
assertThat(controller.since()).isEqualTo("3.2");
assertThat(controller.actions()).hasSize(2);
assertThat(controller.isInternal()).isFalse();
WebService.Action showAction = controller.action("show");
assertThat(showAction).isNotNull();
assertThat(showAction.key()).isEqualTo("show");
assertThat(showAction.isInternal()).isFalse();
assertThat(showAction.path()).isEqualTo("api/metric/show");
WebService.Action createAction = controller.action("create");
assertThat(createAction).isNotNull();
assertThat(createAction.key()).isEqualTo("create");

private void register(NewController newController) {
 if (controllers.containsKey(newController.path)) {
  throw new IllegalStateException(
   format("The web service '%s' is defined multiple times", newController.path));
 }
 controllers.put(newController.path, new Controller(newController));
}

private Action(Controller controller, NewAction newAction) {
 this.key = newAction.key;
 this.deprecatedKey = newAction.deprecatedKey;
 this.path = format("%s/%s", controller.path(), key);
 this.description = newAction.description;
 this.since = newAction.since;
 this.deprecatedSince = newAction.deprecatedSince;
 this.post = newAction.post;
 this.isInternal = newAction.isInternal;
 this.responseExample = newAction.responseExample;
 this.handler = newAction.handler;
 this.changelog = newAction.changelog;
 checkState(this.handler != null, "RequestHandler is not set on action %s", path);
 logWarningIf(isNullOrEmpty(this.description), "Description is not set on action " + path);
 logWarningIf(isNullOrEmpty(this.since), "Since is not set on action " + path);
 logWarningIf(!this.post && this.responseExample == null, "The response example is not set on action " + path);
 Map<String, Param> paramsBuilder = new HashMap<>();
 for (NewParam newParam : newAction.newParams.values()) {
  paramsBuilder.put(newParam.key, new Param(this, newParam));
 }
 this.params = Collections.unmodifiableMap(paramsBuilder);
}

@Override
public void handle(Request request, Response response) throws Exception {
 checkState(context != null, "Webservice global context must be loaded before calling the action");
 String controllerKey = request.mandatoryParam("controller");
 WebService.Controller controller = context.controller(controllerKey);
 checkArgument(controller != null, "Controller does not exist: %s", controllerKey);
 String actionKey = request.mandatoryParam("action");
 WebService.Action action = controller.action(actionKey);
 checkArgument(action != null, "Action does not exist: %s", actionKey);
 if (action.responseExample() == null) {
  response.noContent();
  return;
 }
 try (JsonWriter json = response.newJsonWriter()) {
  json.beginObject()
   .prop("format", action.responseExampleFormat())
   .prop("example", action.responseExampleAsString())
   .endObject();
 }
}

public WebServiceFilter(WebServiceEngine webServiceEngine, SonarRuntime runtime) {
 this.webServiceEngine = webServiceEngine;
 this.includeUrls = concat(
  Stream.of("/api/*"),
  webServiceEngine.controllers().stream()
   .flatMap(controller -> controller.actions().stream())
   .map(toPath()))
    .collect(MoreCollectors.toSet());
 this.excludeUrls = concat(concat(
  Stream.of("/" + CONTROLLER_PROPERTIES + "*"),
  MOVED_WEB_SERVICES.stream()),
  webServiceEngine.controllers().stream()
   .flatMap(controller -> controller.actions().stream())
   .filter(action -> action.handler() instanceof ServletFilterHandler)
   .map(toPath()))
    .collect(MoreCollectors.toSet());
 this.runtime = runtime;
}

private Action(Controller controller, NewAction newAction) {
 this.key = newAction.key;
 this.deprecatedKey = newAction.deprecatedKey;
 this.path = String.format("%s/%s", controller.path(), key);
 this.description = newAction.description;
 this.since = StringUtils.defaultIfBlank(newAction.since, controller.since);
 this.post = newAction.post;
 this.isInternal = newAction.isInternal;
 this.responseExample = newAction.responseExample;
 if (newAction.handler == null) {
  throw new IllegalArgumentException("RequestHandler is not set on action " + path);
 }
 this.handler = newAction.handler;
 ImmutableMap.Builder<String, Param> paramsBuilder = ImmutableMap.builder();
 for (NewParam newParam : newAction.newParams.values()) {
  paramsBuilder.put(newParam.key, new Param(this, newParam));
 }
 this.params = paramsBuilder.build();
}

private static void writeController(JsonWriter writer, WebService.Controller controller, boolean includeInternals) {
 if (includeInternals || !controller.isInternal()) {
  writer.beginObject();
  writer.prop("path", controller.path());
  writer.prop("since", controller.since());
  writer.prop("description", controller.description());
  // sort actions by key
  Ordering<WebService.Action> ordering = Ordering.natural().onResultOf(WebService.Action::key);
  writer.name("actions").beginArray();
  for (WebService.Action action : ordering.sortedCopy(controller.actions())) {
   writeAction(writer, action, includeInternals);
  }
  writer.endArray();
  writer.endObject();
 }
}

 /**
  * Returns true if all the actions are for internal use
  *
  * @see org.sonar.api.server.ws.WebService.Action#isInternal()
  * @since 4.3
  */
 public boolean isInternal() {
  for (Action action : actions()) {
   if (!action.isInternal()) {
    return false;
   }
  }
  return true;
 }
}

 /**
  * Returns true if all the actions are for internal use
  *
  * @see org.sonar.api.server.ws.WebService.Action#isInternal()
  * @since 4.3
  */
 public boolean isInternal() {
  for (Action action : actions()) {
   if (!action.isInternal()) {
    return false;
   }
  }
  return true;
 }
}

@CheckForNull
private WebService.Action getAction(ActionExtractor actionExtractor) {
 String controllerPath = actionExtractor.getController();
 String actionKey = actionExtractor.getAction();
 WebService.Controller controller = getContext().controller(controllerPath);
 return controller == null ? null : controller.action(actionKey);
}

private void register(NewController newController) {
 if (controllers.containsKey(newController.path)) {
  throw new IllegalStateException(
   format("The web service '%s' is defined multiple times", newController.path));
 }
 controllers.put(newController.path, new Controller(newController));
}

private void register(NewController newController) {
 if (controllers.containsKey(newController.path)) {
  throw new IllegalStateException(
   String.format("The web service '%s' is defined multiple times", newController.path));
 }
 controllers.put(newController.path, new Controller(newController));
}

}).define(context);
WebService.Action action = context.controller("api/rule").action("create");
assertThat(action.params()).hasSize(8);

WebService.Controller controller = tester.controller("api/sources");
assertThat(controller).isNotNull();
assertThat(controller.since()).isEqualTo("4.2");
assertThat(controller.description()).isNotEmpty();
assertThat(controller.actions()).hasSize(4);
WebService.Action show = controller.action("show");
assertThat(show).isNotNull();
assertThat(show.handler()).isSameAs(showAction);
assertThat(show.params()).hasSize(3);
WebService.Action raw = controller.action("raw");
assertThat(raw).isNotNull();
assertThat(raw.handler()).isSameAs(rawAction);
assertThat(raw.params()).hasSize(3);
WebService.Action lines = controller.action("lines");
assertThat(lines).isNotNull();
assertThat(lines.handler()).isSameAs(linesAction);
assertThat(lines.params()).hasSize(6);
WebService.Action hash = controller.action("hash");
assertThat(hash).isNotNull();
assertThat(hash.handler()).isSameAs(hashAction);

@Test
public void param_metadata_as_objects() {
 ((WebService) context -> {
  NewController newController = context.createController("api/rule");
  NewAction create = newDefaultAction(newController, "create");
  create.createParam("status")
   .setDefaultValue(RuleStatus.BETA)
   .setPossibleValues(RuleStatus.BETA, RuleStatus.READY)
   .setExampleValue(RuleStatus.BETA);
  create.createParam("max")
   .setDefaultValue(11)
   .setPossibleValues(11, 13, 17)
   .setExampleValue(17);
  newController.done();
 }).define(context);
 WebService.Action action = context.controller("api/rule").action("create");
 assertThat(action.param("status").defaultValue()).isEqualTo("BETA");
 assertThat(action.param("status").possibleValues()).containsOnly("BETA", "READY");
 assertThat(action.param("status").exampleValue()).isEqualTo("BETA");
 assertThat(action.param("max").defaultValue()).isEqualTo("11");
 assertThat(action.param("max").possibleValues()).containsOnly("11", "13", "17");
 assertThat(action.param("max").exampleValue()).isEqualTo("17");
}

 @Test
 public void define_ws() {
  WebService.Controller controller = tester.controller("api/authentication");
  assertThat(controller).isNotNull();
  assertThat(controller.description()).isNotEmpty();
  assertThat(controller.actions()).hasSize(3);

  WebService.Action validate = controller.action("validate");
  assertThat(validate).isNotNull();
  assertThat(validate.handler()).isInstanceOf(ServletFilterHandler.class);
  assertThat(validate.responseExampleAsString()).isNotEmpty();
  assertThat(validate.params()).isEmpty();

  WebService.Action login = controller.action("login");
  assertThat(login).isNotNull();
  assertThat(login.handler()).isInstanceOf(ServletFilterHandler.class);
  assertThat(login.isPost()).isTrue();
  assertThat(login.params()).hasSize(2);

  WebService.Action logout = controller.action("logout");
  assertThat(logout).isNotNull();
  assertThat(logout.handler()).isInstanceOf(ServletFilterHandler.class);
  assertThat(logout.isPost()).isTrue();
  assertThat(logout.params()).isEmpty();
 }
}

private Action(Controller controller, NewAction newAction) {
 this.key = newAction.key;
 this.deprecatedKey = newAction.deprecatedKey;
 this.path = format("%s/%s", controller.path(), key);
 this.description = newAction.description;
 this.since = newAction.since;
 this.deprecatedSince = newAction.deprecatedSince;
 this.post = newAction.post;
 this.isInternal = newAction.isInternal;
 this.responseExample = newAction.responseExample;
 this.handler = newAction.handler;
 this.changelog = newAction.changelog;
 checkState(this.handler != null, "RequestHandler is not set on action %s", path);
 logWarningIf(isNullOrEmpty(this.description), "Description is not set on action " + path);
 logWarningIf(isNullOrEmpty(this.since), "Since is not set on action " + path);
 logWarningIf(!this.post && this.responseExample == null, "The response example is not set on action " + path);
 Map<String, Param> paramsBuilder = new HashMap<>();
 for (NewParam newParam : newAction.newParams.values()) {
  paramsBuilder.put(newParam.key, new Param(this, newParam));
 }
 this.params = Collections.unmodifiableMap(paramsBuilder);
}

@Test
public void fail_to_open_response_example() {
 WebService ws = context -> {
  try {
   NewController controller = context.createController("foo");
   newDefaultAction(controller, "bar").setResponseExample(new URL("file:/does/not/exist"));
   controller.done();
  } catch (MalformedURLException e) {
   e.printStackTrace();
  }
 };
 ws.define(context);
 WebService.Action action = context.controller("foo").action("bar");
 try {
  action.responseExampleAsString();
  fail();
 } catch (IllegalStateException e) {
  assertThat(e).hasMessage("Fail to load file:/does/not/exist");
 }
}

private void initWebServiceEngine(WsUrl... wsUrls) {
 List<WebService.Controller> controllers = new ArrayList<>();
 for (WsUrl wsUrl : wsUrls) {
  String controller = wsUrl.getController();
  WebService.Controller wsController = mock(WebService.Controller.class);
  when(wsController.path()).thenReturn(controller);
  List<WebService.Action> actions = new ArrayList<>();
  for (String action : wsUrl.getActions()) {
   WebService.Action wsAction = mock(WebService.Action.class);
   when(wsAction.path()).thenReturn(controller + "/" + action);
   when(wsAction.key()).thenReturn(action);
   when(wsAction.handler()).thenReturn(wsUrl.getRequestHandler());
   actions.add(wsAction);
  }
  when(wsController.actions()).thenReturn(actions);
  controllers.add(wsController);
 }
 when(webServiceEngine.controllers()).thenReturn(controllers);
 underTest = new WebServiceFilter(webServiceEngine, runtime);
}

@Test
public void action_uninstall_is_defined() {
 logInAsSystemAdministrator();
 WsTester wsTester = new WsTester();
 WebService.NewController newController = wsTester.context().createController(DUMMY_CONTROLLER_KEY);
 underTest.define(newController);
 newController.done();
 WebService.Controller controller = wsTester.controller(DUMMY_CONTROLLER_KEY);
 assertThat(controller.actions()).extracting("key").containsExactly(ACTION_KEY);
 WebService.Action action = controller.actions().iterator().next();
 assertThat(action.isPost()).isTrue();
 assertThat(action.description()).isNotEmpty();
 assertThat(action.responseExample()).isNull();
 assertThat(action.params()).hasSize(1);
 WebService.Param keyParam = action.param(KEY_PARAM);
 assertThat(keyParam).isNotNull();
 assertThat(keyParam.isRequired()).isTrue();
 assertThat(keyParam.description()).isNotNull();
}