docs: Java API ref, C++/Java GSG variants, DB_TXN_SNAPSHOT_SAFE

.github/workflows/docs.yml

@@ -89,11 +89,15 @@ jobs:
 
       # 6. INTERNAL LINK CHECK (hard): every link into migrated content must
       #    resolve. Deferred-tree + un-migrated-asset links are excluded (see
-      #    docs_src/_migrate/lychee.toml). External links are the advisory job.
+      #    docs_src/_migrate/lychee.toml). The javadoc-generated java-api/ tree
+      #    is a build artifact (not migrated Markdown); its doc-comment
+      #    cross-links to the old DocBook paths dangle in this layout, so it is
+      #    excluded from the source set via --exclude-path. External links are
+      #    the advisory job.
       - name: Internal link check (lychee, offline)
         run: |
           nix develop --command bash -c \
-            'shopt -s globstar; lychee --offline --config docs_src/_migrate/lychee.toml --no-progress "docs-build/html/**/*.html"'
+            'shopt -s globstar; lychee --offline --config docs_src/_migrate/lychee.toml --exclude-path docs-build/html/java-api --no-progress "docs-build/html/**/*.html"'
 
       # 7. MAN-LINT (hard): 0 ERRORS from mandoc across every generated .3
       #    (STYLE/WARNING are fine).
@@ -192,7 +196,8 @@ jobs:
           nix develop --command bash -c '
             shopt -s globstar
             lychee --no-progress --scheme http --scheme https \
-              --exclude "localhost" --max-concurrency 8 \
+              --exclude "localhost" --exclude-path docs-build/html/java-api \
+              --max-concurrency 8 \
               "docs-build/html/**/*.html" || true'
 
   # ----------------------------------------------------------------------------

docs_src/_migrate/codespell-baseline.txt

@@ -137,7 +137,6 @@ docs_src/guides/porting/modscope.md	platfrom
 docs_src/guides/programmer_reference/arch_apis.md	extention
 docs_src/guides/programmer_reference/bt_conf.md	preceeding
 docs_src/guides/programmer_reference/ch13s02.md	pre-emptive
-docs_src/guides/programmer_reference/csharp.md	libaries
 docs_src/guides/programmer_reference/embedded.md	seemlessly
 docs_src/guides/programmer_reference/env_encrypt.md	Documenation
 docs_src/guides/programmer_reference/intro_products.md	informaion
@@ -151,3 +150,12 @@ docs_src/guides/programmer_reference/transapp_atomicity.md	ACI
 docs_src/guides/programmer_reference/transapp_throughput.md	ACI
 docs_src/guides/programmer_reference/txn_config.md	ACI
 docs_src/guides/upgrading/changelog_4_7.md	invalide
+docs_src/guides/gsg/cxx/secondaryDelete.md	desireable
+docs_src/guides/gsg_db_rep/cxx/elections.md	desireable
+docs_src/guides/gsg_db_rep/cxx/fwrkmasterreplica.md	applicaton
+docs_src/guides/gsg_db_rep/cxx/rep_init_code.md	peformed
+docs_src/guides/gsg_db_rep/java/elections.md	desireable
+docs_src/guides/gsg_db_rep/java/fwrkmasterreplica.md	occured
+docs_src/guides/gsg_db_rep/java/fwrkmasterreplica.md	applicaton
+docs_src/guides/gsg_db_rep/java/processingloop.md	optins
+docs_src/guides/gsg_txn/java/readmodifywrite.md	retreived

docs_src/_migrate/flag-reconcile.md

