You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by cz...@apache.org on 2026/06/02 08:02:51 UTC
(sling-org-apache-sling-servlets-resolver) branch maia/workflow-1780387363527 created (now bfc9359)
This is an automated email from the ASF dual-hosted git repository.
cziegeler pushed a change to branch maia/workflow-1780387363527
in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-servlets-resolver.git
at bfc9359 docs: update AGENTS.md and README.md with new API, structure, and test details
This branch includes the following new commits:
new bfc9359 docs: update AGENTS.md and README.md with new API, structure, and test details
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
(sling-org-apache-sling-servlets-resolver) 01/01: docs: update AGENTS.md and README.md with new API, structure, and test details
Posted by cz...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
cziegeler pushed a commit to branch maia/workflow-1780387363527
in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-servlets-resolver.git
commit bfc935906fb08b20a5fdbee03d04e7a4f5a177e8
Author: Carsten Ziegeler <cz...@apache.org>
AuthorDate: Tue Jun 2 10:02:43 2026 +0200
docs: update AGENTS.md and README.md with new API, structure, and test details
Co-authored-by: Maia <ma...@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)
```