This is an automated email from the ASF dual-hosted git repository.
kwin pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sling-site.git
The following commit(s) were added to refs/heads/master by this push:
new 141575b42 Document limitations of resource/property names
141575b42 is described below
commit 141575b426a8c3ea80892f52cae915eeef3998c9
Author: Konrad Windszus <[email protected]>
AuthorDate: Tue Jun 10 19:00:30 2025 +0200
Document limitations of resource/property names
Outline for JCR resource provider what/how it escapes/unescapes
automatically.
This relates to SLING-12776.
---
.../content/documentation/the-sling-engine/resources.md | 14 +++++++++++++-
1 file changed, 13 insertions(+), 1 deletion(-)
diff --git a/src/main/jbake/content/documentation/the-sling-engine/resources.md
b/src/main/jbake/content/documentation/the-sling-engine/resources.md
index 31f5fdaa8..5335c03b3 100644
--- a/src/main/jbake/content/documentation/the-sling-engine/resources.md
+++ b/src/main/jbake/content/documentation/the-sling-engine/resources.md
@@ -17,7 +17,7 @@ Resources have a number of essential properties:
| Property | Description |
|---|---|
| Path | Resources are part of a Resource Tree. As such each Resource has a
path which is formed by concatenating the names of all Resources along the root
to the Resource separated by a slash. Ok, really, this is much like a URL path
or a file system path where the slash (`/`) is the separator character. |
-| Name | The name of the Resource is the last element (or segment) in the
path. |
+| Name | The name of the Resource is the last element (or segment) in the
path. Sling itself allows all characters except for `/` or names only
consisting of (arbitrarily many) dots (`.`), however the individual resource
providers may impose additional restrictions on top. |
| Resource Type | Each resource has a resource type which is used by the
Servlet and Script resolver to find the appropriate Servlet or Script to handle
the request for the Resource. |
| Resource Super Type | The (optional explicit) super type of the Resource.
See the section _Resource Types_ below for more details. |
| Adapters | Resources are always `Adaptable` and therefore can be adapted to
a different view. See the section _Resource Adapters_ below for more details. |
@@ -181,6 +181,18 @@ For node type `nt:file` the property is looked up in the
child node `jcr:content
In case when binaries are stored externally (e.g. in a Cloud Storage)
accessing those via Sling just induces additional overhead. Therefore with
[SLING-7140](https://issues.apache.org/jira/browse/SLING-7140) support for
[Oak's Direct Binary
Access](https://jackrabbit.apache.org/oak/docs/features/direct-binary-access.html)
was added. External binaries now expose also as
[`o.a.s.ai.resource.external.ExternalizableInputStream`](https://github.com/apache/sling-org-apache-sling-api/blob/maste
[...]
+#### Resource/Property names
+
+Apart from the regular Sling restrictions on resource names JCR further
restricts which names a JCR item (backing a resource/property) may have. The
restrictions are outlined in the [JCR spec's grammar for JCR
names](https://s.apache.org/jcr-2.0-spec/3_Repository_Model.html#3.2%20Names).
+
+In contrast to JCR API, the Sling Resource API only allows access via names in
[qualified
form](https://s.apache.org/jcr-2.0-spec/3_Repository_Model.html#3.2.5.2%20Qualified%20Form)
but not in [expanded
form](https://s.apache.org/jcr-2.0-spec/3_Repository_Model.html#3.2.5.1%20Expanded%20Form).
+
+##### Escaping/Unescaping
+
+There is no automatic escaping of resource names (i.e. the callers of Sling
Resource API must make sure to either use only valid JCR names or take care of
escaping and potentially unescaping manually). For property names however the
JCR provider automatically escapes during write operations with
[`org.apache.jackrabbit.util.Text.escapeIllegalJcrChars(...)`](https://jackrabbit.apache.org/api/trunk/org/apache/jackrabbit/util/Text.html#escapeIllegalJcrChars(java.lang.String))
and automatica [...]
+
+The recommended name escaping for JCR is outlined at
<https://jackrabbit.apache.org/archive/wiki/JCR/EncodingAndEscaping_115513396.html>
which coincidentally also takes care of escaping invalid Sling characters (`/`
and dots).
+
#### Resource Metadata
The resource metadata exposed in `Resource.getResourceMetadata` get their
values from JCR properties:
