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 0b10a20 docs: update AGENTS.md and README.md with clarifications and
new entries (#38)
0b10a20 is described below
commit 0b10a200e9429e3085d080bfce862f9ecb5ba7da
Author: Carsten Ziegeler <[email protected]>
AuthorDate: Tue Jun 2 09:40:57 2026 +0200
docs: update AGENTS.md and README.md with clarifications and new entries
(#38)
Co-authored-by: Maia <maia@noreply>
---
AGENTS.md | 24 ++++++++++++++----------
README.md | 17 ++++++++++-------
2 files changed, 24 insertions(+), 17 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index 82abeac..2eee88e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,13 +1,13 @@
# Project Overview
-Apache Sling Servlets POST (`org.apache.sling.servlets.post`) is an OSGi
bundle that provides the default POST servlet (`SlingPostServlet`) for Apache
Sling. It handles content creation, modification, deletion, copy, move, import,
and file upload operations against the Sling resource tree (typically backed by
JCR). The bundle exposes extension points via `JakartaPostOperation`,
`SlingJakartaPostProcessor`, `JakartaNodeNameGenerator`, and
`JakartaPostResponseCreator` OSGi services. It sup [...]
+Apache Sling Servlets POST (`org.apache.sling.servlets.post`) is an OSGi
bundle that provides the default POST servlet (`SlingPostServlet`) for Apache
Sling. It handles content creation, modification, deletion, copy, move, import,
restore, checkin/checkout, and file upload operations against the Sling
resource tree (typically backed by JCR). The bundle exposes extension points
via `JakartaPostOperation`, `SlingJakartaPostProcessor`,
`JakartaNodeNameGenerator`, and `JakartaPostResponseCre [...]
# Core Commands
- **Build:** `mvn clean install`
- **Build (skip tests):** `mvn clean install -DskipTests`
- **Unit tests only:** `mvn test`
-- **Integration tests:** `mvn verify` (runs `ModifyOperationIT` via
maven-failsafe-plugin)
+- **Integration tests:** `mvn verify` (runs Failsafe tests, currently
`ModifyOperationIT`)
- **Single test class:** `mvn test -Dtest=HtmlResponseTest`
- **Single IT class:** `mvn verify -Dit.test=ModifyOperationIT`
- **Check OSGi bundle headers:** inspect
`target/org.apache.sling.servlets.post-*.jar` — metadata generated by
`bnd-maven-plugin` from `bnd.bnd`
@@ -18,33 +18,37 @@ Apache Sling Servlets POST
(`org.apache.sling.servlets.post`) is an OSGi bundle
```
pom.xml Maven build descriptor; packaging = jar (OSGi
bundle via bnd)
bnd.bnd OSGi bundle manifest overrides and bnd
instructions
+Protocols.md Protocol notes for POST/file upload behavior
src/
main/java/org/apache/sling/servlets/post/
- *.java Public API: interfaces & abstract classes
(PostOperation, PostResponse, etc.)
+ *.java Public API/SPI: Jakarta-first interfaces plus
legacy compatibility APIs
exceptions/ PreconditionViolatedPersistenceException,
TemporaryPersistenceException
impl/
SlingPostServlet.java Core servlet; dispatches to PostOperation
implementations
- operations/ Built-in operations: Modify, Delete, Copy,
Move, Import, Checkin/out, etc.
+ 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
main/resources/
SLING-INF/nodetypes/chunk.cnd JCR node type for chunked upload nodes
org/apache/sling/servlets/post/ HTML response templates
system/sling.js Bundled JS resource
- test/java/ JUnit 4 unit tests and one Failsafe IT
(ModifyOperationIT)
-developer-tests/ Shell scripts for manual smoke-testing against
a live Sling instance
+ test/java/ JUnit 4 unit tests and Failsafe ITs (currently
one: ModifyOperationIT)
+developer-tests/
+ README.md Notes for running manual developer scripts
+ testFileUploads.sh Upload protocol smoke-test script for a running
Sling instance
```
# Development Patterns & Constraints
- **Java version:** 17 (`sling.java.version` property).
- **OSGi:** Use `org.osgi.service.component.annotations` (`@Component`,
`@Reference`, etc.). No Felix SCR annotations.
-- **Jakarta-first:** New code must use `jakarta.servlet` and Sling Jakarta
APIs (`SlingJakartaHttpServletRequest`, etc.). Legacy `javax.servlet` support
is bridged in `impl/wrapper` only.
+- **Jakarta-first:** New code should use `jakarta.servlet` and Sling Jakarta
APIs (`SlingJakartaHttpServletRequest`, etc.). Legacy `javax.servlet` support
is maintained through wrappers for backwards-compatible SPI integration.
- **Coding style:** 4-space indentation, no tabs. Follow existing Apache Sling
conventions. License headers required on all source files (enforced by
`apache-rat-plugin`).
- **No public API in `impl`:** Classes under `impl` are internal; Javadoc is
excluded for that package. All public SPI lives in
`org.apache.sling.servlets.post` (top-level).
- **OSGi versioning:** Bundle API is baselined by `bnd-baseline-maven-plugin`
— semantic versioning must be maintained. Changing a public interface requires
a minor or major version bump.
- **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 `sling.jcr.contentloader` are
`resolution:=dynamic` in `bnd.bnd`; the bundle works without JCR at runtime.
+- **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.
# Git Workflow
@@ -60,13 +64,13 @@ developer-tests/ Shell scripts for manual
smoke-testing against a
- **Integration tests:** `src/test/java/**/*IT.java` — picked up by
`maven-failsafe-plugin`; run only during `verify` phase.
- **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. See existing `*IT.java` for setup patterns.
+- **Sling Mock:** Use `org.apache.sling.testing.sling-mock.junit4` for tests
needing a resource resolver. `ModifyOperationIT` uses Sling Mock Oak.
# Gotchas
- **Two parallel API families:** The public package has both
`PostOperation`/`PostResponse` (javax-based, deprecated) and
`JakartaPostOperation`/`JakartaPostResponse` (Jakarta-based). Always extend or
implement the Jakarta variants for new work.
- **`bnd-baseline` will fail** if you change a public method signature without
bumping the package version in `package-info.java`.
- **Shaded classes:** `org.apache.jackrabbit.util.ISO8601`, `Text`, and
`JsonTicksConverter` are embedded and relocated. Do not add direct compile-time
imports of those originals in non-impl code.
-- **`ModifyOperationIT`** requires Oak on the classpath; failsafe excludes the
older `jackrabbit-api` jar and substitutes `oak-jackrabbit-api` — if you add
JCR dependencies, verify classpath ordering in the failsafe config.
+- **`ModifyOperationIT` classpath details:** Failsafe excludes
`jackrabbit-api` and the default `jackrabbit-jcr-commons`, then adds a newer
`jackrabbit-jcr-commons` for Oak compatibility. Re-check this setup when
changing JCR/Oak dependencies.
- **File upload chunking:** The chunked upload protocol uses custom JCR node
types defined in `chunk.cnd`. Changes to chunk handling must account for the
`ChunkCleanUpTask` scheduled cleanup.
- **`:redirect` URI validation:** `SlingPostServlet` validates redirect URIs
against the request host to prevent open-redirect. Tests must provide a proper
`Host` header or mock the URI check.
diff --git a/README.md b/README.md
index 01f233c..8ce7054 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@
# Apache Sling Default POST Servlets
-Provides default POST servlets for Apache Sling.
+Provides the default POST servlet bundle for Apache Sling.
This module is part of the [Apache Sling](https://sling.apache.org) project.
You can read more about this module on our [documentation
site](https://sling.apache.org/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.html).
@@ -16,10 +16,11 @@ The bundle provides the default `SlingPostServlet` and
built-in POST operations
- delete
- copy and move
- import
+- restore
- 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` 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 available through wrapper
adapters under `impl/wrapper`.
## Extension points
@@ -47,20 +48,21 @@ For manual file-upload protocol checks against a running
Sling instance on `loca
`sh developer-tests/testFileUploads.sh <testfile>`
-See `developer-tests/README.md` and `Protocols.md` for protocol and script
details.
+The script uploads using regular, streamed, and chunked streamed protocols,
then downloads and compares content. See `developer-tests/README.md` and
`Protocols.md` for protocol and script details.
## Repository layout
```text
pom.xml Maven build descriptor (packaging: jar)
bnd.bnd OSGi bundle instructions and embedded resources
+Protocols.md Protocol notes for POST and upload behavior
src/
main/java/org/apache/sling/servlets/post/
- *.java Public API and SPI
+ *.java Public Jakarta-first API/SPI (+ legacy
compatibility APIs)
exceptions/ Persistence-related exceptions
- impl/ Internal servlet and operation implementation
+ impl/ Internal servlet and operation implementations
operations/ Built-in POST operations
- helper/ Internal helpers (upload, property handling,
naming)
+ helper/ Internal helpers (upload, property handling,
naming, chunking)
wrapper/ Jakarta <-> javax bridging adapters
main/resources/
SLING-INF/nodetypes/chunk.cnd Chunked upload node type definitions
@@ -74,4 +76,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 and `org.apache.sling.jcr.contentloader` imports are configured as
dynamic for runtime flexibility.
+- 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.
