PLUGINAPI-42 Introduce HttpFilter class and deprecate ServletFilter which is using javax.servlet.*

Author: jacek-poreda-sonarsource

plugin-api/src/main/java/org/sonar/api/web/FilterChain.java

@@ -0,0 +1,44 @@
+/*
+ * Sonar Plugin API
+ * Copyright (C) 2009-2023 SonarSource SA
+ * mailto:info 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.web;
+
+import java.io.IOException;
+import org.sonar.api.server.http.HttpRequest;
+import org.sonar.api.server.http.HttpResponse;
+
+/**
+ * Filters use the FilterChain to invoke the next filter in the chain, or if the calling filter
+ * is the last filter in the chain, to invoke the resource at the end of the chain.
+ *
+ * @see HttpFilter
+ * @since 9.16
+ **/
+public interface FilterChain {
+
+  /**
+   * Causes the next filter in the chain to be invoked, or if the calling filter is the last filter
+   * in the chain, causes the resource at the end of the chain to be invoked.
+   *
+   * @param request  the request to pass along the chain.
+   * @param response the response to pass along the chain.
+   */
+  void doFilter(HttpRequest request, HttpResponse response) throws IOException;
+
+}

plugin-api/src/main/java/org/sonar/api/web/HttpFilter.java

@@ -0,0 +1,103 @@
+/*
+ * Sonar Plugin API
+ * Copyright (C) 2009-2023 SonarSource SA
+ * mailto:info 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.web;
+
+import java.io.IOException;
+
+import org.sonar.api.ExtensionPoint;
+import org.sonar.api.server.ServerSide;
+import org.sonar.api.server.http.HttpRequest;
+import org.sonar.api.server.http.HttpResponse;
+
+/**
+ * A filter is an object that performs filtering tasks on either the
+ * request to a resource (a servlet or static content), or on the response
+ * from a resource, or both..
+ *
+ * @since 9.16
+ */
+@ServerSide
+@ExtensionPoint
+public abstract class HttpFilter {
+
+  /**
+   * This method is called exactly once after instantiating the filter. The init
+   * method must complete successfully before the filter is asked to do any
+   * filtering work.
+   */
+  public void init() {
+  }
+
+
+  /**
+   * The <code>doFilter</code> method of the Filter is called by the
+   * SonarQube each time a request/response pair is passed through the
+   * chain due to a client request for a resource at the end of the chain.
+   * The FilterChain passed in to this method allows the Filter to pass
+   * on the request and response to the next entity in the chain.
+   *
+   * <p>A typical implementation of this method would follow the following
+   * pattern:
+   * <ol>
+   * <li>Examine the request
+   * <li>Optionally wrap the request object with a custom implementation to
+   * filter content or headers for input filtering
+   * <li>Optionally wrap the response object with a custom implementation to
+   * filter content or headers for output filtering
+   * <li>
+   * <ul>
+   * <li><strong>Either</strong> invoke the next entity in the chain
+   * using the FilterChain object
+   * (<code>chain.doFilter()</code>),
+   * <li><strong>or</strong> not pass on the request/response pair to
+   * the next entity in the filter chain to
+   * block the request processing
+   * </ul>
+   * <li>Directly set headers on the response after invocation of the
+   * next entity in the filter chain.
+   * </ol>
+   */
+  public abstract void doFilter(HttpRequest request, HttpResponse response, FilterChain chain) throws IOException;
+
+
+  /**
+   * Called by the SonarQube to indicate to a filter that it is being
+   * taken out of service.
+   *
+   * <p>This method is only called once all threads within the filter's
+   * doFilter method have exited or after a timeout period has passed.
+   * After the web container calls this method, it will not call the
+   * doFilter method again on this instance of the filter.
+   *
+   * <p>This method gives the filter an opportunity to clean up any
+   * resources that are being held (for example, memory, file handles,
+   * threads) and make sure that any persistent state is synchronized
+   * with the filter's current state in memory.
+   */
+  public void destroy() {
+  }
+
+  /**
+   * Override to change URL. Default is /*
+   */
+  public UrlPattern doGetPattern() {
+    return UrlPattern.builder().build();
+  }
+}

plugin-api/src/main/java/org/sonar/api/web/ServletFilter.java