@@ -0,0 +1,95 @@
+# Public DB_* flag reconcile (docs vs. engine)
+
+One-time reconcile of the public `DB_*` flags the engine actually accepts
+against what `docs_src/api/c` documents, focused on the transaction /
+environment / database flag surfaces the SSI work touched. Sources of truth:
+
+- `src/dbinc_auto/api_flags.in` — the public flag bit values.
+- `src/dbinc/db.in` — public return codes.
+- `src/txn/txn.c __txn_begin` `__db_fchk` mask — the valid `txn_begin` flags.
+- `src/env/env_method.c __env_set_flags` `OK_FLAGS` — the valid env
+  `set_flags` flags.
+
+"Documented" = the flag token appears (word-boundary) in some
+`docs_src/api/c/*.md` page.
+
+## DB_ENV->txn_begin() flags (src/txn/txn.c mask)
+
+| Flag                   | Before | After this change |
+|------------------------|--------|-------------------|
+| DB_IGNORE_LEASE        | doc    | doc               |
+| DB_READ_COMMITTED      | doc    | doc               |
+| DB_READ_UNCOMMITTED    | doc    | doc               |
+| DB_TXN_BULK            | doc    | doc               |
+| DB_TXN_FAMILY          | **MISSING** | **added** (txnbegin.md) |
+| DB_TXN_NOSYNC          | doc    | doc               |
+| DB_TXN_NOWAIT          | doc    | doc               |
+| DB_TXN_SNAPSHOT        | doc    | doc               |
+| DB_TXN_SNAPSHOT_SAFE   | **MISSING** | **added** (txnbegin.md, +guides, +return codes) |
+| DB_TXN_SYNC            | doc    | doc               |
+| DB_TXN_WAIT            | doc    | doc               |
+| DB_TXN_WRITE_NOSYNC    | doc    | doc               |
+
+Every `txn_begin` flag the engine accepts is now documented.
+
+## DB_ENV->set_flags() flags (src/env/env_method.c OK_FLAGS)
+
+| Flag                     | Status |
+|--------------------------|--------|
+| DB_AUTO_COMMIT           | doc    |
+| DB_CDB_ALLDB             | doc    |
+| DB_DATABASE_LOCKING      | **MISSING** (pre-existing gap; not SSI-era; left as-is) |
+| DB_DIRECT_DB             | doc    |
+| DB_DSYNC_DB              | doc    |
+| DB_MPOOL_AIO             | doc (engine work; already present) |
+| DB_MULTIVERSION          | doc    |
+| DB_NOFLUSH               | **MISSING** (pre-existing gap; not SSI-era; left as-is) |
+| DB_NOLOCKING             | doc    |
+| DB_NOMMAP                | doc    |
+| DB_NOPANIC               | doc    |
+| DB_OVERWRITE             | doc    |
+| DB_PANIC_ENVIRONMENT     | doc    |
+| DB_REGION_INIT           | doc    |
+| DB_TIME_NOTGRANTED       | doc    |
+| DB_TXN_NOSYNC            | doc    |
+| DB_TXN_NOWAIT            | doc    |
+| DB_TXN_SNAPSHOT          | doc    |
+| DB_TXN_WRITE_NOSYNC      | doc    |
+| DB_YIELDCPU              | doc    |
+| DB_HOTBACKUP_IN_PROGRESS | doc    |
+
+Note: `DB_TXN_SNAPSHOT_SAFE` is deliberately **not** a valid `set_flags`
+flag — SSI is a per-transaction property only (the env `OK_FLAGS` mask accepts
+plain `DB_TXN_SNAPSHOT` but not `_SAFE`). `envset_flags.md` now states this
+explicitly under `DB_TXN_SNAPSHOT`.
+
+## Public return codes (src/dbinc/db.in) — SSI-era
+
+| Return code            | Value    | Before | After |
+|------------------------|----------|--------|-------|
+| DB_SNAPSHOT_UNSAFE     | -30967   | **undocumented** | **added** (program_errorret.md) |
+| DB_SNAPSHOT_CONFLICT   | -30968   | **undocumented** | **added** (program_errorret.md) |
+
+There is **no** `DB_TXN_SNAPSHOT_UNSAFE` *flag* — `DB_SNAPSHOT_UNSAFE` is a
+return *code* an SSI transaction may get, not a `txn_begin` option.
+
+## What this change fixed
+
+- `DB_TXN_SNAPSHOT_SAFE` (0x800) — the SSI flag our engine work added:
+  documented on `api/c/txnbegin.md`, cross-noted on `api/c/envset_flags.md`
+  (per-transaction only), and explained in the transactions guide
+  (`guides/gsg_txn/isolation.md`) and the programmer's reference
+  (`guides/programmer_reference/transapp_read.md`).
+- `DB_SNAPSHOT_UNSAFE` / `DB_SNAPSHOT_CONFLICT` return codes documented in
+  `guides/programmer_reference/program_errorret.md`.
+- `DB_TXN_FAMILY` — a legacy public `txn_begin` flag that was never
+  documented; a short entry was added to complete the `txn_begin` flag list.
+- `DB_READ_COMMITTED` / `DB_READ_UNCOMMITTED` / `DB_MPOOL_AIO` — verified
+  already documented; no change needed.
+
+## Out of scope (deliberately left)
+
+`DB_DATABASE_LOCKING` and `DB_NOFLUSH` are valid `set_flags` flags that are
+undocumented, but they are pre-existing Oracle-era gaps unrelated to the SSI
+work; documenting them accurately needs their own audit and is not part of
+this SSI-focused reconcile.

docs_src/api/c/envset_flags.md

@@ -162,6 +162,8 @@ The **flags** parameter must be set by bitwise inclusively **OR**'ing together o
 
   The DB_TXN_SNAPSHOT flag may be used to configure Berkeley DB at any time during the life of the application.
 
