SONAR-5264 Force documentation of web services to be up-to-date

2 files changed, 120 insertions, 39 deletions

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 eacbb069512..792fa6837da 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
@@ -22,16 +22,27 @@ package org.sonar.api.server.ws;
 import com.google.common.base.Splitter;
 import com.google.common.collect.Lists;
 import org.apache.commons.lang.StringUtils;
+import org.slf4j.LoggerFactory;
 
 import javax.annotation.CheckForNull;
+import javax.annotation.Nullable;
 import java.util.List;
+import java.util.Set;
 
 /**
  * @since 4.2
  */
 public abstract class Request {
 
-  public abstract WebService.Action action();
+  private WebService.Action action;
+
+  protected void setAction(WebService.Action action) {
+    this.action = action;
+  }
+
+  public WebService.Action action() {
+    return action;
+  }
 
   /**
    * Returns the name of the HTTP method with which this request was made. Possible
@@ -40,20 +51,20 @@ public abstract class Request {
   public abstract String method();
 
   /**
-   * Returns value of a mandatory parameter
+   * Returns a non-null value. To be used when parameter is required or has a default value.
    *
    * @throws java.lang.IllegalArgumentException is value is null or blank
    */
   public String mandatoryParam(String key) {
     String value = param(key);
-    if (StringUtils.isBlank(value)) {
+    if (value == null) {
       throw new IllegalArgumentException(String.format("Parameter '%s' is missing", key));
     }
     return value;
   }
 
   /**
-   * Returns value of a mandatory parameter
+   * Returns a boolean value. To be used when parameter is required or has a default value.
    *
    * @throws java.lang.IllegalArgumentException is value is null or blank
    */
@@ -63,7 +74,7 @@ public abstract class Request {
   }
 
   /**
-   * Returns value of a mandatory parameter
+   * Returns an int value. To be used when parameter is required or has a default value.
    *
    * @throws java.lang.IllegalArgumentException is value is null or blank
    */
@@ -73,7 +84,7 @@ public abstract class Request {
   }
 
   /**
-   * Returns value of a mandatory parameter
+   * Returns a long value. To be used when parameter is required or has a default value.
    *
    * @throws java.lang.IllegalArgumentException is value is null or blank
    */
@@ -82,53 +93,123 @@ public abstract class Request {
     return Long.parseLong(s);
   }
 
+  public List<String> mandatoryParamAsStrings(String key) {
+    List<String> values = paramAsStrings(key);
+    if (values == null) {
+      throw new IllegalArgumentException(String.format("Parameter '%s' is missing", key));
+    }
+    return values;
+  }
+
   @CheckForNull
-  public abstract String param(String key);
+  public String param(String key) {
+    return param(key, true);
+  }
 
   @CheckForNull
-  public String param(String key, @CheckForNull String defaultValue) {
-    return StringUtils.defaultString(param(key), defaultValue);
+  String param(String key, boolean validateValue) {
+    WebService.Param definition = action.param(key);
+    String value = readParamOrDefaultValue(key, definition);
+    if (value != null && validateValue) {
+      validate(value, definition);
+    }
+    return value;
   }
 
   @CheckForNull
   public List<String> paramAsStrings(String key) {
-    String s = param(key);
-    if (s == null) {
+    WebService.Param definition = action.param(key);
+    String value = readParamOrDefaultValue(key, definition);
+    if (value == null) {
       return null;
     }
-    return Lists.newArrayList(Splitter.on(',').omitEmptyStrings().trimResults().split(s));
+    List<String> values = Lists.newArrayList(Splitter.on(',').omitEmptyStrings().trimResults().split(value));
+    for (String s : values) {
+      validate(s, definition);
+    }
+    return values;
   }
 
   @CheckForNull
-  public Integer paramAsInt(String key) {
-    String s = param(key);
-    return s == null ? null : Integer.parseInt(s);
+  private String readParamOrDefaultValue(String key, @Nullable WebService.Param definition) {
+    if (definition == null) {
+      String message = String.format("BUG - parameter '%s' is undefined for action '%s'", key, action.key());
+      LoggerFactory.getLogger(getClass()).error(message);
+      throw new IllegalArgumentException(message);
+    }
+    String value = StringUtils.defaultString(readParam(key), definition.defaultValue());
+    if (value == null) {
+      return null;
+    }
+    return value;
   }
 
-  public int paramAsInt(String key, int defaultValue) {
-    String s = param(key);
-    return s == null ? defaultValue : Integer.parseInt(s);
+  @CheckForNull
+  protected abstract String readParam(String key);
+
+  private void validate(String value, WebService.Param definition) {
+    Set<String> possibleValues = definition.possibleValues();
+    if (possibleValues != null && !possibleValues.contains(value)) {
+      throw new IllegalArgumentException(String.format(
+        "Value of parameter '%s' (%s) must be one of: %s", definition.key(), value, possibleValues));
+    }
   }
 
+  /**
+   * @deprecated to be dropped in 4.4. Default values are declared in ws metadata
+   */
   @CheckForNull
-  public Long paramAsLong(String key) {
+  @Deprecated
+  public String param(String key, @CheckForNull String defaultValue) {
+    return StringUtils.defaultString(param(key), defaultValue);
+  }
+
+  /**
+   * @deprecated to be dropped in 4.4. Default values must be declared in {@link org.sonar.api.server.ws.WebService} then
+   * this method can be replaced by {@link #mandatoryParamAsBoolean(String)}.
+   */
+  @Deprecated
+  public boolean paramAsBoolean(String key, boolean defaultValue) {
     String s = param(key);
-    return s == null ? null : Long.parseLong(s);
+    return s == null ? defaultValue : Boolean.parseBoolean(s);
+  }
+
+  /**
+   * @deprecated to be dropped in 4.4. Default values must be declared in {@link org.sonar.api.server.ws.WebService} then
+   * this method can be replaced by {@link #mandatoryParamAsInt(String)}.
+   */
+  @Deprecated
+  public int paramAsInt(String key, int defaultValue) {
+    String s = param(key);
+    return s == null ? defaultValue : Integer.parseInt(s);
   }
 
+  /**
+   * @deprecated to be dropped in 4.4. Default values must be declared in {@link org.sonar.api.server.ws.WebService} then
+   * this method can be replaced by {@link #mandatoryParamAsLong(String)}.
+   */
+  @Deprecated
   public long paramAsLong(String key, long defaultValue) {
     String s = param(key);
     return s == null ? defaultValue : Long.parseLong(s);
   }
 
+
   @CheckForNull
   public Boolean paramAsBoolean(String key) {
     String s = param(key);
     return s == null ? null : Boolean.parseBoolean(s);
   }
 
-  public boolean paramAsBoolean(String key, boolean defaultValue) {
+  @CheckForNull
+  public Integer paramAsInt(String key) {
     String s = param(key);
-    return s == null ? defaultValue : Boolean.parseBoolean(s);
+    return s == null ? null : Integer.parseInt(s);
+  }
+
+  @CheckForNull
+  public Long paramAsLong(String key) {
+    String s = param(key);
+    return s == null ? null : Long.parseLong(s);
   }
 }
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 cc2803e1ba3..a5ac15ea8d1 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
@@ -23,6 +23,7 @@ import com.google.common.base.Charsets;
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableMap;
 import com.google.common.collect.Maps;
+import com.google.common.collect.Sets;
 import org.apache.commons.io.FilenameUtils;
 import org.apache.commons.io.IOUtils;
 import org.apache.commons.lang.StringUtils;
@@ -37,6 +38,7 @@ import java.util.Arrays;
 import java.util.Collection;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 
 /**
  * Defines a web service. Note that contrary to the deprecated {@link org.sonar.api.web.Webservice}
@@ -434,7 +436,7 @@ public interface WebService extends ServerExtension {
   class NewParam {
     private String key, description, exampleValue, defaultValue;
     private boolean required = false;
-    private Collection<Object> possibleValues = null;
+    private Set<String> possibleValues = null;
 
     private NewParam(String key) {
       this.key = key;
@@ -469,9 +471,8 @@ public interface WebService extends ServerExtension {
      *
      * @since 4.4
      */
-    public NewParam setPossibleValues(@Nullable Object... s) {
-      this.possibleValues = (s == null ? null : Arrays.asList(s));
-      return this;
+    public NewParam setPossibleValues(@Nullable Object... values) {
+      return setPossibleValues(values == null ? (Collection) null : Arrays.asList(values));
     }
 
     /**
@@ -480,8 +481,15 @@ public interface WebService extends ServerExtension {
      *
      * @since 4.4
      */
-    public NewParam setPossibleValues(@Nullable Collection c) {
-      this.possibleValues = c;
+    public NewParam setPossibleValues(@Nullable Collection values) {
+      if (values == null) {
+        this.possibleValues = null;
+      } else {
+        this.possibleValues = Sets.newLinkedHashSet();
+        for (Object value : values) {
+          this.possibleValues.add(value.toString());
+        }
+      }
       return this;
     }
 
@@ -503,7 +511,7 @@ public interface WebService extends ServerExtension {
   class Param {
     private final String key, description, exampleValue, defaultValue;
     private final boolean required;
-    private final List<String> possibleValues;
+    private final Set<String> possibleValues;
 
     public Param(NewParam newParam) {
       this.key = newParam.key;
@@ -511,15 +519,7 @@ public interface WebService extends ServerExtension {
       this.exampleValue = newParam.exampleValue;
       this.defaultValue = newParam.defaultValue;
       this.required = newParam.required;
-      if (newParam.possibleValues == null) {
-        this.possibleValues = null;
-      } else {
-        ImmutableList.Builder<String> builder = ImmutableList.builder();
-        for (Object possibleValue : newParam.possibleValues) {
-          builder.add(possibleValue.toString());
-        }
-        this.possibleValues = builder.build();
-      }
+      this.possibleValues = newParam.possibleValues;
     }
 
     public String key() {
@@ -552,7 +552,7 @@ public interface WebService extends ServerExtension {
      * @since 4.4
      */
     @CheckForNull
-    public List<String> possibleValues() {
+    public Set<String> possibleValues() {
       return possibleValues;
     }