SCANJLIB-276 Allow to use a local Scanner Engine

henryju · web-flow · commit 8c7105dfbee5 · 2025-07-17T09:47:17.000+02:00
diff --git a/lib/src/main/java/org/sonarsource/scanner/lib/ScannerProperties.java b/lib/src/main/java/org/sonarsource/scanner/lib/ScannerProperties.java
@@ -103,6 +103,11 @@ private ScannerProperties() {
    */
   public static final String JAVA_EXECUTABLE_PATH = "sonar.scanner.javaExePath";
 
+  /**
+   * Path of the Scanner Engine JAR to be used.
+   */
+  public static final String SCANNER_ENGINE_JAR_PATH = "sonar.scanner.engineJarPath";
+
   /**
    * Flag to skip the JRE provisioning.
    */
diff --git a/lib/src/main/java/org/sonarsource/scanner/lib/internal/cache/CachedFile.java b/lib/src/main/java/org/sonarsource/scanner/lib/internal/cache/CachedFile.java
@@ -20,13 +20,15 @@
 package org.sonarsource.scanner.lib.internal.cache;
 
 import java.nio.file.Path;
+import javax.annotation.CheckForNull;
+import javax.annotation.Nullable;
 
 public class CachedFile {
 
   private final Path pathInCache;
-  private final boolean cacheHit;
+  private final Boolean cacheHit;
 
-  public CachedFile(Path pathInCache, boolean cacheHit) {
+  public CachedFile(Path pathInCache, @Nullable Boolean cacheHit) {
     this.pathInCache = pathInCache;
     this.cacheHit = cacheHit;
   }
@@ -35,7 +37,8 @@ public Path getPathInCache() {
     return pathInCache;
   }
 
-  public boolean isCacheHit() {
+  @CheckForNull
+  public Boolean getCacheHit() {
     return cacheHit;
   }
 }
diff --git a/lib/src/main/java/org/sonarsource/scanner/lib/internal/facade/AbstractScannerEngineFacade.java b/lib/src/main/java/org/sonarsource/scanner/lib/internal/facade/AbstractScannerEngineFacade.java
@@ -30,11 +30,11 @@ public abstract class AbstractScannerEngineFacade implements ScannerEngineFacade
   private final Map<String, String> bootstrapProperties;
   private final boolean isSonarQubeCloud;
   private final String serverVersion;
-  private final boolean wasEngineCacheHit;
+  private final Boolean wasEngineCacheHit;
   private final JreCacheHit wasJreCacheHit;
 
   protected AbstractScannerEngineFacade(Map<String, String> bootstrapProperties, boolean isSonarQubeCloud, @Nullable String serverVersion,
-    boolean wasEngineCacheHit, @Nullable JreCacheHit wasJreCacheHit) {
+    @Nullable Boolean wasEngineCacheHit, @Nullable JreCacheHit wasJreCacheHit) {
     this.bootstrapProperties = bootstrapProperties;
     this.isSonarQubeCloud = isSonarQubeCloud;
     this.serverVersion = serverVersion;
@@ -69,7 +69,9 @@ private void addStatsProperties(Map<String, String> allProps) {
     if (wasJreCacheHit != null) {
       allProps.put("sonar.scanner.wasJreCacheHit", wasJreCacheHit.name());
     }
-    allProps.put("sonar.scanner.wasEngineCacheHit", String.valueOf(wasEngineCacheHit));
+    if (wasEngineCacheHit != null) {
+      allProps.put("sonar.scanner.wasEngineCacheHit", String.valueOf(wasEngineCacheHit));
+    }
   }
 
   protected abstract boolean doAnalyze(Map<String, String> allProps);
diff --git a/lib/src/main/java/org/sonarsource/scanner/lib/internal/facade/forked/JavaRunnerFactory.java b/lib/src/main/java/org/sonarsource/scanner/lib/internal/facade/forked/JavaRunnerFactory.java
@@ -86,7 +86,7 @@ public JavaRunner createRunner(ScannerHttpClient scannerHttpClient, FileCache fi
     } else {
       var cachedFile = getJreFromServer(scannerHttpClient, fileCache, properties, true);
       if (cachedFile.isPresent()) {
-        return new JavaRunner(cachedFile.get().getPathInCache(), cachedFile.get().isCacheHit() ? JreCacheHit.HIT : JreCacheHit.MISS);
+        return new JavaRunner(cachedFile.get().getPathInCache(), Boolean.TRUE.equals(cachedFile.get().getCacheHit()) ? JreCacheHit.HIT : JreCacheHit.MISS);
       }
     }
     String javaHome = system.getEnvironmentVariable("JAVA_HOME");
@@ -145,7 +145,7 @@ private static Optional<CachedFile> getJreFromServer(ScannerHttpClient scannerHt
       var cachedFile = fileCache.getOrDownload(jreMetadata.get().getFilename(), jreMetadata.get().getSha256(), "SHA-256",
         new JreDownloader(scannerHttpClient, jreMetadata.get()));
       var extractedDirectory = extractArchive(cachedFile.getPathInCache());
-      return Optional.of(new CachedFile(extractedDirectory.resolve(jreMetadata.get().javaPath), cachedFile.isCacheHit()));
+      return Optional.of(new CachedFile(extractedDirectory.resolve(jreMetadata.get().javaPath), cachedFile.getCacheHit()));
     } catch (HashMismatchException e) {
       if (retry) {
         // A new JRE might have been published between the metadata fetch and the download
diff --git a/lib/src/main/java/org/sonarsource/scanner/lib/internal/facade/forked/NewScannerEngineFacade.java b/lib/src/main/java/org/sonarsource/scanner/lib/internal/facade/forked/NewScannerEngineFacade.java
@@ -28,7 +28,7 @@ public class NewScannerEngineFacade extends AbstractScannerEngineFacade {
 
   private NewScannerEngineFacade(Map<String, String> bootstrapProperties, ScannerEngineLauncher launcher,
     boolean isSonarQubeCloud, @Nullable String serverVersion) {
-    super(bootstrapProperties, isSonarQubeCloud, serverVersion, launcher.isEngineCacheHit(), launcher.getJreCacheHit());
+    super(bootstrapProperties, isSonarQubeCloud, serverVersion, launcher.getEngineCacheHit(), launcher.getJreCacheHit());
     this.launcher = launcher;
   }
 
diff --git a/lib/src/main/java/org/sonarsource/scanner/lib/internal/facade/forked/ScannerEngineLauncher.java b/lib/src/main/java/org/sonarsource/scanner/lib/internal/facade/forked/ScannerEngineLauncher.java
@@ -31,6 +31,7 @@
 import java.util.Optional;
 import java.util.Set;
 import java.util.stream.Collectors;
+import javax.annotation.CheckForNull;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.sonarsource.scanner.lib.ScannerProperties;
@@ -156,8 +157,9 @@ private static String buildJsonProperties(Map<String, String> properties) {
     return new Gson().toJson(jsonObject);
   }
 
-  public boolean isEngineCacheHit() {
-    return scannerEngineJar.isCacheHit();
+  @CheckForNull
+  public Boolean getEngineCacheHit() {
+    return scannerEngineJar.getCacheHit();
   }
 
   public JreCacheHit getJreCacheHit() {
diff --git a/lib/src/main/java/org/sonarsource/scanner/lib/internal/facade/forked/ScannerEngineLauncherFactory.java b/lib/src/main/java/org/sonarsource/scanner/lib/internal/facade/forked/ScannerEngineLauncherFactory.java
@@ -21,20 +21,25 @@
 
 import com.google.gson.Gson;
 import java.io.IOException;
+import java.nio.file.Files;
 import java.nio.file.Path;
+import java.nio.file.Paths;
 import java.util.Collections;
 import java.util.Map;
 import javax.annotation.Nullable;
 import org.apache.commons.lang3.StringUtils;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
+import org.sonarsource.scanner.lib.internal.MessageException;
 import org.sonarsource.scanner.lib.internal.cache.CachedFile;
 import org.sonarsource.scanner.lib.internal.cache.FileCache;
 import org.sonarsource.scanner.lib.internal.cache.HashMismatchException;
 import org.sonarsource.scanner.lib.internal.http.ScannerHttpClient;
 import org.sonarsource.scanner.lib.internal.util.ProcessWrapperFactory;
 import org.sonarsource.scanner.lib.internal.util.System2;
 
+import static org.sonarsource.scanner.lib.ScannerProperties.SCANNER_ENGINE_JAR_PATH;
+
 public class ScannerEngineLauncherFactory {
 
   private static final Logger LOG = LoggerFactory.getLogger(ScannerEngineLauncherFactory.class);
@@ -53,15 +58,28 @@ public ScannerEngineLauncherFactory(System2 system) {
   public ScannerEngineLauncher createLauncher(ScannerHttpClient scannerHttpClient, FileCache fileCache, Map<String, String> properties) {
     JavaRunner javaRunner = javaRunnerFactory.createRunner(scannerHttpClient, fileCache, properties);
     jreSanityCheck(javaRunner);
-    var scannerEngine = getScannerEngine(scannerHttpClient, fileCache, true);
+    var scannerEngine = getScannerEngine(scannerHttpClient, fileCache, properties);
     return new ScannerEngineLauncher(javaRunner, scannerEngine);
   }
 
   private static void jreSanityCheck(JavaRunner javaRunner) {
     javaRunner.execute(Collections.singletonList("--version"), null, LOG::debug);
   }
 
-  private static CachedFile getScannerEngine(ScannerHttpClient scannerHttpClient, FileCache fileCache, boolean retry) {
+  private static CachedFile getScannerEngine(ScannerHttpClient scannerHttpClient, FileCache fileCache, Map<String, String> properties) {
+    String scannerEngineJarPathPropValue = properties.get(SCANNER_ENGINE_JAR_PATH);
+    if (scannerEngineJarPathPropValue != null) {
+      var path = Paths.get(scannerEngineJarPathPropValue).toAbsolutePath();
+      if (!Files.isRegularFile(path)) {
+        throw new MessageException("Scanner Engine jar path '" + scannerEngineJarPathPropValue + "' does not exist. Please check property '" + SCANNER_ENGINE_JAR_PATH + "'.");
+      }
+      LOG.info("Using the configured Scanner Engine '{}'", path);
+      return new CachedFile(path, null);
+    }
+    return provisionScannerEngine(scannerHttpClient, fileCache, true);
+  }
+
+  private static CachedFile provisionScannerEngine(ScannerHttpClient scannerHttpClient, FileCache fileCache, boolean retry) {
     try {
       var scannerEngineMetadata = getScannerEngineMetadata(scannerHttpClient);
       return fileCache.getOrDownload(scannerEngineMetadata.getFilename(), scannerEngineMetadata.getSha256(), "SHA-256",
@@ -70,7 +88,7 @@ private static CachedFile getScannerEngine(ScannerHttpClient scannerHttpClient,
       if (retry) {
         // A new scanner-engine might have been published between the metadata fetch and the download
         LOG.warn("Failed to get the scanner-engine, retrying...");
-        return getScannerEngine(scannerHttpClient, fileCache, false);
+        return provisionScannerEngine(scannerHttpClient, fileCache, false);
       }
       throw e;
     }
@@ -81,7 +99,7 @@ private static ScannerEngineMetadata getScannerEngineMetadata(ScannerHttpClient
       String response = scannerHttpClient.callRestApi(API_PATH_ENGINE);
       return new Gson().fromJson(response, ScannerEngineMetadata.class);
     } catch (Exception e) {
-      throw new IllegalStateException("Failed to get the scanner-engine metadata", e);
+      throw new MessageException("Failed to get the scanner-engine metadata: " + e.getMessage(), e);
     }
   }
 
diff --git a/lib/src/main/java/org/sonarsource/scanner/lib/internal/facade/inprocess/IsolatedLauncherFactory.java b/lib/src/main/java/org/sonarsource/scanner/lib/internal/facade/inprocess/IsolatedLauncherFactory.java
@@ -77,7 +77,7 @@ IsolatedLauncherAndClassloader createLauncher(final LegacyScannerEngineDownloade
       IsolatedLauncher objProxy = IsolatedLauncherProxy.create(cl, IsolatedLauncher.class, launcherImplClassName);
       tempCleaning.clean();
 
-      return new IsolatedLauncherAndClassloader(objProxy, cl, jarFiles.stream().allMatch(CachedFile::isCacheHit));
+      return new IsolatedLauncherAndClassloader(objProxy, cl, jarFiles.stream().allMatch(CachedFile::getCacheHit));
     } catch (Exception e) {
       // Catch all other exceptions, which relates to reflection
       throw new ScannerException("Unable to execute SonarScanner analysis", e);
diff --git a/lib/src/main/java/org/sonarsource/scanner/lib/internal/facade/simulation/SimulationScannerEngineFacade.java b/lib/src/main/java/org/sonarsource/scanner/lib/internal/facade/simulation/SimulationScannerEngineFacade.java
@@ -40,7 +40,7 @@ public class SimulationScannerEngineFacade extends AbstractScannerEngineFacade {
 
   public SimulationScannerEngineFacade(Map<String, String> bootstrapProperties, boolean isSonarCloud,
     @Nullable String serverVersion) {
-    super(bootstrapProperties, isSonarCloud, serverVersion, false, null);
+    super(bootstrapProperties, isSonarCloud, serverVersion, null, null);
   }
 
   @Override
diff --git a/lib/src/test/java/org/sonarsource/scanner/lib/internal/cache/FileCacheTest.java b/lib/src/test/java/org/sonarsource/scanner/lib/internal/cache/FileCacheTest.java
@@ -126,14 +126,14 @@ public void download(String filename, Path toFile) throws IOException {
       .hasFileName("sonar-foo-plugin-1.5.jar");
     assertThat(cachedFile.getPathInCache().getParent()).hasParent(cache.getDir());
     assertThat(read(cachedFile.getPathInCache())).isEqualTo("body");
-    assertThat(cachedFile.isCacheHit()).isFalse();
+    assertThat(cachedFile.getCacheHit()).isFalse();
 
     var againFromCache = cache.getOrDownload("sonar-foo-plugin-1.5.jar", "ABCDE", HASH_ALGO, downloader);
     assertThat(againFromCache.getPathInCache()).isRegularFile()
       .hasFileName("sonar-foo-plugin-1.5.jar");
     assertThat(againFromCache.getPathInCache().getParent()).hasParent(cache.getDir());
     assertThat(read(againFromCache.getPathInCache())).isEqualTo("body");
-    assertThat(againFromCache.isCacheHit()).isTrue();
+    assertThat(againFromCache.getCacheHit()).isTrue();
   }
 
   @Test
diff --git a/lib/src/test/java/org/sonarsource/scanner/lib/internal/facade/forked/ScannerEngineLauncherFactoryTest.java b/lib/src/test/java/org/sonarsource/scanner/lib/internal/facade/forked/ScannerEngineLauncherFactoryTest.java
@@ -20,14 +20,19 @@
 package org.sonarsource.scanner.lib.internal.facade.forked;
 
 import java.io.IOException;
+import java.nio.file.Files;
 import java.nio.file.Path;
-import java.util.HashMap;
 import java.util.Map;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.RegisterExtension;
 import org.junit.jupiter.api.io.TempDir;
+import org.slf4j.event.Level;
+import org.sonarsource.scanner.lib.internal.MessageException;
 import org.sonarsource.scanner.lib.internal.cache.FileCache;
 import org.sonarsource.scanner.lib.internal.http.ScannerHttpClient;
+import testutils.LogTester;
 
+import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.anyMap;
@@ -44,32 +49,59 @@ class ScannerEngineLauncherFactoryTest {
   private final FileCache fileCache = mock(FileCache.class);
   private final JavaRunnerFactory javaRunnerFactory = mock(JavaRunnerFactory.class);
 
+  @RegisterExtension
+  private final LogTester logTester = new LogTester();
+
   @TempDir
   private Path temp;
 
   @Test
-  void createLauncher() {
+  void createLauncher_use_engine_provisioning_by_default() {
     when(scannerHttpClient.callRestApi(API_PATH_ENGINE)).thenReturn("{\"filename\":\"scanner-engine.jar\",\"sha256\":\"123456\"}");
     when(javaRunnerFactory.createRunner(eq(scannerHttpClient), eq(fileCache), anyMap())).thenReturn(mock(JavaRunner.class));
 
     ScannerEngineLauncherFactory factory = new ScannerEngineLauncherFactory(javaRunnerFactory);
-    factory.createLauncher(scannerHttpClient, fileCache, new HashMap<>());
+    factory.createLauncher(scannerHttpClient, fileCache, Map.of());
 
     verify(fileCache).getOrDownload(eq("scanner-engine.jar"), eq("123456"), eq("SHA-256"),
       any(ScannerEngineLauncherFactory.ScannerEngineDownloader.class));
   }
 
+  @Test
+  void createLauncher_use_local_scanner_engine_if_specified(@TempDir Path temp) throws IOException {
+    Path jarPath = temp.resolve("my-engine.jar");
+    Files.createFile(jarPath);
+    when(javaRunnerFactory.createRunner(eq(scannerHttpClient), eq(fileCache), anyMap())).thenReturn(mock(JavaRunner.class));
+
+    ScannerEngineLauncherFactory factory = new ScannerEngineLauncherFactory(javaRunnerFactory);
+    factory.createLauncher(scannerHttpClient, fileCache, Map.of("sonar.scanner.engineJarPath", jarPath.toString()));
+
+    verifyNoInteractions(fileCache);
+    assertThat(logTester.logs(Level.INFO)).contains("Using the configured Scanner Engine '" + jarPath + "'");
+  }
+
+  @Test
+  void createLauncher_fails_if_local_scanner_engine_doesnt_exist() {
+    when(javaRunnerFactory.createRunner(eq(scannerHttpClient), eq(fileCache), anyMap())).thenReturn(mock(JavaRunner.class));
+
+    ScannerEngineLauncherFactory factory = new ScannerEngineLauncherFactory(javaRunnerFactory);
+    Map<String, String> properties = Map.of("sonar.scanner.engineJarPath", "dontexist.jar");
+    assertThatThrownBy(() -> factory.createLauncher(scannerHttpClient, fileCache, properties))
+      .isInstanceOf(MessageException.class)
+      .hasMessage("Scanner Engine jar path 'dontexist.jar' does not exist. Please check property 'sonar.scanner.engineJarPath'.");
+  }
+
   @Test
   void createLauncher_fail_to_download_engine_metadata() {
-    when(scannerHttpClient.callRestApi(API_PATH_ENGINE)).thenThrow(new IllegalStateException());
+    when(scannerHttpClient.callRestApi(API_PATH_ENGINE)).thenThrow(new IllegalStateException("Some error"));
     when(javaRunnerFactory.createRunner(eq(scannerHttpClient), eq(fileCache), anyMap())).thenReturn(mock(JavaRunner.class));
 
     ScannerEngineLauncherFactory factory = new ScannerEngineLauncherFactory(javaRunnerFactory);
     Map<String, String> properties = Map.of();
 
     assertThatThrownBy(() -> factory.createLauncher(scannerHttpClient, fileCache, properties))
-      .isInstanceOf(IllegalStateException.class)
-      .hasMessage("Failed to get the scanner-engine metadata");
+      .isInstanceOf(MessageException.class)
+      .hasMessage("Failed to get the scanner-engine metadata: Some error");
 
     verifyNoInteractions(fileCache);
   }
@@ -80,7 +112,7 @@ void scannerEngineDownloader_download() throws IOException {
     var output = temp.resolve(filename);
     new ScannerEngineLauncherFactory.ScannerEngineDownloader(scannerHttpClient,
       new ScannerEngineLauncherFactory.ScannerEngineMetadata(filename, "123456", null))
-      .download(filename, output);
+        .download(filename, output);
     verify(scannerHttpClient).downloadFromRestApi(API_PATH_ENGINE, output);
   }
 
@@ -90,7 +122,7 @@ void scannerEngineDownloader_download_withDownloadUrl() throws IOException {
     var output = temp.resolve(filename);
     new ScannerEngineLauncherFactory.ScannerEngineDownloader(scannerHttpClient,
       new ScannerEngineLauncherFactory.ScannerEngineMetadata(filename, "123456", "https://localhost/scanner-engine.jar"))
-      .download(filename, output);
+        .download(filename, output);
     verify(scannerHttpClient).downloadFromExternalUrl("https://localhost/scanner-engine.jar", output);
   }
 }

Original file line number	Diff line number	Diff line change
`@@ -20,13 +20,15 @@`
`20`	`20`	`package org.sonarsource.scanner.lib.internal.cache;`
`21`	`21`
`22`	`22`	`import java.nio.file.Path;`
	`23`	`+import javax.annotation.CheckForNull;`
	`24`	`+import javax.annotation.Nullable;`
`23`	`25`
`24`	`26`	`public class CachedFile {`
`25`	`27`
`26`	`28`	`private final Path pathInCache;`
`27`		`- private final boolean cacheHit;`
	`29`	`+ private final Boolean cacheHit;`
`28`	`30`
`29`		`- public CachedFile(Path pathInCache, boolean cacheHit) {`
	`31`	`+ public CachedFile(Path pathInCache, @Nullable Boolean cacheHit) {`
`30`	`32`	`this.pathInCache = pathInCache;`
`31`	`33`	`this.cacheHit = cacheHit;`
`32`	`34`	`}`
`@@ -35,7 +37,8 @@ public Path getPathInCache() {`
`35`	`37`	`return pathInCache;`
`36`	`38`	`}`
`37`	`39`
`38`		`- public boolean isCacheHit() {`
	`40`	`+ @CheckForNull`
	`41`	`+ public Boolean getCacheHit() {`
`39`	`42`	`return cacheHit;`
`40`	`43`	`}`
`41`	`44`	`}`
Original file line number	Diff line number	Diff line change
`@@ -28,7 +28,7 @@ public class NewScannerEngineFacade extends AbstractScannerEngineFacade {`
`28`	`28`
`29`	`29`	`private NewScannerEngineFacade(Map<String, String> bootstrapProperties, ScannerEngineLauncher launcher,`
`30`	`30`	`boolean isSonarQubeCloud, @Nullable String serverVersion) {`
`31`		`- super(bootstrapProperties, isSonarQubeCloud, serverVersion, launcher.isEngineCacheHit(), launcher.getJreCacheHit());`
	`31`	`+ super(bootstrapProperties, isSonarQubeCloud, serverVersion, launcher.getEngineCacheHit(), launcher.getJreCacheHit());`
`32`	`32`	`this.launcher = launcher;`
`33`	`33`	`}`
`34`	`34`
Original file line number	Diff line number	Diff line change
`@@ -40,7 +40,7 @@ public class SimulationScannerEngineFacade extends AbstractScannerEngineFacade {`
`40`	`40`
`41`	`41`	`public SimulationScannerEngineFacade(Map<String, String> bootstrapProperties, boolean isSonarCloud,`
`42`	`42`	`@Nullable String serverVersion) {`
`43`		`- super(bootstrapProperties, isSonarCloud, serverVersion, false, null);`
	`43`	`+ super(bootstrapProperties, isSonarCloud, serverVersion, null, null);`
`44`	`44`	`}`
`45`	`45`
`46`	`46`	`@Override`