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-engine.git
The following commit(s) were added to refs/heads/master by this push:
new ce69e3a docs: add AGENTS.md, CLAUDE.md, and expand README (#78)
ce69e3a is described below
commit ce69e3a4e9f7e679e1e6cf5cc0827bb0f98acfe7
Author: Carsten Ziegeler <[email protected]>
AuthorDate: Tue Jun 2 07:30:55 2026 +0200
docs: add AGENTS.md, CLAUDE.md, and expand README (#78)
Add AGENTS.md with project overview, build commands, layout, development
patterns, git workflow, testing guidelines, and gotchas. Add CLAUDE.md
as a pointer to AGENTS.md. Expand README with an overview, requirements,
build/test commands, repository layout, and notes.
Co-authored-by: Maia <maia@noreply>
---
AGENTS.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
CLAUDE.md | 1 +
README.md | 76 ++++++++++++++++++++++++++++++++++++++++++++--
3 files changed, 176 insertions(+), 2 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..5bdde00
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,101 @@
+# Project Overview
+
+`org.apache.sling.engine` is the core OSGi bundle of Apache Sling. It
implements the main HTTP request processing pipeline: receiving servlet
requests via the OSGi HTTP Whiteboard, resolving resources, running servlet
filter chains, dispatching to content renderers, and returning responses. The
bundle bridges both `javax.servlet` (legacy) and `jakarta.servlet` APIs through
adapter classes, and registers JMX beans for request processing metrics.
+
+# Core Commands
+
+```bash
+# Build and package (skip tests)
+mvn clean install -DskipTests
+
+# Full build with tests
+mvn clean install
+
+# Run all tests
+mvn test
+
+# Run a single test class
+mvn test -Dtest=SlingRequestPathInfoTest
+
+# Run tests with a name pattern
+mvn test -Dtest="*FilterChain*"
+
+# License header check (Apache RAT)
+mvn apache-rat:check
+
+# Run with Spotless formatting check (inherited from parent POM)
+mvn spotless:check
+
+# Apply Spotless formatting
+mvn spotless:apply
+
+# Run Japex microbenchmarks
+mvn test -Pbenchmarks
+```
+
+There is no dev server to start — this is an OSGi bundle deployed into a Sling
instance.
+
+# Project Layout
+
+```
+pom.xml Maven build descriptor
+bnd.bnd OSGi bundle manifest overrides
(Import-Package, Provide-Capability)
+src/
+ main/java/org/apache/sling/engine/
+ *.java Public API (EngineConstants, RequestUtil,
RequestInfo)
+ impl/ Internal implementation (not part of public
API)
+ SlingMainServlet.java Entry point: registers with OSGi HTTP
Whiteboard
+ SlingRequestProcessorImpl.java Core request processing pipeline
+ Config.java OSGi DS component configuration interface
+ StaticResponseHeader.java Configurable static response headers
+ adapter/ javax↔jakarta servlet API bridges
+ console/ Felix Web Console plugins
+ debug/ RequestProgressTracker integration, request
info provider
+ filter/ Servlet filter chain management
(ServletFilterManager, etc.)
+ helper/ ServletContext wrappers, filter config,
request listeners
+ log/ Custom access logging (ClientAbortException,
log format)
+ parameters/ Multipart/form request parameter parsing
+ request/ RequestData, SlingRequestPathInfo, dispatcher
+ jmx/ JMX MBean interfaces (public)
+ servlets/ Error handler servlet base
+ test/java/ Unit tests mirroring src/main/java package
structure
+ test/resources/japex/ Japex benchmark configuration XMLs
+target/ Build output (do not edit)
+```
+
+# Development Patterns & Constraints
+
+- **Java 17** required (`sling.java.version=17` in `pom.xml`).
+- **OSGi DS (Declarative Services) R7** annotations only — use
`org.osgi.service.component.annotations.*`. No Felix SCR annotations.
+- OSGi metatype annotations (`@ObjectClassDefinition`, `@AttributeDefinition`)
define component configuration.
+- All implementation classes live under `impl.*` — never expose `impl` types
through public API packages.
+- Both `javax.servlet` (3.1) and `jakarta.servlet` (6.1) APIs are supported.
Adapter classes in `impl/adapter/` bridge them; do not bypass these adapters.
+- Logging via SLF4J (`org.slf4j`). No `java.util.logging` or `log4j` direct
usage.
+- 4-space indentation, Apache license header on every source file.
+- `bnd.bnd` controls OSGi imports and capability declarations. Update it if
adding new optional imports.
+- Baseline check (`bnd-baseline-maven-plugin`) enforces semantic versioning —
increment package versions when changing public API.
+
+# Git Workflow
+
+- Branch from `master`. Feature branches named
`feature/SLING-XXXXX-short-description` or `fix/SLING-XXXXX-short-description`.
+- Commit messages reference the JIRA issue: `SLING-XXXXX Short description of
change`.
+- PRs target `master`. CI (Jenkins) must pass before merge.
+- Do not push directly to `master`.
+
+# Testing Guidelines
+
+- Framework: **JUnit 4** (`junit:junit`) + **Mockito** 4.x + **OSGi Mock**
(`org.apache.sling.testing.osgi-mock.junit4`).
+- Test classes live in `src/test/java/` in the same package as the class under
test.
+- Name test classes `<ClassName>Test.java`.
+- Run all tests: `mvn test`. Run one class: `mvn test -Dtest=ClassName`.
+- Coverage reports are not generated by default; add `-Pjacoco` if the parent
POM profile exists.
+- Benchmarks (Japex) are in `src/test/java/.../benchmarks/` and only run with
`-Pbenchmarks`.
+
+# Gotchas
+
+- The bundle parent POM (`sling-bundle-parent`) supplies most plugin
configuration (Spotless, RAT, baseline, bnd). Check it before adding plugins
already inherited.
+- `bnd-baseline-maven-plugin` will fail the build if a public package version
wasn't bumped after an API change. Increment the `package-info.java` `@Version`
annotation.
+- `mockito-inline` is required alongside `mockito-core` to mock final
classes/methods; both must stay version-aligned.
+- The `org.apache.sling.engine.servlets` package baseline is temporarily
excluded (see `pom.xml` `<diffpackages>`) due to SLING-11728.
+- `javax.servlet` imports in `bnd.bnd` use a version range `[2.6,4)` to stay
compatible with both Servlet 3.x containers and the wrappers provided by
`org.apache.felix.http.wrappers`.
+- The `SlingMainServlet` registers as an OSGi HTTP Whiteboard servlet — it is
not instantiated by a traditional servlet container; test it with OSGi Mock,
not a servlet container mock.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..9a80b01
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+read @AGENTS.md
diff --git a/README.md b/README.md
index 0ea38bb..6ec7e7e 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,78 @@
# Apache Sling Engine Implementation
-This module is part of the [Apache Sling](https://sling.apache.org) project.
+This module is part of the [Apache Sling](https://sling.apache.org) project
and implements the core Sling request processing pipeline.
-This is the engine of Sling.
+## Overview
+
+`org.apache.sling.engine` provides the Sling engine bundle that:
+
+- registers the main servlet via OSGi HTTP Whiteboard
+- resolves resources and dispatches requests
+- manages Sling filter chains and request/response wrapping
+- exposes request processor and filter processor metrics via JMX
+- supports both `javax.servlet` (legacy) and `jakarta.servlet` through adapter
classes
+
+## Requirements
+
+- Java 17
+- Maven
+
+## Build and test
+
+```bash
+# Build and package (skip tests)
+mvn clean install -DskipTests
+
+# Full build with tests
+mvn clean install
+
+# Run all tests
+mvn test
+
+# Run a single test class
+mvn test -Dtest=SlingRequestPathInfoTest
+
+# Run tests with a name pattern
+mvn test -Dtest="*FilterChain*"
+
+# License header check (Apache RAT)
+mvn apache-rat:check
+
+# Check formatting (Spotless, inherited from parent POM)
+mvn spotless:check
+
+# Apply formatting
+mvn spotless:apply
+
+# Run Japex microbenchmarks
+mvn test -Pbenchmarks
+```
+
+## Repository layout
+
+```text
+pom.xml Maven build descriptor
+bnd.bnd OSGi bundle manifest instructions
+src/
+ main/java/org/apache/sling/engine/
+ *.java Public API
+ impl/ Internal implementation
+ adapter/ javax <-> jakarta servlet adapters
+ console/ Web Console plugins
+ debug/ RequestProgressTracker integration
+ filter/ Sling filter chain management
+ helper/ Servlet context/request listener helpers
+ log/ Request logging support
+ parameters/ Request parameter and multipart handling
+ request/ Request data and dispatching
+ jmx/ JMX MBean interfaces
+ servlets/ Error handler servlet API
+ test/java/ Unit tests
+ test/resources/japex/ Benchmark configurations
+```
+
+## Notes
+
+- OSGi Declarative Services annotations are used
(`org.osgi.service.component.annotations`).
+- The bundle imports `javax.servlet` with a compatibility range and supports
Jakarta Servlet API in parallel.
