SONAR-2172: New extension point - Initializer

* Rename AbstractInitializer to Initializer

* Execute Initializers before Sensors

4 files changed, 85 insertions, 29 deletions

diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/AbstractInitializer.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/Initializer.java
index 9c34f2869c9..fa52021df9f 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/AbstractInitializer.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/Initializer.java
@@ -19,24 +19,28 @@
  */
 package org.sonar.api.batch;
 
-import org.sonar.api.batch.Phase.Name;
+import org.sonar.api.BatchExtension;
 import org.sonar.api.resources.Project;
 
 /**
+ * <p>
+ * Initializer can execute external tool (like a Maven plugin), change project configuration. For example CoberturaMavenInitializer invokes
+ * the Codehaus Cobertura Mojo and sets path to Cobertura report according to Maven POM.
+ * </p>
+ * 
+ * <p>
+ * Initializers are executed first and once during project analysis.
+ * </p>
+ * 
  * @since 2.6
  */
-@Phase(name = Name.PRE)
-public abstract class AbstractInitializer implements Sensor {
+public abstract class Initializer implements BatchExtension, CheckProject {
 
   public boolean shouldExecuteOnProject(Project project) {
     return true;
   }
 
-  public void analyse(Project project, SensorContext context) {
-    prepare(project);
-  }
-
-  public abstract void prepare(Project project);
+  public abstract void execute(Project project);
 
   @Override
   public String toString() {
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/Sensor.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/Sensor.java
index ee50d58e49e..e8d9791d2cb 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/Sensor.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/Sensor.java
@@ -23,38 +23,41 @@ import org.sonar.api.BatchExtension;
 import org.sonar.api.resources.Project;
 
 /**
- * <p>A Sensor is invoked once during the analysis of a project. The sensor can invoke a maven plugin,
- * parse a flat file, connect to a web server... For example the Cobertura Sensor invokes the Codehaus Cobertura MOJO.
- * Then the generated XML file is parsed and used to save the first-level of measures on resources
- * (project, package or class).</p>
- *
- * <p>Sensors are executed first during project analysis. Sensor are generally used to add measure at the
- * lowest level of the resource tree. A sensor can access and save measures on the whole tree of resources.</p>
- *
- * <p>A particular attention should be given to resource exclusion. Sonar already manages exclusions at file level : if
- * you try to save a measure on a resource that is excluded in the settings, then Sonar will not save the measure.
- * When handling a plugin or an external tool, you should make sure that exclusions are passed if you are going to get
- * back consolidated data.</p>
- *
+ * <p>
+ * A Sensor is invoked once during the analysis of a project. The sensor can parse a flat file, connect to a web server... Sensor are
+ * generally used to add measure at the lowest level of the resource tree. A sensor can access and save measures on the whole tree of
+ * resources.
+ * </p>
+ * 
+ * <p>
+ * For example the Cobertura Sensor parses Cobertura report and saves the first-level of measures on resources.
+ * </p>
+ * 
+ * <p>
+ * A particular attention should be given to resource exclusion. Sonar already manages exclusions at file level : if you try to save a
+ * measure on a resource that is excluded in the settings, then Sonar will not save the measure. When handling a plugin or an external tool,
+ * you should make sure that exclusions are passed if you are going to get back consolidated data.
+ * </p>
+ * 
  * @since 1.10
  */
 public interface Sensor extends BatchExtension, CheckProject {
 
   /**
    * Sensors that depend upon Squid must declare the following method :
-   * <code>
-   *
-   * @DependsUpon public String dependsUponSquidAnalysis() {
-   * return Sensor.FLAG_SQUID_ANALYSIS;
-   * }
-   * </code>
+   * 
+   * <pre>
+   * &#064;DependsUpon
+   * public String dependsUponSquidAnalysis() {
+   *   return Sensor.FLAG_SQUID_ANALYSIS;
    * }
+   * </pre>
    */
   String FLAG_SQUID_ANALYSIS = "squid";
 
   /**
    * The method that is going to be run when the sensor is called
-   *
+   * 
    * @param project the project the sensor runs on
    * @param context the context
    */
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/maven/DependsUponMavenPlugin.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/maven/DependsUponMavenPlugin.java
index 11ea8d00f75..f58e5f7dc30 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/maven/DependsUponMavenPlugin.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/maven/DependsUponMavenPlugin.java
@@ -24,7 +24,13 @@ import org.sonar.api.batch.SupportedEnvironment;
 import org.sonar.api.resources.Project;
 
 /**
- * Used for Sensors and PostJobs only.
+ * Can be used only for {@link org.sonar.api.batch.Initializer Initializers}, {@link org.sonar.api.batch.Sensor Sensors} and
+ * {@link org.sonar.api.batch.PostJob PostJobs}.
+ * 
+ * <p>
+ * If extension implements this interface, then it would be available only when Sonar executed from Maven. So we recommend to use this
+ * interface for Initializers instead of Sensors.
+ * </p>
  * 
  * @since 1.10
  */
diff --git a/sonar-plugin-api/src/test/java/org/sonar/api/batch/InitializerTest.java b/sonar-plugin-api/src/test/java/org/sonar/api/batch/InitializerTest.java
new file mode 100644
index 00000000000..7dd85e996dc
--- /dev/null
+++ b/sonar-plugin-api/src/test/java/org/sonar/api/batch/InitializerTest.java
@@ -0,0 +1,43 @@
+/*
+ * Sonar, open source software quality management tool.
+ * Copyright (C) 2008-2011 SonarSource
+ * mailto:contact AT sonarsource DOT com
+ *
+ * Sonar 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.
+ *
+ * Sonar 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 Sonar; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02
+ */
+package org.sonar.api.batch;
+
+import static org.hamcrest.Matchers.is;
+import static org.junit.Assert.assertThat;
+import static org.mockito.Mockito.mock;
+
+import org.junit.Test;
+import org.sonar.api.resources.Project;
+
+public class InitializerTest {
+
+  @Test
+  public void shouldBeExecutedByDefault() {
+    Project project = mock(Project.class);
+    assertThat(new FakeInitializer().shouldExecuteOnProject(project), is(true));
+  }
+
+  private class FakeInitializer extends Initializer {
+    @Override
+    public void execute(Project project) {
+    }
+  }
+
+}