io.agentscope.extensions.jdbc.dialect

JDBC dialect layer: table-domain interfaces (table) + aggregate abstract class + vendor implementations (vendor).

This package is the assembly layer. io.agentscope.extensions.jdbc.dialect.AbstractJdbcDialect is the aggregate abstract class that implements all table-domain interfaces and the io.agentscope.extensions.jdbc.dialect.SandboxLockStrategy contract. It holds the unified table prefix with per-table overrides. io.agentscope.extensions.jdbc.dialect.BoundSql is the unified return type for business SQL ("SQL + bind params"). io.agentscope.extensions.jdbc.dialect.AbstractJdbcDialectBuilder handles SPI-based auto-detection and optional table creation.

(1) dialect.table: one interface per table (abstract DDL + ANSI business SQL defaults), methods prefixed with table short name

+--------------------+ +------------------------+ +--------------------+
| StoreDialect | | SessionStateDialect | | SnapshotDialect |
| DDL (abstract) | | DDL (abstract) | | DDL (abstract) |
| ANSI SQL (default) | | ANSI SQL (default) | | ANSI SQL (default) |
| base name "store" | | base name "sessions" | | base name "snaps" |
+--------+-----------+ +----------+-------------+ +--------+-----------+
| | |
v v v <- implements (aggregate implements all table-domain interfaces + SandboxLockStrategy)
+--------+--------------------------+--------------------------+-----------+
| AbstractJdbcDialect aggregate abstract class |
| Implements StoreDialect, SessionStateDialect, SnapshotDialect, SandboxLockStrategy |
| Holds tablePrefix + per-table overrides; from(DataSource) returns builder |
| build() detects DB -> binds DataSource -> assembles names -> auto-creates tables |
| createTableDdls() collects all DDL; tryEnter() default = table-based lock |
| Final name resolution: override > prefix + base |
+--------+--------------------------+--------------------------+-----------+
| | |
v v v <- extends (one class per database — ALL differences in one file)

(2) dialect.vendor: override only DDL + divergent SQL + lock (if native), inherit ANSI defaults

+----------------------+ +----------------------+ +------------------+ +------------------+
| MysqlDialect | | PostgresDialect | | H2Dialect | | SqliteDialect |
| ON DUPLICATE KEY | | ON CONFLICT | | MERGE INTO | | ON CONFLICT |
| LONGTEXT/LONGBLOB | | TEXT/BYTEA | | CLOB/BLOB | | TEXT/BLOB |
| tryEnter: GET_LOCK | | tryEnter: inherited | | tryEnter: inherited | | tryEnter: inherited |
+----------------------+ +----------------------+ +------------------+ +------------------+

(3) Adding a database with native locks = override tryEnter() in the vendor class (no separate strategy class)

Adding a new table

• Create a table-domain interface in table (methods prefixed with the table short name).

• Add it to the aggregate's implements clause, plus name-override field + final resolver

• builder method + add a line to createTableDdls().

• Override the abstract DDL in each vendor class.

Adding a new database

• Create a vendor class extending io.agentscope.extensions.jdbc.dialect.AbstractJdbcDialect.

• Override DDL, divergent SQL, and supports(). Override tryEnter() only if the database has native advisory locks.

• Register the class in META-INF/services/io.agentscope.extensions.jdbc.dialect.AbstractJdbcDialect.