SONAR-2127 API: do not automatically create hierarchy of resource tree

10 files changed, 202 insertions, 53 deletions

diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/AbstractSourceImporter.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/AbstractSourceImporter.java
index f32e3e951ff..b11a96f5655 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/AbstractSourceImporter.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/AbstractSourceImporter.java
@@ -19,11 +19,6 @@
  */
 package org.sonar.api.batch;
 
-import java.io.File;
-import java.io.IOException;
-import java.nio.charset.Charset;
-import java.util.List;
-
 import org.apache.commons.io.FileUtils;
 import org.sonar.api.CoreProperties;
 import org.sonar.api.resources.Language;
@@ -32,6 +27,11 @@ import org.sonar.api.resources.ProjectFileSystem;
 import org.sonar.api.resources.Resource;
 import org.sonar.api.utils.SonarException;
 
+import java.io.File;
+import java.io.IOException;
+import java.nio.charset.Charset;
+import java.util.List;
+
 /**
  * A pre-implementation for a sensor that imports sources
  * 
@@ -88,6 +88,7 @@ public abstract class AbstractSourceImporter implements Sensor {
       if (resource != null) {
         try {
           String source = FileUtils.readFileToString(file, sourcesEncoding.name());
+          context.index(resource);
           context.saveSource(resource, source);
         } catch (IOException e) {
           throw new SonarException("Unable to read and import the source file : '" + file.getAbsolutePath() + "' with the charset : '"
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 ae0f10862c4..07b58dc1a13 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
@@ -23,6 +23,7 @@ import org.sonar.api.design.Dependency;
 import org.sonar.api.measures.Measure;
 import org.sonar.api.measures.MeasuresFilter;
 import org.sonar.api.measures.Metric;
+import org.sonar.api.resources.DuplicatedSourceException;
 import org.sonar.api.resources.ProjectLink;
 import org.sonar.api.resources.Resource;
 import org.sonar.api.rules.Violation;
@@ -37,6 +38,57 @@ import java.util.Set;
  */
 public interface SensorContext {
 
+  /**
+   * Indexes a resource as a direct child of project. This method does nothing and returns true if the resource already indexed.
+   *
+   * @return false if the resource is excluded
+   * @since 2.6
+   */
+  boolean index(Resource resource);
+
+
+  /**
+   * Indexes a resource. This method does nothing if the resource is already indexed.
+   *
+   * @param resource        the resource to index. Not nullable
+   * @param parentReference a reference to the parent. If null, the the resource is indexed as a direct child of project.
+   * @return false if the parent is not indexed or if the resource is excluded
+   * @since 2.6
+   */
+  boolean index(Resource resource, Resource parentReference);
+
+  /**
+   * Returns true if the referenced resource is excluded. An excluded resource is not indexed.
+   * @since 2.6
+   */
+  boolean isExcluded(Resource reference);
+
+  /**
+   * @since 2.6
+   */
+  boolean isIndexed(Resource reference);
+
+  /**
+   * Search for an indexed resource.
+   *
+   * @param reference the resource reference
+   * @return the indexed resource, null if it's not indexed
+   * @since 1.10. Generic types since 2.6.
+   */
+  <R extends Resource> R getResource(R reference);
+
+  /**
+   * @since 2.6
+   */
+  Resource getParent(Resource reference);
+
+  /**
+   * @since 2.6
+   */
+
+  Collection<Resource> getChildren(Resource reference);
+
+
   // ----------- MEASURES ON PROJECT --------------
 
   /**
@@ -68,15 +120,13 @@ public interface SensorContext {
 
   /**
    * Key is updated when saving the resource.
-   * 
+   *
    * @return the key as saved in database. Null if the resource is set as excluded.
+   * @deprecated use the methods index()
    */
+  @Deprecated
   String saveResource(Resource resource);
 
-  /**
-   * @return the resource saved in sonar index
-   */
-  Resource getResource(Resource resource);
 
   /**
    * Find all measures for this project. Never return null.
@@ -105,9 +155,9 @@ public interface SensorContext {
 
   /**
    * Save a coding rule violation.
-   * 
-   * @since 2.5
+   *
    * @param force allows to force creation of violation even if it was supressed by {@link org.sonar.api.rules.ViolationFilter}
+   * @since 2.5
    */
   void saveViolation(Violation violation, boolean force);
 
@@ -137,9 +187,15 @@ public interface SensorContext {
   // ----------- FILE SOURCES --------------
 
   /**
-   * Does nothing if the resource is set as excluded.
+   * Save the source code of a file. The file must be have been indexed before.
+   * Note: the source stream is not closed.
+   *
+   * @return false if the resource is excluded or not indexed
+   * @throws org.sonar.api.resources.DuplicatedSourceException
+   *          if the source has already been set on this resource
+   * @since 1.10. Returns a boolean since 2.6.
    */
-  void saveSource(Resource resource, String source);
+  boolean saveSource(Resource reference, String source) throws DuplicatedSourceException;
 
   // ----------- LINKS --------------
 
@@ -163,18 +219,18 @@ public interface SensorContext {
 
   /**
    * Creates an event for a given date
-   * 
-   * @param name the event name
+   *
+   * @param name        the event name
    * @param description the event description
-   * @param category the event category
-   * @param date the event date
+   * @param category    the event category
+   * @param date        the event date
    * @return the created event
    */
   Event createEvent(Resource resource, String name, String description, String category, Date date);
 
   /**
    * Deletes an event
-   * 
+   *
    * @param event the event to delete
    */
   void deleteEvent(Event event);
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/SonarIndex.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/SonarIndex.java
index de6d6e1f670..8811492b955 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/SonarIndex.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/SonarIndex.java
@@ -19,41 +19,102 @@
  */
 package org.sonar.api.batch;
 
-import java.util.Collection;
-import java.util.Date;
-import java.util.List;
-import java.util.Set;
-
 import org.sonar.api.design.Dependency;
 import org.sonar.api.measures.Measure;
 import org.sonar.api.measures.MeasuresFilter;
 import org.sonar.api.measures.Metric;
+import org.sonar.api.resources.DuplicatedSourceException;
 import org.sonar.api.resources.Project;
 import org.sonar.api.resources.ProjectLink;
 import org.sonar.api.resources.Resource;
 import org.sonar.api.rules.Violation;
 import org.sonar.graph.DirectedGraphAccessor;
 
+import java.util.Collection;
+import java.util.Date;
+import java.util.List;
+import java.util.Set;
+
 public abstract class SonarIndex implements DirectedGraphAccessor<Resource, Dependency> {
 
-  public abstract Project getProject();
+  /**
+   * Indexes a resource as a direct child of project. This method does nothing and returns true if the resource already indexed.
+   *
+   * @return false if the resource is excluded
+   * @since 2.6
+   */
+  public abstract boolean index(Resource resource);
+
+
+  /**
+   * Indexes a resource. This method does nothing if the resource is already indexed.
+   *
+   * @param resource        the resource to index. Not nullable
+   * @param parentReference a reference to the indexed parent. If null, the resource is indexed as a direct child of project.
+   * @return false if the parent is not indexed or if the resource is excluded
+   * @since 2.6
+   */
+  public abstract boolean index(Resource resource, Resource parentReference);
 
-  public abstract Resource getResource(Resource resource);
+  /**
+   * Returns true if the referenced resource is excluded. An excluded resource is not indexed.
+   * @since 2.6
+   */
+  public abstract boolean isExcluded(Resource reference);
+
+  /**
+   * @since 2.6
+   */
+  public abstract boolean isIndexed(Resource reference);
+
+  /**
+   * Search for an indexed resource.
+   *
+   * @param reference the resource reference
+   * @return the indexed resource, null if it's not indexed
+   * @since 1.10. Generic types since 2.6.
+   */
+  public abstract <R extends Resource> R getResource(R reference);
+
+  /**
+   * @since 2.6
+   */
+  public abstract Resource getParent(Resource reference);
+
+  /**
+   * @since 2.6
+   */
+
+  public abstract Collection<Resource> getChildren(Resource reference);
+
+  /**
+   * Save the source code of a file. The file must be have been indexed before.
+   * Note: the source stream is not closed.
+   *
+   * @return false if the resource is excluded or not indexed
+   * @throws org.sonar.api.resources.DuplicatedSourceException
+   *          if the source has already been set on this resource
+   */
+  public abstract boolean setSource(Resource reference, String source) throws DuplicatedSourceException;
+
+  public abstract Project getProject();
 
   public final Collection<Resource> getResources() {
     return getVertices();
   }
 
-  public abstract List<Resource> getChildren(Resource resource);
-
+  /**
+   * Indexes the resource.
+   * @return the indexed resource, even if it's excluded
+   * @deprecated since 2.6. Use methods index()
+   */
+  @Deprecated
   public abstract Resource addResource(Resource resource);
 
   public abstract Measure getMeasure(Resource resource, Metric metric);
 
   public abstract <M> M getMeasures(Resource resource, MeasuresFilter<M> filter);
 
-  public abstract void setSource(Resource resource, String source);
-
   /**
    * @since 2.5
    */
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/resources/Directory.java b/sonar-plugin-api/src/main/java/org/sonar/api/resources/Directory.java
index ebf2b745c42..b2135800217 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/resources/Directory.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/resources/Directory.java
@@ -59,11 +59,11 @@ public class Directory extends Resource {
   }
 
   public String getScope() {
-    return Resource.SCOPE_SPACE;
+    return Scopes.DIRECTORY;
   }
 
   public String getQualifier() {
-    return Resource.QUALIFIER_DIRECTORY;
+    return Qualifiers.DIRECTORY;
   }
 
   public Resource getParent() {
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/resources/DuplicatedSourceException.java b/sonar-plugin-api/src/main/java/org/sonar/api/resources/DuplicatedSourceException.java
new file mode 100644
index 00000000000..8cbd6dce026
--- /dev/null
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/resources/DuplicatedSourceException.java
@@ -0,0 +1,14 @@
+package org.sonar.api.resources;
+
+import org.apache.commons.lang.ObjectUtils;
+import org.sonar.api.utils.SonarException;
+
+/**
+ * @since 2.6
+ */
+public final class DuplicatedSourceException extends SonarException {
+
+  public DuplicatedSourceException(Resource resource) {
+    super(ObjectUtils.toString(resource));
+  }
+}
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/resources/File.java b/sonar-plugin-api/src/main/java/org/sonar/api/resources/File.java
index e8d2b02cafc..24b7d32b6b8 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/resources/File.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/resources/File.java
@@ -19,12 +19,12 @@
  */
 package org.sonar.api.resources;
 
-import java.util.List;
-
 import org.apache.commons.lang.StringUtils;
 import org.apache.commons.lang.builder.ToStringBuilder;
 import org.sonar.api.utils.WildcardPattern;
 
+import java.util.List;
+
 /**
  * This class is an implementation of a resource of type FILE
  * 
@@ -32,6 +32,8 @@ import org.sonar.api.utils.WildcardPattern;
  */
 public class File extends Resource<Directory> {
 
+  public static final String SCOPE = Scopes.FILE;
+
   private String directoryKey;
   private String filename;
   private Language language;
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/resources/Library.java b/sonar-plugin-api/src/main/java/org/sonar/api/resources/Library.java
index 1681a06b108..61f85842340 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/resources/Library.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/resources/Library.java
@@ -21,7 +21,7 @@ package org.sonar.api.resources;
 
 import org.apache.commons.lang.builder.ToStringBuilder;
 
-public class Library extends Resource {
+public final class Library extends Resource {
 
   private String name;
   private String description;
@@ -68,12 +68,12 @@ public class Library extends Resource {
 
   @Override
   public String getScope() {
-    return Resource.SCOPE_SET;
+    return Scopes.PROJECT;
   }
 
   @Override
   public String getQualifier() {
-    return Resource.QUALIFIER_LIB;
+    return Qualifiers.LIBRARY;
   }
 
   @Override
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/resources/Project.java b/sonar-plugin-api/src/main/java/org/sonar/api/resources/Project.java
index e4f14394dfa..9890eeb830d 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/resources/Project.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/resources/Project.java
@@ -36,6 +36,8 @@ import java.util.List;
  */
 public class Project extends Resource {
 
+  public static final String SCOPE = Scopes.PROJECT;
+
   /**
    * @deprecated since version 1.11. Constant moved to CoreProperties
    */
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/resources/Qualifiers.java b/sonar-plugin-api/src/main/java/org/sonar/api/resources/Qualifiers.java
index f5f87b2161a..bb1c77e99ac 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/resources/Qualifiers.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/resources/Qualifiers.java
@@ -19,13 +19,35 @@
  */
 package org.sonar.api.resources;
 
+/**
+ * The qualifier determines the exact type of a resource.
+ * Plugins can use their own qualifiers.
+ * @since 2.6
+ */
 public interface Qualifiers {
 
   String VIEW = "VW";
   String SUBVIEW = "SVW";
-  String LIB = "LIB";
+
+  /**
+   * Library, for example a JAR dependency of Java projects.
+   * Scope is Scopes.PROJECT
+   */
+  String LIBRARY = "LIB";
+
+  /**
+   * Single project or root of multi-modules projects
+   * Scope is Scopes.PROJECT
+   */
   String PROJECT = "TRK";
+
+  /**
+   * Module of multi-modules project. It's sometimes called sub-project.
+   * Scope is Scopes.PROJECT
+   */
   String MODULE = "BRC";
+
+
   String PACKAGE = "PAC";
   String DIRECTORY = "DIR";
   String FILE = "FIL";
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/resources/Scopes.java b/sonar-plugin-api/src/main/java/org/sonar/api/resources/Scopes.java
index fc8a29f2bbb..001fbd96e5e 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/resources/Scopes.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/resources/Scopes.java
@@ -20,7 +20,10 @@
 package org.sonar.api.resources;
 
 /**
- * Resource scopes are not extendable by plugins.
+ * Resource scopes are used to group resources. They relate to persisted resources only (project, directories and files).
+ * They are generally used in UI to display/hide some services or in web services.
+ *
+ * Resource scopes are not extensible by plugins. 
  */
 public interface Scopes {
   /**
@@ -31,23 +34,11 @@ public interface Scopes {
   /**
    * For example directory or Java package. Persisted in database.
    */
-  String NAMESPACE = "DIR";
+  String DIRECTORY = "DIR";
 
   /**
    * For example a Java file. Persisted in database.
    */
   String FILE = "FIL";
 
-  /**
-   * For example a Java class or a Java interface. Not persisted in database.
-   */
-  String TYPE = "TYP";
-
-  /**
-   * For example a Java method. Not persisted in database.
-   */
-  String METHOD = "MET";
-
-  
-  String[] ORDERED_SCOPES = {PROJECT, NAMESPACE, FILE, TYPE, METHOD};
-}
+}
\ No newline at end of file