+  Note that only plain snapshot isolation can be configured environment-wide. The serializable-snapshot-isolation flag DB_TXN_SNAPSHOT_SAFE is a per-transaction flag only: it is accepted by <a href="txnbegin.md" class="xref" title="DB_ENV-&gt;txn_begin()">DB_ENV-&gt;txn_begin()</a> but not by `DB_ENV->set_flags()`, so SSI must be requested for each transaction individually.
+
 - `DB_TXN_WRITE_NOSYNC`
 
   If set, Berkeley DB will write, but will not synchronously flush, the log on transaction commit. This means that transactions exhibit the ACI (atomicity, consistency, and isolation) properties, but not D (durability); that is, database integrity will be maintained, but if the system fails, it is possible some number of the most recently committed transactions may be undone during recovery. The number of transactions at risk is governed by how often the system flushes dirty buffers to disk and how often the log is checkpointed.

docs_src/api/c/txnbegin.md

@@ -57,6 +57,10 @@ The **flags** parameter must be set to 0 or by bitwise inclusively **OR**'ing to
 
   The bulk insert optimization is effective only for top-level transactions. The `DB_TXN_BULK` flag is ignored when **parent** is non-null.
 
+- `DB_TXN_FAMILY`
+
+  Start this transaction as part of a transaction family: a group of transactions that share locks and never conflict with one another. A family transaction is read-only from the caller's perspective and does not itself perform updates; it is used to hand a common locking context to a set of cooperating transactions (for example, a client/server design that spreads one logical unit of work across several transaction handles). When this flag is set the transaction is created read-only and shares the locker of its family, so operations performed under different members of the same family do not deadlock against each other.
+
 - `DB_TXN_NOSYNC`
 
   Do not synchronously flush the log when this transaction commits or prepares. This means the transaction will exhibit the ACI (atomicity, consistency, and isolation) properties, but not D (durability); that is, database integrity will be maintained but it is possible that this transaction may be undone during recovery.
@@ -75,6 +79,14 @@ The **flags** parameter must be set to 0 or by bitwise inclusively **OR**'ing to
 
   The error `DB_LOCK_DEADLOCK` will be returned from update operations if a snapshot transaction attempts to update data which was modified after the snapshot transaction read it.
 
+- `DB_TXN_SNAPSHOT_SAFE`
+
+  This transaction will execute with **serializable snapshot isolation** (SSI). This is a Berkeley DB extension beyond `DB_TXN_SNAPSHOT`: it implies `DB_TXN_SNAPSHOT` (the transaction reads a consistent snapshot as of its start, as above) and additionally enables serializable conflict detection (the Cahill SSI algorithm). Berkeley DB tracks read/write anti-dependencies between concurrent snapshot-safe transactions and, when it detects a dependency cycle that could produce a non-serializable schedule, aborts one of the transactions so the committed history is equivalent to some serial order.
+
+  A transaction that hits such a potential anomaly is aborted with one of two Berkeley DB-specific error returns instead of committing: <a href="../../guides/programmer_reference/program_errorret.md" class="olink">DB_SNAPSHOT_UNSAFE</a> (a potential serializable-snapshot anomaly was detected via a read/write anti-dependency) or <a href="../../guides/programmer_reference/program_errorret.md" class="olink">DB_SNAPSHOT_CONFLICT</a> (a conflicting snapshot update was detected). On either return the application must abort the transaction and may retry it. As with `DB_TXN_SNAPSHOT`, snapshot behavior applies to databases opened with <a href="dbopen.md#dbopen_DB_MULTIVERSION" class="link">DB_MULTIVERSION</a>.
+
+  A `DB_TXN_SNAPSHOT_SAFE` (SSI) transaction **cannot be prepared for two-phase commit**: <a href="txnprepare.md" class="xref" title="DB_TXN-&gt;prepare()">DB_TXN-&gt;prepare()</a> returns `EINVAL` for such a transaction, because SSI's conflict status is not frozen at prepare time and a later-detected anomaly could not be honored after the transaction had entered the prepared state.
+
 - `DB_TXN_SYNC`
 
   Synchronously flush the log when this transaction commits or prepares. This means the transaction will exhibit all of the ACID (atomicity, consistency, isolation, and durability) properties.

docs_src/build.py

