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 ef8b36d docs: update AGENTS.md and README.md with new API, structure,
and test details (#67)
ef8b36d is described below
commit ef8b36de924c146b75d682d2fe8d67618798e31e
Author: Carsten Ziegeler <[email protected]>
AuthorDate: Tue Jun 2 11:09:09 2026 +0200
docs: update AGENTS.md and README.md with new API, structure, and test
details (#67)
Co-authored-by: Maia <maia@noreply>
---
AGENTS.md | 58 ++++++++++++++++++++++++++++++----------------------------
README.md | 15 ++++++++++++---
2 files changed, 42 insertions(+), 31 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index 7295593..4eaedb7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,6 @@
# 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 [...]
+Apache Sling Servlets Resolver is an OSGi bundle that implements Sling servlet
and script resolution services. It provides `ServletResolver`, the deprecated
`SlingScriptResolver` bridge (`SlingScriptResolverImpl`), and Sling error
handling integration, resolving requests by traversing resource-type
hierarchies with selector/extension/method matching. It also tracks servlets
registered as OSGi services, mounts them as virtual resources, handles bundled
scripts via the `sling.servlet` capa [...]
# Core commands
@@ -10,6 +10,7 @@ Apache Sling Servlets Resolver is an OSGi bundle that
implements the Sling API `
- **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`
+- **Single resource-hiding integration test class:** `mvn verify
-Dit.test=BasicResourceHidingIT`
- **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"`
@@ -24,38 +25,39 @@ bnd.bnd OSGi bundle manifest
overrides
findbugs-exclude.xml SpotBugs suppression rules
src/
main/java/org/apache/sling/servlets/resolver/
+ api/
+ IgnoredServletResourcePredicate.java Optional servlet/script hiding
predicate API
+ jmx/
+ SlingServletResolverCacheMBean.java Resolver cache
management/inspection interface
internal/
- SlingServletResolver.java Core ServletResolver/SlingScriptResolver impl
- ResolverConfig.java OSGi DS configuration interface
(@ObjectClassDefinition)
- ScriptResource.java Resource wrapping a script file
- PathBasedServletAcceptor.java
+ SlingServletResolver.java Core ServletResolver implementation
+ SlingScriptResolverImpl.java Deprecated SlingScriptResolver
bridge
+ ResolverConfig.java OSGi DS configuration interface
(@ObjectClassDefinition)
resolution/
- ResolutionCache.java Caches servlet resolution results
+ ResolutionCache.java Caches servlet/script 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
+ ResourceCollector.java Collects candidate resources for
resolution
+ LocationCollector.java Computes search paths for a request
+ WeightedResource.java Sorting/ranking of resolution
candidates
resource/
- ServletMounter.java Registers servlets as virtual resources
+ ServletMounter.java Registers servlets as virtual
resources
ServletResourceProvider.java
MergingServletResourceProvider.java
- ServletResource.java
- ServletResourceProviderFactory.java
bundle/
- BundledScriptTracker.java Tracks scripts in OSGi bundle capabilities
+ BundledScriptTracker.java Tracks scripts in OSGi bundle
capabilities
+ BundledScriptTrackerHC.java Optional health check for
bundled-script consistency
BundledScriptServlet.java
- BundledHooks.java
defaults/
DefaultServlet.java
DefaultErrorHandlerServlet.java
console/
- WebConsolePlugin.java Felix Web Console diagnostic plugin
+ 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
+ internal/ Unit tests (JUnit 4 + Mockito +
Sling mocks)
+ internal/resourcehiding/ Unit tests for hiding predicate
behavior
+ it/ Pax Exam integration tests
+ it/resourcehiding/ Integration tests for hidden
servlet fallback behavior
+target/ Build output — do not edit
```
# Development patterns & constraints
@@ -63,12 +65,12 @@ target/ Build output — do not edit
- **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.
+- **Imports:** Prefer constructor injection (immutable `@Reference` fields)
where component lifecycle allows 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.
+- **Formatting:** 4-space indentation, no tabs. Follow existing code style;
Spotless may run via the parent build, so keep formatting consistent with
existing files.
+- **Package visibility:** Keep implementation classes in `*.internal.*`; only
stable extension points belong in exported API packages (for example
`org.apache.sling.servlets.resolver.api`).
+- **Both servlet APIs:** The codebase supports both `javax.servlet` (Servlet
4) and `jakarta.servlet` (Servlet 6.1). 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
@@ -83,17 +85,17 @@ target/ Build output — do not edit
- **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`.
+- **Test placement:** Unit tests in `src/test/java/.../internal/` (including
`internal/resourcehiding/`); integration tests in `src/test/java/.../it/`
(including `it/resourcehiding/`).
+- **Coverage focus:** Prioritize resolution logic (`ResourceCollector`,
`LocationCollector`, `SlingServletResolver`), bundled-script tracking/health
checks, and resource-hiding behavior via `IgnoredServletResourcePredicate`.
- **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.
+- **Build the jar before running ITs.** Failsafe reads `${bundle.filename}`
(the project jar under `target/`). Running `mvn verify` from scratch handles
this, but running Failsafe goals directly can 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.
+- **Dual servlet API support (javax + jakarta):** Resolver behavior is
validated across both APIs (for example secure-request opting tests). When
fixing servlet behavior, review both execution paths.
- **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/README.md b/README.md
index e2cba81..051aed6 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 [](https://ci-builds.apache.org/job/Sling/job/modules/job/sling-org-apache-sling-servlets-resolver/job/master/) [](https://ci-builds.apache.org/job/Sling/job/modules/job/sling-or
[...]
-# Apache Sling Servlet Resolver
+# Apache Sling Servlets Resolver
This module is part of the [Apache Sling](https://sling.apache.org) project.
@@ -20,6 +20,7 @@ See the
[servlets](https://sling.apache.org/documentation/the-sling-engine/servl
- 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`)
+- Maintains servlet/script resolution caches with JMX inspection and cache
management support
- Includes resolver diagnostics through a Felix Web Console plugin
- Supports optional servlet/script hiding via `IgnoredServletResourcePredicate`
- Provides a configurable bundled-script health check
(`BundledScriptTrackerHC`)
@@ -32,25 +33,33 @@ This module requires **Java 17** and uses Maven.
- Run unit tests: `mvn test`
- Run full verification (unit + integration tests): `mvn verify`
- Run integration tests only: `mvn verify -Dsurefire.skip=true`
+- Run verification without integration tests: `mvn verify -DskipITs`
- Run SpotBugs check: `mvn spotbugs:check`
+- Run a single unit test class: `mvn test -Dtest=ResourceCollectorTest`
+- Run a single integration test class: `mvn verify
-Dit.test=ServletSelectionIT`
## Project structure
```text
src/main/java/org/apache/sling/servlets/resolver/
+ api/
+ IgnoredServletResourcePredicate.java
+ jmx/
+ SlingServletResolverCacheMBean.java
internal/
SlingServletResolver.java
SlingScriptResolverImpl.java
ResolverConfig.java
helper/ (resource and location collectors)
+ resolution/ (resolver cache implementation)
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)
+ internal/resourcehiding/ (unit tests for hiding predicate behavior)
it/ (Pax Exam integration tests)
+ it/resourcehiding/ (integration tests for hidden servlet fallback behavior)
```