@@ -28,7 +28,6 @@
 import java.util.Set;
 import java.util.function.Predicate;
 import java.util.stream.Collectors;
-import javax.servlet.Filter;
 import org.sonar.api.ExtensionPoint;
 import org.sonar.api.server.ServerSide;
 
@@ -38,11 +37,13 @@
 import static org.sonar.api.utils.Preconditions.checkArgument;
 
 /**
+ * {@code @deprecated} since 9.16. Use {@link org.sonar.api.web.HttpFilter} instead.
  * @since 3.1
  */
 @ServerSide
 @ExtensionPoint
-public abstract class ServletFilter implements Filter {
+@Deprecated(forRemoval = true, since = "9.16")
+public abstract class ServletFilter implements javax.servlet.Filter {
 
   /**
    * Override to change URL. Default is /*
@@ -65,7 +66,7 @@ private UrlPattern(Builder builder) {
       this.exclusions = unmodifiableList(new ArrayList<>(builder.exclusions));
       if (builder.inclusionPredicates.isEmpty()) {
         // because Stream#anyMatch() returns false if stream is empty
-        this.inclusionPredicates = new Predicate[] {s -> true};
+        this.inclusionPredicates = new Predicate[]{s -> true};
       } else {
         this.inclusionPredicates = builder.inclusionPredicates.stream().toArray(Predicate[]::new);
       }

plugin-api/src/main/java/org/sonar/api/web/UrlPattern.java

@@ -0,0 +1,197 @@
+/*
+ * Sonar Plugin API
+ * Copyright (C) 2009-2023 SonarSource SA
+ * mailto:info 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.web;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.HashSet;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Set;
+import java.util.function.Predicate;
+import java.util.stream.Collectors;
+
+import static java.util.Arrays.asList;
+import static java.util.Collections.unmodifiableList;
+import static org.apache.commons.lang.StringUtils.substringBeforeLast;
+import static org.sonar.api.utils.Preconditions.checkArgument;
+
+public final class UrlPattern {
+
+  private static final String MATCH_ALL = "/*";
+
+  private final List<String> inclusions;
+  private final List<String> exclusions;
+  private final Predicate<String>[] inclusionPredicates;
+  private final Predicate<String>[] exclusionPredicates;
+
+  private UrlPattern(Builder builder) {
+    this.inclusions = unmodifiableList(new ArrayList<>(builder.inclusions));
+    this.exclusions = unmodifiableList(new ArrayList<>(builder.exclusions));
+    if (builder.inclusionPredicates.isEmpty()) {
+      // because Stream#anyMatch() returns false if stream is empty
+      this.inclusionPredicates = new Predicate[]{s -> true};
+    } else {
+      this.inclusionPredicates = builder.inclusionPredicates.stream().toArray(Predicate[]::new);
+    }
+    this.exclusionPredicates = builder.exclusionPredicates.stream().toArray(Predicate[]::new);
+  }
+
+  public boolean matches(String path) {
+    return !Arrays.stream(exclusionPredicates).anyMatch(pattern -> pattern.test(path)) &&
+      Arrays.stream(inclusionPredicates).anyMatch(pattern -> pattern.test(path));
+  }
+
+  /**
+   * @since 6.0
+   */
+  public Collection<String> getInclusions() {
+    return inclusions;
+  }
+
+  /**
+   * @since 6.0
+   */
+  public Collection<String> getExclusions() {
+    return exclusions;
+  }
+
+  public String label() {
+    return "UrlPattern{" +
+      "inclusions=[" + convertPatternsToString(inclusions) + "]" +
+      ", exclusions=[" + convertPatternsToString(exclusions) + "]" +
+      '}';
+  }
+
+  private static String convertPatternsToString(List<String> input) {
+    StringBuilder output = new StringBuilder();
+    if (input.isEmpty()) {
+      return "";
+    }
+    if (input.size() == 1) {
+      return output.append(input.get(0)).toString();
+    }
+    return output.append(input.get(0)).append(", ...").toString();
+  }
+
+  /**
+   * Defines only a single inclusion pattern. This is a shortcut for {@code builder().includes(inclusionPattern).build()}.
+   */
+  public static UrlPattern create(String inclusionPattern) {
+    return builder().includes(inclusionPattern).build();
+  }
+
+  /**
+   * @since 6.0
+   */
+  public static Builder builder() {
+    return new Builder();
+  }
+
+  /**
+   * @since 6.0
+   */
+  public static class Builder {
+    private static final String WILDCARD_CHAR = "*";
+    private static final Collection<String> STATIC_RESOURCES = unmodifiableList(asList(
+      "*.css", "*.css.map", "*.ico", "*.png", "*.jpg", "*.jpeg", "*.gif", "*.svg", "*.js", "*.js.map", "*.pdf", "/json/*", "*.woff2",
+      "/static/*", "/robots.txt", "/favicon.ico", "/apple-touch-icon*", "/mstile*"));
+
+    private final Set<String> inclusions = new LinkedHashSet<>();
+    private final Set<String> exclusions = new LinkedHashSet<>();
+    private final Set<Predicate<String>> inclusionPredicates = new HashSet<>();
+    private final Set<Predicate<String>> exclusionPredicates = new HashSet<>();
+
+    private Builder() {
+    }
+
+    public static Collection<String> staticResourcePatterns() {
+      return STATIC_RESOURCES;
+    }
+
+    /**
+     * Add inclusion patterns. Supported formats are:
+     * <ul>
+     *   <li>path prefixed by / and ended by * or /*, for example "/api/foo/*", to match all paths "/api/foo" and "api/api/foo/something/else"</li>
+     *   <li>path prefixed by / and ended by .*, for example "/api/foo.*", to match exact path "/api/foo" with any suffix like "/api/foo.protobuf"</li>
+     *   <li>path prefixed by *, for example "*\/foo", to match all paths "/api/foo" and "something/else/foo"</li>
+     *   <li>path with leading slash and no wildcard, for example "/api/foo", to match exact path "/api/foo"</li>
+     * </ul>
+     */
+    public Builder includes(String... includePatterns) {
+      return includes(asList(includePatterns));
+    }
+
+    /**
+     * Add exclusion patterns. See format described in {@link #includes(String...)}
+     */
+    public Builder includes(Collection<String> includePatterns) {
+      this.inclusions.addAll(includePatterns);
+      this.inclusionPredicates.addAll(includePatterns.stream()
+        .filter(pattern -> !MATCH_ALL.equals(pattern))
+        .map(Builder::compile)
+        .collect(Collectors.toList()));
+      return this;
+    }
+
+    public Builder excludes(String... excludePatterns) {
+      return excludes(asList(excludePatterns));
+    }
+
+    public Builder excludes(Collection<String> excludePatterns) {
+      this.exclusions.addAll(excludePatterns);
+      this.exclusionPredicates.addAll(excludePatterns.stream()
+        .map(Builder::compile)
+        .collect(Collectors.toList()));
+      return this;
+    }
+
+    public UrlPattern build() {
+      return new UrlPattern(this);
+    }
+
+    private static Predicate<String> compile(String pattern) {
+      int countStars = pattern.length() - pattern.replace(WILDCARD_CHAR, "").length();
+      if (countStars == 0) {
+        checkArgument(pattern.startsWith("/"), "URL pattern must start with slash '/': %s", pattern);
+        return url -> url.equals(pattern);
+      }
+      checkArgument(countStars == 1, "URL pattern accepts only zero or one wildcard character '*': %s", pattern);
+      if (pattern.charAt(0) == '/') {
+        checkArgument(pattern.endsWith(WILDCARD_CHAR), "URL pattern must end with wildcard character '*': %s", pattern);
+        if (pattern.endsWith("/*")) {
+          String path = pattern.substring(0, pattern.length() - "/*".length());
+          return url -> url.startsWith(path);
+        }
+        if (pattern.endsWith(".*")) {
+          String path = pattern.substring(0, pattern.length() - ".*".length());
+          return url -> substringBeforeLast(url, ".").equals(path);
+        }
+        String path = pattern.substring(0, pattern.length() - "*".length());
+        return url -> url.startsWith(path);
+      }
+      checkArgument(pattern.startsWith(WILDCARD_CHAR), "URL pattern must start with wildcard character '*': %s", pattern);
+      // remove the leading *
+      String path = pattern.substring(1);
+      return url -> url.endsWith(path);
+    }
+  }
+}