SONAR-7512 New symbol reference API

12 files changed, 474 insertions, 74 deletions

diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/SensorContext.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/SensorContext.java
index 1c159c38b78..044f5f36c16 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/SensorContext.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/SensorContext.java
@@ -32,6 +32,7 @@ import org.sonar.api.batch.sensor.issue.Issue;
 import org.sonar.api.batch.sensor.issue.NewIssue;
 import org.sonar.api.batch.sensor.measure.Measure;
 import org.sonar.api.batch.sensor.measure.NewMeasure;
+import org.sonar.api.batch.sensor.symbol.NewSymbolTable;
 import org.sonar.api.config.Settings;
 import org.sonar.api.utils.Version;
 
@@ -89,9 +90,13 @@ public interface SensorContext {
    */
   NewHighlighting newHighlighting();
 
-  // ------------ SYMBOL REFERENCES ------------
+  // ------------ SYMBOL TABLE ------------
 
-  // TODO
+  /**
+   * Builder to define symbol table of a file. Don't forget to call {@link NewSymbolTable#save()} once all symbols are provided.
+   * @since 5.6
+   */
+  NewSymbolTable newSymbolTable();
 
   // ------------ TESTS ------------
 
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/highlighting/NewHighlighting.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/highlighting/NewHighlighting.java
index af4c145713f..6f59fad4bad 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/highlighting/NewHighlighting.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/highlighting/NewHighlighting.java
@@ -40,7 +40,9 @@ public interface NewHighlighting {
    * @param startOffset Starting position in file for this type of text. Beginning of a file starts with offset '0'.
    * @param endOffset End position in file for this type of text.
    * @param typeOfText see {@link TypeOfText} values.
+   * @deprecated since 5.6 Only supported to ease migration from old API. Please prefer {@link #highlight(int, int, int, int)}.
    */
+  @Deprecated
   NewHighlighting highlight(int startOffset, int endOffset, TypeOfText typeOfText);
 
   /**
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/internal/InMemorySensorStorage.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/internal/InMemorySensorStorage.java
new file mode 100644
index 00000000000..32c91d18610
--- /dev/null
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/internal/InMemorySensorStorage.java
@@ -0,0 +1,82 @@
+/*
+ * 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.batch.sensor.internal;
+
+import com.google.common.collect.HashBasedTable;
+import com.google.common.collect.Table;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.EnumMap;
+import java.util.HashMap;
+import java.util.Map;
+import org.sonar.api.batch.sensor.coverage.CoverageType;
+import org.sonar.api.batch.sensor.coverage.internal.DefaultCoverage;
+import org.sonar.api.batch.sensor.cpd.internal.DefaultCpdTokens;
+import org.sonar.api.batch.sensor.highlighting.internal.DefaultHighlighting;
+import org.sonar.api.batch.sensor.issue.Issue;
+import org.sonar.api.batch.sensor.measure.Measure;
+import org.sonar.api.batch.sensor.symbol.internal.DefaultSymbolTable;
+
+class InMemorySensorStorage implements SensorStorage {
+
+  Table<String, String, Measure> measuresByComponentAndMetric = HashBasedTable.create();
+
+  Collection<Issue> allIssues = new ArrayList<>();
+
+  Map<String, DefaultHighlighting> highlightingByComponent = new HashMap<>();
+  Map<String, DefaultCpdTokens> cpdTokensByComponent = new HashMap<>();
+  Map<String, Map<CoverageType, DefaultCoverage>> coverageByComponent = new HashMap<>();
+  Map<String, DefaultSymbolTable> symbolsPerComponent = new HashMap<>();
+
+  @Override
+  public void store(Measure measure) {
+    measuresByComponentAndMetric.row(measure.inputComponent().key()).put(measure.metric().key(), measure);
+  }
+
+  @Override
+  public void store(Issue issue) {
+    allIssues.add(issue);
+  }
+
+  @Override
+  public void store(DefaultHighlighting highlighting) {
+    highlightingByComponent.put(highlighting.inputFile().key(), highlighting);
+  }
+
+  @Override
+  public void store(DefaultCoverage defaultCoverage) {
+    String key = defaultCoverage.inputFile().key();
+    if (!coverageByComponent.containsKey(key)) {
+      coverageByComponent.put(key, new EnumMap<CoverageType, DefaultCoverage>(CoverageType.class));
+    }
+    coverageByComponent.get(key).put(defaultCoverage.type(), defaultCoverage);
+  }
+
+  @Override
+  public void store(DefaultCpdTokens defaultCpdTokens) {
+    cpdTokensByComponent.put(defaultCpdTokens.inputFile().key(), defaultCpdTokens);
+  }
+
+  @Override
+  public void store(DefaultSymbolTable symbolTable) {
+    symbolsPerComponent.put(symbolTable.inputFile().key(), symbolTable);
+  }
+
+}
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/internal/MockAnalysisMode.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/internal/MockAnalysisMode.java
new file mode 100644
index 00000000000..9193fdd3704
--- /dev/null
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/internal/MockAnalysisMode.java
@@ -0,0 +1,50 @@
+/*
+ * 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.batch.sensor.internal;
+
+import org.sonar.api.batch.AnalysisMode;
+
+public class MockAnalysisMode implements AnalysisMode {
+  private boolean isPreview = false;
+  private boolean isIssues = false;
+
+  @Override
+  public boolean isPreview() {
+    return isPreview;
+  }
+
+  public void setPreview(boolean value) {
+    this.isPreview = value;
+  }
+
+  @Override
+  public boolean isIssues() {
+    return this.isIssues;
+  }
+
+  public void setIssues(boolean issues) {
+    this.isIssues = issues;
+  }
+
+  @Override
+  public boolean isPublish() {
+    return !isPreview && !isIssues;
+  }
+}
\ No newline at end of file
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/internal/SensorContextTester.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/internal/SensorContextTester.java
index b0c19108f16..0e4d51f9795 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/internal/SensorContextTester.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/internal/SensorContextTester.java
@@ -20,22 +20,19 @@
 package org.sonar.api.batch.sensor.internal;
 
 import com.google.common.annotations.Beta;
-import com.google.common.collect.HashBasedTable;
-import com.google.common.collect.Table;
 import java.io.File;
 import java.io.Serializable;
 import java.nio.file.Path;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Collections;
-import java.util.EnumMap;
-import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 import javax.annotation.CheckForNull;
 import org.sonar.api.SonarQubeVersion;
-import org.sonar.api.batch.AnalysisMode;
 import org.sonar.api.batch.fs.InputModule;
+import org.sonar.api.batch.fs.TextRange;
 import org.sonar.api.batch.fs.internal.DefaultFileSystem;
 import org.sonar.api.batch.fs.internal.DefaultInputModule;
 import org.sonar.api.batch.fs.internal.DefaultTextPointer;
@@ -58,6 +55,8 @@ import org.sonar.api.batch.sensor.issue.internal.DefaultIssue;
 import org.sonar.api.batch.sensor.measure.Measure;
 import org.sonar.api.batch.sensor.measure.NewMeasure;
 import org.sonar.api.batch.sensor.measure.internal.DefaultMeasure;
+import org.sonar.api.batch.sensor.symbol.NewSymbolTable;
+import org.sonar.api.batch.sensor.symbol.internal.DefaultSymbolTable;
 import org.sonar.api.config.Settings;
 import org.sonar.api.internal.SonarQubeVersionFactory;
 import org.sonar.api.measures.Metric;
@@ -236,6 +235,11 @@ public class SensorContextTester implements SensorContext {
     return new DefaultCpdTokens(settings, sensorStorage);
   }
 
+  @Override
+  public NewSymbolTable newSymbolTable() {
+    return new DefaultSymbolTable(sensorStorage);
+  }
+
   public List<TypeOfText> highlightingTypeAt(String componentKey, int line, int lineOffset) {
     DefaultHighlighting syntaxHighlightingData = sensorStorage.highlightingByComponent.get(componentKey);
     if (syntaxHighlightingData == null) {
@@ -251,73 +255,18 @@ public class SensorContextTester implements SensorContext {
     return result;
   }
 
-  public static class MockAnalysisMode implements AnalysisMode {
-    private boolean isPreview = false;
-    private boolean isIssues = false;
-
-    @Override
-    public boolean isPreview() {
-      return isPreview;
-    }
-
-    public void setPreview(boolean value) {
-      this.isPreview = value;
-    }
-
-    @Override
-    public boolean isIssues() {
-      return this.isIssues;
-    }
-
-    public void setIssues(boolean issues) {
-      this.isIssues = issues;
-    }
-
-    @Override
-    public boolean isPublish() {
-      return !isPreview && !isIssues;
-    }
-  }
-
-  private static class InMemorySensorStorage implements SensorStorage {
-
-    private Table<String, String, Measure> measuresByComponentAndMetric = HashBasedTable.create();
-
-    private Collection<Issue> allIssues = new ArrayList<>();
-
-    private Map<String, DefaultHighlighting> highlightingByComponent = new HashMap<>();
-    private Map<String, DefaultCpdTokens> cpdTokensByComponent = new HashMap<>();
-    private Map<String, Map<CoverageType, DefaultCoverage>> coverageByComponent = new HashMap<>();
-
-    @Override
-    public void store(Measure measure) {
-      measuresByComponentAndMetric.row(measure.inputComponent().key()).put(measure.metric().key(), measure);
-    }
-
-    @Override
-    public void store(Issue issue) {
-      allIssues.add(issue);
-    }
-
-    @Override
-    public void store(DefaultHighlighting highlighting) {
-      highlightingByComponent.put(highlighting.inputFile().key(), highlighting);
+  public Collection<TextRange> referencesForSymbolAt(String componentKey, int line, int lineOffset) {
+    DefaultSymbolTable symbolTable = sensorStorage.symbolsPerComponent.get(componentKey);
+    if (symbolTable == null) {
+      return Collections.emptyList();
     }
-
-    @Override
-    public void store(DefaultCoverage defaultCoverage) {
-      String key = defaultCoverage.inputFile().key();
-      if (!coverageByComponent.containsKey(key)) {
-        coverageByComponent.put(key, new EnumMap<CoverageType, DefaultCoverage>(CoverageType.class));
+    DefaultTextPointer location = new DefaultTextPointer(line, lineOffset);
+    for (Map.Entry<TextRange, Set<TextRange>> symbol : symbolTable.getReferencesBySymbol().entrySet()) {
+      if (symbol.getKey().start().compareTo(location) <= 0 && symbol.getKey().end().compareTo(location) > 0) {
+        return symbol.getValue();
       }
-      coverageByComponent.get(key).put(defaultCoverage.type(), defaultCoverage);
     }
-
-    @Override
-    public void store(DefaultCpdTokens defaultCpdTokens) {
-      cpdTokensByComponent.put(defaultCpdTokens.inputFile().key(), defaultCpdTokens);
-    }
-
+    return Collections.emptyList();
   }
 
 }
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/internal/SensorStorage.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/internal/SensorStorage.java
index 031ee725728..3ea574b5bf6 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/internal/SensorStorage.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/internal/SensorStorage.java
@@ -25,6 +25,7 @@ import org.sonar.api.batch.sensor.cpd.internal.DefaultCpdTokens;
 import org.sonar.api.batch.sensor.highlighting.internal.DefaultHighlighting;
 import org.sonar.api.batch.sensor.issue.Issue;
 import org.sonar.api.batch.sensor.measure.Measure;
+import org.sonar.api.batch.sensor.symbol.internal.DefaultSymbolTable;
 
 /**
  * Interface for storing data computed by sensors.
@@ -49,4 +50,9 @@ public interface SensorStorage {
    */
   void store(DefaultCpdTokens defaultCpdTokens);
 
+  /**
+   * @since 5.6 
+   */
+  void store(DefaultSymbolTable symbolTable);
+
 }
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/symbol/NewSymbol.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/symbol/NewSymbol.java
new file mode 100644
index 00000000000..46368ed5ee1
--- /dev/null
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/symbol/NewSymbol.java
@@ -0,0 +1,50 @@
+/*
+ * 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.batch.sensor.symbol;
+
+import com.google.common.annotations.Beta;
+import org.sonar.api.batch.fs.InputFile;
+import org.sonar.api.batch.fs.TextRange;
+
+/**
+ * This builder is used to define symbol references on files.
+ * @since 5.6
+ */
+@Beta
+public interface NewSymbol {
+
+  /**
+   * Register a new symbol reference.
+   * @param startOffset Starting position in file for the declaration of this symbol. Beginning of a file starts with offset '0'.
+   * @param endOffset End position in file for this symbol declaration.
+   */
+  NewSymbol newReference(int startOffset, int endOffset);
+
+  /**
+   * Register a new symbol.
+   * @param range Range of text for the symbol declaration. See for example {@link InputFile#newRange(int, int, int, int)}.
+   */
+  NewSymbol newReference(TextRange range);
+
+  /**
+   * Shortcut to avoid calling {@link InputFile#newRange(int, int, int, int)}
+   */
+  NewSymbol newReference(int startLine, int startLineOffset, int endLine, int endLineOffset);
+}
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/symbol/NewSymbolTable.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/symbol/NewSymbolTable.java
new file mode 100644
index 00000000000..1e8487c557d
--- /dev/null
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/symbol/NewSymbolTable.java
@@ -0,0 +1,63 @@
+/*
+ * 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.batch.sensor.symbol;
+
+import com.google.common.annotations.Beta;
+import org.sonar.api.batch.fs.InputFile;
+import org.sonar.api.batch.fs.TextRange;
+
+/**
+ * This builder is used to define symbol references on files.
+ * @since 5.6
+ */
+@Beta
+public interface NewSymbolTable {
+
+  /**
+   * The file the symbol table belongs to.
+   */
+  NewSymbolTable onFile(InputFile inputFile);
+
+  /**
+   * Register a new symbol declaration.
+   * @param startOffset Starting position in file for the declaration of this symbol. Beginning of a file starts with offset '0'.
+   * @param endOffset End position in file for this symbol declaration.
+   * @deprecated since 5.6 Only supported to ease migration from old API. Please prefer {@link #newSymbol(int, int, int, int)}.
+   */
+  @Deprecated
+  NewSymbol newSymbol(int startOffset, int endOffset);
+
+  /**
+   * Register a new symbol declaration.
+   * @param range Range of text for the symbol declaration. See for example {@link InputFile#newRange(int, int, int, int)}.
+   */
+  NewSymbol newSymbol(TextRange range);
+
+  /**
+   * Shortcut to avoid calling {@link InputFile#newRange(int, int, int, int)}
+   */
+  NewSymbol newSymbol(int startLine, int startLineOffset, int endLine, int endLineOffset);
+
+  /**
+   * Call this method only once when your are done with defining all symbols of the file.
+   * @throws IllegalStateException if you have defined overlapping symbols
+   */
+  void save();
+}
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/symbol/internal/DefaultSymbolTable.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/symbol/internal/DefaultSymbolTable.java
new file mode 100644
index 00000000000..ba4aa897646
--- /dev/null
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/symbol/internal/DefaultSymbolTable.java
@@ -0,0 +1,152 @@
+/*
+ * 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.batch.sensor.symbol.internal;
+
+import com.google.common.base.Preconditions;
+import java.util.Collection;
+import java.util.Comparator;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.Set;
+import java.util.TreeSet;
+import org.sonar.api.batch.fs.InputFile;
+import org.sonar.api.batch.fs.TextRange;
+import org.sonar.api.batch.fs.internal.DefaultInputFile;
+import org.sonar.api.batch.sensor.internal.DefaultStorable;
+import org.sonar.api.batch.sensor.internal.SensorStorage;
+import org.sonar.api.batch.sensor.symbol.NewSymbol;
+import org.sonar.api.batch.sensor.symbol.NewSymbolTable;
+
+public class DefaultSymbolTable extends DefaultStorable implements NewSymbolTable {
+
+  private final Map<TextRange, Set<TextRange>> referencesBySymbol;
+  private DefaultInputFile inputFile;
+
+  public DefaultSymbolTable(SensorStorage storage) {
+    super(storage);
+    referencesBySymbol = new LinkedHashMap<>();
+  }
+
+  public Map<TextRange, Set<TextRange>> getReferencesBySymbol() {
+    return referencesBySymbol;
+  }
+
+  @Override
+  public DefaultSymbolTable onFile(InputFile inputFile) {
+    Preconditions.checkNotNull(inputFile, "file can't be null");
+    this.inputFile = (DefaultInputFile) inputFile;
+    return this;
+  }
+
+  public InputFile inputFile() {
+    return inputFile;
+  }
+
+  @Override
+  public NewSymbol newSymbol(int startLine, int startLineOffset, int endLine, int endLineOffset) {
+    checkInputFileNotNull();
+    TextRange declarationRange;
+    try {
+      declarationRange = inputFile.newRange(startLine, startLineOffset, endLine, endLineOffset);
+    } catch (Exception e) {
+      throw new IllegalArgumentException("Unable to create symbol on file " + inputFile, e);
+    }
+    return newSymbol(declarationRange);
+  }
+
+  @Override
+  public NewSymbol newSymbol(int startOffset, int endOffset) {
+    checkInputFileNotNull();
+    TextRange declarationRange;
+    try {
+      declarationRange = inputFile.newRange(startOffset, endOffset);
+    } catch (Exception e) {
+      throw new IllegalArgumentException("Unable to create symbol on file " + inputFile, e);
+    }
+    return newSymbol(declarationRange);
+  }
+
+  @Override
+  public NewSymbol newSymbol(TextRange range) {
+    checkInputFileNotNull();
+    TreeSet<TextRange> references = new TreeSet<>(new Comparator<TextRange>() {
+      @Override
+      public int compare(TextRange o1, TextRange o2) {
+        return o1.start().compareTo(o2.start());
+      }
+    });
+    referencesBySymbol.put(range, references);
+    return new DefaultSymbol(inputFile, range, references);
+  }
+
+  private static class DefaultSymbol implements NewSymbol {
+
+    private final Collection<TextRange> references;
+    private final DefaultInputFile inputFile;
+    private final TextRange declaration;
+
+    public DefaultSymbol(DefaultInputFile inputFile, TextRange declaration, Collection<TextRange> references) {
+      this.inputFile = inputFile;
+      this.declaration = declaration;
+      this.references = references;
+    }
+
+    @Override
+    public NewSymbol newReference(int startOffset, int endOffset) {
+      TextRange referenceRange;
+      try {
+        referenceRange = inputFile.newRange(startOffset, endOffset);
+      } catch (Exception e) {
+        throw new IllegalArgumentException("Unable to create symbol reference on file " + inputFile, e);
+      }
+      return newReference(referenceRange);
+    }
+
+    @Override
+    public NewSymbol newReference(int startLine, int startLineOffset, int endLine, int endLineOffset) {
+      TextRange referenceRange;
+      try {
+        referenceRange = inputFile.newRange(startLine, startLineOffset, endLine, endLineOffset);
+      } catch (Exception e) {
+        throw new IllegalArgumentException("Unable to create symbol reference on file " + inputFile, e);
+      }
+      return newReference(referenceRange);
+    }
+
+    @Override
+    public NewSymbol newReference(TextRange range) {
+      Preconditions.checkNotNull(range, "Provided range is null");
+      Preconditions.checkArgument(!declaration.overlap(range), "Overlapping symbol declaration and reference for symbol at %s", declaration);
+      references.add(range);
+      return this;
+    }
+
+  }
+
+  @Override
+  protected void doSave() {
+    checkInputFileNotNull();
+    storage.store(this);
+  }
+
+  private void checkInputFileNotNull() {
+    Preconditions.checkState(inputFile != null, "Call onFile() first");
+  }
+}
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/symbol/internal/package-info.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/symbol/internal/package-info.java
new file mode 100644
index 00000000000..532d1a1744a
--- /dev/null
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/symbol/internal/package-info.java
@@ -0,0 +1,21 @@
+/*
+ * 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.
+ */
+@javax.annotation.ParametersAreNonnullByDefault
+package org.sonar.api.batch.sensor.symbol.internal;
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/symbol/package-info.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/symbol/package-info.java
new file mode 100644
index 00000000000..ff6a1ac9138
--- /dev/null
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/symbol/package-info.java
@@ -0,0 +1,21 @@
+/*
+ * 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.
+ */
+@javax.annotation.ParametersAreNonnullByDefault
+package org.sonar.api.batch.sensor.symbol;
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/source/Symbolizable.java b/sonar-plugin-api/src/main/java/org/sonar/api/source/Symbolizable.java
index e6dac0d2840..1e40f26a23c 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/source/Symbolizable.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/source/Symbolizable.java
@@ -19,11 +19,10 @@
  */
 package org.sonar.api.source;
 
+import java.util.List;
 import org.sonar.api.component.Perspective;
 import org.sonar.api.component.ResourcePerspectives;
 
-import java.util.List;
-
 /**
  * Use this perspective to save symbol references on files.
  * See {@link ResourcePerspectives}.
@@ -44,7 +43,7 @@ public interface Symbolizable extends Perspective {
      * The length of the reference is assumed to be the same as the symbol's length.
      */
     void newReference(Symbol symbol, int fromOffset);
-    
+
     /**
      * Creates a new reference for a symbol.
      * The offsets are global in the file.