From b738fdefddbf88842e3a7ef22f98bfe8c5ca1e11 Mon Sep 17 00:00:00 2001
From: simonbrandhof <simon.brandhof@gmail.com>
Date: Thu, 28 Apr 2011 12:55:50 +0200
Subject: Define new constants in DecoratorBarriers

START_VIOLATION_TRACKING and END_OF_VIOLATION_TRACKING are used to benefit from tracking data of Violation :

- Violation#isSwitchedOff()
- Violation#getCreatedAt()

More information in Javadoc.
---
 .../org/sonar/api/batch/DecoratorBarriers.java     | 38 +++++++++++++++++++---
 .../main/java/org/sonar/api/rules/Violation.java   | 13 +++++---
 2 files changed, 41 insertions(+), 10 deletions(-)

(limited to 'sonar-plugin-api/src')

diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/DecoratorBarriers.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/DecoratorBarriers.java
index 429050ecc74..526c87c6c9e 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/DecoratorBarriers.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/DecoratorBarriers.java
@@ -20,8 +20,13 @@
 package org.sonar.api.batch;
 
 /**
- * Barriers are used to define the order of execution of Decorators.
- * 
+ * Barriers are used to define the order of execution of Decorators. Decorators must be annotated with the following :
+ *
+ * <ul>
+ *   <li{@code @DependsUpon(BARRIER)} in order to be executed after BARRIER
+ *   <li{@code @DependedUpon(BARRIER)} in order to be executed before BARRIER
+ * </ul>
+ *
  * @since 2.3
  */
 public interface DecoratorBarriers {
@@ -32,16 +37,39 @@ public interface DecoratorBarriers {
    * This barrier is used by a decorator in order to :
    * <ul>
    * <li>be executed after all the decorators which generate violations :
-   * <code>@DependsUpon(value=DecoratorBarriers.END_OF_VIOLATIONS_GENERATION</code></li>
-   * <li>declare that it generates violations : <code>@DependedUpon(value=DecoratorBarriers.END_OF_VIOLATIONS_GENERATION</code></li>
+   * {@code @DependsUpon(value=DecoratorBarriers.END_OF_VIOLATIONS_GENERATION}</li>
+   * <li>declare that it generates violations : {@code @DependedUpon(value=DecoratorBarriers.END_OF_VIOLATIONS_GENERATION}</li>
    * </ul>
    */
   String END_OF_VIOLATIONS_GENERATION = "END_OF_VIOLATIONS_GENERATION";
 
+  /**
+   * Extensions which call the method {@code Violation#setSwitchedOff} must be executed before this barrier
+   * ({@code @DependedUpon(value=DecoratorBarriers.VIOLATION_TRACKING})
+   *
+   * This barrier is after {@code END_OF_VIOLATIONS_GENERATION}
+   *
+   * @since 2.8
+   */
+  String START_VIOLATION_TRACKING = "START_VIOLATION_TRACKING";
+
+  /*
+  * This barrier is after {@code END_OF_VIOLATIONS_GENERATION} and {@code START_VIOLATION_TRACKING}.
+  * Decorators executed after this barrier ({@code @DependsUpon(value=DecoratorBarriers.END_OF_VIOLATION_TRACKING})
+  * can benefit from all the features of violation tracking :
+  * <ul>
+  *   <li>{@code Violation#getCreatedAt()}</li>
+  *   <li>{@code Violation#isSwitchedOff()}, usually to know if a violation has been flagged as false-positives in UI</li>
+  * </ul>
+  *
+  * @since 2.8
+  */
+  String END_OF_VIOLATION_TRACKING = "END_OF_VIOLATION_TRACKING";
+
   /**
    * Any kinds of time machine data are calculated before this barrier. Decorators executed after this barrier can use
    * Measure#getVariationValue() and Measure#getTendency() methods.
-   * 
+   *
    * @since 2.5
    */
   String END_OF_TIME_MACHINE = "END_OF_TIME_MACHINE";
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/rules/Violation.java b/sonar-plugin-api/src/main/java/org/sonar/api/rules/Violation.java
index 4c3bf2e0a67..fc7ec235484 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/rules/Violation.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/rules/Violation.java
@@ -39,7 +39,7 @@ public class Violation {
   private Integer lineId;
   private Double cost;
   private Date createdAt;
-  private boolean switchedOff;
+  private boolean switchedOff=false;
 
   /**
    * Creates of a violation from a rule. Will need to define the resource later on
@@ -221,14 +221,17 @@ public class Violation {
 
   /**
    * Switches off the current violation. This is a kind of "mute", which means the violation exists but won't be counted as an active
-   * violation (and thus, won't be counted in the total number of violations).
+   * violation (and thus, won't be counted in the total number of violations). It's usually used for false-positives.
+   *
+   * The extensions which call this method must be executed
    * 
    * @since 2.8
-   * @param switchedOff
+   * @param b
    *          if true, the violation is considered OFF
    */
-  public void setSwitchedOff(boolean switchedOff) {
-    this.switchedOff = switchedOff;
+  public Violation setSwitchedOff(boolean b) {
+    this.switchedOff = b;
+    return this;
   }
 
   /**
-- 
cgit v1.2.3