[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

@@ -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

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

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

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.
  *

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
  */

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.
  *

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.
  *

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
  */

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
  */

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
  */

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
  */

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