@@ -16,6 +16,7 @@
 """
 import html
 import re
+import shutil
 import subprocess
 import sys
 import tomllib
@@ -32,6 +33,23 @@
 MAN_OUT = REPO / "docs-build/man/man3"
 PDF_OUT = REPO / "docs-build/pdf"
 PDF_CSS = HERE / "_templates/pdf-print.css"
+# Java binding sources -> javadoc HTML (a generated artifact, gitignored).
+# Lands under the HTML site (docs-build/html/java-api/) so index.md's link
+# resolves and it publishes/installs alongside the rest of the site.
+JAVA_SRC = REPO / "lang/java/src"
+JAVA_API_OUT = OUT / "java-api"
+# Public packages, matching the set the historical Oracle Javadoc published
+# (excludes the bundled ObjectWeb ASM copy, the compat shims, and the
+# db.internal / persist.impl / util.keyrange internals). Referenced-but-not-
+# documented internals still resolve via -sourcepath.
+JAVA_PACKAGES = [
+    "com.sleepycat.bind", "com.sleepycat.bind.serial", "com.sleepycat.bind.tuple",
+    "com.sleepycat.collections",
+    "com.sleepycat.db",
+    "com.sleepycat.persist", "com.sleepycat.persist.evolve",
+    "com.sleepycat.persist.model", "com.sleepycat.persist.raw",
+    "com.sleepycat.util",
+]
 # API .md trees whose refentry pages become section-3 man pages.
 API_DIRS = [HERE / "api/c", HERE / "api/stl"]
 
@@ -153,7 +171,6 @@ def _copy_assets():
     (`![](deadlock.jpg)`) but migrate stored them under `<tree>/img/`, so
     flatten each `img/` into the page dir (docs-build/html/<tree>/deadlock.jpg).
     Without this the <img>/asset links dangle -- the link-check gate catches it."""
-    import shutil
     for img_dir in SRC.rglob("img"):
         if not img_dir.is_dir():
             continue
@@ -483,6 +500,43 @@ def build_pdf(version, site):
     return built
 
 
+# --- Java API reference: regenerate javadoc from lang/java/src (always current
+# with the code, unlike the frozen 2013 HTML). Output is a build artifact under
+# docs-build/java-api/ (gitignored), linked from index.md. Guarded on javadoc
+# availability like the PDF path -- skip-with-note if the JDK is absent.
+
+def build_java_api(version, site):
+    """Run javadoc over the public com.sleepycat.* packages into
+    docs-build/java-api/. Returns the output dir, or None if javadoc/sources
+    are unavailable (skipped-with-note). The 2005-era doc comments carry
+    legacy HTML that javadoc 21's doclint rejects, so -Xdoclint:none keeps it
+    warnings-only; -sourcepath spans all of lang/java/src so referenced
+    internals resolve while only JAVA_PACKAGES are documented."""
+    if not shutil.which("javadoc"):
+        print("(javadoc not found: skipping Java API reference)")
+        return None
+    if not JAVA_SRC.exists():
+        print(f"(no {JAVA_SRC}: skipping Java API reference)")
+        return None
+    JAVA_API_OUT.mkdir(parents=True, exist_ok=True)
+    title = f"{site['project']} Java API {version}"
+    cmd = [
+        "javadoc", "-quiet", "-Xdoclint:none",
+        "-d", str(JAVA_API_OUT),
+        "-sourcepath", str(JAVA_SRC),
+        "-windowtitle", title,
+        "-doctitle", title,
+        "-notimestamp",
+        *JAVA_PACKAGES,
+    ]
+    p = subprocess.run(cmd, capture_output=True, text=True)
+    if p.returncode != 0:
+        raise RuntimeError(f"javadoc failed:\n{p.stderr[-1500:]}")
+    if not (JAVA_API_OUT / "index.html").exists():
+        raise RuntimeError("javadoc produced no index.html")
+    return JAVA_API_OUT
+
+
 def _selfcheck():
     """Guard the md->man reshape: NAME/SYNOPSIS/DESCRIPTION split, heading
     promotion, and in-list heading demotion."""
@@ -525,6 +579,11 @@ def _selfcheck():
                  'a href="../../api/c/env.md#x" b href="foo.md" c href="http://x/y.md"')
     assert '../../api/c/env.html#x' in got and 'foo.html' in got
     assert 'http://x/y.md' in got, "absolute .md URL must not be rewritten"
+    # Java API: the documented package set matches the historical public
+    # surface and excludes the bundled/internal packages.
+    assert "com.sleepycat.db" in JAVA_PACKAGES
+    assert "com.sleepycat.asm" not in JAVA_PACKAGES
+    assert "com.sleepycat.db.internal" not in JAVA_PACKAGES
     print("selfcheck ok")
 
 
@@ -538,6 +597,9 @@ def main(build_pdf_too=True):
     print(f"built {n} HTML pages -> {OUT}  (version {version})")
     m = build_man(version, site)
     print(f"built {m} man pages -> {MAN_OUT}  (version {version})")
+    jdir = build_java_api(version, site)
+    if jdir:
+        print(f"built Java API reference -> {jdir}  (version {version})")
     if build_pdf_too:
         books = build_pdf(version, site)
         print(f"built {len(books)} PDF books -> {PDF_OUT}  (version {version})")