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-resolver.git
The following commit(s) were added to refs/heads/master by this push:
new ea344cf docs: add AGENTS.md, CLAUDE.md, and expand README (#66)
ea344cf is described below
commit ea344cf4481e54ca5583a7fcf005b168f77a2a2a
Author: Carsten Ziegeler <[email protected]>
AuthorDate: Tue Jun 2 07:31:00 2026 +0200
docs: add AGENTS.md, CLAUDE.md, and expand README (#66)
Adds AGENTS.md with full project overview, core commands, layout,
development patterns, testing guidelines, and gotchas. Adds CLAUDE.md
as a pointer to AGENTS.md. Expands README.md with highlights, build
instructions, and project structure tree.
Co-authored-by: Maia <maia@noreply>
---
AGENTS.md | 99 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
CLAUDE.md | 1 +
README.md | 48 ++++++++++++++++++++++++++++++-
3 files changed, 147 insertions(+), 1 deletion(-)
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..7295593
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,99 @@
+# Project overview
+
+Apache Sling Servlets Resolver is an OSGi bundle that implements the Sling API
`ServletResolver` and `SlingScriptResolver` interfaces. It resolves incoming
HTTP requests to the correct servlet or script by traversing a resource-type
hierarchy and applying selector/extension/method matching rules. It also tracks
servlets registered as OSGi services, mounts them as virtual resources, handles
bundled scripts (scripts embedded in OSGi bundles via the `sling.servlet`
capability), manages serv [...]
+
+# Core commands
+
+- **Build (compile + package OSGi bundle):** `mvn clean package -DskipTests`
+- **Full test suite (unit + integration):** `mvn verify`
+- **Unit tests only:** `mvn test`
+- **Integration tests only (requires built jar):** `mvn verify
-Dsurefire.skip=true`
+- **Single unit test class:** `mvn test -Dtest=ResourceCollectorTest`
+- **Single integration test class:** `mvn verify -Dit.test=ServletSelectionIT`
+- **SpotBugs static analysis:** `mvn spotbugs:check`
+- **Skip integration tests:** `mvn verify -DskipITs`
+- **Debug integration test container:** `mvn verify -Dpax.vm.options="-Xmx512M
-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005"`
+
+There is no dev server — this is an OSGi bundle deployed into a running Sling
instance.
+
+# Project layout
+
+```
+pom.xml Maven build descriptor
+bnd.bnd OSGi bundle manifest overrides
+findbugs-exclude.xml SpotBugs suppression rules
+src/
+ main/java/org/apache/sling/servlets/resolver/
+ internal/
+ SlingServletResolver.java Core ServletResolver/SlingScriptResolver impl
+ ResolverConfig.java OSGi DS configuration interface
(@ObjectClassDefinition)
+ ScriptResource.java Resource wrapping a script file
+ PathBasedServletAcceptor.java
+ resolution/
+ ResolutionCache.java Caches servlet resolution results
+ helper/
+ ResourceCollector.java Collects candidate resources for resolution
+ LocationCollector.java Computes search paths for a request
+ WeightedResource.java Sorting/ranking of resolution candidates
+ AbstractResourceCollector.java
+ NamedScriptResourceCollector.java
+ resource/
+ ServletMounter.java Registers servlets as virtual resources
+ ServletResourceProvider.java
+ MergingServletResourceProvider.java
+ ServletResource.java
+ ServletResourceProviderFactory.java
+ bundle/
+ BundledScriptTracker.java Tracks scripts in OSGi bundle capabilities
+ BundledScriptServlet.java
+ BundledHooks.java
+ defaults/
+ DefaultServlet.java
+ DefaultErrorHandlerServlet.java
+ console/
+ WebConsolePlugin.java Felix Web Console diagnostic plugin
+ test/java/org/apache/sling/servlets/resolver/
+ internal/ Unit tests (JUnit 4 + Mockito + Sling mocks)
+ it/ Integration tests (Pax Exam / OSGi container)
+target/ Build output — do not edit
+```
+
+# Development patterns & constraints
+
+- **Java version:** 17; use `var` and records where appropriate, but avoid
preview features.
+- **OSGi annotations:** Use `org.osgi.service.component.annotations`
(`@Component`, `@Reference`, `@Activate`, `@Deactivate`). Do not use Felix SCR
annotations.
+- **Configuration:** Declare component configs via `@ObjectClassDefinition`
interfaces (see `ResolverConfig`). Property keys use `.` as separator matching
the OSGi Metatype convention.
+- **Imports:** Prefer constructor injection (immutable `@Reference` fields)
over field injection where components allow it.
+- **Nullability:** Annotate nullable return values and parameters with
`@Nullable` / `@NotNull` from `org.jetbrains.annotations`.
+- **Logging:** SLF4J only (`org.slf4j.Logger`). No `java.util.logging` or
`System.out`.
+- **Formatting:** 4-space indentation, no tabs. Follow existing code style;
Spotless is not enforced at build time but consistency matters.
+- **Package visibility:** Keep implementation classes in `*.internal.*`; do
not expose internal types in public API packages.
+- **Both servlet APIs:** The codebase supports both `javax.servlet` (Servlet
4) and `jakarta.servlet` (Servlet 6). When adding servlet-related code check
both paths.
+- **No public API changes without versioning:** OSGi semantic versioning is
enforced via the `baseline` plugin. Changing exported package APIs requires a
version bump aligned with OSGi rules.
+
+# Git workflow
+
+- Branch from `master` for all changes.
+- Commit messages: `SLING-XXXXX - Short imperative description` (Jira issue
prefix required for non-trivial changes).
+- No force-pushes to `master`.
+- PRs are reviewed via GitHub; CI runs the full Maven build including
integration tests.
+- Follow [Apache Sling contributing
guidelines](https://sling.apache.org/contributing.html).
+
+# Testing guidelines
+
+- **Unit test framework:** JUnit 4 (`junit:junit`), Mockito 5, Sling OSGi Mock
(`org.apache.sling.testing.osgi-mock`), Sling Mock
(`org.apache.sling.testing.sling-mock`).
+- **Integration test framework:** Pax Exam 4 with a forked OSGi container
(Felix Framework). Tests suffixed `IT` run via `maven-failsafe-plugin`.
+- **Test placement:** Unit tests in `src/test/java/.../internal/`; integration
tests in `src/test/java/.../it/`.
+- **Coverage:** No enforced threshold; aim for meaningful coverage of
resolution logic, especially `ResourceCollector`, `LocationCollector`, and
`SlingServletResolver`.
+- **Running a single unit test:** `mvn test -Dtest=ClassName`
+- **Running a single IT:** `mvn verify -Dit.test=ClassName`
+- Integration tests spin up a real OSGi framework; they are slow (~1–2 min)
and require the bundle jar to be built first.
+
+# Gotchas
+
+- **Build the jar before running ITs.** Failsafe reads `${bundle.filename}`
(the project jar under `target/`). Running `mvn verify` from scratch handles
this, but `mvn failsafe:integration-test` alone will fail if the jar is missing.
+- **SpotBugs runs at `process-classes` phase**, before tests. A SpotBugs
violation will prevent tests from running. Check `target/spotbugsXml.xml` for
details. Use `findbugs-exclude.xml` to suppress false positives with
justification.
+- **Dual servlet API support (javax + jakarta):** Some classes have parallel
implementations (e.g., `DefaultErrorHandlerServlet` /
`DefaultErrorHandlerJakartaServlet`). When fixing a bug in one, check the
counterpart.
+- **OSGi baseline check:** Adding or changing exported types without bumping
the package version causes a build failure. Run `mvn verify` to catch this
early.
+- **Pax Exam memory:** The forked OSGi container starts with `-Xmx512M` by
default. Override with `-Dpax.vm.options` if tests OOM.
+- **`ResolutionCache`** is a required OSGi service dependency of
`SlingServletResolver`. In tests that mock the resolver, this must be provided
or the component will not activate.
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 c8624d2..e2cba81 100644
--- a/README.md
+++ b/README.md
@@ -6,5 +6,51 @@
This module is part of the [Apache Sling](https://sling.apache.org) project.
-Bundle implementing the Sling API ServletResolver. See the
[servlets](https://sling.apache.org/documentation/the-sling-engine/servlets.html)
and [scripts](https://sling.apache.org/documentation/bundles/scripting.html)
documentation for how this works.
+This OSGi bundle implements Sling's servlet and script resolution services:
+- `org.apache.sling.api.servlets.ServletResolver` via `SlingServletResolver`
+- `org.apache.sling.api.scripting.SlingScriptResolver` via
`SlingScriptResolverImpl` (deprecated API bridge)
+- `org.apache.sling.api.servlets.JakartaErrorHandler` for error handling using
Sling's resolution algorithm
+
+See the
[servlets](https://sling.apache.org/documentation/the-sling-engine/servlets.html)
and [scripts](https://sling.apache.org/documentation/bundles/scripting.html)
documentation for resolution behavior.
+
+## Highlights
+
+- Supports both `javax.servlet` (4.x) and `jakarta.servlet` (6.1) APIs
+- Resolves scripts and servlets across resource-type hierarchies with
selector/extension/method matching
+- Mounts OSGi servlet services into the resource tree through dedicated
resource providers
+- Tracks bundled scripts contributed through OSGi capabilities
(`sling.servlet`)
+- Includes resolver diagnostics through a Felix Web Console plugin
+- Supports optional servlet/script hiding via `IgnoredServletResourcePredicate`
+- Provides a configurable bundled-script health check
(`BundledScriptTrackerHC`)
+
+## Build and test
+
+This module requires **Java 17** and uses Maven.
+
+- Build bundle (skip tests): `mvn clean package -DskipTests`
+- Run unit tests: `mvn test`
+- Run full verification (unit + integration tests): `mvn verify`
+- Run integration tests only: `mvn verify -Dsurefire.skip=true`
+- Run SpotBugs check: `mvn spotbugs:check`
+
+## Project structure
+
+```text
+src/main/java/org/apache/sling/servlets/resolver/
+ internal/
+ SlingServletResolver.java
+ SlingScriptResolverImpl.java
+ ResolverConfig.java
+ helper/ (resource and location collectors)
+ resource/ (servlet mounting/resource providers)
+ bundle/ (bundled script tracking and servlet wrapper support)
+ defaults/ (default and error handler servlets)
+ console/ (Web Console diagnostics)
+ jmx/
+ SlingServletResolverCacheMBean.java
+
+src/test/java/org/apache/sling/servlets/resolver/
+ internal/ (unit tests)
+ it/ (Pax Exam integration tests)
+```
