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-site.git


The following commit(s) were added to refs/heads/master by this push:
     new ec6e1d2  Update docs about bundle resource provider
ec6e1d2 is described below

commit ec6e1d2e5b495742a27101480d56a8a46e4f687a
Author: Carsten Ziegeler <czieg...@adobe.com>
AuthorDate: Sun Feb 4 16:13:54 2018 -0800

    Update docs about bundle resource provider
---
 .../bundle-resources-extensions-bundleresource.md  | 76 +++++++++++++++++-----
 1 file changed, 58 insertions(+), 18 deletions(-)

diff --git 
a/src/main/jbake/content/documentation/bundles/bundle-resources-extensions-bundleresource.md
 
b/src/main/jbake/content/documentation/bundles/bundle-resources-extensions-bundleresource.md
index ee7f809..7490a26 100644
--- 
a/src/main/jbake/content/documentation/bundles/bundle-resources-extensions-bundleresource.md
+++ 
b/src/main/jbake/content/documentation/bundles/bundle-resources-extensions-bundleresource.md
@@ -1,4 +1,4 @@
-title=Bundle Resources (extensions.bundleresource)             
+title=Bundle Resources (org.apache.sling.bundleresource.impl)          
 type=page
 status=published
 tags=resources,bundles
@@ -6,45 +6,85 @@ tags=resources,bundles
 
 [TOC]
 
-## Introduction
+# Introduction
 
 The Bundle Resource Provider provides access to files/directories included in 
an OSGi bundle through the Sling `ResourceResolver`. 
 
-## Resource Types
+# Configuration
+
+If a bundle wants to provide resources, it must specify the Bundle manifest 
header `Sling-Bundle-Resources` containing a list of absolute paths. The paths 
are separated by comma. Without any additional information such a path is 
mapped 1:1 meaning that the specified path is used as the root resource path 
and the corresponding resource is at the same path in the bundle. 
+
+The following example header maps the paths `/libs/sling/explorer` and 
`/libs/sling/servlet/default/explorer` in the resource tree to resources in the 
bundle at the same path:
+
+    ...
+    Sling-Bundle-Resources: /libs/sling/explorer,                         
+        /libs/sling/servlet/default/explorer
+    ...
+
+If such an entry points to a file in the bundle, only this file is mapped. If 
such an entry points to a directory in the bundle, the whole sub tree below 
this directory is mapped.
+
+It's also possible to map resources from the bundle to a different location in 
the resource tree. In this case the path has to be extended with a path 
directive to declare where the resources are in the bundle. Again the following 
example maps the path `/libs/sling/explorer` in the resource tree to resources 
below `/resources/explorer` in the bundle
+
+    ...
+    Sling-Bundle-Resources: /libs/sling/explorer;path:=/resources/explorer
+    ...
+
+# Resource Types
 
 Files and directories are mapped into the resource tree as regular `Resource` 
instances whose resource type depends on the actual nature of the mapped 
resource:
 
    * Regular files are assigned the `nt:file` resource type
    * Directories are assigned the `nt:folder` resource type
 
+# Defining Resources Through JSON
 
-## Adapters
+By default, there is a 1:1 mapping between resources in the bundle and 
resources in the resource tree as explained above. While this works for adding 
files to the resource tree, it doesn't support adding arbitrary resources to 
the resource tree where the resources just have a map of properties and are not 
actually a file. By specifying the directive `propsJSON` with an extension, all 
files in the bundle having this extension are passed as JSON files and the 
contained structure is added a [...]
 
-Filesystem resources extend from Sling's `AbstractResource` class and thus are 
adaptable to any type for which an `AdapterFactory` is registered supporting 
bundle resources. In addition `BundleResource` support the following adapters 
natively:
+For example with the following definition in the manifest:
 
-   * `java.net.URL` -- A valid `bundle://` URL to the resource in the bundle. 
-   * `java.io.InputStream` -- An `InputStream` to read file contents. Doesn't 
apply to folders.
+    ...
+    Sling-Bundle-Resources: 
/products;path:=/resources/products.json;propsJSON:=json
+    ...
 
+the resource path `/products` is mapped to bundle resources at 
`/resources/products.json` and all bundle resources with the `json` extension 
are parsed. For example with the following `products.json`:
 
-## Configuration
+    {
+        "sling:resourceType" : "products",
+        "sling" : {
+            "sling:resourceType" : "product",
+            "name" : "sling",
+            "title : "Apache Sling"
+        }
+    }
+    
+a resource named `products` with the resource type `products` has a single 
child resource named `sling` and the above three properties.
 
-Providing bundles have a Bundle manifest header `Sling-Bundle-Resources` 
containing a list of absolute paths provided by the bundle. The paths are 
separated by comma or whitespace (SP, TAB, VTAB, CR, LF). 
+It's also possible to add additional properties to a file from a bundle 
resource. For example if the bundle contains the resource `tree.gif` and a JSON 
file `tree.gif.json` with the directive to parse all files ending in `json`, a 
file resource `tree.gif` exists in the resource tree with the additional 
properties from the json file. The JSON file can also override the default 
resource type in this case. In addition this json file can also contain nested 
resources below the file resource.
 
-Example (manifest.mf):
+# Adapters
 
+Filesystem resources extend from Sling's `AbstractResource` class and thus are 
adaptable to any type for which an `AdapterFactory` is registered supporting 
bundle resources. In addition `BundleResource` support the following adapters 
natively:
 
-    ...
-    Sling-Bundle-Resources: /libs/sling/explorer,                         
-        /libs/sling/servlet/default/explorer
-    ...
+   * `java.net.URL` -- A valid `bundle://` URL to the resource in the bundle. 
+   * `java.io.InputStream` -- An `InputStream` to read file contents. Doesn't 
apply to folders.
 
 
-It's also possible to map resources from the bundle to a different location in 
the resource tree. In this case the path has to be extended with a path 
attrribute to declare where the resources are in the bundle:
+# Capability
 
+The bundle implementing the support for bundle resources must provide the 
following extender capability:
 
-    ...
-    Sling-Bundle-Resources: 
/somepath/inthe/resourcetree;path:=/path/inthe/bundle
-    ...
+    <Provide-Capability>
+       
osgi.extender;osgi.extender="org.apache.sling.bundleresource";version:Version="1.1"
+    <Provide-Capability>
+
+Bundles providing resources to the resource tree using the described mechanism 
should also require this capability to ensure at runtime that there is an 
implementation picking up those bundle resources. This can be done by using the 
following require capability header:
+
+    <Require-Capability>
+        
osgi.extender;filter:="(&(osgi.extender=org.apache.sling.bundleresource)(version<=1.1.0)(!(version>=2.0.0)))"
+    </Require-Capability>
+
+Without requiring the capability, the bundle containing the resources might 
resolve successfully but the resource are not part of the resource tree as 
there is no implementation picking them up.
 
+# WebConsole Plugin
 
 The Bundle Resource Provider also has a web console plugin through which the 
currently installed bundles can be seen.

-- 
To stop receiving notification emails like this one, please contact
cziege...@apache.org.

Reply via email to