[sling-site] branch master updated: clarify binary handling

[kw...@apache.org]

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 8e51fa7  clarify binary handling
     new 72b7fef  Merge branch 'master' of git@github.com:apache/sling-site.git
8e51fa7 is described below

commit 8e51fa7111062c897efd8cea1ff94a9ae543deca
Author: Konrad Windszus <kw...@apache.org>
AuthorDate: Mon Sep 21 09:12:52 2020 +0200

    clarify binary handling
---
 .../jbake/content/documentation/the-sling-engine/resources.md  | 10 +++++++++-
 1 file changed, 9 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 f7eccd0..69c445d 100644
--- a/src/main/jbake/content/documentation/the-sling-engine/resources.md
+++ b/src/main/jbake/content/documentation/the-sling-engine/resources.md
@@ -27,7 +27,7 @@ For a complete description of the `Resource` interface, please refer to the [`Re
 
 The properties are either exposed via the `ValueMap` or `ModifiableValueMap` adaptable or by calling `Resource.getValueMap()`.
 
-To get the main binary property from a given resource one can adapt it to an `InputStream`. Most resource providers return the underlying wrapper binary in that case.
+To get the *main* binary property from a given resource one can adapt it to an `InputStream`. Most resource providers return the underlying wrapper binary in that case. For arbitrary binary properties one must use the `ValueMap` which will return `InputStream` for such properties.
 
 ### Resource Types
 
@@ -144,6 +144,14 @@ Path Parameter | Example Value | Description | Since
  --- | --- | --- | ---
 | `v` | `1.0` | Retrieves the underlying JCR node from the [version history](https://docs.adobe.com/docs/en/spec/jcr/2.0/15_Versioning.html) leveraging the version label given in the value. | [SLING-848](https://issues.apache.org/jira/browse/SLING-848)
 
+#### Main Binary Property
+
+The main binary property (i.e. the one being exposed by `Resource.adaptTo(InputStream.class)`) is determined like follows:
+
+1. `jcr:data` is such a property exists, otherwise
+2. the primary item of the underlying node (as defined by [Node.getPrimaryItem()](https://docs.adobe.com/docs/en/spec/jsr170/javadocs/jcr-2.0/javax/jcr/Node.html#getPrimaryItem())).
+
+For node type `nt:file` the property is looked up in the child node `jcr:content` for both cases. For all other node types it is looked up in the underlying node of the current resource.
 
 ### Bundle-based Resources