From 8df4926f4f2a9f6bfe8efbad75a8ba628f9dd089 Mon Sep 17 00:00:00 2001
From: Lukas Eder <lukas.eder@gmail.com>
Date: Fri, 14 Jun 2024 09:04:15 +0200
Subject: [PATCH] [jOOQ/jOOQ#16827] Add disclaimer about resolve not throwing
 exceptions

---
 jOOQ/src/main/java/org/jooq/Source.java | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/jOOQ/src/main/java/org/jooq/Source.java b/jOOQ/src/main/java/org/jooq/Source.java
index 46c86b08b0..8b18f6021d 100644
--- a/jOOQ/src/main/java/org/jooq/Source.java
+++ b/jOOQ/src/main/java/org/jooq/Source.java
@@ -104,6 +104,11 @@ public final class Source {
      * <li>A file system resource</li>
      * <li>A non-resource string (see {@link #of(String)})
      * </ul>
+     * <p>
+     * Note that if users expect a resource descriptor to resolve, but the
+     * resource is not found, instead of throwing an exception on
+     * {@link #reader()} or {@link #readString()}, this will just produce the
+     * input string again, as if {@link #of(String)} was called.
      */
     public static final Source resolve(String string) {
         return new Source(string, null, null, null, null, null, null, null, -1, true);
@@ -119,6 +124,11 @@ public final class Source {
      * <li>A file system resource</li>
      * <li>A non-resource string (see {@link #of(String)})
      * </ul>
+     * <p>
+     * Note that if users expect a resource descriptor to resolve, but the
+     * resource is not found, instead of throwing an exception on
+     * {@link #reader()} or {@link #readString()}, this will just produce the
+     * input string again, as if {@link #of(String)} was called.
      */
     public static final Source resolve(String string, String charsetName) {
         return new Source(string, null, charsetName, null, null, null, null, null, -1, true);
@@ -134,6 +144,11 @@ public final class Source {
      * <li>A file system resource</li>
      * <li>A non-resource string (see {@link #of(String)})
      * </ul>
+     * <p>
+     * Note that if users expect a resource descriptor to resolve, but the
+     * resource is not found, instead of throwing an exception on
+     * {@link #reader()} or {@link #readString()}, this will just produce the
+     * input string again, as if {@link #of(String)} was called.
      */
     public static final Source resolve(String string, Charset charset) {
         return new Source(string, null, null, charset, null, null, null, null, -1, true);
@@ -149,6 +164,11 @@ public final class Source {
      * <li>A file system resource</li>
      * <li>A non-resource string (see {@link #of(String)})
      * </ul>
+     * <p>
+     * Note that if users expect a resource descriptor to resolve, but the
+     * resource is not found, instead of throwing an exception on
+     * {@link #reader()} or {@link #readString()}, this will just produce the
+     * input string again, as if {@link #of(String)} was called.
      */
     public static final Source resolve(String string, CharsetDecoder charsetDecoder) {
         return new Source(string, null, null, null, charsetDecoder, null, null, null, -1, true);