Author: kwin
Date: Tue Feb 2 18:02:28 2016
New Revision: 1728165
URL: http://svn.apache.org/viewvc?rev=1728165&view=rev
Log:
SLING-3423 document the resource merger bundle and the two resource picker
implementations
Added:
sling/site/trunk/content/documentation/bundles/resource-merger.mdtext
Modified:
sling/site/trunk/content/documentation/bundles.mdtext
sling/site/trunk/content/documentation/the-sling-engine/resources.mdtext
Modified: sling/site/trunk/content/documentation/bundles.mdtext
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles.mdtext?rev=1728165&r1=1728164&r2=1728165&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/bundles.mdtext (original)
+++ sling/site/trunk/content/documentation/bundles.mdtext Tue Feb 2 18:02:28
2016
@@ -13,6 +13,7 @@ Title: Bundles
* [Accessing Filesystem Resources (org.apache.sling.fsresource)]({{
refs.accessing-filesystem-resources-extensions-fsresource.path }})
* [Bundle Resources (extensions.bundleresource)]({{
refs.bundle-resources-extensions-bundleresource.path }})
* [NoSQL Resource Providers (org.apache.sling.nosql)]({{
refs.nosql-resource-providers.path }})
+* [Resource Merger (org.apache.sling.resourcemerger)]({{
refs.resource-merger.path }})
## Users, Groups, Access, Permissions, ACLs on Resources
Added: sling/site/trunk/content/documentation/bundles/resource-merger.mdtext
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/resource-merger.mdtext?rev=1728165&view=auto
==============================================================================
--- sling/site/trunk/content/documentation/bundles/resource-merger.mdtext
(added)
+++ sling/site/trunk/content/documentation/bundles/resource-merger.mdtext Tue
Feb 2 18:02:28 2016
@@ -0,0 +1,121 @@
+Title: Resource Merger (org.apache.sling.resourcemerger)
+[TOC]
+
+
+# Introduction
+**This documentation only applies to versions >= 1.2 (due to major changes
done in [SLING-3423](https://issues.apache.org/jira/browse/SLING-3423))**
+
+The Resource Merger bundle provides two resource provider factories
+
+* `MergingResourceProvider` (only for reading)
+* `CRUDMergingResourceProvider` (for reading and writing)
+
+Those providers give access to virtual resources which provide a merged view
on multiple other resources.
+
+Each `MergedResourcePicker` service implementation in the system provides one
unique mount point/root path (usually starting with `/mnt`) exposing a view on
merged resources from at least two different locations.
+
+The exact merging mechanism depends on the resource picker implementation (see
below). The order of the merging is important as the overlying resource may
overwrite properties/child resources from the underlying resource (but not
vice-versa).
+It is possible to
+
+* remove existing resource/properties from the underlying resources,
+* modify existing properties/child resources of the underlying resources and
+* add new properties/child resources
+
+You may use any of the merge properties described below to influence the
merging behaviour. All those special properties are not exposed below the mount
point.
+
+The `CRUDMergingResourceProvider` not only gives read-access to the merged
resources but even allows to write. This provider always writes inside the
topmost resource path (being returned as last item by the resource picker).
Currently both resource pickers shipped with the Sling Resource Merger bundle
do not allow to write.
+
+
+# Merge Properties
+
+Property Name | Type | Description
+------------- | -------------
+sling:hideProperties | String[] | Allows to hide the properties with the given
names from the underlying resource. `*` hides all properties.
+sling:hideChildren| String[] | Allows to hide the child resources with the
given names from the underlying resource. `*` hides all child resources.
+sling:hideResource | Boolean | If `true` then the resource with the name which
contains this property should not be exposed!
+sling:orderBefore | String | Contains the name of the preceeding sibling
resource. This order is considered when calling e.g. `Resource.listChildren()`
or `Resource.getChildren()` on the merged resource.
+
+# Resource Pickers
+
+## Merging Resource Picker (Overlay approach)
+
+Description | Merged Resource Path | Merging Order | Read-Only | Related Ticket
+------------- | -------------
+Merging based on the resource resolver's search path | `/mnt/overlay/<relative
resource path>` | Last resource resolver search path first (Order = Descending
search paths). | `true` |
[SLING-2986](https://issues.apache.org/jira/browse/SLING-2986)
+
+This picker is thought for globally overlaying content by placing the
diff-resource in "/apps" without actually touching anything in "/libs" (since
this is only thought for Sling itself). This should be used whenever some
deviation of content is desired which is initially shipped with Sling. The
client (i.e. the code using the merged resource) does not have to know if there
is an overlay in place.
+
+
+### Example
+
+ /libs/sling/example (nt:folder)
+ +-- sling:resourceType = "some/resource/type"
+ +-- child1 (nt:folder)
+ | +-- property1 = "property from /libs/sling/example/child1"
+ +-- child2 (nt:folder)
+ | +-- property1 = "property from /libs/sling/example/child2"
+ +-- child3 (nt:folder)
+ | +-- property1 = "property from /libs/sling/example/child3"
+
+
+ /apps/sling/example (sling:Folder)
+ +-- property1 = "property added in apps"
+ +-- child1 (nt:folder)
+ | +-- sling:hideResource = true
+ +-- child2 (nt:folder)
+ | +-- property1 = "property from /apps/sling/example/child2"
+ +-- child3 (nt:folder)
+ | +-- property2 = "property from /apps/sling/example/child3"
+
+
+ /mnt/overlay/sling/example (sling:Folder)
+ +-- sling:resourceType = "some/resource/type"
+ +-- property1 = "property added in apps"
+ +-- child2 (nt:folder)
+ | +-- property1 = "property from /apps/sling/example/child2"
+ +-- child3 (nt:folder)
+ | +-- property1 = "property from /libs/sling/example/child3"
+ | +-- property2 = "property from /apps/sling/example/child3"
+
+
+
+## Overriding Resource Picker (Override approach)
+
+Description | Merged Resource Path | Merging Order | Read-Only | Related Ticket
+------------- | -------------
+Merging based on the `sling:resourceSuperType` | `/mnt/override/<absolute
resource type>` | The topmost resource type (having itself no
`sling:resourceSuperType` defined) is the base. The resources are overlaid in
the order from the most generic one to the most specific one (which is the one
having the most inheritance levels). | `true` |
[SLING-3675](https://issues.apache.org/jira/browse/SLING-3657)
+
+This picker is thought for extending content of another already existing
resource (which should not be modified). The client (i.e. the code using the
merged resource) must directly reference the most specific resource type (i.e.
it must be aware of the sub resource type).
+
+### Example
+
+ /apps/sling/base (nt:folder)
+ +-- child1 (nt:folder)
+ | +-- property1 = "property from /libs/sling/example/child1"
+ +-- child2 (nt:folder)
+ | +-- property1 = "property from /libs/sling/example/child2"
+ +-- child3 (nt:folder)
+ | +-- property1 = "property from /libs/sling/example/child3"
+
+
+ /apps/sling/example (sling:Folder)
+ +-- sling:resourceSuperType = "/apps/sling/base"
+ +-- property1 = "property added in /apps/sling/example"
+ +-- child1 (nt:folder)
+ | +-- sling:hideResource = true
+ +-- child2 (nt:folder)
+ | +-- property1 = "property from /apps/sling/example/child2"
+ +-- child3 (nt:folder)
+ | +-- property2 = "property from /apps/sling/example/child3"
+
+
+ /mnt/overlay/apps/sling/example (sling:Folder)
+ +-- sling:resourceSuperType = "/apps/sling/base"
+ +-- property1 = "property added in /apps/sling/example"
+ +-- child2 (nt:folder)
+ | +-- property1 = "property from /apps/sling/example/child2"
+ +-- child3 (nt:folder)
+ | +-- property1 = "property from /libs/sling/example/child3"
+ | +-- property2 = "property from /apps/sling/example/child3"
+
+
Modified:
sling/site/trunk/content/documentation/the-sling-engine/resources.mdtext
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/the-sling-engine/resources.mdtext?rev=1728165&r1=1728164&r2=1728165&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/the-sling-engine/resources.mdtext
(original)
+++ sling/site/trunk/content/documentation/the-sling-engine/resources.mdtext
Tue Feb 2 18:02:28 2016
@@ -126,6 +126,12 @@ The Filesystem Resource Provider provide
For details see [File System Resources]({{
refs.accessing-filesystem-resources-extensions-fsresource.path }}).
+### Merged Resources
+
+The merged resource provider exposes a view on merged resources from multiple
locations.
+
+For details see [Resource Merger]({{ refs.resource-merger.path }}).
+
### Custom Resource providers
Custom ResourceProvider services can be used to integrate your own custom
resources in the Sling resource tree.
