This is an automated email from the ASF dual-hosted git repository. jsedding pushed a commit to branch resolver-2.x-backports in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-servlets-resolver.git
commit 044960dc3605ec0be45be492a4fbe05eec0faa8f 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> (cherry picked from commit ef8b36de924c146b75d682d2fe8d67618798e31e) --- 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) ```
