pgjdbc/pgjdbc GitHub issues and pull requests (mirror)
help / color / mirror / Atom feedFrom: vlsi (@vlsi) <[email protected]>
To: pgjdbc/pgjdbc <[email protected]>
Subject: [pgjdbc/pgjdbc] PR #4077: pgjdbc: introduce @PgApi / @PgTags / @PgPropertyType annotations on PGProperty
Date: Mon, 18 May 2026 08:58:32 +0000
Message-ID: <[email protected]> (raw)
Adds three CLASS-retained annotations in org.postgresql.annotations and applies them to all 87 PGProperty values. The annotations are the contract a documentation generator can read via ASM bytecode inspection — without exposing the data at runtime.
The annotations are is used in https://github.com/pgjdbc/pgjdbc/pull/4075 to implement https://github.com/pgjdbc/pgjdbc/issues/1687
---
The annotations are designed after https://github.com/apiguardian-team/apiguardian with several changes:
* The annotations are renamed to avoid third-party dependencies
* I've added special fields to track "available since, deprecated in, hidden in", see https://github.com/apiguardian-team/apiguardian/issues/207
* I've added `status=HIDDEN` so we can hide certain members at the bytecode later, see https://github.com/apiguardian-team/apiguardian/issues/208
---
```
PgApi(status, introducedIn, deprecatedIn, hiddenIn)
Lifecycle status (STABLE / EXPERIMENTAL / MAINTAINED / INTERNAL /
DEPRECATED / HIDDEN) plus three orthogonal version axes so docs can
render "Available since X.Y; deprecated in Y.Z; hidden in Z.W"
without losing any.
PgTags(Tag[]) — topical buckets (SSL, AUTHENTICATION, FETCH, TIMEOUT,
NETWORK, KERBEROS_GSS, ...) plus the OPERATIONS secondary tag for
properties tuned at deployment time. Drives section-specific
sub-tables in the docs.
PgPropertyType(Kind) — semantic data type, with unit-bearing variants
(DURATION_SECONDS / DURATION_MILLIS, SIZE_BYTES / SIZE_EXPRESSION).
Surfaces "is this number seconds or milliseconds?" — a long-standing
pgjdbc foot-gun.
```
All annotations use `@Retention(CLASS)` so they are visible to bytecode readers but not exposed at runtime. Pg-prefixed names avoid collisions with widely-used annotation libraries (`org.apiguardian.api.API` ships with JUnit Jupiter), so a user typing `@Pg...` in their IDE sees only pgjdbc annotations.
Each DEPRECATED `@PgApi` sits alongside the standard JDK `@Deprecated` so that both bytecode readers and the compiler / IDE see the deprecation.
view thread (3+ messages) latest in thread
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: github://pgjdbc/pgjdbc
Cc: [email protected], [email protected]
Subject: Re: [pgjdbc/pgjdbc] PR #4077: pgjdbc: introduce @PgApi / @PgTags / @PgPropertyType annotations on PGProperty
In-Reply-To: <<[email protected]>>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox