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-resource.git
The following commit(s) were added to refs/heads/master by this push:
new ec69c71 docs: tighten AGENTS.md and README.md project documentation
(#56)
ec69c71 is described below
commit ec69c714c6446231cd1e0bed7a9065a52b7be09d
Author: Carsten Ziegeler <[email protected]>
AuthorDate: Thu Jul 16 17:57:19 2026 +0200
docs: tighten AGENTS.md and README.md project documentation (#56)
Co-authored-by: Maia <maia@noreply>
---
AGENTS.md | 67 +++++++++++++++++++--------------------------------------------
README.md | 11 +++++++----
2 files changed, 27 insertions(+), 51 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index 56ee469..5047963 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -23,6 +23,9 @@ mvn test -Dtest=JcrResourceProviderSessionHandlingTest
# Run a single test method
mvn test -Dtest=JcrValueMapTest#testPutMultipleValues
+# Generate coverage report
+mvn test jacoco:report
+
# Apply Spotless code formatting (inherited from sling-bundle-parent)
mvn spotless:apply
@@ -34,70 +37,41 @@ mvn apache-rat:check
# API baseline check
mvn bnd-baseline:baseline
-
-# Generate coverage report
-mvn test jacoco:report
```
No dev server — this is a pure OSGi bundle deployed into a Sling/Felix runtime.
# Project Layout
-```
+```text
pom.xml Maven build descriptor
-bnd.bnd OSGi metadata (optional scripting import,
conditional packages, Sling namespaces/nodetypes)
+bnd.bnd OSGi metadata and package instructions
src/
main/
java/org/apache/sling/jcr/resource/
- api/
- JcrResourceChange.java Public API type for JCR-backed
resource change details
- JcrResourceConstants.java Public constants for JCR resource
handling
- package-info.java Exported package metadata/versioning
annotations
- internal/
- HelperData.java Shared runtime helper/context data for
resource/value map internals
- JcrListenerBaseConfig.java OSGi config model for JCR observation
listener behavior
- JcrResourceListener.java JCR observation listener and event
bridge
- JcrModifiableValueMap.java Writable ValueMap backed by a JCR Node
- JcrValueMap.java Read-only ValueMap backed by JCR
properties
- JcrSystemUserValidator.java Validates service-user principal names
- NodeUtil.java JCR node utility helpers
- scripting/
- JcrObjectsBindingsValuesProvider.java Exposes JCR objects to script
bindings
- helper/
- JcrPropertyMapCacheEntry.java Property map caching
- AccessLogger.java Structured access logging helpers
- JcrResourceUtil.java JCR query/value conversion utility
methods
- LazyInputStream.java Lazy binary stream wrapper for JCR
values
- Converter.java and *Converter.java Type conversion helpers
(Boolean, Date, Calendar, Number, String, ZonedDateTime)
- jcr/
- JcrResourceProvider.java Main JCR ResourceProvider
implementation
- JcrProviderStateFactory.java Session/provider-state lifecycle
factory
- JcrProviderState.java Provider state holder
- JcrItemResourceFactory.java Creates Resource from JCR Item
- JcrItemResource.java Base resource wrapping a JCR Item
- JcrNodeResource.java Resource wrapping a JCR Node
- JcrPropertyResource.java Resource wrapping a JCR Property
- JcrNodeResourceIterator.java Iterator over node-backed
resources
- JcrNodeResourceMetadata.java Metadata support for node
resources
- BasicQueryLanguageProvider.java Query language provider
integration
- BinaryDownloadUriProvider.java Direct binary download URI support
- JcrExternalizableInputStream.java URI-capable lazy binary
InputStream wrapper
- ContextUtil.java Context/resource-resolver utility
methods
- resources/SLING-INF/nodetypes/ CND node-type definitions (folder,
resource, vanitypath, redirect, mapping)
+ api/ Public API (JcrResourceChange,
JcrResourceConstants)
+ internal/ Internal implementation
+ helper/ Conversion utilities, cache entry, access
logging, lazy streams
+ helper/jcr/ Core JCR ResourceProvider, provider state,
query/binary support
+ scripting/ Optional scripting bindings integration
+ resources/SLING-INF/nodetypes/
+ Sling/JCR node type definitions (folder,
resource, vanitypath, redirect, mapping)
test/
- java/… JUnit 4 tests mirroring the main package
structure (includes provider session-handling coverage)
-target/ Build output (generated classes,
OSGI-INF, surefire-reports, baseline report)
+ java/ JUnit 4 tests plus shared test infrastructure
+ (JcrItemResourceTestBase,
SlingRepositoryTestBase, SlingRepositoryProvider)
+target/ Build output (generated classes, OSGI-INF,
SLING-INF, surefire-reports, baseline report)
+ Includes generated-sources/annotations and
generated-test-sources/test-annotations
```
# Development Patterns & Constraints
- **Java version**: source/target compatibility Java 8
(`sling.java.version=8`).
- **Parent POM**: inherits build defaults/checks from
`org.apache.sling:sling-bundle-parent:66`.
+- **Artifact version**: current development version is `3.3.7-SNAPSHOT`.
- **OSGi annotations**: use `org.osgi.service.component.annotations` (R6/R7).
Do not use Felix SCR annotations.
- **Nullability**: annotate with `org.jetbrains.annotations` (`@NotNull`,
`@Nullable`) on public API where applicable.
- **License header**: every `.java` and `.xml` source file must carry the
Apache 2.0 license block. Run `mvn apache-rat:check` to verify.
- **Formatting**: Spotless is enforced by the parent POM. Run `mvn
spotless:apply` before committing. 4-space indentation; no tabs.
-- **Import order**: follow the Spotless-enforced order (static imports →
`javax.*` → `java.*` → third-party → internal).
- **Internal API**: everything under `*.internal.*` is private API. Do not
expose internal types in public OSGi service contracts.
- **Public API compatibility**: types in `org.apache.sling.jcr.resource.api`
are baseline-checked; keep semantic versioning constraints in mind.
- **OSGi descriptors**: generated at build time from annotations/bnd; do not
hand-edit generated `OSGI-INF` files.
@@ -108,7 +82,7 @@ target/ Build output (generated
classes, OSGI-INF,
- Default branch: `master`.
- Feature branches: `feature/<jira-id>-short-description` or
`fix/<jira-id>-short-description`.
- Commit messages: short imperative subject line; reference JIRA issue
(`SLING-XXXXX`) where applicable.
-- PRs target `master`. CI runs Maven build + tests via Jenkins (`Jenkinsfile`
at repo root).
+- PRs target `master`. CI runs Jenkins pipeline from `Jenkinsfile`
(`slingOsgiBundleBuild()`).
- See [CONTRIBUTING.md](CONTRIBUTING.md) for Apache CLA and code-review
process.
# Testing Guidelines
@@ -116,7 +90,7 @@ target/ Build output (generated
classes, OSGI-INF,
- **Framework**: JUnit 4 (`junit:junit`), Mockito 5, Hamcrest 2, JMock.
- **Sling testing**: `org.apache.sling.testing.sling-mock.junit4` +
`sling-mock-oak` for integration-style tests against an in-memory Oak
repository.
- **Test location**: `src/test/java/` mirroring the main package structure.
Test classes end with `Test`.
-- **Shared base classes**: `JcrItemResourceTestBase`,
`SlingRepositoryTestBase` — extend these for tests needing a live JCR session.
+- **Shared base classes**: `JcrItemResourceTestBase`,
`SlingRepositoryTestBase`; utility collaborators include
`SlingRepositoryProvider` and `JcrTestNodeResource`.
- **Session lifecycle coverage**: `JcrResourceProviderSessionHandlingTest`
covers provider session handling and cleanup paths.
- **Coverage report**: `mvn test jacoco:report` (JaCoCo is inherited from
parent POM).
- Do not use `@RunWith(MockitoJUnitRunner.class)` and `@Rule MockitoRule`
together in the same class.
@@ -125,7 +99,7 @@ target/ Build output (generated
classes, OSGI-INF,
- **Oak version pinned**: `oak.version=1.44.0` is the minimum for
`JackrabbitNode.getPropertyOrNull`. Bumping below 1.44.0 breaks compilation.
- **Jackrabbit compatibility**: `jackrabbit.version=2.18.0` is part of the
current dependency baseline.
-- **sling-mock exclusion**: `org.apache.sling.testing.sling-mock.junit4` must
exclude `org.apache.sling.jcr.resource` to avoid classpath conflicts with the
bundle under test (configured in `pom.xml`).
+- **sling-mock exclusion**: `org.apache.sling.testing.sling-mock.junit4`
excludes `org.apache.sling.jcr.resource` to avoid classpath conflicts with the
bundle under test (configured in `pom.xml`).
- **`bnd-baseline`**: baseline checks enforce semantic versioning for exported
packages; API changes may require package version updates.
- **Conditional packages**: `org.apache.jackrabbit.util` and
`org.apache.jackrabbit.name` are inlined via `-conditionalpackage` in
`bnd.bnd`; do not add them as explicit `Import-Package` entries.
- **Scripting API is optional**: `org.apache.sling.scripting.api` is optional
at runtime; code must handle its absence.
@@ -137,4 +111,3 @@ target/ Build output
(generated classes, OSGI-INF,
<!-- sling-security-default:start -->
The threat model for this project is
https://github.com/apache/sling/blob/master/docs/threat-model.md .
<!-- sling-security-default:end -->
-
diff --git a/README.md b/README.md
index 6ab08ed..1d071e3 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@
This module is part of the [Apache Sling](https://sling.apache.org) project.
This bundle provides Sling's JCR-backed resource provider and resolver
internals.
-It maps JCR nodes and properties to Sling `Resource` objects, handles
provider/session lifecycle, supports query and binary download integrations,
and emits resource change events from JCR observation.
+It maps JCR nodes and properties to Sling `Resource` objects, handles
provider/session lifecycle, supports query and binary download integrations,
exposes JCR-backed `ValueMap` implementations, and emits resource change events
from JCR observation.
## Build and test
@@ -64,18 +64,21 @@ src/
helper/jcr/ Core JCR ResourceProvider, provider state,
query/binary support
scripting/ Optional scripting bindings integration
resources/SLING-INF/nodetypes/
- Sling/JCR node type definitions
+ Sling/JCR node type definitions (folder,
resource, vanitypath, redirect, mapping)
test/
- java/ JUnit 4 tests (Mockito, Hamcrest, JMock,
sling-mock-oak), including provider session handling coverage
+ java/ JUnit 4 tests plus shared test infrastructure
+target/ Build output (generated classes, OSGI-INF,
SLING-INF, surefire-reports, baseline report)
+ Includes generated-sources/annotations and
generated-test-sources/test-annotations
```
## Key technical details
- Java source/target level is Java 8 (`sling.java.version=8`).
- Parent POM is `org.apache.sling:sling-bundle-parent:66`.
+- Current artifact development version is `3.3.7-SNAPSHOT`.
- Oak baseline is `1.44.0` (minimum required for
`JackrabbitNode.getPropertyOrNull` support).
- Jackrabbit baseline is `2.18.0`.
- `org.apache.sling.scripting.api` is optional at runtime
(`resolution:=optional` in `bnd.bnd`).
- Adapter metadata is generated by `sling-maven-plugin` during
`process-classes`.
- `org.apache.jackrabbit.util` and `org.apache.jackrabbit.name` are embedded
via `-conditionalpackage`.
-- Bundle nodetypes are provided from `src/main/resources/SLING-INF/nodetypes/`.
+- Bundle nodetypes are provided from `src/main/resources/SLING-INF/nodetypes/`
(`folder.cnd`, `resource.cnd`, `vanitypath.cnd`, `redirect.cnd`, `mapping.cnd`).
