SONAR-16097 Add plugin cache to the Sensor API

4 files changed, 154 insertions, 0 deletions

diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/Beta.java b/sonar-plugin-api/src/main/java/org/sonar/api/Beta.java
new file mode 100644
index 00000000000..228515acfc5
--- /dev/null
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/Beta.java
@@ -0,0 +1,40 @@
+/*
+ * SonarQube
+ * Copyright (C) 2009-2022 SonarSource SA
+ * mailto:info 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;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * This annotations marks API as experimental.
+ * API marked with it can be subject to breaking changes or removal in any future version without compliance with deprecation policies.
+ */
+@Retention(RetentionPolicy.CLASS)
+@Target({
+  ElementType.ANNOTATION_TYPE,
+  ElementType.CONSTRUCTOR,
+  ElementType.FIELD,
+  ElementType.METHOD,
+  ElementType.TYPE})
+@Documented
+public @interface Beta {}
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 d1a43ae930d..da9578d0c98 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
@@ -20,11 +20,14 @@
 package org.sonar.api.batch.sensor;
 
 import java.io.Serializable;
+import org.sonar.api.Beta;
 import org.sonar.api.SonarRuntime;
 import org.sonar.api.batch.fs.FileSystem;
 import org.sonar.api.batch.fs.InputFile;
 import org.sonar.api.batch.fs.InputModule;
 import org.sonar.api.batch.rule.ActiveRules;
+import org.sonar.api.batch.sensor.cache.ReadCache;
+import org.sonar.api.batch.sensor.cache.WriteCache;
 import org.sonar.api.batch.sensor.code.NewSignificantCode;
 import org.sonar.api.batch.sensor.coverage.NewCoverage;
 import org.sonar.api.batch.sensor.cpd.NewCpdTokens;
@@ -218,4 +221,33 @@ public interface SensorContext {
    */
   void markForPublishing(InputFile inputFile);
 
+  /**
+   * Access object to write cache that will be stored and made available in a future analysis.
+   * If cache is disabled, the methods in the returned object will have no effect.
+   * This API is experimental and can be changed or dropped at any time.
+   * @see #isCacheEnabled()
+   * @since 9.4
+   */
+  @Beta
+  WriteCache nextCache();
+
+  /**
+   * Access object to read cached data. The origin of the cached data is not specified and could come from a different branch.
+   * If cache is disabled, the methods in the returned object will have no effect.
+   * This API is experimental and can be changed or dropped at any time.
+   * @see #isCacheEnabled()
+   * @since 9.4
+   */
+  @Beta
+  ReadCache previousAnalysisCache();
+
+  /**
+   * Returns true if caching is enabled.
+   * This API is experimental and can be changed or dropped at any time.
+   * @see #nextCache()
+   * @see #previousAnalysisCache()
+   * @since 9.4
+   */
+  @Beta
+  boolean isCacheEnabled();
 }
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/cache/ReadCache.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/cache/ReadCache.java
new file mode 100644
index 00000000000..e9b497393be
--- /dev/null
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/cache/ReadCache.java
@@ -0,0 +1,38 @@
+/*
+ * SonarQube
+ * Copyright (C) 2009-2022 SonarSource SA
+ * mailto:info 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.cache;
+
+import java.io.InputStream;
+import org.sonar.api.Beta;
+
+@Beta
+public interface ReadCache {
+  /**
+   * Returns an input stream for the data cached with the key.
+   * It's the responsibility of the caller to close the stream.
+   * @throws IllegalArgumentException if cache doesn't contain key
+   */
+  InputStream read(String key);
+
+  /**
+   * Checks whether the cache contains a key
+   */
+  boolean contains(String key);
+}
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/cache/WriteCache.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/cache/WriteCache.java
new file mode 100644
index 00000000000..1a6bf3ce032
--- /dev/null
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/cache/WriteCache.java
@@ -0,0 +1,44 @@
+/*
+ * SonarQube
+ * Copyright (C) 2009-2022 SonarSource SA
+ * mailto:info 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.cache;
+
+import java.io.InputStream;
+import org.sonar.api.Beta;
+
+@Beta
+public interface WriteCache {
+  /**
+   * Save a new entry in the cache. The stream will be consumed immediately.
+   * @throws IllegalArgumentException if the cache already contains the key
+   */
+  void write(String key, InputStream data);
+
+  /**
+   * Save a new entry in the cache.
+   * @throws IllegalArgumentException if the cache already contains the key
+   */
+  void write(String key, byte[] data);
+
+  /**
+   * Copy a cached entry from the previous cache to the new one.
+   * @throws IllegalArgumentException if the previous cache doesn't contain given key or if this cache already contains the key
+   */
+  void copyFromPrevious(String key);
+}