SONAR-3209 Add new batch component - FileLinesContextFactory

* As was discussed with Simon: better to have new beta class
  than new beta method.

* This also provides ability to use this factory from Decorator.

3 files changed, 48 insertions, 8 deletions

diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/SensorContext.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/SensorContext.java
index 1cc5b291403..fc9189410c2 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/SensorContext.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/SensorContext.java
@@ -19,9 +19,7 @@
  */
 package org.sonar.api.batch;
 
-import com.google.common.annotations.Beta;
 import org.sonar.api.design.Dependency;
-import org.sonar.api.measures.FileLinesContext;
 import org.sonar.api.measures.Measure;
 import org.sonar.api.measures.MeasuresFilter;
 import org.sonar.api.measures.Metric;
@@ -152,12 +150,6 @@ public interface SensorContext {
    */
   Measure saveMeasure(Resource resource, Measure measure);
 
-  /**
-   * @since 2.14
-   */
-  @Beta
-  FileLinesContext createFileLinesContext(Resource resource);
-
   // ----------- RULE VIOLATIONS --------------
 
   /**
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/measures/FileLinesContext.java b/sonar-plugin-api/src/main/java/org/sonar/api/measures/FileLinesContext.java
index f2fe4dcaf18..51a16d337f4 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/measures/FileLinesContext.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/measures/FileLinesContext.java
@@ -31,6 +31,9 @@ import com.google.common.annotations.Beta;
  * <li>author of line 4 is Simon</li>
  * </ul>
  * Numbering of lines starts from 1.
+ * Also note that you can't update what already was saved, however it is safe to call {@link #save()} several times.
+ * <p>
+ * Instances of this interface can be obtained using {@link FileLinesContextFactory}.
  *
  * <p>This interface is not intended to be implemented by clients.</p>
  *
@@ -39,6 +42,9 @@ import com.google.common.annotations.Beta;
 @Beta
 public interface FileLinesContext {
 
+  /**
+   * @throws UnsupportedOperationException on attempt to update already saved data
+   */
   void setIntValue(String metricKey, int line, int value);
 
   /**
@@ -46,6 +52,9 @@ public interface FileLinesContext {
    */
   Integer getIntValue(String metricKey, int line);
 
+  /**
+   * @throws UnsupportedOperationException on attempt to update already saved data
+   */
   void setStringValue(String metricKey, int line, String value);
 
   /**
@@ -53,6 +62,9 @@ public interface FileLinesContext {
    */
   String getStringValue(String metricKey, int line);
 
+  /**
+   * Saves unsaved values.
+   */
   void save();
 
 }
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/measures/FileLinesContextFactory.java b/sonar-plugin-api/src/main/java/org/sonar/api/measures/FileLinesContextFactory.java
new file mode 100644
index 00000000000..5fff3a6380c
--- /dev/null
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/measures/FileLinesContextFactory.java
@@ -0,0 +1,36 @@
+/*
+ * Sonar, open source software quality management tool.
+ * Copyright (C) 2008-2012 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.measures;
+
+import com.google.common.annotations.Beta;
+import org.sonar.api.BatchComponent;
+import org.sonar.api.resources.Resource;
+
+/**
+ * <p>This interface is not intended to be implemented by clients.</p>
+ *
+ * @since 2.14
+ */
+@Beta
+public interface FileLinesContextFactory extends BatchComponent {
+
+  FileLinesContext createFor(Resource resource);
+
+}