Complete forUri deprecation across registry and tag APIs without removing 1.x support

[jmanico]

Reviewed 2026-09-25 (America/Los_Angeles) against main at bd249f5. Execution order and cross-issue ownership: #169. Batch 01.

This scope replaces the dated implementation prescriptions in the original report and earlier comments; linked historical evidence remains useful but must be rechecked before implementation.

Current state and scope

#161 already clarified Encode and TLD context guidance. Re-audit current Javadocs/TLDs rather than repeating that work. Remaining API surfaces include Encoders.URI, Encoders.forName("uri"), and the JSP/Jakarta ForUriTag classes.

• Add missing Java annotations and @deprecated text; document registry lookup retention and mark all four TLD tag/function descriptions consistently.
• Explain component encoding with forUriComponent, application-level whole-URL validation/scheme restrictions, and encoding for the enclosing HTML context. Do not imply URI parsing alone validates a URL's use.
• Preserve existing methods, names, taglib URIs and runtime behavior throughout 1.x; removal is a decision in Decide future-major compatibility policy without committing 1.x to breaking changes #142, not part of this issue.
• Keep JSP/Jakarta parity and descriptor tests green, and validate generated Javadocs. Enable focused deprecation diagnostics without turning all legacy warnings into an unrelated build failure.
• Supply migration text to Rewrite the README and context guide, incorporating #114 and current 1.5 contracts #128; link the resulting guidance from the historical Alternative method for deprecated forUri() method #54 discussion if useful. Align ESAPI URL-component semantics and define safe adapter context contracts #100 owns changing the ESAPI delegate.

Completed in batch 01

Contributor PR #170 was reviewed, approved, and merged as 98608dd52c46e4f250e5eff4d3a6fda218a22dd3, with all 20 checks passing. Coordinated follow-up #172 merged as fe5e0ad174481c2f23a566aa33069a0e45562785, also with all 20 checks passing, completing the URL/context guidance alongside #100.

Encoders.URI, both ForUriTag classes, and all eight legacy tag/function descriptions now carry deprecation guidance. Encoders.forName("uri") remains recognized. Existing methods, tag names/URIs, and core/registry/tag runtime output remain intact throughout 1.x; a regression checks retained facade/Writer/registry output. Generated Javadoc deprecation descriptions and the public adapter contract were inspected, 31-file JSP/Jakarta parity passed, and deprecation diagnostics remain nonfatal. Shared migration guidance explicitly separates component encoding, application URL validation, and enclosing-context encoding; supplied to #128. Removal remains a decision in #142.