Document RuntimeHints testing strategies

Closes gh-29523

framework-docs/src/main/java/org/springframework/docs/core/aot/hints/importruntimehints/SpellCheckService.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2002-2022 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.docs.core.aot.hints.importruntimehints;
+
+import java.util.Locale;
+
+import org.springframework.aot.hint.RuntimeHints;
+import org.springframework.aot.hint.RuntimeHintsRegistrar;
+import org.springframework.context.annotation.ImportRuntimeHints;
+import org.springframework.core.io.ClassPathResource;
+import org.springframework.stereotype.Component;
+
+@Component
+@ImportRuntimeHints(SpellCheckService.SpellCheckServiceRuntimeHints.class)
+public class SpellCheckService {
+
+	public void loadDictionary(Locale locale) {
+		ClassPathResource resource = new ClassPathResource("dicts/" + locale.getLanguage() + ".txt");
+		//...
+	}
+
+	static class SpellCheckServiceRuntimeHints implements RuntimeHintsRegistrar {
+
+		@Override
+		public void registerHints(RuntimeHints hints, ClassLoader classLoader) {
+			hints.resources().registerPattern("dicts/*");
+		}
+	}
+
+}

framework-docs/src/main/java/org/springframework/docs/core/aot/hints/testing/SampleReflection.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2002-2022 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.docs.core.aot.hints.testing;
+
+import java.lang.reflect.Method;
+
+import org.apache.commons.logging.Log;
+import org.apache.commons.logging.LogFactory;
+
+import org.springframework.util.ClassUtils;
+
+public class SampleReflection {
+
+	private final Log logger = LogFactory.getLog(SampleReflection.class);
+
+	public void performReflection() {
+		try {
+			Class<?> springVersion = ClassUtils.forName("org.springframework.core.SpringVersion", null);
+			Method getVersion = ClassUtils.getMethod(springVersion, "getVersion");
+			String version = (String) getVersion.invoke(null);
+			logger.info("Spring version:" + version);
+		}
+		catch (Exception exc) {
+			logger.error("reflection failed", exc);
+		}
+	}
+}

framework-docs/src/main/java/org/springframework/docs/core/aot/hints/testing/SampleReflectionRuntimeHintsTests.java

@@ -0,0 +1,54 @@
+/*
+ * Copyright 2002-2022 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.docs.core.aot.hints.testing;
+
+import java.util.List;
+
+import org.junit.jupiter.api.Test;
+
+import org.springframework.aot.hint.ExecutableMode;
+import org.springframework.aot.hint.RuntimeHints;
+import org.springframework.aot.test.agent.EnabledIfRuntimeHintsAgent;
+import org.springframework.aot.test.agent.RuntimeHintsInvocations;
+import org.springframework.aot.test.agent.RuntimeHintsRecorder;
+import org.springframework.core.SpringVersion;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+// This annotation conditions the execution of tests only if the agent is loaded in the current JVM
+// it also tags tests with the "RuntimeHints" JUnit tag
+@EnabledIfRuntimeHintsAgent
+class SampleReflectionRuntimeHintsTests {
+
+	@Test
+	void shouldRegisterReflectionHints() {
+		RuntimeHints runtimeHints = new RuntimeHints();
+		// Call a RuntimeHintsRegistrar that contributes hints like:
+		runtimeHints.reflection().registerType(SpringVersion.class, typeHint -> {
+			typeHint.withMethod("getVersion", List.of(), ExecutableMode.INVOKE);
+		});
+
+		// Invoke the relevant piece of code we want to test within a recording lambda
+		RuntimeHintsInvocations invocations = RuntimeHintsRecorder.record(() -> {
+			SampleReflection sample = new SampleReflection();
+			sample.performReflection();
+		});
+		// assert that the recorded invocations are covered by the contributed hints
+		assertThat(invocations).match(runtimeHints);
+	}
+
+}

framework-docs/src/main/java/org/springframework/docs/core/aot/hints/testing/SpellCheckServiceTests.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2002-2022 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.docs.core.aot.hints.testing;
+
+import org.junit.jupiter.api.Test;
+
+import org.springframework.aot.hint.RuntimeHints;
+import org.springframework.aot.hint.RuntimeHintsRegistrar;
+import org.springframework.aot.hint.predicate.RuntimeHintsPredicates;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+public class SpellCheckServiceTests {
+
+	// tag::hintspredicates[]
+	@Test
+	void shouldRegisterResourceHints() {
+		RuntimeHints hints = new RuntimeHints();
+		new SpellCheckServiceRuntimeHints().registerHints(hints, getClass().getClassLoader());
+		assertThat(RuntimeHintsPredicates.resource().forResource("dicts/en.txt"))
+				.accepts(hints);
+	}
+	// end::hintspredicates[]
+
+	// Copied here because it is package private in SpellCheckService
+	static class SpellCheckServiceRuntimeHints implements RuntimeHintsRegistrar {
+
+		@Override
+		public void registerHints(RuntimeHints hints, ClassLoader classLoader) {
+			hints.resources().registerPattern("dicts/*");
+		}
+	}
+}

framework-docs/src/main/java/org/springframework/docs/core/aot/refresh/AotProcessingSample.java

@@ -0,0 +1,52 @@
+/*
+ * Copyright 2002-2022 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.docs.core.aot.refresh;
+
+import org.springframework.aot.hint.RuntimeHints;
+import org.springframework.context.annotation.AnnotationConfigApplicationContext;
+import org.springframework.context.annotation.ComponentScan;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Import;
+
+public class AotProcessingSample {
+
+	public void createAotContext() {
+		// tag::aotcontext[]
+		RuntimeHints hints = new RuntimeHints();
+		AnnotationConfigApplicationContext context = new AnnotationConfigApplicationContext();
+		context.register(MyApplication.class);
+		context.refreshForAotProcessing(hints);
+		// end::aotcontext[]
+	}
+
+	// tag::myapplication[]
+	@Configuration(proxyBeanMethods=false)
+	@ComponentScan
+	@Import({DataSourceConfiguration.class, ContainerConfiguration.class})
+	public class MyApplication {
+
+	}
+	// end::myapplication[]
+
+	class DataSourceConfiguration {
+
+	}
+
+	class ContainerConfiguration {
+
+	}
+}