docs: how to use the Micronaut ResourceLoader API with example using ResourceResolver

src/main/docs/guide/resources.adoc

@@ -0,0 +1,9 @@
+Micronaut Framework provides support for loading resources from files into memory, rooted at the api:core.io.ResourceLoader[] API. Two built-in implementations include api:core.io.file.DefaultFileSystemResourceLoader[] and api:core.io.scan.DefaultClassPathResourceLoader[].
+
+A convenience class api:core.io.ResourceResolver[] is provided that leverages both of these  implementations. The following example illustrates using the API to read a text file from the classpath.
+
+snippet::io.micronaut.docs.resources.MyResourceLoader[tags="class",indent=0,title="ResourceResolver Example"]
+
+<1> Injects an instance of `ResourceResolver`
+<2> Uses the `ResourceResolver` API to get a `URL` to a file in the classpath, if it exists.
+<3> api:core.io.IOUtils[] provides further support for I/O operations, in this case reading the file contents into a String.

src/main/docs/guide/toc.yml

@@ -346,6 +346,8 @@ i18n:
   title: Internationalization
   bundle: Resource Bundles
   localizedMessageSource: Localized Message Source
+resources:
+  title: Resources
 appendix:
   title: Appendices
   architecture:

test-suite-groovy/src/test/groovy/io/micronaut/docs/resources/MyResourceLoader.groovy

@@ -0,0 +1,28 @@
+package io.micronaut.docs.resources
+
+import io.micronaut.context.annotation.Requires
+import io.micronaut.core.io.IOUtils
+import io.micronaut.core.io.ResourceResolver
+import jakarta.inject.Singleton
+
+@Requires(property='spec.name', value='ResourceLoaderSpec')
+// tag::class[]
+@Singleton
+class MyResourceLoader {
+
+    private final ResourceResolver resourceResolver // <1>
+
+    MyResourceLoader(ResourceResolver resourceResolver) { // <1>
+        this.resourceResolver = resourceResolver
+    }
+
+    Optional<String> getClasspathResourceAsText(String path) throws Exception {
+        Optional<URL> url = resourceResolver.getResource('classpath:' + path) // <2>
+        if (url.isPresent()) {
+            return Optional.of(IOUtils.readText(new BufferedReader(new InputStreamReader(url.get().openStream()))))  // <3>
+        } else {
+            return Optional.empty()
+        }
+    }
+}
+// end::class[]

test-suite-groovy/src/test/groovy/io/micronaut/docs/resources/ResourceLoaderSpec.groovy

@@ -0,0 +1,26 @@
+package io.micronaut.docs.resources
+
+import io.micronaut.context.ApplicationContext
+import spock.lang.Specification
+
+class ResourceLoaderSpec extends Specification {
+
+    void "test example for ResourceResolver"() {
+
+        when:
+        ApplicationContext applicationContext = ApplicationContext.run(
+                'spec.name': 'ResourceLoaderSpec',
+                'test'
+        )
+        MyResourceLoader myResourceLoader = applicationContext.getBean(MyResourceLoader)
+
+        then:
+        myResourceLoader
+        Optional<String> text = myResourceLoader.getClasspathResourceAsText('hello.txt');
+        text.isPresent()
+        'Hello!' == text.get().trim()
+
+        cleanup:
+        applicationContext.stop()
+    }
+}

test-suite-groovy/src/test/resources/hello.txt

@@ -0,0 +1 @@
+Hello!

test-suite-kotlin/src/test/kotlin/io/micronaut/docs/resources/MyResourceLoader.kt

