SONAR-7459 new interface org.sonar.api.Plugin

It allows to check version of SonarQube to filter extensions

4 files changed, 191 insertions, 2 deletions

diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/Plugin.java b/sonar-plugin-api/src/main/java/org/sonar/api/Plugin.java
new file mode 100644
index 00000000000..ac67fe1c2bf
--- /dev/null
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/Plugin.java
@@ -0,0 +1,139 @@
+/*
+ * 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;
+
+import com.google.common.annotations.Beta;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.List;
+
+import static java.util.Arrays.asList;
+import static java.util.Objects.requireNonNull;
+
+/**
+ * Entry-point for plugins to inject extensions into SonarQube.
+ * <p>The JAR manifest must declare the name of the implementation class in the property <code>Plugin-Class</code>.
+ * This property is automatically set by sonar-packaging-maven-plugin when building plugin.</p>
+ * <p>Example of implementation:
+ * <pre>
+ * package com.mycompany.sonarqube;
+ * public class MyPlugin implements Plugin {
+ *   {@literal @}Override
+ *   public void define(Context context) {
+ *     context.addExtensions(MySensor.class, MyRules.class);
+ *     if (context.getSonarQubeVersion().isGreaterThanOrEqual(SonarQubeVersion.V5_6)) {
+ *       // Extension which supports only versions 5.6 and greater
+ *       // See org.sonar.api.SonarQubeVersion for more details.
+ *       context.addExtension(MyNewExtension.class);
+ *     }
+ *   }
+ * }
+ * </pre>
+ * </p>
+ * <p>Example of pom.xml:</p>
+ * <pre>
+ * &lt;project&gt;
+ *   ...
+ *   &lt;packaging&gt;sonar-plugin&lt;/packaging&gt;
+ *
+ *   &lt;build&gt;
+ *     &lt;plugins&gt;
+ *       &lt;plugin&gt;
+ *         &lt;groupId&gt;org.sonarsource.sonar-packaging-maven-plugin&lt;/groupId&gt;
+ *         &lt;artifactId&gt;sonar-packaging-maven-plugin&lt;/artifactId&gt;
+ *         &lt;extensions&gt;true&lt;/extensions&gt;
+ *         &lt;configuration&gt;
+ *           &lt;pluginClass&gt;com.mycompany.sonarqube.MyPlugin&lt;/pluginClass&gt;
+ *         &lt;/configuration&gt;
+ *       &lt;/plugin&gt;
+ *     &lt;/plugins&gt;
+ *   &lt;/build&gt;
+ * &lt;/project&gt;
+ * </pre>
+ *
+ * @since 5.5
+ */
+@Beta
+public interface Plugin {
+
+  class Context {
+    private final SonarQubeVersion version;
+    private final List extensions = new ArrayList();
+
+    public Context(SonarQubeVersion version) {
+      this.version = version;
+    }
+
+    public SonarQubeVersion getSonarQubeVersion() {
+      return version;
+    }
+
+    /**
+     * Add an extension as :
+     * <ul>
+     *   <li>a Class that is annotated with {@link org.sonar.api.batch.BatchSide} or {@link org.sonar.api.server.ServerSide}.
+     *   The extension will be instantiated once. Its dependencies are injected through constructor parameters.</li>
+     *   <li>an instance that is annotated with {@link org.sonar.api.batch.BatchSide} or {@link org.sonar.api.server.ServerSide}</li>
+     * </ul>
+     * Only a single component can be registered for a class. It's not allowed for example to register:
+     * <ul>
+     *   <li>two MyExtension.class</li>
+     *   <li>MyExtension.class and new MyExtension()</li>
+     * </ul>
+     */
+    public Context addExtension(Object extension) {
+      requireNonNull(extension);
+      this.extensions.add(extension);
+      return this;
+    }
+
+    /**
+     * @see #addExtension(Object)
+     */
+    public Context addExtensions(Collection extensions) {
+      this.extensions.addAll(extensions);
+      return this;
+    }
+
+    /**
+     * @see #addExtension(Object)
+     */
+    public Context addExtensions(Object first, Object second, Object... others) {
+      addExtension(first);
+      addExtension(second);
+      addExtensions(asList(others));
+      return this;
+    }
+
+    public List getExtensions() {
+      return extensions;
+    }
+  }
+
+  /**
+   * This method is executed at runtime when:
+   * <ul>
+   *   <li>Web Server starts</li>
+   *   <li>Compute Engine starts</li>
+   *   <li>Scanner starts</li>
+   * </ul>
+   */
+  void define(Context context);
+}
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/SonarPlugin.java b/sonar-plugin-api/src/main/java/org/sonar/api/SonarPlugin.java
index 823f1517b60..d9d45225532 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/SonarPlugin.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/SonarPlugin.java
@@ -29,7 +29,7 @@ import java.util.List;
  * 
  * @since 2.8
  */
-public abstract class SonarPlugin {
+public abstract class SonarPlugin implements Plugin {
 
   /**
    * Classes of the implemented extensions.
@@ -44,4 +44,8 @@ public abstract class SonarPlugin {
     return getClass().getSimpleName();
   }
 
+  @Override
+  public void define(Context context) {
+    context.addExtensions(getExtensions());
+  }
 }
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 d1544367704..260df6f9722 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
@@ -56,7 +56,7 @@ import static java.lang.String.format;
  * the ws is fully implemented in Java and does not require any Ruby on Rails code.
  * <p/>
  * <p/>
- * The classes implementing this extension point must be declared in {@link org.sonar.api.SonarPlugin#getExtensions()}.
+ * The classes implementing this extension point must be declared by {@link org.sonar.api.Plugin}.
  * <p/>
  * <h3>How to use</h3>
  * <pre>
diff --git a/sonar-plugin-api/src/test/java/org/sonar/api/PluginTest.java b/sonar-plugin-api/src/test/java/org/sonar/api/PluginTest.java
new file mode 100644
index 00000000000..204a430dde3
--- /dev/null
+++ b/sonar-plugin-api/src/test/java/org/sonar/api/PluginTest.java
@@ -0,0 +1,46 @@
+/*
+ * 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;
+
+import java.util.Arrays;
+import org.junit.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.sonar.api.SonarQubeVersion.V5_5;
+
+public class PluginTest {
+
+  @Test
+  public void test_context() {
+    Plugin.Context context = new Plugin.Context(new SonarQubeVersion(V5_5));
+
+    assertThat(context.getSonarQubeVersion().get()).isEqualTo(V5_5);
+    assertThat(context.getExtensions()).isEmpty();
+
+    context.addExtension("foo");
+    assertThat(context.getExtensions()).containsOnly("foo");
+
+    context.addExtensions(Arrays.asList("bar", "baz"));
+    assertThat(context.getExtensions()).containsOnly("foo", "bar", "baz");
+
+    context.addExtensions("one", "two", "three", "four");
+    assertThat(context.getExtensions()).containsOnly("foo", "bar", "baz", "one", "two", "three", "four");
+  }
+}