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-jcr-base.git
The following commit(s) were added to refs/heads/master by this push:
new 9d09194 docs: expand AGENTS.md and README.md with initializer,
allow-list, and mount details (#18)
9d09194 is described below
commit 9d09194bd30dcc735214dd6bb4e17762b93da953
Author: Carsten Ziegeler <[email protected]>
AuthorDate: Tue Jun 2 11:09:32 2026 +0200
docs: expand AGENTS.md and README.md with initializer, allow-list, and
mount details (#18)
Co-authored-by: Maia <maia@noreply>
---
AGENTS.md | 21 ++++++++++++++++-----
README.md | 35 ++++++++++++++++++++++++++++++-----
2 files changed, 46 insertions(+), 10 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index 3e04374..ee14a35 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,6 @@
# Project Overview
-`org.apache.sling.jcr.base` is an OSGi bundle that provides JCR foundation
classes for Apache Sling. It supplies abstract base classes for implementing
`SlingRepository` (`AbstractSlingRepository2`,
`AbstractSlingRepositoryManager`), a `loginAdministrative` allow-list enforced
via OSGi component configuration, JCR node-type loading utilities,
access-control helpers, and a proxy/mount layer that lets multiple JCR
repositories appear as one. All components use OSGi R6/R7 Declarative Servic
[...]
+`org.apache.sling.jcr.base` is an OSGi bundle that provides JCR foundation
classes for Apache Sling. It includes base classes for implementing
`SlingRepository` (`AbstractSlingRepository2`,
`AbstractSlingRepositoryManager`), `loginAdministrative` allow-list enforcement
via OSGi component configuration, repository initializer execution
(`SlingRepositoryInitializer` services), JCR node-type/namespace loading
utilities, access-control helpers, and a proxy/mount layer that lets multiple
JCR [...]
# Core Commands
@@ -14,6 +14,9 @@ mvn clean verify
# Run all tests
mvn test
+# Run coverage report
+mvn test jacoco:report
+
# Run a single test class
mvn test -Dtest=LoginAdminAllowListTest
@@ -41,23 +44,26 @@ bnd.bnd OSGi bundle manifest
overrides
src/
main/java/org/apache/sling/jcr/base/
AbstractSlingRepository2.java Base SlingRepository implementation
- AbstractSlingRepositoryManager.java Manages repository lifecycle +
allow-list
- NodeTypeLoader.java Registers CND node-type definitions
+ AbstractSlingRepositoryManager.java Manages repository lifecycle,
initializers, and allow-list
+ NodeTypeLoader.java Registers CND node-type definitions and
namespaces
package-info.java Package-level OSGi version annotation
internal/
LoginAdminAllowList.java Enforces loginAdministrative allow-list
LoginAdminAllowListConfiguration.java OSGi Metatype config interface
AllowListFragment.java Whiteboard fragment for allow-list
entries
LegacyFragment.java Compatibility shim for old allow-list
configs
- RepositoryPrinter*.java Felix WebConsole status printer
+ RepositoryPrinter*.java Felix WebConsole status printer
provider + printer
loader/Loader.java Bootstraps node types from bundle
resources
mount/Proxy*.java Proxy wrappers for RepositoryMount SPI
+ mount/ChainedIterator.java Iterator utility for mount proxy
traversal
spi/
RepositoryMount.java SPI: plug in an additional JCR
repository
util/
AccessControlUtil.java JCR/Jackrabbit ACL helpers
RepositoryAccessor.java Repository lookup (JNDI / RMI / OSGi)
- test/java/… JUnit 4 tests mirroring the main package tree
+ test/java/… JUnit 4 tests mirroring the main
package tree
+ RepositoryInitializersTest.java Verifies SlingRepositoryInitializer
ordering/failure behavior
+ internal/AllowListWiringTest.java Verifies allow-list wiring across
modern + legacy configs
target/ Build output (gitignored)
```
@@ -71,6 +77,7 @@ target/ Build output (gitignored)
- Logging via SLF4J only (`org.slf4j.Logger`); never use `java.util.logging`
or `System.out`.
- All source files require the Apache License 2.0 header; RAT enforces this.
- The `bnd.bnd` file declares `Import-Package` overrides (e.g., optional RMI
import). Keep it in sync when adding new optional dependencies.
+- Repository initializer execution order follows OSGi service ranking
(`SlingRepositoryInitializer` with higher ranking runs first).
# Git Workflow
@@ -85,14 +92,18 @@ target/ Build output (gitignored)
- Framework: **JUnit 4** with Mockito 5 and Sling OSGi Mock / Sling Mock / JCR
Mock
- Test files mirror main sources under `src/test/java/…`
- OSGi component tests use `OsgiContext` (from
`org.apache.sling.testing.osgi-mock.junit4`)
+- `RepositoryInitializersTest` covers initializer ordering and repository
registration failure paths.
+- Allow-list behavior is covered by `LoginAdminAllowListTest`,
`AllowListWiringTest`, and `LegacyFragmentTest`.
- Run coverage: `mvn test jacoco:report` (JaCoCo is inherited from the Sling
bundle parent POM)
- Coverage report appears in `target/site/jacoco/`
# Gotchas
- **`loginAdministrative` is off by default**: bundles must register an
`AllowListFragment` OSGi service to be permitted. Tests that call
`loginAdministrative` without wiring the allow-list will get an exception.
+- **Allow-list configuration names changed from "whitelist" to "allowlist"**:
modern PIDs/properties are preferred, while legacy whitelist naming is still
supported for compatibility.
- **OSGi mock version matters**: the tests use `osgi-mock.junit4` 3.x; mixing
with 2.x artefacts breaks context setup.
- **RMI dependency is optional**: `jackrabbit-jcr-rmi` is `provided` scope and
the Import-Package is `resolution:=optional`. Do not make it mandatory.
+- **Repository startup is blocked on initializer failures**: exceptions/errors
from `SlingRepositoryInitializer` prevent SlingRepository service registration.
- **Baseline check**: the parent POM runs OSGi semantic-version baseline
against the previous release JAR. Adding API without bumping the package
version will fail the build.
- **Spotless must pass before RAT**: run `mvn spotless:apply` before
committing; otherwise the RAT XML-header check may report false positives on
reformatted files.
- The `internal` packages are deliberately excluded from Javadoc generation
(see `pom.xml` `maven-javadoc-plugin` config).
diff --git a/README.md b/README.md
index cd8b489..abd7681 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@
This module is part of the [Apache Sling](https://sling.apache.org) project.
-The JCR base bundle provides JCR utility classes, base implementations for
`SlingRepository`, login administrative allow-list enforcement, node type
loading helpers, and support for repository mounts.
+The JCR base bundle provides JCR utility classes, base implementations for
`SlingRepository`, login administrative allow-list enforcement, repository
initializer execution, node type and namespace loading helpers, repository
status printer support, and repository mount integration for JCR-based legacy
access.
# Build
@@ -24,6 +24,11 @@ mvn clean verify
mvn test
mvn test -Dtest=LoginAdminAllowListTest
mvn test -Dtest=LoginAdminAllowListTest#testAllowList
+mvn test -Dtest=RepositoryInitializersTest
+```
+
+```bash
+mvn test jacoco:report
```
# Code Quality
@@ -34,18 +39,25 @@ mvn apache-rat:check
mvn spotless:apply
```
+```bash
+mvn javadoc:javadoc
+```
+
# Requirements
* Java 8 source/target
-* OSGi Declarative Services (`org.osgi.service.component.annotations`)
-* Optional Jackrabbit RMI support via `jackrabbit-jcr-rmi` (provided scope)
+* Maven build for an OSGi bundle (Sling bundle parent)
+* OSGi Declarative Services and Metatype annotations
(`org.osgi.service.component.annotations`,
`org.osgi.service.metatype.annotations`)
+* Optional Jackrabbit RMI support via `jackrabbit-jcr-rmi` (provided scope,
optional package import)
# Main Components
* `AbstractSlingRepository2` and `AbstractSlingRepositoryManager` provide the
core Sling repository base implementation and lifecycle integration.
-* `LoginAdminAllowList`, `AllowListFragment`, and `LegacyFragment` enforce and
bridge `loginAdministrative` allow-list configuration.
+* `LoginAdminAllowList`, `AllowListFragment`, and `LegacyFragment` enforce and
bridge `loginAdministrative` allow-list configuration across modern and legacy
property names.
+* `SlingRepositoryInitializer` services are tracked and executed during
repository startup, ordered by OSGi service ranking.
* `NodeTypeLoader` and `internal.loader.Loader` register CND node types and
JCR namespaces from bundle headers.
-* `org.apache.sling.jcr.base.spi.RepositoryMount` and the internal proxy
classes support JCR repository mounts.
+* `org.apache.sling.jcr.base.spi.RepositoryMount` and the internal proxy
classes support JCR repository mounts through a single active mount selected by
service ranking.
+* `internal.RepositoryPrinterProvider` and `internal.RepositoryPrinter` expose
repository information to the Felix Web Console.
* `util.AccessControlUtil` and `util.RepositoryAccessor` provide reusable JCR
access-control and repository lookup utilities.
# Project Structure
@@ -66,6 +78,11 @@ Current configuration uses allow-list naming:
Legacy whitelist PIDs and properties are still supported for backward
compatibility, but they are deprecated.
+Also supported for backward compatibility:
+
+* Legacy main PID: `org.apache.sling.jcr.base.internal.LoginAdminWhitelist`
+* Legacy fragment factory PID:
`org.apache.sling.jcr.base.internal.LoginAdminWhitelist.fragment`
+
# Repository Mount
Apache Sling provides support for pluggable resource providers. While this
allows for a very flexible and efficient
@@ -79,6 +96,8 @@ itself with the service registration property
*RepositoryMount.MOUNT_POINTS_KEY*
the paths in the JCR tree where the mount takes over the control of the JCR
nodes. The *RepositoryMount* can be registered
at a single path or multiple.
+The JCR base implementation uses a single active mount. If multiple
`RepositoryMount` services are available, the one with the highest OSGi service
ranking is used.
+
As *RepositoryMount* extends *JackrabbitRepository* the implementation of a
mount needs to implement the whole JCR API.
This is a lot of work compared to a *ResourceProvider*, therefore a
*RepositoryMount* should only be used if legacy
code using JCR API needs to be supported.
@@ -89,3 +108,9 @@ When present, the following bundle manifest headers are
processed to register re
* `Sling-Nodetypes`
* `Sling-Namespaces`
+
+# Repository Initializers
+
+Services implementing `org.apache.sling.jcr.api.SlingRepositoryInitializer`
are executed at repository startup before the repository service is registered.
+
+If an initializer throws an exception or error, repository service
registration is aborted.