@@ -0,0 +1,26 @@
+package io.micronaut.docs.resources
+
+import io.micronaut.context.annotation.Requires
+import io.micronaut.core.io.IOUtils
+import io.micronaut.core.io.ResourceResolver
+import jakarta.inject.Singleton
+import java.io.BufferedReader
+import java.io.InputStreamReader
+import java.util.*
+
+@Requires(property = "spec.name", value = "ResourceLoaderTest")
+// tag::class[]
+@Singleton
+class MyResourceLoader(private val resourceResolver: ResourceResolver) { // <1>
+
+    @Throws(Exception::class)
+    fun getClasspathResourceAsText(path: String): Optional<String> {
+        val url = resourceResolver.getResource("classpath:$path") // <2>
+        return if (url.isPresent) {
+            Optional.of(IOUtils.readText(BufferedReader(InputStreamReader(url.get().openStream()))))  // <3>
+        } else {
+            Optional.empty()
+        }
+    }
+}
+// end::class[]

test-suite-kotlin/src/test/kotlin/io/micronaut/docs/resources/ResourceLoaderTest.kt

@@ -0,0 +1,26 @@
+package io.micronaut.docs.resources
+
+import io.micronaut.context.ApplicationContext
+import org.junit.jupiter.api.Assertions
+import org.junit.jupiter.api.Test
+
+internal class ResourceLoaderTest {
+
+    @Test
+    @Throws(Exception::class)
+    fun testExampleForResourceResolver() {
+
+        val applicationContext = ApplicationContext.run(
+            mapOf("spec.name" to "ResourceLoaderTest"),
+            "test"
+        )
+        val myResourceLoader = applicationContext.getBean(MyResourceLoader::class.java)
+
+        Assertions.assertNotNull(myResourceLoader)
+        val text = myResourceLoader.getClasspathResourceAsText("hello.txt")
+        Assertions.assertTrue(text.isPresent)
+        Assertions.assertEquals("Hello!", text.get().trim { it <= ' ' })
+
+        applicationContext.stop()
+    }
+}

test-suite-kotlin/src/test/resources/hello.txt

@@ -0,0 +1 @@
+Hello!

test-suite/src/test/java/io/micronaut/docs/resources/MyResourceLoader.java

@@ -0,0 +1,33 @@
+package io.micronaut.docs.resources;
+
+import io.micronaut.context.annotation.Requires;
+import io.micronaut.core.io.IOUtils;
+import io.micronaut.core.io.ResourceResolver;
+import jakarta.inject.Singleton;
+
+import java.io.BufferedReader;
+import java.io.InputStreamReader;
+import java.net.URL;
+import java.util.Optional;
+
+@Requires(property="spec.name", value="ResourceLoaderTest")
+// tag::class[]
+@Singleton
+public class MyResourceLoader {
+
+    private final ResourceResolver resourceResolver;
+
+    public MyResourceLoader(ResourceResolver resourceResolver) {  // <1>
+        this.resourceResolver = resourceResolver;
+    }
+
+    public Optional<String> getClasspathResourceAsText(String path) throws Exception {
+        Optional<URL> url = resourceResolver.getResource("classpath:" + path); // <2>
+        if (url.isPresent()) {
+            return Optional.of(IOUtils.readText(new BufferedReader(new InputStreamReader(url.get().openStream())))); // <3>
+        } else {
+            return Optional.empty();
+        }
+    }
+}
+// end::class[]

test-suite/src/test/java/io/micronaut/docs/resources/ResourceLoaderTest.java

@@ -0,0 +1,30 @@
+package io.micronaut.docs.resources;
+
+import io.micronaut.context.ApplicationContext;
+import org.junit.jupiter.api.Test;
+
+import java.util.Map;
+import java.util.Optional;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class ResourceLoaderTest {
+
+    @Test
+    void testExampleForResourceResolver() throws Exception {
+        ApplicationContext applicationContext = ApplicationContext.run(
+            Map.of("spec.name", "ResourceLoaderTest"),
+            "test"
+        );
+        MyResourceLoader myResourceLoader = applicationContext.getBean(MyResourceLoader.class);
+
+        assertNotNull(myResourceLoader);
+        Optional<String> text = myResourceLoader.getClasspathResourceAsText("hello.txt");
+        assertTrue(text.isPresent());
+        assertEquals("Hello!", text.get().trim());
+
+        applicationContext.stop();
+    }
+}

test-suite/src/test/resources/hello.txt

@@ -0,0 +1 @@
+Hello!