From eba5c5b895b13abf935a687887f74ec2fe6b8468 Mon Sep 17 00:00:00 2001
From: Lukas Eder <lukas.eder@gmail.com>
Date: Wed, 27 Apr 2022 14:05:40 +0200
Subject: [PATCH] [jOOQ/jOOQ#13496] Specify the Scope subtype lifecycles in
 their Javadoc

- Context
- DSLContext
- ExecuteContext
- GeneratorContext
- Meta
- Migration
- MigrationContext
- RecordContext
- ResourceManagingScope
- TransactionContext
- VisitContext
---
 jOOQ/src/main/java/org/jooq/Context.java       | 12 ++++++++++++
 jOOQ/src/main/java/org/jooq/DSLContext.java    | 18 +++++++++++-------
 .../src/main/java/org/jooq/ExecuteContext.java | 10 +++++++++-
 .../main/java/org/jooq/GeneratorContext.java   |  7 ++++++-
 jOOQ/src/main/java/org/jooq/Meta.java          |  3 +++
 jOOQ/src/main/java/org/jooq/Migration.java     |  3 +++
 .../main/java/org/jooq/MigrationContext.java   |  3 +++
 jOOQ/src/main/java/org/jooq/ParseContext.java  |  3 +++
 jOOQ/src/main/java/org/jooq/RecordContext.java |  3 +++
 .../java/org/jooq/ResourceManagingScope.java   |  3 +++
 .../main/java/org/jooq/TransactionContext.java |  3 +++
 jOOQ/src/main/java/org/jooq/VisitContext.java  |  4 ++++
 12 files changed, 63 insertions(+), 9 deletions(-)

diff --git a/jOOQ/src/main/java/org/jooq/Context.java b/jOOQ/src/main/java/org/jooq/Context.java
index 7fb09e7ceb..3cf610679f 100644
--- a/jOOQ/src/main/java/org/jooq/Context.java
+++ b/jOOQ/src/main/java/org/jooq/Context.java
@@ -53,6 +53,18 @@ import org.jetbrains.annotations.Nullable;
 
 /**
  * A context type that is used for rendering SQL or for binding.
+ * <p>
+ * This type implements {@link Scope} and thus has a lifecycle defined by the
+ * rendering or binding operation.
+ * <p>
+ * The {@link #data()} map contents are maintained for the entirety of the
+ * rendering or binding operation, and are passed along to child {@link Scope}
+ * types, including e.g.
+ * <ul>
+ * <li>{@link GeneratorContext}: When computing client side computed column
+ * values</li>
+ * <li>{@link BindingSQLContext}: When generating the SQL for bind values</li>
+ * </ul>
  *
  * @author Lukas Eder
  * @see BindContext
diff --git a/jOOQ/src/main/java/org/jooq/DSLContext.java b/jOOQ/src/main/java/org/jooq/DSLContext.java
index 13aad618cd..bedc0c82e4 100644
--- a/jOOQ/src/main/java/org/jooq/DSLContext.java
+++ b/jOOQ/src/main/java/org/jooq/DSLContext.java
@@ -127,13 +127,12 @@ import io.r2dbc.spi.ConnectionFactory;
  * A contextual DSL providing "attached" implementations to the
  * <code>org.jooq</code> interfaces.
  * <p>
- * Apart from the {@link DSL}, this contextual DSL is the main entry point
- * for client code, to access jOOQ classes and functionality that are related to
- * {@link Query} execution. Unlike objects created through the
- * <code>DSL</code> type, objects created from a <code>DSLContext</code> will be
- * "attached" to the <code>DSLContext</code>'s {@link #configuration()}, such
- * that they can be executed immediately in a fluent style. An example is given
- * here:
+ * Apart from the {@link DSL}, this contextual DSL is the main entry point for
+ * client code, to access jOOQ classes and functionality that are related to
+ * {@link Query} execution. Unlike objects created through the <code>DSL</code>
+ * type, objects created from a <code>DSLContext</code> will be "attached" to
+ * the <code>DSLContext</code>'s {@link #configuration()}, such that they can be
+ * executed immediately in a fluent style. An example is given here:
  * <p>
  * <code><pre>
  * DSLContext create = DSL.using(connection, dialect);
@@ -152,6 +151,11 @@ import io.r2dbc.spi.ConnectionFactory;
  * constructor. Please consider thread-safety concerns documented in
  * {@link Configuration}, should you want to reuse the same
  * <code>Configuration</code> instance in various threads and / or transactions.
+ * <p>
+ * {@link DSLContext} is a {@link Scope} type, mostly for convenience access to
+ * its underlying {@link Configuration} properties, including the
+ * {@link #data()} map, which it shares with the {@link Configuration}. It does
+ * not have an independent lifecycle.
  *
  * @see DSL
  * @see Configuration
diff --git a/jOOQ/src/main/java/org/jooq/ExecuteContext.java b/jOOQ/src/main/java/org/jooq/ExecuteContext.java
index 4e600534d7..0530815ff4 100644
--- a/jOOQ/src/main/java/org/jooq/ExecuteContext.java
+++ b/jOOQ/src/main/java/org/jooq/ExecuteContext.java
@@ -43,7 +43,6 @@ import java.sql.ResultSet;
 import java.sql.SQLException;
 import java.sql.SQLWarning;
 import java.sql.Statement;
-import java.time.Instant;
 import java.util.stream.Collector;
 
 import org.jooq.conf.Settings;
@@ -57,6 +56,15 @@ import org.jetbrains.annotations.Nullable;
 /**
  * A context object for {@link Query} execution passed to registered
  * {@link ExecuteListener}'s.
+ * <p>
+ * This type implements {@link Scope} and thus has a lifecycle defined by the
+ * query execution.
+ * <p>
+ * The {@link #data()} map contents are maintained for the entirety of the
+ * execution, and are passed along to child {@link Scope} types, including e.g.
+ * <ul>
+ * <li>{@link BindingScope}: When passing bind values or reading results.</li>
+ * </ul>
  *
  * @author Lukas Eder
  * @see ExecuteListener
diff --git a/jOOQ/src/main/java/org/jooq/GeneratorContext.java b/jOOQ/src/main/java/org/jooq/GeneratorContext.java
index e9b9e034cc..bd555b3849 100644
--- a/jOOQ/src/main/java/org/jooq/GeneratorContext.java
+++ b/jOOQ/src/main/java/org/jooq/GeneratorContext.java
@@ -43,9 +43,14 @@ import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 /**
- * A generator context is an argument object that is passed to a
+ * A {@link GeneratorContext} is an argument object that is passed to a
  * {@link Generator} when generating client side computed columns.
  * <p>
+ * It is a {@link Scope} that models the short lived lifecycle of the generation
+ * of the client side computed column. Its {@link #data()} map is inherited from
+ * the parent {@link Context} scope, if available, or it is an empty map in case
+ * no rendering {@link Context} was available.
+ * <p>
  * This API is part of a commercial only feature. To use this feature, please
  * use the jOOQ Professional Edition or the jOOQ Enterprise Edition.
  *
diff --git a/jOOQ/src/main/java/org/jooq/Meta.java b/jOOQ/src/main/java/org/jooq/Meta.java
index 1651543f10..243b339c40 100644
--- a/jOOQ/src/main/java/org/jooq/Meta.java
+++ b/jOOQ/src/main/java/org/jooq/Meta.java
@@ -82,6 +82,9 @@ import org.jetbrains.annotations.NotNull;
  * objects, not JDBC {@link ResultSet} objects with hard-to-remember API
  * constraints</li>
  * </ol>
+ * <p>
+ * This type is a {@link Scope} with independent lifecycle and its own
+ * {@link #data()} map.
  *
  * @author Lukas Eder
  */
diff --git a/jOOQ/src/main/java/org/jooq/Migration.java b/jOOQ/src/main/java/org/jooq/Migration.java
index ceaa717747..d42099b1f7 100644
--- a/jOOQ/src/main/java/org/jooq/Migration.java
+++ b/jOOQ/src/main/java/org/jooq/Migration.java
@@ -47,6 +47,9 @@ import org.jetbrains.annotations.ApiStatus.Experimental;
 /**
  * An executable migration between two {@link Commit} instances.
  * <p>
+ * This type is a {@link Scope} with independent lifecycle and its own
+ * {@link #data()} map.
+ * <p>
  * This is EXPERIMENTAL functionality and subject to change in future jOOQ
  * versions.
  *
diff --git a/jOOQ/src/main/java/org/jooq/MigrationContext.java b/jOOQ/src/main/java/org/jooq/MigrationContext.java
index 2f38356df4..9150e0acd0 100644
--- a/jOOQ/src/main/java/org/jooq/MigrationContext.java
+++ b/jOOQ/src/main/java/org/jooq/MigrationContext.java
@@ -47,6 +47,9 @@ import org.jetbrains.annotations.ApiStatus.Experimental;
 /**
  * The context in which a {@link Migration} is executed.
  * <p>
+ * This type is a {@link Scope} with independent lifecycle and its own
+ * {@link #data()} map.
+ * <p>
  * This is EXPERIMENTAL functionality and subject to change in future jOOQ
  * versions.
  *
diff --git a/jOOQ/src/main/java/org/jooq/ParseContext.java b/jOOQ/src/main/java/org/jooq/ParseContext.java
index 62d130af01..374fd37b37 100644
--- a/jOOQ/src/main/java/org/jooq/ParseContext.java
+++ b/jOOQ/src/main/java/org/jooq/ParseContext.java
@@ -50,6 +50,9 @@ import org.jetbrains.annotations.Nullable;
 /**
  * A publicly available API for the internal parse context that allows for
  * parsing SQL fragements.
+ * <p>
+ * This type is a {@link Scope} with independent lifecycle and its own
+ * {@link #data()} map.
  *
  * @author Lukas Eder
  */
diff --git a/jOOQ/src/main/java/org/jooq/RecordContext.java b/jOOQ/src/main/java/org/jooq/RecordContext.java
index 97e1003cd9..b281ead05b 100644
--- a/jOOQ/src/main/java/org/jooq/RecordContext.java
+++ b/jOOQ/src/main/java/org/jooq/RecordContext.java
@@ -43,6 +43,9 @@ import org.jetbrains.annotations.Nullable;
 /**
  * A context object for {@link Record} manipulation passed to registered
  * {@link RecordListener}'s.
+ * <p>
+ * This type is a {@link Scope} with independent lifecycle and its own
+ * {@link #data()} map.
  *
  * @author Lukas Eder
  */
diff --git a/jOOQ/src/main/java/org/jooq/ResourceManagingScope.java b/jOOQ/src/main/java/org/jooq/ResourceManagingScope.java
index 6a5ca5c587..7da7b4eb38 100644
--- a/jOOQ/src/main/java/org/jooq/ResourceManagingScope.java
+++ b/jOOQ/src/main/java/org/jooq/ResourceManagingScope.java
@@ -68,6 +68,9 @@ import java.sql.SQLXML;
  *     }
  * }
  * </pre></code>
