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 902ecca docs: expand AGENTS.md and README.md with new files and
commands (#55)
902ecca is described below
commit 902ecca62f0471d76dffc73605400a81185beb8f
Author: Carsten Ziegeler <[email protected]>
AuthorDate: Tue Jun 2 11:09:19 2026 +0200
docs: expand AGENTS.md and README.md with new files and commands (#55)
Co-authored-by: Maia <maia@noreply>
---
AGENTS.md | 23 +++++++++++++++++++----
README.md | 18 ++++++++++++++----
2 files changed, 33 insertions(+), 8 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index 872314e..daabbfe 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,6 @@
# Project Overview
-`org.apache.sling.jcr.resource` is an OSGi bundle that implements Sling's
JCR-backed resource provider and resolver internals. It maps JCR
nodes/properties to Sling `Resource` objects, handles session/provider-state
lifecycle, exposes JCR-backed `ValueMap` implementations, and emits
resource-change events from JCR observation. The bundle runs in an OSGi
container with a JCR repository (typically Jackrabbit Oak).
+`org.apache.sling.jcr.resource` is an OSGi bundle that implements Sling's
JCR-backed resource provider and resolver internals. It maps JCR
nodes/properties to Sling `Resource` objects, handles session/provider-state
lifecycle, supports query and binary download integrations, exposes JCR-backed
`ValueMap` implementations, and emits resource-change events from JCR
observation. The bundle runs in an OSGi container with a JCR repository
(typically Jackrabbit Oak).
# Core Commands
@@ -17,6 +17,9 @@ mvn test
# Run a single test class
mvn test -Dtest=JcrResourceProviderTest
+# Run session-handling focused provider tests
+mvn test -Dtest=JcrResourceProviderSessionHandlingTest
+
# Run a single test method
mvn test -Dtest=JcrValueMapTest#testPutMultipleValues
@@ -31,6 +34,9 @@ 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.
@@ -39,14 +45,16 @@ No dev server — this is a pure OSGi bundle deployed into a
Sling/Felix runtime
```
pom.xml Maven build descriptor
-bnd.bnd OSGi manifest extras (optional scripting
import, conditional packages, Sling namespaces/nodetypes)
+bnd.bnd OSGi metadata (optional scripting import,
conditional packages, Sling namespaces/nodetypes)
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
@@ -58,6 +66,8 @@ src/
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
@@ -71,16 +81,18 @@ src/
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)
test/
- java/… JUnit 4 tests mirroring the main package
structure
-target/ Build output (ignored by git)
+ 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)
```
# 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`.
- **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.
@@ -105,14 +117,17 @@ target/ Build output
(ignored by git)
- **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.
+- **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.
# Gotchas
- **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`).
- **`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.
+- **Adapter metadata generation**: `sling-maven-plugin` generates adapter
metadata during `process-classes`; do not hand-maintain generated metadata.
- **No standalone runner**: the bundle cannot run standalone; deploy into
Sling/Felix or use `sling-mock-oak` for repository-backed tests.
diff --git a/README.md b/README.md
index d26adca..6ab08ed 100644
--- a/README.md
+++ b/README.md
@@ -24,8 +24,14 @@ mvn test
# Run a single test class
mvn test -Dtest=JcrResourceProviderTest
+# Run session lifecycle/provider handling tests
+mvn test -Dtest=JcrResourceProviderSessionHandlingTest
+
# Run a single test method
mvn test -Dtest=JcrValueMapTest#testPutMultipleValues
+
+# Generate coverage report
+mvn test jacoco:report
```
## Development checks
@@ -52,14 +58,15 @@ bnd.bnd OSGi metadata and package
instructions
src/
main/
java/org/apache/sling/jcr/resource/
- api/ Public API (for example JcrResourceChange,
constants)
- internal/ Internal implementation
(resource/provider/listener/value map helpers)
- helper/jcr/ Core JCR ResourceProvider and resource
wrappers
+ 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
test/
- java/ JUnit 4 tests (Mockito, Hamcrest, JMock,
sling-mock-oak)
+ java/ JUnit 4 tests (Mockito, Hamcrest, JMock,
sling-mock-oak), including provider session handling coverage
```
## Key technical details
@@ -67,5 +74,8 @@ src/
- Java source/target level is Java 8 (`sling.java.version=8`).
- Parent POM is `org.apache.sling:sling-bundle-parent:66`.
- 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/`.
