Document Spring Boot substitutions

Closes gh-1475

Author: sdeleuze

spring-native/src/main/java/org/springframework/nativex/substitutions/boot/NativeSpringBootVersion.java

@@ -27,7 +27,9 @@
 
 import org.springframework.boot.origin.Origin;
 
-// TODO Work with Boot team on build time invocation of determineSpringBootVersion() and avoid generated code in org.springframework.boot package
+/**
+ * See {@link Target_SpringBootVersion}.
+ */
 final class NativeSpringBootVersion {
 
 	private static String VERSION = determineSpringBootVersion();

spring-native/src/main/java/org/springframework/nativex/substitutions/boot/Target_BeanDefinitionLoader.java

@@ -10,6 +10,13 @@
 import org.springframework.nativex.substitutions.OnlyIfPresent;
 import org.springframework.nativex.substitutions.WithAot;
 
+/**
+ * Why this substitution exists?
+ * Because BeanDefinitionLoader is package private and need to be referenced from {@link Target_SpringApplication} (SpringApplication substitution).
+ *
+ * How this substitution workarounds the problem?
+ * It provides aliases for some its methods.
+ */
 @TargetClass(className = "org.springframework.boot.BeanDefinitionLoader", onlyWith = { WithAot.class, OnlyIfPresent.class })
 final class Target_BeanDefinitionLoader {
 

spring-native/src/main/java/org/springframework/nativex/substitutions/boot/Target_DatabaseInitializationDependencyConfigurer.java

@@ -30,6 +30,13 @@
 import com.oracle.svm.core.annotate.Substitute;
 import com.oracle.svm.core.annotate.TargetClass;
 
+/**
+ * Why this substitution exists?
+ * To avoid using SpringFactoriesLoader#loadFactoryNames() in order to use reflection-less variant when possible.
+ *
+ * How this substitution workarounds the problem?
+ * It invokes SpringFactoriesLoader#loadFactories() when possible instead (which is using underneath StaticSpringFactories generated AOT).
+ */
 @TargetClass(className="org.springframework.boot.sql.init.dependency.DatabaseInitializationDependencyConfigurer$DependsOnDatabaseInitializationPostProcessor", onlyWith = { WithAot.class, OnlyIfPresent.class })
 final class Target_DatabaseInitializationDependencyConfigurer {
 

spring-native/src/main/java/org/springframework/nativex/substitutions/boot/Target_FailureAnalyzers.java

@@ -27,6 +27,13 @@
 import org.springframework.nativex.substitutions.OnlyIfPresent;
 import org.springframework.nativex.substitutions.WithAot;
 
+/**
+ * Why this substitution exists?
+ * To avoid using SpringFactoriesLoader#loadFactoryNames() in order to use reflection-less variant when possible.
+ *
+ * How this substitution workarounds the problem?
+ * It invokes SpringFactoriesLoader#loadFactories instead (which is using underneath StaticSpringFactories generated AOT).
+ */
 @TargetClass(className="org.springframework.boot.diagnostics.FailureAnalyzers", onlyWith = { WithAot.class, OnlyIfPresent.class })
 final class Target_FailureAnalyzers {
 

spring-native/src/main/java/org/springframework/nativex/substitutions/boot/Target_JsonParserFactory.java

@@ -27,6 +27,16 @@
 import org.springframework.nativex.substitutions.RemoveYamlSupport;
 import org.springframework.util.ClassUtils;
 
+/**
+ * Why this substitution exists?
+ * To avoid shipping YamlJsonParser in the native image when Yaml support is disabled via removeYamlSupport Spring AOT flag.
+ *
+ * How this substitution workarounds the problem?
+ * It substitutes JsonParserFactory#getJsonParser with an alternative version without the related if clause when removeYamlSupport is true.
+ *
+ * Possible improvements
+ * Perform all the ClassUtils#isPresent() checks (including Gson one) at build time.
+ */
 @TargetClass(className = "org.springframework.boot.json.JsonParserFactory", onlyWith = { RemoveYamlSupport.class, OnlyIfPresent.class })
 final class Target_JsonParserFactory {
 

spring-native/src/main/java/org/springframework/nativex/substitutions/boot/Target_SpringApplication.java

@@ -35,6 +35,16 @@
 import org.springframework.nativex.substitutions.WithAot;
 import org.springframework.util.StringUtils;
 
+/**
+ * Why this substitution exists?
+ *  - It provide different codepaths when AOT mode is enabled.
+ *
+ * How this substitution workarounds the problem?
+ * - It skips BeanDefinitionLoader#load() when AOT mode is enabled in order to skip A LOT of runtime infrastructure to be included in the native image
+ *   like AnnotatedBeanDefinitionReader, XmlBeanDefinitionReader, GroovyBeanDefinitionReader and ClassPathBeanDefinitionScanner.
+ * - It uses org.springframework.aot.ContextBootstrapInitializer (via getSpringFactoriesInstances(ApplicationContextInitializer.class)) when AOT mode
+ *   is enabled to load the precomputed beans.
+ */
 @TargetClass(className = "org.springframework.boot.SpringApplication", onlyWith = { WithAot.class, OnlyIfPresent.class })
 final class Target_SpringApplication {
 

spring-native/src/main/java/org/springframework/nativex/substitutions/boot/Target_SpringApplicationBannerPrinter.java

@@ -24,6 +24,13 @@
 import org.springframework.core.env.Environment;
 import org.springframework.nativex.substitutions.OnlyIfPresent;
 
+/**
+ * Why this substitution exists?
+ * To avoid shipping ImageBanner in the native image which is shipping itself a subset of AWT (really bad for the memory footprint).
+ *
+ * How this substitution workarounds the problem?
+ * It disables image banner support and just returns the default one.
+ */
 @TargetClass(className = "org.springframework.boot.SpringApplicationBannerPrinter", onlyWith = OnlyIfPresent.class)
 final class Target_SpringApplicationBannerPrinter {
 

spring-native/src/main/java/org/springframework/nativex/substitutions/boot/Target_SpringBootVersion.java

@@ -21,6 +21,15 @@
 
 import org.springframework.nativex.substitutions.OnlyIfPresent;
 
+/**
+ * Why this substitution exists?
+ * SpringBootVersion#determineSpringBootVersion() current implementation is triggering usage of a lot of infrastructure
+ * (especially via jarFile.getManifest()) to identify the Spring Boot version at runtime.
+ *
+ * How this substitution workarounds the problem?
+ * NativeSpringBootVersion#determineSpringBootVersion() is invoked at build time because it is invoked to populate
+ * NativeSpringBootVersion#VERSION + NativeSpringBootVersion configured to be initialized at build time in SpringBootHints.
+ */
 @TargetClass(className = "org.springframework.boot.SpringBootVersion", onlyWith = OnlyIfPresent.class)
 final class Target_SpringBootVersion {
 

spring-native/src/main/java/org/springframework/nativex/substitutions/boot/Target_WebApplicationType.java

@@ -7,6 +7,14 @@
 import org.springframework.nativex.substitutions.OnlyIfPresent;
 import org.springframework.nativex.substitutions.WithAot;
 
+/**
+ * Why this substitution exists?
+ * Because WebApplicationType#deduceFromClasspath() is package private and need to be referenced from
+ * {@link Target_SpringApplication} (SpringApplication substitution).
+ *
+ * How this substitution workarounds the problem?
+ * It provides an alias for this method.
+ */
 @TargetClass(className = "org.springframework.boot.WebApplicationType", onlyWith = { WithAot.class, OnlyIfPresent.class })
 final class Target_WebApplicationType {