+ * <p>
+ * This type is a {@link Scope} with whose lifecycle is typically tied to an
+ * {@link ExecuteContext}, sharing the latter's {@link #data()} map.
  *
  * @author Lukas Eder
  */
diff --git a/jOOQ/src/main/java/org/jooq/TransactionContext.java b/jOOQ/src/main/java/org/jooq/TransactionContext.java
index 2eaff3fb88..bd18420ce6 100644
--- a/jOOQ/src/main/java/org/jooq/TransactionContext.java
+++ b/jOOQ/src/main/java/org/jooq/TransactionContext.java
@@ -43,6 +43,9 @@ import org.jetbrains.annotations.Nullable;
 /**
  * A context object that is used to pass arguments to the various methods of
  * {@link TransactionProvider}.
+ * <p>
+ * This type is a {@link Scope} with independent lifecycle and its own
+ * {@link #data()} map.
  *
  * @author Lukas Eder
  */
diff --git a/jOOQ/src/main/java/org/jooq/VisitContext.java b/jOOQ/src/main/java/org/jooq/VisitContext.java
index edf57a1948..3345f1ceb6 100644
--- a/jOOQ/src/main/java/org/jooq/VisitContext.java
+++ b/jOOQ/src/main/java/org/jooq/VisitContext.java
@@ -43,6 +43,10 @@ import org.jetbrains.annotations.Nullable;
 /**
  * A context object for {@link QueryPart} traversal passed to registered
  * {@link VisitListener}'s.
+ * <p>
+ * This type is a {@link Scope} with whose lifecycle is shared with the parent
+ * rendering {@link Context} scope. It also shares the latter's {@link #data()}
+ * map.
  *
  * @author Lukas Eder
  * @see VisitListener