This is an automated email from the ASF dual-hosted git repository.
cziegeler pushed a commit to branch master
in repository
https://gitbox.apache.org/repos/asf/sling-org-apache-sling-servlets-post.git
The following commit(s) were added to refs/heads/master by this push:
new 7881ffd docs: update AGENTS.md and README.md with
PostOperationProxyProvider and JSON stack details (#39)
7881ffd is described below
commit 7881ffd66449c6e2ec9596e7534fd24b0c27dd83
Author: Carsten Ziegeler <[email protected]>
AuthorDate: Tue Jun 2 11:09:14 2026 +0200
docs: update AGENTS.md and README.md with PostOperationProxyProvider and
JSON stack details (#39)
Co-authored-by: Maia <maia@noreply>
---
AGENTS.md | 5 ++++-
README.md | 10 ++++++++--
2 files changed, 12 insertions(+), 3 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index 2eee88e..9ffa371 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,10 +21,11 @@ bnd.bnd OSGi bundle manifest
overrides and bnd instructio
Protocols.md Protocol notes for POST/file upload behavior
src/
main/java/org/apache/sling/servlets/post/
- *.java Public API/SPI: Jakarta-first interfaces plus
legacy compatibility APIs
+ *.java Public API/SPI: Jakarta-first interfaces plus
legacy compatibility APIs (operations, responses, processors, naming)
exceptions/ PreconditionViolatedPersistenceException,
TemporaryPersistenceException
impl/
SlingPostServlet.java Core servlet; dispatches to PostOperation
implementations
+ PostOperationProxyProvider.java Registers compatibility wrappers for
legacy services
operations/ Built-in operations: Modify, Delete, Copy,
Move, Import, Restore, Checkin/out, streamed upload
helper/ Internal helpers: file upload, property value
handling, node naming, chunked upload
wrapper/ Jakarta↔javax bridging adapters for legacy SPI
consumers
@@ -49,6 +50,7 @@ developer-tests/
- **Shading:** `maven-shade-plugin` inlines selected classes from
`jackrabbit-jcr-commons` and `sling-jcr-contentparser` (relocated under
`impl.*` packages) to avoid runtime dependency conflicts.
- **Dynamic imports:** JCR packages and `org.apache.sling.jcr.contentloader`
are `resolution:=dynamic` in `bnd.bnd`; the bundle works without JCR at runtime.
- **Dual servlet API dependencies:** `jakarta.servlet-api` is primary, while
`javax.servlet-api` and `org.apache.felix.http.wrappers` remain for
compatibility adapters.
+- **JSON stack:** Jakarta JSON (`jakarta.json-api`) is used for Jakarta
responses, while legacy JSON support remains for compatibility APIs.
# Git Workflow
@@ -65,6 +67,7 @@ developer-tests/
- **Test placement:** Mirror the main source package structure under
`src/test/java`.
- **Coverage:** No coverage gate configured; rely on code review.
- **Sling Mock:** Use `org.apache.sling.testing.sling-mock.junit4` for tests
needing a resource resolver. `ModifyOperationIT` uses Sling Mock Oak.
+- **Response tests:** Both legacy and Jakarta response implementations have
dedicated tests (`HtmlResponseTest`/`JakartaHtmlResponseTest`,
`JsonResponseTest`/`JakartaJsonResponseTest`).
# Gotchas
diff --git a/README.md b/README.md
index 8ce7054..a6b157f 100644
--- a/README.md
+++ b/README.md
@@ -20,7 +20,7 @@ The bundle provides the default `SlingPostServlet` and
built-in POST operations
- checkin/checkout and versioning helpers
- file upload (regular, streamed, and chunked)
-The implementation is **Jakarta Servlet-first** and uses Sling Jakarta APIs.
Legacy `javax.servlet` SPI integration remains available through wrapper
adapters under `impl/wrapper`.
+The implementation is **Jakarta Servlet-first** and uses Sling Jakarta APIs.
Legacy `javax.servlet` SPI integration remains supported via adapters in
`impl/wrapper` and service proxying in `PostOperationProxyProvider`.
## Extension points
@@ -31,6 +31,8 @@ Custom behavior can be provided via OSGi services such as:
- `JakartaNodeNameGenerator`
- `JakartaPostResponseCreator`
+The corresponding legacy extension types (`PostOperation`,
`SlingPostProcessor`, `NodeNameGenerator`, `PostResponseCreator`) are still
supported through compatibility wrappers.
+
## Build and test
Java 17 is required.
@@ -41,6 +43,7 @@ Java 17 is required.
- Integration tests (Failsafe, including `ModifyOperationIT`): `mvn verify`
- Single unit test class: `mvn test -Dtest=HtmlResponseTest`
- Single integration test class: `mvn verify -Dit.test=ModifyOperationIT`
+- Inspect generated bundle metadata: `jar tf
target/org.apache.sling.servlets.post-*.jar | grep -E
'META-INF/MANIFEST.MF|SLING-INF/nodetypes/chunk.cnd'`
## Manual upload smoke tests
@@ -55,12 +58,14 @@ The script uploads using regular, streamed, and chunked
streamed protocols, then
```text
pom.xml Maven build descriptor (packaging: jar)
bnd.bnd OSGi bundle instructions and embedded resources
+Jenkinsfile ASF Jenkins pipeline definition
Protocols.md Protocol notes for POST and upload behavior
src/
main/java/org/apache/sling/servlets/post/
*.java Public Jakarta-first API/SPI (+ legacy
compatibility APIs)
exceptions/ Persistence-related exceptions
impl/ Internal servlet and operation implementations
+ PostOperationProxyProvider.java Legacy service proxy registration
operations/ Built-in POST operations
helper/ Internal helpers (upload, property handling,
naming, chunking)
wrapper/ Jakarta <-> javax bridging adapters
@@ -77,4 +82,5 @@ developer-tests/ Manual developer test scripts
- OSGi metadata is generated with bnd (`bnd-maven-plugin`), with API baseline
checks via `bnd-baseline-maven-plugin`.
- The build shades selected classes from `jackrabbit-jcr-commons` and
`sling-jcr-contentparser` into internal `impl` packages.
- JCR (`javax.jcr.*`) and `org.apache.sling.jcr.contentloader` imports are
configured as dynamic for runtime flexibility.
-- The bundle depends on `jakarta.servlet-api` as primary API and keeps
`javax.servlet-api` plus `org.apache.felix.http.wrappers` for compatibility
adapters.
+- The bundle uses `jakarta.servlet-api` as the primary servlet API while
keeping `javax.servlet-api` and `org.apache.felix.http.wrappers` for
compatibility adapters.
+- JSON support is split between Jakarta JSON APIs for Jakarta responses and
legacy JSON support for backwards-compatible APIs.
