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-get.git
The following commit(s) were added to refs/heads/master by this push:
new 0d716e6 docs: update AGENTS.md and README.md with HEAD servlet, bnd,
and baseline notes (#24)
0d716e6 is described below
commit 0d716e624a112e9f68a527a5492237b7560d390b
Author: Carsten Ziegeler <[email protected]>
AuthorDate: Thu Jul 16 17:25:07 2026 +0200
docs: update AGENTS.md and README.md with HEAD servlet, bnd, and baseline
notes (#24)
Co-authored-by: Maia <maia@noreply>
---
AGENTS.md | 16 +++++++++-------
README.md | 8 ++++++--
2 files changed, 15 insertions(+), 9 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index cabaedf..748068c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,6 @@
# Project Overview
-This is `org.apache.sling.servlets.get`, an OSGi bundle that provides the
default GET servlets for Apache Sling. It handles HTML, plain-text, JSON, and
XML rendering of Sling resources, plus stream delivery, redirect handling, and
Sling/version info endpoints. The bundle ships as a shaded JAR (via
`maven-shade-plugin`) that inlines `ISO8601` from `jackrabbit-jcr-commons`.
Requires Java 17 and Maven 3.9+.
+This is `org.apache.sling.servlets.get`, an OSGi bundle that provides the
default GET and HEAD servlets for Apache Sling. It handles HTML, plain-text,
JSON, and XML rendering of Sling resources, plus stream delivery, redirect
handling, and Sling/version info endpoints. The bundle ships as a shaded JAR
(via `maven-shade-plugin`) and inlines `ISO8601` from `jackrabbit-jcr-commons`.
Requires Java 17 and Maven 3.9+.
# Core Commands
@@ -36,7 +36,7 @@ There is no dev server — this bundle must be deployed to a
running Sling insta
```
pom.xml Maven build descriptor
-bnd.bnd OSGi bundle manifest overrides (optional imports
for JCR)
+bnd.bnd OSGi import instructions + inlined ISO8601 resource
src/
main/java/org/apache/sling/servlets/get/impl/
DefaultGetServlet.java Central dispatcher — routes GET/HEAD by
selector/extension
@@ -58,19 +58,21 @@ src/
test/java/... Mirrors main package structure; JUnit
4/Mockito/Sling Mock tests
test/resources/ Test JSON fixtures (data.json, samplefile.json)
target/ Build output — do not edit
+ baseline/ OSGi baseline comparison reports
+ surefire-reports/ Maven Surefire test reports
```
# Development Patterns & Constraints
- **Java 17**, OSGi R7 component model using
`org.osgi.service.component.annotations` (`@Component`, `@Activate`,
`@Deactivate`, `@Reference`). Never use Felix SCR annotations.
- **OSGi metatype configs**: this codebase also uses
`org.osgi.service.metatype.annotations` (`@Designate`,
`@ObjectClassDefinition`, `@AttributeDefinition`) for servlet configuration.
-- **Jakarta namespace**: the codebase uses `jakarta.servlet.*` and
`jakarta.json.*`. Do not mix in `javax.servlet.*` (it is listed as
optional/provided for legacy compat only).
+- **Servlet APIs**: runtime code uses `jakarta.servlet.*` and
`jakarta.json.*`; `javax.servlet-api` remains a provided compatibility
dependency and should not be used in new production code.
- **No public API**: everything lives under
`org.apache.sling.servlets.get.impl`. There is no public package export; do not
add one without intentional design.
- **Shading**: `org.apache.jackrabbit.util` is relocated to
`org.apache.sling.servlets.get.impl.jackrabbit` at package time. Never import
the original class name in production code that will run inside the bundle.
- **Code style**: 4-space indentation, no tabs. Spotless enforces formatting
(inherited from `sling-bundle-parent`). Run `mvn spotless:apply` before
committing.
- **License headers**: All source files must carry the Apache 2.0 license
header. RAT checks this on every build.
- **Logging**: use SLF4J 2.x (`org.slf4j`). No `System.out` or
`java.util.logging`.
-- **Tests**: JUnit 4 + Mockito 3. Sling Mock (sling-mock-oak variant) is
available for integration-style tests.
+- **Tests**: JUnit 4 + Mockito 3; `junit-addons` and Sling Mock
(sling-mock-oak variant) are available for integration-style tests.
# Git Workflow
@@ -84,7 +86,7 @@ target/ Build output — do not edit
- Framework: **JUnit 4** (`junit:junit`). Do not add JUnit 5 without updating
the parent POM.
- Test classes live under `src/test/java/` mirroring the production package
path.
-- Mocking/test support: **Mockito 3**, **Sling Mock**
(`org.apache.sling.testing.sling-mock.junit4` and sling-mock-oak), plus Sling
servlet helpers for request/response tests.
+- Mocking/test support: **Mockito 3**, `junit-addons`, **Sling Mock**
(`org.apache.sling.testing.sling-mock.junit4` and sling-mock-oak), plus Sling
servlet helpers for request/response tests.
- Run all tests: `mvn test`
- Run one class: `mvn test -Dtest=ClassName`
- Reports land in `target/surefire-reports/`.
@@ -94,9 +96,10 @@ target/ Build output — do not edit
- **Shaded JAR vs. plain JAR**: `maven-shade-plugin` runs at `package` phase
and produces the final artifact. `target/original-*.jar` is the pre-shade
output. Deploy the shaded JAR to OSGi, not the original.
- **Shaded sources are also generated**: both shaded and `original-*` source
JARs are produced during packaging.
-- **`bnd.bnd` optional imports**: `javax.jcr` is marked
`resolution:=optional`. Code that uses JCR must guard against missing packages
at runtime.
+- **`bnd.bnd` specifics**: `javax.jcr`/`javax.jcr.version` imports are marked
`resolution:=optional`, and `ISO8601.class` is explicitly inlined from
`jackrabbit-jcr-commons`.
- **Sling API 3.x**: This bundle targets `org.apache.sling.api` 3.0.0, which
uses `SlingJakartaHttpServletRequest`/`SlingJakartaHttpServletResponse`. These
differ from the older `SlingHttpServletRequest` — don't mix them.
- **Parent POM version drift**: Many dependency versions (JUnit, Mockito, OSGi
annotations) are managed by `sling-bundle-parent`. Check the parent before
adding explicit versions.
+- **Baseline reports**: package/build output includes OSGi baseline data under
`target/baseline/`; review those reports when changing exported/consumed API
behavior.
- **RAT failures**: Adding files without license headers (e.g., test fixtures)
will fail the RAT check. Add a RAT exclusion in the parent config or prepend
the header.
# Security
@@ -104,4 +107,3 @@ target/ Build output — do not edit
<!-- sling-security-default:start -->
The threat model for this project is
https://github.com/apache/sling/blob/master/docs/threat-model.md .
<!-- sling-security-default:end -->
-
diff --git a/README.md b/README.md
index 90ef63b..c38710c 100644
--- a/README.md
+++ b/README.md
@@ -47,7 +47,7 @@ mvn apache-rat:check
mvn install -DskipTests
```
-To deploy to a running Sling instance:
+To deploy to a running Sling instance (there is no local dev server in this
module):
```bash
mvn sling:install
@@ -60,17 +60,20 @@ mvn sling:install
- Original (pre-shade) artifacts are also generated:
- `target/original-org.apache.sling.servlets.get-<version>.jar`
- Source JARs are generated for both shaded and original variants.
+- OSGi baseline comparison reports are generated under `target/baseline/`.
## Implementation notes
- Uses OSGi R7 Declarative Services annotations
(`org.osgi.service.component.annotations`).
- Uses OSGi Metatype annotations (`org.osgi.service.metatype.annotations`) for
servlet configuration.
-- Uses Jakarta Servlet (`jakarta.servlet`) and Jakarta JSON (`jakarta.json`)
APIs.
+- Uses Jakarta Servlet (`jakarta.servlet`) and Jakarta JSON (`jakarta.json`)
APIs at runtime, while keeping `javax.servlet-api` as a provided compatibility
dependency.
- Targets Sling API `3.x` (`SlingJakartaHttpServletRequest` /
`SlingJakartaHttpServletResponse`).
- Produces a shaded JAR at package time.
- Relocates `org.apache.jackrabbit.util` to
`org.apache.sling.servlets.get.impl.jackrabbit` and inlines `ISO8601`.
- Keeps `javax.jcr` imports optional in `bnd.bnd` for environments without JCR
packages.
+- Uses OWASP Java Encoder (`org.owasp.encoder`) in rendering paths.
- Uses SLF4J (`org.slf4j`) for logging.
+- This module does not export a public API package; implementation lives under
`org.apache.sling.servlets.get.impl`.
## Project layout
@@ -97,4 +100,5 @@ src/
ResourceTraversor.java
test/java/... JUnit 4 + Mockito + Sling Mock tests
test/resources/ JSON fixtures (for example `data.json`,
`samplefile.json`)
+target/baseline/ OSGi baseline comparison output (build-time)
```
