You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by bd...@apache.org on 2017/09/26 10:57:43 UTC
[2/2] sling-site git commit: Resync content with svn revision 1809724
Sling-query pages need work.
Resync content with svn revision 1809724
Sling-query pages need work.
The following staged pages are affected:
https://sling.apache.org/ng/documentation/bundles/content-distribution.html
https://sling.apache.org/ng/documentation/bundles/content-loading-jcr-contentloader.html
https://sling.apache.org/ng/documentation/bundles/discovery-api-and-impl.html
https://sling.apache.org/ng/documentation/bundles/jcr-installer-provider.html
https://sling.apache.org/ng/documentation/bundles/models.html
https://sling.apache.org/ng/documentation/bundles/org-apache-sling-junit-bundles.html
https://sling.apache.org/ng/documentation/bundles/repository-initialization.html
https://sling.apache.org/ng/documentation/bundles/resource-merger.html
https://sling.apache.org/ng/documentation/bundles/scheduler-service-commons-scheduler.html
https://sling.apache.org/ng/documentation/bundles/sling-pipes.html
https://sling.apache.org/ng/documentation/bundles/sling-query.html
https://sling.apache.org/ng/documentation/bundles/sling-query/basic-ideas.html
https://sling.apache.org/ng/documentation/bundles/sling-query/examples.html
https://sling.apache.org/ng/documentation/bundles/sling-query/hierarchy-operators.html
https://sling.apache.org/ng/documentation/bundles/sling-query/methods.html
https://sling.apache.org/ng/documentation/bundles/sling-query/modifiers.html
https://sling.apache.org/ng/documentation/bundles/sling-query/operators.html
https://sling.apache.org/ng/documentation/bundles/sling-query/selectors.html
https://sling.apache.org/ng/documentation/bundles/sling-query/vs-jcr.html
https://sling.apache.org/ng/documentation/development/jsr-305.html
https://sling.apache.org/ng/documentation/development/release-management.html
https://sling.apache.org/ng/documentation/the-sling-engine/architecture.html
https://sling.apache.org/ng/documentation/the-sling-engine/service-authentication.html
https://sling.apache.org/ng/documentation/tutorials-how-tos/46-line-blog.html
https://sling.apache.org/ng/news.html
https://sling.apache.org/ng/old-stuff/scriptengineintegration/groovy-support.html
https://sling.apache.org/ng/old-stuff/scriptengineintegration/xslt-processing-pipeline.html
Project: http://git-wip-us.apache.org/repos/asf/sling-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/sling-site/commit/e7c2d03c
Tree: http://git-wip-us.apache.org/repos/asf/sling-site/tree/e7c2d03c
Diff: http://git-wip-us.apache.org/repos/asf/sling-site/diff/e7c2d03c
Branch: refs/heads/master
Commit: e7c2d03cd76da00ba8683d569182d627832545f8
Parents: d65a41d
Author: Bertrand Delacretaz <bd...@apache.org>
Authored: Tue Sep 26 12:56:47 2017 +0200
Committer: Bertrand Delacretaz <bd...@apache.org>
Committed: Tue Sep 26 12:56:47 2017 +0200
----------------------------------------------------------------------
.../bundles/content-distribution.md | 53 ++-
.../content-loading-jcr-contentloader.md | 35 ++
.../bundles/discovery-api-and-impl.md | 4 +-
.../bundles/jcr-installer-provider.md | 18 +-
.../content/documentation/bundles/models.md | 48 ++-
.../bundles/org-apache-sling-junit-bundles.md | 2 +-
.../bundles/repository-initialization.md | 21 +
.../documentation/bundles/resource-merger.md | 12 +-
.../scheduler-service-commons-scheduler.md | 6 +-
.../documentation/bundles/sling-pipes.md | 394 +++++++++----------
.../documentation/bundles/sling-query.md | 19 +-
.../bundles/sling-query/basic-ideas.md | 75 ++++
.../bundles/sling-query/examples.md | 59 +++
.../bundles/sling-query/hierarchy-operators.md | 37 ++
.../bundles/sling-query/methods.md | 184 +++++++++
.../bundles/sling-query/modifiers.md | 61 +++
.../bundles/sling-query/operators.md | 47 +++
.../bundles/sling-query/selectors.md | 67 ++++
.../documentation/bundles/sling-query/vs-jcr.md | 17 +
.../documentation/development/jsr-305.md | 6 +-
.../development/release-management.md | 7 +
.../the-sling-engine/architecture.md | 2 +-
.../the-sling-engine/service-authentication.md | 14 +-
.../tutorials-how-tos/46-line-blog.md | 14 +-
src/main/jbake/content/news.md | 36 +-
.../scriptengineintegration/groovy-support.md | 10 +-
.../xslt-processing-pipeline.md | 10 +-
27 files changed, 992 insertions(+), 266 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/sling-site/blob/e7c2d03c/src/main/jbake/content/documentation/bundles/content-distribution.md
----------------------------------------------------------------------
diff --git a/src/main/jbake/content/documentation/bundles/content-distribution.md b/src/main/jbake/content/documentation/bundles/content-distribution.md
index 21f1445..a9bf6e8 100644
--- a/src/main/jbake/content/documentation/bundles/content-distribution.md
+++ b/src/main/jbake/content/documentation/bundles/content-distribution.md
@@ -36,6 +36,13 @@ A forward distribution setup allows one to transfer content from a source instan
org.apache.sling.distribution.packaging.impl.importer.LocalDistributionPackageImporterFactory-default
name="default"
+#### Trigger forward distribution
+
+Forward distribution can be triggered by sending a `POST` HTTP request to the agent resource on the source instance with the parameter `action=ADD` and parameters `path=<resourcePath>`.
+
+The example below distributes the path `/content/sample1`
+
+ $ curl -v -u admin:admin http://localhost:8080/libs/sling/distribution/services/agents/publish -d 'action=ADD' -d 'path=/content/sample1'
### Reverse distribution
@@ -66,6 +73,13 @@ A reverse distribution setup allows one to transfer content from a farm of sourc
agent.target="(name=reverse)"
+#### Trigger reverse distribution
+
+Reverse distribution can be triggered by sending a `POST` HTTP request to the agent resource on the target instance with the parameter `action=PULL`.
+
+The example below adds the the path `/content/sample1` and then reverse distribute it.
+
+ $ curl -v -u admin:admin http://localhost:8081/libs/sling/distribution/services/agents/publish -d 'action=PULL' -d 'path=/content/sample1'
### Sync distribution
@@ -164,11 +178,42 @@ A multidatacenter sync distribution setup allows one to synchronize content in a
## Additional options
-### How to trigger distribution over HTTP?
-
### How to configure binary-less distribution?
-### How to configure priority paths?
+Binary-less distribution is supported for deployments over a shared data store and involving agents that leverage the
+Vault based Distribution package exporter (Factory PID:
+org.apache.sling.distribution.serialization.impl.vlt.VaultDistributionPackageBuilderFactory) package builder.
+
+With binary-less mode enabled, the content packages distributed contain references to binaries rather than
+the actual binaries.
+
+SCD does not explicitly deal with binary references. Instead, it configures Apache Jackrabbit FileVault
+export options in order to assemble/import binary references.
+
+Upon import, if a referenced binary is not visible on the destination instance, SCD will retry distributing the content package
+after a delay has elapsed.
+
+Binary-less is configured by setting the 'useReferences' to true on the VaultDistributionPackageBuilderFactory.
+
+### How to configure priority queue?
+
+SCD agents allow to prioritize the distribution of content depending on its path.
+This feature improves the delays in use cases where a subset of the content to be distributed must meet tighter delay
+than the remaining one (e.g. news flash).
+
+Each agent can be configured with one or more priority queues.
+
+In order to setup the priority queues, configure the 'priorityQueues' agent property by providing the queuePrefix and path regular expression.
+
+### How to configure retry strategy?
+
+The agent behaviour upon failed distribution request can be configured via the Retry Strategy 'retry.strategy' and
+'retry.attempts' properties.
-### How to configure error queues?
+With the 'none' strategy, an agent will retry distributing an item forever, blocking the queue until the distribution succeeds.
+The 'none' strategy guarantees the distribution order but may block the queue until someone resolves the situation.
+With the 'errorQueue' strategy, an agent will automatically create an additional error queue. The agent will
+retry up to 'retry.attempts' attempts then move the failed item to the error queue. The error queue is passive and allow
+to keep track of the failed distribution item for post analysis.
+The 'errorQueue' strategy does not guarantee the distribution order, but it guarantee that the queue is stuck for a bounded number of retries.
http://git-wip-us.apache.org/repos/asf/sling-site/blob/e7c2d03c/src/main/jbake/content/documentation/bundles/content-loading-jcr-contentloader.md
----------------------------------------------------------------------
diff --git a/src/main/jbake/content/documentation/bundles/content-loading-jcr-contentloader.md b/src/main/jbake/content/documentation/bundles/content-loading-jcr-contentloader.md
index 5ddfec4..de98810 100644
--- a/src/main/jbake/content/documentation/bundles/content-loading-jcr-contentloader.md
+++ b/src/main/jbake/content/documentation/bundles/content-loading-jcr-contentloader.md
@@ -217,6 +217,12 @@ Nodes, Properties and in fact complete subtrees may be described in JSON files u
By default, the `sling-jcr-contentloader` bundle tries to extract certain file types during content loading. These include `json`, `xml`, `zip`, and `jar` files. Therefore all available extractors are used for content processing. However if some files should be put into the repository unextracted, the `ignoreImportProviders` directive can be used with a comma separated list of extensions that should not be extracted, like `ignoreImportProviders:="jar,zip"`. Please note that the value needs to be put into quotation marks if more than one value is used like in the example.
+### File name escaping
+
+When the node name you want to import with the JCR ContentLoader contains characters that are not allowed in typical file systems (e.g. a ":" is not allowed on windows file systems), you can URL-encode the file name. It uses the [Java URLDecoder](https://docs.oracle.com/javase/8/docs/api/java/net/URLDecoder.html) internally.
+
+Example: `jcr%3Acontent.txt` will be loaded into a node named `jcr:content.txt`.
+
### Workspace Targetting
By default, initial content will be loaded into the default workspace. To override this, add a `Sling-Initial-Content-Workspace` bundle manifest header to specify the workspace. Note that *all* content from a bundle will be loaded into the same workspace.
@@ -278,4 +284,33 @@ The initial content found in the [sling-test folder of the launchpad initial con
Those tests can be used as verified examples of initial content loading. Contributions are welcome to improve the coverage of those tests.
+## ACLs and Principals
+
+By adding a `security:acl` object to a content node definition in JSON you can define an ACL for this node. For each array entry in this example an ACE is added. Example:
+
+ {
+ "security:acl": [
+ { "principal": "TestGroup1", "granted": ["jcr:read","jcr:write"] },
+ { "principal": "TestUser1", "granted": ["jcr:read"], "denied": ["jcr:write"] }
+ ]
+ }
+
+If ACLs already exist on the node you can add an `order` property to each array entry controlling the position where the new ACE is inserted into the list of existing ACEs. Possible values for this property:
+
+* **first**: Place the target ACE as the first amongst its siblings
+* **last**: Place the target ACE as the last amongst its siblings
+* **before xyz**: Place the target ACE immediately before the sibling whose name is xyz
+* **after xyz**: Place the target ACE immediately after the sibling whose name is xyz
+* **numeric**: Place the target ACE at the specified index
+
+You can also add new principals (users or groups) to the repository by adding a `security:principals` object. This is not related to any specific path/node, so you can add this JSON fragment anywhere. Example for creating one use and one group:
+
+ {
+ "security:principals": [
+ { "name": "TestUser1", "password": "mypassword", "extraProp1": "extraProp1Value" },
+ { "name": "TestGroup1", "isgroup": "true", "members": ["TestUser1"], "extraProp1": "extraProp1Value" }
+ ]
+ }
+
+
[i18n-json-file-based]: https://sling.apache.org/documentation/bundles/internationalization-support-i18n.html#json-file-based
http://git-wip-us.apache.org/repos/asf/sling-site/blob/e7c2d03c/src/main/jbake/content/documentation/bundles/discovery-api-and-impl.md
----------------------------------------------------------------------
diff --git a/src/main/jbake/content/documentation/bundles/discovery-api-and-impl.md b/src/main/jbake/content/documentation/bundles/discovery-api-and-impl.md
index e59fb99..9e7930b 100644
--- a/src/main/jbake/content/documentation/bundles/discovery-api-and-impl.md
+++ b/src/main/jbake/content/documentation/bundles/discovery-api-and-impl.md
@@ -334,8 +334,8 @@ The following properties can be configured (at [/system/console/configMgr/org.ap
2x the TTL, after which time the message will be ignored.
- [1]: http://localhost:8888/system/console/configMgr/org.apache.sling.discovery.impl.Config
- [2]: http://localhost:8888/system/console/topology
+ [1]: http://localhost:8080/system/console/configMgr/org.apache.sling.discovery.impl.Config
+ [2]: http://localhost:8080/system/console/topology
## discovery.oak: Oak-based, OOTB-implementation
http://git-wip-us.apache.org/repos/asf/sling-site/blob/e7c2d03c/src/main/jbake/content/documentation/bundles/jcr-installer-provider.md
----------------------------------------------------------------------
diff --git a/src/main/jbake/content/documentation/bundles/jcr-installer-provider.md b/src/main/jbake/content/documentation/bundles/jcr-installer-provider.md
index 84a9c55..f321a3c 100644
--- a/src/main/jbake/content/documentation/bundles/jcr-installer-provider.md
+++ b/src/main/jbake/content/documentation/bundles/jcr-installer-provider.md
@@ -54,15 +54,15 @@ We use `curl` to create content, to make it easy to reproduce the example by cop
By default, JCRInstall picks up bundles found in folders named *install* under `/libs` and `/apps`, so we start by creating such a folder:
- curl -X MKCOL http://admin:admin@localhost:8888/apps/jcrtest
- curl -X MKCOL http://admin:admin@localhost:8888/apps/jcrtest/install
+ curl -X MKCOL http://admin:admin@localhost:8080/apps/jcrtest
+ curl -X MKCOL http://admin:admin@localhost:8080/apps/jcrtest/install
And we copy the bundle to install in that folder (a backslash in command lines means *continued on next line*):
curl -T desktop_awt_all-2.0.0.jar \
- http://admin:admin@localhost:8888/apps/jcrtest/install/desktop_awt_all-2.0.0.jar
+ http://admin:admin@localhost:8080/apps/jcrtest/install/desktop_awt_all-2.0.0.jar
That's it. After 2-3 seconds, the bundle should be picked up by JCRInstall, installed and started. If this works you'll see a small *Knopflerfish Desktop* window on your desktop, and Sling's OSGi console can of course be used to check the details.
@@ -71,7 +71,7 @@ Removing the bundle from the repository will cause it to be uninstalled, so:
curl -X DELETE \
- http://admin:admin@localhost:8888/apps/jcrtest/install/desktop_awt_all-2.0.0.jar
+ http://admin:admin@localhost:8080/apps/jcrtest/install/desktop_awt_all-2.0.0.jar
Should cause the *Knopflerfish Desktop* window to disappear as the bundle is uninstalled.
@@ -86,13 +86,13 @@ Let's try this feature by creating a configuration with two properties:
curl \
-F "jcr:primaryType=sling:OsgiConfig" \
-F foo=bar -F works=yes \
- http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid
+ http://admin:admin@localhost:8080/apps/jcrtest/install/some.config.pid
And verify the contents of our config node:
curl \
- http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid.json
+ http://admin:admin@localhost:8080/apps/jcrtest/install/some.config.pid.json
Which should display something like
@@ -102,7 +102,7 @@ Which should display something like
"jcr:primaryType":"sling:OsgiConfig","works":"yes"}
-At this point, JCRInstall should have picked up our new config and installed it. The logs would confirm that, but we can also use the OSGi console's config status page (http://localhost:8888/system/console/config) to check it. That page should now contain:
+At this point, JCRInstall should have picked up our new config and installed it. The logs would confirm that, but we can also use the OSGi console's config status page (http://localhost:8080/system/console/config) to check it. That page should now contain:
PID=some.config.pid
@@ -120,7 +120,7 @@ Let's try modifying the configuration parameters:
curl \
-F works=updated -F even=more \
- http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid
+ http://admin:admin@localhost:8080/apps/jcrtest/install/some.config.pid
And check the changes in the console page:
@@ -139,7 +139,7 @@ We can now delete the configuration node:
curl -X DELETE \
- http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid
+ http://admin:admin@localhost:8080/apps/jcrtest/install/some.config.pid
And verify that the corresponding configuration is gone in the console page (after 1-2 seconds, like for all other JCRInstall operations).
http://git-wip-us.apache.org/repos/asf/sling-site/blob/e7c2d03c/src/main/jbake/content/documentation/bundles/models.md
----------------------------------------------------------------------
diff --git a/src/main/jbake/content/documentation/bundles/models.md b/src/main/jbake/content/documentation/bundles/models.md
index 988870f..da8ef8f 100644
--- a/src/main/jbake/content/documentation/bundles/models.md
+++ b/src/main/jbake/content/documentation/bundles/models.md
@@ -255,18 +255,37 @@ The `@PostConstruct` annotation can be used to add methods which are invoked upo
`@PostConstruct` methods in a super class will be invoked first.
+Since Sling Models Implementation 1.4.6, `@PostConstruct` methods may return a `false` boolean value in which case the model creation will fail without logging any exception
+(a message will be logged at the `DEBUG` level).
+
## Via
-If the injection should be based on a JavaBean property of the adaptable, you can indicate this using the `@Via` annotation:
+In some cases, a different object should be used as the adaptable instead of the original adaptable. This can be done
+using the `@Via` annotation. By default, this can be done using a JavaBean property of the adaptable:
::java
@Model(adaptables=SlingHttpServletRequest.class)
public interface MyModel {
- // will return request.getResource().adaptTo(ValueMap.class).get("propertyName", String.class)
+ // will return request.getResource().getValueMap().get("propertyName", String.class)
@Inject @Via("resource")
String getPropertyName();
}
+
+A different strategy can be used to define the adaptable by specifying a `type` attribute:
+
+ ::java
+ @Model(adaptables=Resource.class)
+ public interface MyModel {
+
+ // will return resource.getChild("jcr:content").getValueMap().get("propertyName", String.class)
+ @Inject @Via(value = "jcr:content", type = ChildResource.class)
+ String getPropertyName();
+
+ }
+
+See the [Via Types](#via-types-since-api-134implementation-140) section below for details on the included types for `@Via`.
+
## Source
If there is ambiguity where a given injection could be handled by more than one injector, the `@Source` annotation can be used to define which injector is responsible:
@@ -361,7 +380,7 @@ Injectors are invoked in order of their service ranking, from lowest to highest.
: methods to call upon model option creation (only for model classes)
`@Via`
-: use a JavaBean property of the adaptable as the source of the injection
+: change the adaptable as the source of the injection
`@Default`
: set default values for a field or method
@@ -522,3 +541,26 @@ If you want to generate a bundle header compliant with Sling Models < 1.3.4 (i.e
<_plugin>org.apache.sling.bnd.models.ModelsScannerPlugin;generatePackagesHeader=true</_plugin>
</instructions>
</configuration>
+
+# Via Types (Since API 1.3.4/Implementation 1.4.0)
+
+As discussed in the [Via](#via) section above, it is possible to select a different adaptable than the original value using the `@Via` annotation. The following standard types are provided (all types are in the package `org.apache.sling.models.annotations.via`)
+
+`@Via` type value | Description
+----------------------------- | ------------------------------
+`BeanProperty` (default) | Uses a JavaBean property from the adaptable.
+`ChildResource` | Uses a child resource from the adaptable, assuming the adaptable is a `Resource`.
+`ForcedResourceType` | Creates a wrapped resource with the provided resource type. If the adaptable is a `SlingHttpServletRequest`, a wrapped request is created as well to contain the wrapped resource.
+`ResourceSuperType` | Creates a wrapped resource with the resource type set to the adaptable's resource super type. If the adaptable is a `SlingHttpServletRequest`, a wrapped request is created as well to contain the wrapped resource.
+
+## Custom Via Type
+
+Defining your own type for the `@Via` annotation is a two step process. The first step is to create a marker class implementing the `@ViaProviderType` annotation. This class can be entirely empty, e.g.
+
+ ::java
+ public class MyCustomProviderType implements ViaProviderType {}
+
+The second step is to create an OSGi service implementing the `ViaProvider` interface. This interface defines two methods:
+
+* `getType()` should return the marker class.
+* `getAdaptable()` should return the new adaptable or `ViaProvider.ORIGINAL` to indicate that the original adaptable should be used.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/sling-site/blob/e7c2d03c/src/main/jbake/content/documentation/bundles/org-apache-sling-junit-bundles.md
----------------------------------------------------------------------
diff --git a/src/main/jbake/content/documentation/bundles/org-apache-sling-junit-bundles.md b/src/main/jbake/content/documentation/bundles/org-apache-sling-junit-bundles.md
index b99d32c..1e88fc7 100644
--- a/src/main/jbake/content/documentation/bundles/org-apache-sling-junit-bundles.md
+++ b/src/main/jbake/content/documentation/bundles/org-apache-sling-junit-bundles.md
@@ -160,7 +160,7 @@ The following customizers are currently used in Sling
The provisioning of an appropriate instance can be done with the [slingstart-maven-plugin](/documentation/development/slingstart.html). An example for that is given at [`testing/samples/module-with-it`](https://svn.apache.org/viewvc/sling/trunk/testing/samples/module-with-it). Since `slingstart-maven-plugin` 1.5.0 it is possible to bootstrap a Sling Server from a `model.txt` below `src/test/provisioning` independent of the packaging (see [SLING-6068](https://issues.apache.org/jira/browse/SLING-6068)).
#### LaunchpadCustomizer ####
-The *[`LaunchpadCustomizer.java`](https://svn.apache.org/repos/asf/sling/trunk/launchpad/integration-tests/src/main/java/org/apache/sling/junit/teleporter/customizers/LaunchpadCustomizer.java)* only verifies that a Sling instance is ready at a given port and configures the `ClientSideTeleporter` to deploy to `http://localhost:8888` with the credentials `admin`:`admin`. `LaunchpadCustomizer` uses the `HttpTestBase` therefore some parameters are customizable through system properties. There is no bootstrapping of an instance done here, so this must be done separately!
+The *[`LaunchpadCustomizer.java`](https://svn.apache.org/repos/asf/sling/trunk/launchpad/integration-tests/src/main/java/org/apache/sling/junit/teleporter/customizers/LaunchpadCustomizer.java)* only verifies that a Sling instance is ready at a given port and configures the `ClientSideTeleporter` to deploy to `http://localhost:8080` with the credentials `admin`:`admin`. `LaunchpadCustomizer` uses the `HttpTestBase` therefore some parameters are customizable through system properties. There is no bootstrapping of an instance done here, so this must be done separately!
#### BWIT_TeleporterCustomizer ####
The *[`BWIT_TeleporterCustomizer.java`](http://svn.apache.org/viewvc/sling/trunk/testing/samples/bundle-with-it/src/test/java/org/apache/sling/junit/teleporter/customizers/BWIT_TeleporterCustomizer.java)* relies on `SlingTestBase` to set the server's base url and credentials. Additionally the test bundle is adjusted so that the API is not included in it (but rather referenced from another bundle). The bootstrapping of the Sling instance is tweaked through system properties which are desribed [here](http://labs.6dglobal.com/blog/2013-06-05/creating-integration-tests-apache-sling/) and implicitly done by the customizer itself.
http://git-wip-us.apache.org/repos/asf/sling-site/blob/e7c2d03c/src/main/jbake/content/documentation/bundles/repository-initialization.md
----------------------------------------------------------------------
diff --git a/src/main/jbake/content/documentation/bundles/repository-initialization.md b/src/main/jbake/content/documentation/bundles/repository-initialization.md
index a9edf80..d7c2f48 100644
--- a/src/main/jbake/content/documentation/bundles/repository-initialization.md
+++ b/src/main/jbake/content/documentation/bundles/repository-initialization.md
@@ -54,6 +54,15 @@ The language is self-explaining but please refer to the actual test cases for de
# Nodetypes inside the path apply to just that path element
create path /content/example.com(sling:Folder)
+
+ # Nodetypes and mixins applied to just a path element
+ # Specifying mixins require
+ # o.a.s.repoinit.parser 1.2.0 and
+ # o.a.s.jcr.repoinit 1.2.0
+ create path /content/example.com(sling:Folder mixin mix:referenceable,mix:shareable)
+
+ # Mixins applied to just a path element
+ create path /content/example.com(mixin mix:referenceable)
# A nodetype in front is used as the default for all path elements
create path (nt:unstructured) /var
@@ -72,6 +81,14 @@ The language is self-explaining but please refer to the actual test cases for de
allow jcr:modifyProperties on /apps restriction(rep:ntNames,sling:Folder,nt:unstructured) restriction(rep:itemNames,prop1,prop2)
allow jcr:addChildNodes on /apps,/content restriction(rep:glob,/cat/*,*/cat,*cat/*)
end
+
+ # Set repository level ACL
+ # Setting repository level ACL require
+ # o.a.s.repoinit.parser 1.2.0 and
+ # o.a.s.jcr.repoinit 1.2.0
+ set repository ACL for alice,bob
+ allow jcr:namespaceManagement,jcr:nodeTypeDefinitionManagement
+ end
# register namespace requires
# o.a.s.repoinit.parser 1.0.4
@@ -98,6 +115,10 @@ The language is self-explaining but please refer to the actual test cases for de
create user demoUser with password {SHA-256} dc460da4ad72c482231e28e688e01f2778a88ce31a08826899d54ef7183998b5
+ # disable service user
+ create service user deprecated_service_user
+ disable service user deprecated_service_user : "Disabled user to make an example"
+
create service user the-last-one
## Providing repoinit statements from the Sling provisioning model or other URLs
http://git-wip-us.apache.org/repos/asf/sling-site/blob/e7c2d03c/src/main/jbake/content/documentation/bundles/resource-merger.md
----------------------------------------------------------------------
diff --git a/src/main/jbake/content/documentation/bundles/resource-merger.md b/src/main/jbake/content/documentation/bundles/resource-merger.md
index 9c4c207..2474b82 100644
--- a/src/main/jbake/content/documentation/bundles/resource-merger.md
+++ b/src/main/jbake/content/documentation/bundles/resource-merger.md
@@ -36,27 +36,27 @@ Property Name | Type | Description
sling:hideProperties | String[] | Hides the properties with the given names. `*` hides all properties (since version 1.3.2 the wildcard only affects underlying properties and no longer local ones, see also [SLING-5468](https://issues.apache.org/jira/browse/SLING-5468)).
sling:hideChildren| String[] | Hides the child resources with the given names. `*` hides all child resources (since version 1.3.2 the wildcard only affects underlying child resources and no longer local ones, see also [SLING-5468](https://issues.apache.org/jira/browse/SLING-5468)). If one value starts with `!` this is a negation (which means the property with the given value should not be hidden). Since by default nothing is hidden the negation is only useful if you specify multiple values for this property. E.g. giving the values `[!child1,*]` hides all children except for the one with the name `child1`. If you have a resource name starting with `!` you must escape it with an additional `!` in front if you want to reference it in `sling:hideChildren`, e.g. `!!child1` means that the resource with the name `!child1` should be hidden.
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 is influencing the order of resources when calling e.g. `Resource.listChildren()` or `Resource.getChildren()` on the merged resource. This is only necessary if the default resource order is not sufficient (see below).
+sling:orderBefore | String | Contains the name of the preceding sibling resource. This is influencing the order of resources when calling e.g. `Resource.listChildren()` or `Resource.getChildren()` on the merged resource. This is only necessary if the default child resource order is not sufficient (see below).
# Child Resource Order
For a merged resource the order of its child resources is the following:
-First the ones from the base resource, then the ones from the overlaying resources. The children only defined by the topmost resource come last.
+First the ones from the underlying resource, then the ones from the overlying resources.
-In case the same child is defined in more than one resource, its position is taken from the highest overlaying resource (since version 1.3.2, see also [SLING-4915](https://issues.apache.org/jira/browse/SLING-4915)).
+In case the same child is defined in more than one resource, its position is taken from the highest overlaying resource (since version 1.3.2, see also [SLING-4915](https://issues.apache.org/jira/browse/SLING-4915), for some more examples for more complicated merges look at [SLING-6956](https://issues.apache.org/jira/browse/SLING-6956)).
For example:
base/
+--child1
- +--child2
+--child3
+ +--child5
overlay/
- +--child4
+--child2
+--child3
+ +--child4
- resulting order: child1, child4, child2, child3
+ resulting order: child1, child5, child2, child3, child4
You can overwrite that behaviour by leveraging the `sling:orderBefore` property.
http://git-wip-us.apache.org/repos/asf/sling-site/blob/e7c2d03c/src/main/jbake/content/documentation/bundles/scheduler-service-commons-scheduler.md
----------------------------------------------------------------------
diff --git a/src/main/jbake/content/documentation/bundles/scheduler-service-commons-scheduler.md b/src/main/jbake/content/documentation/bundles/scheduler-service-commons-scheduler.md
index d3c885b..82f02ae 100644
--- a/src/main/jbake/content/documentation/bundles/scheduler-service-commons-scheduler.md
+++ b/src/main/jbake/content/documentation/bundles/scheduler-service-commons-scheduler.md
@@ -13,9 +13,11 @@ The notion of Job used in this context is a different one than the one used for
The following examples show you how to define and schedule a job by leveraging the whiteboard pattern.
-### Scheduling with a cron expression
+### Scheduling with a cron expression
+
+The cron expression format is described in the [Quartz Cron Documentation](http://www.quartz-scheduler.org/documentation/quartz-2.x/tutorials/crontrigger.html#format) and requires either 6 or 7 fields separated by white space. The first field always indicates the second (not the minute).
-The following job is executed every minute by setting *scheduler.expression* to the cron expression *"0 * * * * ?"*:
+The following job is executed every minute by setting *scheduler.expression* to the cron expression `0 * * * * ?`:
package sling.docu.examples;
http://git-wip-us.apache.org/repos/asf/sling-site/blob/e7c2d03c/src/main/jbake/content/documentation/bundles/sling-pipes.md
----------------------------------------------------------------------
diff --git a/src/main/jbake/content/documentation/bundles/sling-pipes.md b/src/main/jbake/content/documentation/bundles/sling-pipes.md
index 3b19556..3e5de58 100644
--- a/src/main/jbake/content/documentation/bundles/sling-pipes.md
+++ b/src/main/jbake/content/documentation/bundles/sling-pipes.md
@@ -3,13 +3,14 @@ type=page
status=published
~~~~~~
-tool for doing extract - transform - load operations through a resource tree configuration.
+tool set for doing extract - transform - load operations by chaining proven code bits.
often one-shot data transformations need sample code to be written & executed. This tiny tool set intends to provide ability to do such transformations with proven & reusable blocks called pipes, streaming resources from one to the other.
## What is a pipe
getOutputBinding
+
^
|
getInput +---+---+ getOutput
@@ -20,21 +21,22 @@ often one-shot data transformations need sample code to be written & executed. T
A sling pipe is essentially a sling resource stream:
-- it provides an output as a sling resource iterator
-- it gets its input either from a configured path, either, if its chained (see container pipes below), from another pipe's output
-- each pipe can have additional dynamic inputs using other's bindings, and outputing its own bindings
+- it provides an output as a sling resource iterator,
+- it gets its input either from a configured path, either from former pipe's output,
+- each pipe can have contextual inputs using any other pipe's bindings, and outputting its own bindings
At this moment, there are 3 types of pipes to consider:
- "reader" pipes, that will just output a set of resource depending on the input
-- "writer" pipes, that write to the repository, depending on configuration and output
+- "writer" pipes, that modify the repository, depending on configuration and input
- "container" pipes, that contains pipes, and whose job is to chain their execution : input is the input of their first pipe,
output is the output of the last pipe it contains.
-A `Plumber` osgi service is provided to help getting & executing pipes.
+A `Plumber` osgi service is provided to help getting, building & executing pipes.
-## Registered Pipes
-a pipe configuration is a jcr node, with:
+## How to configure & execute a pipe
+
+A pipe configuration is ultimately a jcr node, with properties (varying a lot depending on the pipe type):
- `sling:resourceType` property, which must be a pipe type registered by the plumber
- `name` property, that will be used in bindings as an id, and will be the key for the output bindings (default value being a value map of the current output resource). Note that the node name will be used in case no name is provided.
@@ -44,46 +46,148 @@ a pipe configuration is a jcr node, with:
- `additionalScripts` is a multi value property to declare scripts that can be reused in expressions
- `conf` optional child node that contains addition configuration of the pipe (depending on the type)
+This configuration can be generated quickly through Pipe Builder API.
+
+Once configuration is done, it's possible to execute Pipes
+
+- through plain java, with configured pipe resource as parameter,
+- through PipeBuilder API,
+- through HTTP API with GET (read) or POST (read/write) methods against configured pipe resource
+
+### Pipe Builder API
+Plumber can provider a PipeBuilder with `newPipe(ResourceResolver resolver)` API, that gives a fluent
+API to quickly configure and run pipes.
+e.g.
+
+ plumber.newPipe(resolver).xpath('//element(*,nt:unstructured)[@sling:resourceType='to/delete']").rm().run();
+
+will search for resource of type `to/delete` and remove them.
+
+PipeBuilder basically will automatically configure a container pipe, chaining pipes you can configure
+ with a fluent API:
+
+- `pipe(type)` generate a new subpipe,
+- `with(Object...)` add to actual subpipe configuration node key/value configurations,
+- `expr(String)` add an expression configuration
+- `path(String)` add an input path,
+- `name(String)` specify a name (there would be a default one, named 'one', 'two', ... depending on the position otherwise),
+- `conf(Object...)` add an extra configuration node with key/value properties/values
+
+note that that configuration part has shortcuts for some pipes. Typically, above sample is a shorter equivalent of
+
+ plumber.newPipe(resolver).pipe('slingPipes/xpath').expr('//element(*,nt:unstructured)[@sling:resourceType='to/delete']").pipe('slingPipes/rm').run();
+
+when available, shortcuts will be specified next to each pipe type documentation.
+
+Once you are happy with the pipe you have created, you can terminate the builder with following command:
+
+- `build()` will build the pipe under /var/pipes/... (random node under timed base path),
+- `run(bindings)` will build the pipe, and run it with additional `bindings`,
+- `runAsync(bindings)` will do the same, but asynchronously,
+- `run()` will build & run synchronously the pipe, with no bindings.
+
+### HTTP API
+##### Request Path
+
+- either you'll need to create a slingPipes/plumber resource, say `etc/pipes` and then to execute
+
+ curl -u admin:admin -F "path=/etc/pipes/mySamplePipe" http://localhost:8080/etc/pipes.json
+
+- either you execute the request directly on the pipe Path, e.g.
+
+ curl -u admin:admin http://localhost:8080/etc/pipes/mySamplePipe.json
+
+which will return you the path of the resources that have been through the output of the configured pipe.
+
+In the eventuality of a long execution (synchronous or asynchronous), you can retrieve the status of a pipe, by executing
+
+ GET /etc/pipes/mySamplePipe.status.json
+
+##### Request Parameter `binding`
+
+you can add as `bindings` parameter a json object of global bindings you want to add for the execution of the pipe
+
+e.g.
+
+
+ curl -u admin:admin -F "path=/etc/pipes/test" -F "bindings={testBinding:'foo'}" http://localhost:4502/etc/pipes.json
+
+
+will returns something like
+
+ {"size":2, "items":["/one/output/resource", "another/one"]}
+
+##### Request Parameter `writer`
+
+you can configure output of your servlet, with `writer` parameter, a json object as a pattern to the result you want to have. The values of the json
+object are expressions and can reuse each pipe's subpipe binding.
+
+e.g.
+
+ curl -u admin:admin http://localhost:4502/etc/pipes/users.json?writer={"user":"${user.fullName}"}
+
+will returns something similar to
+
+ {"size":2, "items":[{'user':'John Smith','path':'/home/users/q/q123jk1UAZS'},{'user':'John Doe','path':'/home/users/q/q153jk1UAZS'}]}
+
+##### Request Parameter `dryRun`
+if parameter dryRun is set to true, and the executed pipe is supposed to modify content, it will log (at best it can) the change it *would* have done, without doing anything
+
+##### Request Parameter `size`
+default response is truncated to 10 items, if you need more (or less), you can modify that settings with the size parameter
+
+##### Request Parameter `async`
+allow asynchronous execution of the given type. This is advised in case you plan your pipe execution to last longer than the session of your HTTP client.
+If used, the returned value will be id of the created sling Job.
+In that case you can monitor the pipes path with `status` selector as described above until it has the value `finished`.
+
+## Registered Pipes
+
### readers
-#### Base pipe
-rather dummy pipe, outputs what is in input (so what is configured in path). Handy for doing some test mostly, and giving basic functionalities to others that inherit from it
+##### Base pipe `echo(path)`
+outputs what is in input (so what is configured in path)
- `sling:resourceType` is `slingPipes/base`
-#### SlingQuery Pipe
+##### SlingQuery Pipe (`$(expr)`)
executes $(getInput()).children(expression)
- `sling:resourceType` is `slingPipes/slingQuery`
- `expr` mandatory property, contains slingQuery expression through which getInput()'s children will be computed to getOutput()
-#### JsonPipe
-feeds bindings with remote json
-
-- `sling:resourceType` is `slingPipes/json`
-- `expr` mandatory property contains url that will be called, the json be sent to the output bindings, getOutput = getInput.
-An empty url or a failing url will block the pipe at that given place.
-
-#### MultiPropertyPipe
+##### MultiPropertyPipe
iterates through values of input multi value property and write them to bindings
- `sling:resourceType` is `slingPipes/multiProperty`
- `path` should be the path of a mv property
-#### XPathPipe
+##### XPathPipe (`xpath(expr)`)
retrieve resources resulting of an xpath query
- `sling:resourceType` is `slingPipes/xpath`
- `expr` should be a valid xpath query
-### JsonPipe
+##### TraversePipe (`traverse()`)
+traverse current input resource's tree, outputing, as resources, either the node of the tree, either its properties
+
+- `sling:resourceType` is `slingPipes/traverse`,
+- `breadthFirst` the tree visit will be done deep first, unless this flag is set to true,
+- `depth` max depth the visit should go to,
+- `properties` is a flag mentioning the pipe should traverse node's property,
+- `nameGlobs` filters the property that should get outputed
+
+##### JsonPipe (`json(expr)`)
feeds bindings with remote json
- `sling:resourceType` is `slingPipes/json`
- `expr` mandatory property contains url that will be called, the json be sent to the output bindings, getOutput = getInput.
An empty url or a failing url will block the pipe at that given place.
-#### AuthorizablePipe
+In case the json is an array, the pipe will loop over
+the array elements, and output each one in the binding. Output resource remains each time the input one.
+
+##### AuthorizablePipe (`auth(conf)`)
retrieve authorizable resource corresponding to the id passed in expression, or if not found (or void expression),
from the input path, output the found authorizable's resource
@@ -94,27 +198,43 @@ from the input path, output the found authorizable's resource
- `addToGroup` (expression) add found authorizable to instanciated group (in that case, considered as a write pipe)
- `bindMembers` (boolean) if found authorizable is a group, bind the members (in that case, considered as a write pipe)
-#### ParentPipe
+##### ParentPipe (`parent()`)
outputs the parent resource of input resource
+
- `sling:resourceType` is `slingPipes/parent`
-#### FilterPipe
+##### FilterPipe (`grep(conf)`)
outputs the input resource if its matches its configuration
- `sling:resourceType` is `slingPipes/filter`
- `conf` node tree that will be tested against the current input of the pipe, each `/conf/sub@prop=value` will triggers a test
on `./sub@prop` property of the current input, testing if its value matches `value` regex. If the special `slingPipesFilter_noChildren=${true}`
property is there with the value instantiated as a true boolean, then filter will pass if corresponding node has no children.
+- `slingPipesFilter_test='${...}'` evaluates the property value, and filters out the stream if the expression is not a boolean or false
- `slingPipesFilter_not='true'` inverts the expected result of the filter
+
+as an example,
+
+ echo('/content/foo').grep('foo','bar','slingPipesFilter_not',true).run()
+
+will either return `/content/foo` either nothing depending on it
+not containing `@foo=bar`
+
+ echo('content/foo').name('FOO').grep('slingPipesFilter_test','${FOO.foo == "bar"}').run()
+
+is an equivalent
+
### containers
-#### Container Pipe
+##### Container Pipe
assemble a sequence of pipes
- `sling:resourceType` is `slingPipes/container`
- `conf` node contains child pipes' configurations, that will be configured in the order they are found (note you should use sling:OrderedFolder)
-#### ReferencePipe
+Note that pipe builder api automatically creates one for you to chain the subpipe you are configuring
+
+##### ReferencePipe
execute the pipe referenced in path property
- `sling:resourceType` is `slingPipes/reference`
@@ -122,7 +242,7 @@ execute the pipe referenced in path property
### writers
-#### Write Pipe
+##### Write Pipe (`write(conf)`)
writes given nodes & properties to current input
- `sling:resourceType` is `slingPipes/write`
@@ -132,13 +252,16 @@ Note that properties that will be evaluated (in an expression) as `null` for a g
removed from it. E.g. `./conf/some/node@prop=${null}` will add `./conf/some/node` structure
if not in current input resource, but remove its `prop` property if any).
-### MovePipe
+e.g. `echo('/content/foo').write('foo','bar').run()` will write `@foo=bar` in `/content/foo`
+
+
+##### MovePipe (`mv(expr)`)
JCR move of current input to target path (can be a node or a property)
- `sling:resourceType` is `slingPipes/mv`
-- `expr` target path, note that parent path must exists
+- `expr` full target path, note that parent path must exists
-#### RemovePipe
+##### RemovePipe (`rm()`)
removes the input resource, returns the parent, regardless of the resource being a node, or
a property
@@ -146,7 +269,7 @@ a property
- `conf` node tree that will be used to filter relative properties & subtrees to the current resource to remove.
A subnode is considered to be removed if it has no property configured, nore any child.
-#### PathPipe
+##### PathPipe (`mkdir(expr)`)
get or create path given in expression
- `sling:resourceType` is `slingPipes/path`
@@ -168,190 +291,59 @@ is the path of the current resource of previous pipe named `previousPipe`
global bindings can be set at pipe execution, external scripts can be added to the execution as well (see pipe
configurations)
-## How to execute a pipe
-for now it's possible to execute Pipes through GET (read) or POST (read/write) commands:
-
-### Request Path
-
-- either you'll need to create a slingPipes/plumber resource, say `etc/pipes` and then to execute
-
- curl -u admin:admin -F "path=/etc/pipes/mySamplePipe" http://localhost:8080/etc/pipes.json
-
-- either you execute the request directly on the pipe Path, e.g.
-
- curl -u admin:admin http://localhost:8080/etc/pipes/mySamplePipe.json
-
-which will return you the path of the pipes that have been through the output of the configured pipe.
-
-### Request Parameter `binding`
-
-you can add as `bindings` parameter a json object of global bindings you want to add for the execution of the pipe
-
-e.g.
+## sample configurations
+##### slingQuery | write
+write repository user prefix Ms/Mr depending on gender
- curl -u admin:admin -F "path=/etc/pipes/test" -F "bindings={testBinding:'foo'}" http://localhost:4502/etc/pipes.json
+ plumber.newPipe(resolver).xpath('/jcr:root/home/users//element(*,rep:Users)')
+ .$('nt:unstructured#profile')
+ .write("fullName","${(profile.gender === 'female' ? 'Ms ' + profile.fullName : 'Mr ' + profile.fullName)}")
+ .run()
+##### slingQuery | multiProperty | authorizable | write
+move badge<->user relation ship from badge->users MV property to a user->badges MV property
-will returns something like
+ plumber.newPipe(resolver).echo('/etc/badges/jcr:content/par')
+ .$('[sling:resourceType=myApp/components/badge]').name('badge')
+ .pipe('slingPipes/multiProperty').path('${path.badge}/profiles').name('profile')
+ .auth('${profile}').name('user')
+ .echo('${path.user}/profile')
+ .write('badges','+[${path.badge}]')
+ .run()
- {"size":2, "items":["/one/output/resource", "another/one"]}
-### Request Parameter `writer`
+##### echo | $ | $ | echo | json | write
+this use case is for completing repository website with external system's data (that has an json api),
+it does
-you can add as `writer` parameter a json object as a pattern to the result you want to have. The values of the json
-object are expressions and can reuse each pipe's subpipe binding.
-Note
-this works only if the pipe called is a container
-pipe.
+- loop over "my:Page" country/language tree under `/content/mySite`,
+- fetch json with contextual parameter that must be in upper case,
+- and write part of the returned json in the current resource.
-e.g.
+This pipe is run asynchronously in case the execution takes long.
+
- curl -u admin:admin http://localhost:4502/etc/pipes/users.json?writer={"user":"${user.fullName}"}
+ plumber.newPipe(resolver)
+ .echo("/content/mySite")
+ .$('my:Page')
+ .$('my:Page').name("localePage")
+ .echo('${path.localePage}/jcr:content').name("content")
+ .json('https://www.external.com/api/${content.country.toUpperCase()}.json.name('api')
+ .write('cachedValue','${api.remoteJsonValueWeWant}')
+ .runAsync(null)
-will returns something similar to
-
-{"size":2, "items":[{'user':'John Smith','path':'/home/users/q/q123jk1UAZS'},{'user':'John Doe','path':'/home/users/q/q153jk1UAZS'}]}
-
-### Request Parameter `dryRun`
-if parameter dryRun is set to true, and the executed pipe is supposed to modify content, it will log (at best it can) the change it *would* have done, without doing anything
-### Request Parameter `size`
-default response is truncated to 10 items, if you need more (or less), you can modify that settings with the size parameter
+##### xpath | parent | rm
-## sample configurations
+- query all user profile nodes with bad properties,
+- get the parent node (user node)
+- remove it
-### slingQuery | write
-this pipe parse all profile nodes, and
-
- {
- "sling:resourceType":"slingPipes/container",
- "name":"Dummy User prefix Sample",
- "jcr:description":"prefix all full names of profile with "Mr" or "Ms" depending on gender",
- "conf":{
- "profile": {
- "sling:resourceType":"slingPipes/slingQuery",
- "expr":"nt:unstructured#profile",
- "path":"/home/users"
- },
- "writeFullName": {
- "sling:resourceType":"slingPipes/write",
- "conf": {
- "fullName":"${(profile.gender === 'female' ? 'Ms ' + profile.fullName : 'Mr ' + profile.fullName)}",
- "generatedBy":"slingPipes"
- }
- }
- }
- }
-
-### slingQuery | multiProperty | authorizable | write
- {
- "jcr:primaryType": "sling:Folder",
- "jcr:description": "move badge<->user relation ship from badge MV property to a user MV property"
- "name": "badges",
- "sling:resourceType": "slingPipes/container",
- "conf": {
- "jcr:primaryType": "sling:OrderedFolder",
- "badge": {
- "jcr:primaryType": "sling:Folder",
- "jcr:description": "outputs all badge component resources",
- "expr": "[sling:resourceType=myApp/components/badge]",
- "path": "/etc/badges/badges-admin/jcr:content",
- "sling:resourceType": "slingPipes/slingQuery"
- },
- "profile": {
- "jcr:primaryType": "sling:Folder",
- "jcr:description": "retrieve all user ids from a mv property",
- "path": "${path.badge}/profiles",
- "sling:resourceType": "slingPipes/multiProperty"
- },
- "user": {
- "jcr:primaryType": "sling:OrderedFolder",
- "jcr:description": "outputs user resource",
- "expr": "profile",
- "sling:resourceType": "slingPipes/authorizable"
- },
- "write": {
- "jcr:primaryType": "sling:OrderedFolder",
- "jcr:descritption": "patches the badge path to the badges property of the user profile"
- "path": "${path.user}/profile",
- "sling:resourceType": "slingPipes/write",
- "conf": {
- "jcr:primaryType": "nt:unstructured",
- "badges": "+[${path.badge}]"
- }
- }
- }
- }
-
-
-### xpath | json | write
-this use case is for completing repository profiles with external system's data (that has an json api)
-
- {
- "jcr:primaryType": "nt:unstructured",
- "jcr:description": "this pipe retrieves json info from an external system and writes them to the user profile, uses moment.js, it
- distributes modified resources using publish distribution agent",
- "sling:resourceType": "slingPipes/container",
- "distribution.agent": "publish",
- "additionalScripts": "/etc/source/moment.js",
- "conf": {
- "jcr:primaryType": "sling:OrderedFolder",
- "profile": {
- "jcr:primaryType": "sling:OrderedFolder",
- "expr": "/jcr:root/home/users//element(profile,nt:unstructured)[@uid]",
- "jcr:description": "query all user profile nodes",
- "sling:resourceType": "slingPipes/xpath"
- },
- "json": {
- "jcr:primaryType": "sling:OrderedFolder",
- "expr": "${(profile.uid ? 'https://my.external.system.corp.com/profiles/' + profile.uid.substr(0,2) + '/' + profile.uid + '.json' : '')",
- "jcr:description": "retrieves json information relative to the given profile, if the uid is not found, expr is empty: the pipe will do nothing",
- "sling:resourceType": "slingPipes/json"
- },
- "write": {
- "jcr:primaryType": "sling:OrderedFolder",
- "path": "path.profile",
- "jcr:description": "write json information to the profile node",
- "sling:resourceType": "slingPipes/write",
- "conf": {
- "jcr:primaryType": "sling:OrderedFolder",
- "background": "${json.opt('background')}",
- "about": "${json.opt('about')}",
- "birthday": "${(json.opt('birthday') ? moment(json.opt('birthday'), \"MMMM DD\").toDate() : '')}",
- "mobile": "${json.opt('mobile')}"
- }
- }
- }
- }
-
-### xpath | parent | rm
-
- {
- "jcr:primaryType": "nt:unstructured",
- "jcr:description": "this pipe removes user with bad property in their profile",
- "sling:resourceType": "slingPipes/container",
- "conf": {
- "jcr:primaryType": "sling:OrderedFolder",
- "profile": {
- "jcr:primaryType": "sling:OrderedFolder",
- "expr": "/jcr:root/home/users//element(profile,nt:unstructured)[@bad]",
- "jcr:description": "query all user profile nodes with bad properties",
- "sling:resourceType": "slingPipes/xpath"
- },
- "parent": {
- "jcr:primaryType": "sling:OrderedFolder",
- "jcr:description": "get the parent node (user node)",
- "sling:resourceType": "slingPipes/parent"
- },
- "rm": {
- "jcr:primaryType": "sling:OrderedFolder",
- "jcr:description": "remove it",
- "sling:resourceType": "slingPipes/rm",
- }
- }
- }
+ plumber.newPipe(resolver)
+ .xpath("/jcr:root/home/users//element(profile,nt:unstructured)[@bad]")
+ .parent().rm().run()
some other samples are in https://github.com/npeltier/sling-pipes/tree/master/src/test/
http://git-wip-us.apache.org/repos/asf/sling-site/blob/e7c2d03c/src/main/jbake/content/documentation/bundles/sling-query.md
----------------------------------------------------------------------
diff --git a/src/main/jbake/content/documentation/bundles/sling-query.md b/src/main/jbake/content/documentation/bundles/sling-query.md
index 94ec00d..4e14629 100644
--- a/src/main/jbake/content/documentation/bundles/sling-query.md
+++ b/src/main/jbake/content/documentation/bundles/sling-query.md
@@ -35,8 +35,8 @@ SlingQuery is inspired by the jQuery framework. jQuery is the source of method n
## Features
-* useful [operations](https://github.com/Cognifide/Sling-Query/wiki/Method-list) to traverse the resource tree,
-* flexible [filtering syntax](https://github.com/Cognifide/Sling-Query/wiki/Selector-syntax),
+* useful [operations]({{ refs.methods.path }}) to traverse the resource tree,
+* flexible [filtering syntax]({{ refs.selectors.path }}),
* lazy evaluation of the query result,
* `SlingQuery` object is immutable (thread-safe),
* fluent, friendly, jQuery-like API.
@@ -53,14 +53,13 @@ Add following Maven dependency to your `pom.xml`:
## Documentation
-* [CIRCUIT 2014 presentation](http://cognifide.github.io/Sling-Query/circuit2014/)
-* [Basic ideas](https://github.com/Cognifide/Sling-Query/wiki/Basic-ideas)
-* [Method list](https://github.com/Cognifide/Sling-Query/wiki/Method-list)
-* [Selector syntax](https://github.com/Cognifide/Sling-Query/wiki/Selector-syntax)
- * [Operator list](https://github.com/Cognifide/Sling-Query/wiki/Operator-list)
- * [Modifier list](https://github.com/Cognifide/Sling-Query/wiki/Modifier-list)
- * [Hierarchy operator list](https://github.com/Cognifide/Sling-Query/wiki/Hierarchy-operator-list)
-* [Examples](https://github.com/Cognifide/Sling-Query/wiki/Examples)
+* [Basic ideas]({{ refs.basic-ideas.path }})
+* [Method list]({{ refs.methods.path }})
+* [Selector syntax]({{ refs.selectors.path }})
+ * [Operator list]({{ refs.operators.path }})
+ * [Modifier list]({{ refs.modifiers.path }})
+ * [Hierarchy operator list]({{ refs.hierarchy-operators.path }})
+* [Examples]({{ refs.examples.path }})
## External resources
http://git-wip-us.apache.org/repos/asf/sling-site/blob/e7c2d03c/src/main/jbake/content/documentation/bundles/sling-query/basic-ideas.md
----------------------------------------------------------------------
diff --git a/src/main/jbake/content/documentation/bundles/sling-query/basic-ideas.md b/src/main/jbake/content/documentation/bundles/sling-query/basic-ideas.md
new file mode 100644
index 0000000..b683534
--- /dev/null
+++ b/src/main/jbake/content/documentation/bundles/sling-query/basic-ideas.md
@@ -0,0 +1,75 @@
+Title: Basic ideas
+
+### Collections
+
+`SlingQuery` class represents a collection of resources. Basic collection can be created explicitly via a dollar method:
+
+ $(resource1, resource2, resource3)
+
+Above method creates a new `SlingQuery` object that consists of 3 resources. This object implements `Iterable<Resource>` interface, so can be used in foreach statements directly:
+
+ for (Resource resource in $(...)) { }
+
+### Operations
+
+`SlingQuery` class defines a number of methods which can be used to transform current collection into a new one. Following code:
+
+ $(resource1, resource2).parent()
+
+will replace each resource with its direct parent. If some resource is a repository root, it will be skipped. Some methods replace each resource with another resource (eg. `parent()` or `closest()`). Other methods can replace each resource with a set of resources:
+
+ $(resource1, resource2).children();
+
+Resulting object will contain direct children of both `resource1` and `resource2` objects. There are also methods that doesn't add any new resources, but removes existing:
+
+ $(resource1, resource2).first();
+
+Methods can be chained to create more complex query. Eg. following code will return last direct child of the `resource`:
+
+ $(resource).children().last();
+
+#### Laziness
+
+All operations are lazy (except `prev()` and sometimes `not()`). It means that `SlingQuery` won't read any resources until it's actually necessary. Example:
+
+ $(resource).children().children().first();
+
+`children().children()` construction reads all grand-children of the given resource. However, the last method limits the output to the first found resource. As a result, `SlingQuery` won't iterate over all children and grand-children, but it will simply take the first child of the `resource` and return its first child.
+
+#### Immutability
+
+`SlingQuery` object is immutable and each operation creates a new one. We can "freeze" some collection before performing more operations on it:
+
+ SlingQuery children = $(resource).children();
+ SlingQuery firstChild = children.first();
+ for (Resource child : children) { /* will display all children */ }
+ for (Resource child : firstChild) { /* will display the first child */ }
+
+### Selectors
+
+Some operations may take an additional string selector parameter that defines a filtering. Selector could be used to define resource type, resource attributes and additional modifiers. Example selector could look like this:
+
+ "cq:Page"
+
+It will match all resources with the given resource type. Example:
+
+ $(resource).children("cq:Page")
+
+will return only children with `cq:Page` resource type. You could also filter these resources defining any number of attributes in the square brackets:
+
+ $(resource).children("cq:Page[jcr:title=Some title][jcr:description=Some desc]")
+
+And finally, you could add some modifiers at the end:
+
+ $(resource).children("cq:Page[jcr:content/cq:template=my/template]:even")
+
+Above resources will find `cq:Page` children of the resource, using template `my/template` and return not all of them, but only those with even indices (eg. if matching children of the `resource` are `page_0`, `page_1` and `page_2`, only the first and the last will be returned).
+
+All parts of the selector are optional. In fact, an empty string (`""`) is a valid selector, accepting all resources. However, the defined order (resource type, attributes in square brackets and modifiers) has to be followed. Example selectors:
+
+ "foundation/components/richtext" // resource type
+ "foundation/components/richtext:first" // resource type with modifier
+ "[property=value][property2=value2]" // two attributes
+ ":even" // modifier
+ ":even:not(:first)" // two modifiers, the second one is nested
+
http://git-wip-us.apache.org/repos/asf/sling-site/blob/e7c2d03c/src/main/jbake/content/documentation/bundles/sling-query/examples.md
----------------------------------------------------------------------
diff --git a/src/main/jbake/content/documentation/bundles/sling-query/examples.md b/src/main/jbake/content/documentation/bundles/sling-query/examples.md
new file mode 100644
index 0000000..6c6309f
--- /dev/null
+++ b/src/main/jbake/content/documentation/bundles/sling-query/examples.md
@@ -0,0 +1,59 @@
+Title: Examples
+
+Get containing page (like [PageManager#getContainingPage](https://docs.adobe.com/docs/en/aem/6-3/develop/ref/javadoc/com/day/cq/wcm/api/PageManager.html#getContainingPage(org.apache.sling.api.resource.Resource)))
+
+ $(resource).closest("cq:Page")
+
+Get first ancestor with a given template
+
+ $(resource).closest("cq:Page[jcr:content/cq:template=/apps/geometrixx/templates/homepage]")
+
+List siblings of the current page which can be displayed in the navigation
+
+ $(resource).closest("cq:Page").siblings("cq:Page[jcr:content/hiddenInNav=false]")
+
+Get the first sibling of the current page
+
+ $(resource).closest("cq:Page").siblings("cq:Page").first()
+
+Get page ancestor closest to the root
+
+ $(resource).parents("cq:Page").last()
+
+Get the second child of each resource:
+
+ $(resource1, resource2, resource3).children(":eq(1)")
+
+Get the first two children of each resource:
+
+ $(resource1, resource2, resource3).children(":lt(2)")
+
+Closest ancestor page having non-empty parsys
+
+ $(resource).closest("cq:Page foundation/components/parsys:parent")
+
+Get all parents of the current resource and adapt them to Page object
+
+ Iterable<Page> breadcrumbs = $(resource).parents("cq:Page").map(Page.class);
+
+Get all parents of the current resource up to the home page
+
+ Iterable<Page> breadcrumbs;
+ breadcrumbs = $(resource).parentsUntil(
+ "cq:Page[jcr:content/cq:template=/apps/geometrixx/templates/homepage]",
+ "cq:Page").map(Page.class);
+
+List all grand-children pages having empty parsys
+
+ $(resource).children("cq:Page").children("cq:Page").has("foundation/components/parsys:empty)
+
+Use JCR query to find all `cq:Page`s with a given template
+
+ $(resourceResolver)
+ .searchStrategy(SearchStrategy.QUERY)
+ .find("cq:PageContent[cq:template=/apps/geometrixx/templates/homepage]")
+ .parent()
+
+Find children named `en` or `de`
+
+ $(resource).children("#en, #de")
http://git-wip-us.apache.org/repos/asf/sling-site/blob/e7c2d03c/src/main/jbake/content/documentation/bundles/sling-query/hierarchy-operators.md
----------------------------------------------------------------------
diff --git a/src/main/jbake/content/documentation/bundles/sling-query/hierarchy-operators.md b/src/main/jbake/content/documentation/bundles/sling-query/hierarchy-operators.md
new file mode 100644
index 0000000..978a871
--- /dev/null
+++ b/src/main/jbake/content/documentation/bundles/sling-query/hierarchy-operators.md
@@ -0,0 +1,37 @@
+Title: Hierarchy operators
+
+### Child operator (`parent > child`)
+
+Select all direct child resources specified by `child` of resources specified by `parent`
+
+ // find all richtext components placed directly into parsys resources
+ $(resource).find('foundation/components/parsys > foundation/components/richtext')
+ // alternative version
+ $(resource).find('foundation/components/parsys').children('foundation/components/richtext')
+
+### Descendant operator (`ancestor descendant`)
+
+Select all resources that are `descendant`s of a given `ancestor`
+
+ // find all resources containing `someAttribute` on the `cq:Page`s being direct children of the resource
+ $(resource).children('cq:Page [someAttribute]')
+ // alternative version
+ $(resource).children('cq:Page').find('[someAttribute]')
+
+### Next adjacent operator (`prev + next`)
+
+Selects all next resources matching `next` that are immediately preceded by a sibling `prev`
+
+ // find next sibling of the cq:Page containing the resource
+ $(resource).closest('cq:Page + cq:Page')
+ // alternative version
+ $(resource).closest('cq:Page').next('cq:Page')
+
+### Next siblings operator (`prev ~ next`)
+
+Selects all sibling resources that follow after the `prev` element, have the same parent, and match the filtering `siblings` selector
+
+ // find all next siblings of the cq:Page containing the resource
+ $(resource).closest('cq:Page ~ cq:Page')
+ // alternative version
+ $(resource).closest('cq:Page').nextAll('cq:Page')
http://git-wip-us.apache.org/repos/asf/sling-site/blob/e7c2d03c/src/main/jbake/content/documentation/bundles/sling-query/methods.md
----------------------------------------------------------------------
diff --git a/src/main/jbake/content/documentation/bundles/sling-query/methods.md b/src/main/jbake/content/documentation/bundles/sling-query/methods.md
new file mode 100644
index 0000000..85d26e1
--- /dev/null
+++ b/src/main/jbake/content/documentation/bundles/sling-query/methods.md
@@ -0,0 +1,184 @@
+Title: Method list
+
+### `$(Resource... resources)`
+
+Create a new SlingQuery object, using passed resources as an initial collection. Example:
+
+ $(resource); // a simple SlingQuery collection containing one resource
+
+### `.add(Resource... resources)`
+
+Add resources to the collection.
+
+ $(resource).children().add(resource); // collection contains resource and all its children
+
+### `.asList()`
+
+Transform SlingQuery collection into a lazy list.
+
+ $(resource).children("cq:Page").asList().get(0); // get the first child page
+ $(resource).children().asList().isEmpty(); // return true if the resource have no children
+
+### `.children([selector])`
+
+Get list of the children for each resource in the collection. Pass `selector` to filter children. Example:
+
+ $(resource).children("cq:Page"); // get all page children of the resource
+ $(resource).children().children(); // get all grand-children of the resource
+
+### `.closest(selector)`
+
+For each resource in the collection, return the first element matching the selector testing the resource itself and traversing up its ancestors. Example:
+
+ $(resource).closest("cq:Page"); // find containing page, like PageManager#getContainingPage
+ // let's assume that someCqPageResource is a cq:Page
+ $(someCqPageResource).closest("cq:Page"); // return the same resource
+
+### `.eq(index)`
+
+Reduce resource collection to the one resource at the given 0-based index. Example:
+
+ $(resource0, resource1, resource2).eq(1); // return resource1
+ $(resource).children().eq(0); // return first child of the resource
+
+### `.filter(selector)`
+
+Filter resource collection using given selector.
+
+ final Calendar someTimeAgo = Calendar.getInstance();
+ someTimeAgo.add(Calendar.HOUR, -5);
+
+ // get children pages modified in the last 5 hours
+ SlingQuery query = $(resource).children("cq:Page").filter(new Predicate<Resource>() {
+ @Override
+ public boolean accepts(Resource resource) {
+ return resource.adaptTo(Page.class).getLastModified().after(someTimeAgo);
+ }
+ });
+
+### `.find([selector])`
+
+For each resource in collection return all its descendants using [selected strategy](#searchstrategystrategy). Please notice that invoking this method on a resource being a root of a large subtree may and will cause performance problems.
+
+ $(resource).find("cq:Page"); // find all descendant pages
+
+### `.first()`
+
+Filter resource collection to the first element. Equivalent to `.eq(0)` or `.slice(0, 0)`.
+
+ $(resource).siblings().first(); // get the first sibling of the current resource
+
+### `.has(selector)`
+
+Pick such resources from the collection that have descendant matching the selector. Example:
+
+ $(...).children('cq:Page').has(foundation/components/richtext) // find children pages containing some richtext component
+
+This method uses [selected strategy](#searchstrategystrategy) to iterate over resource descendants.
+
+### `.last()`
+
+Filter resource collection to the last element.
+
+ $(resource).siblings().last(); // get the last sibling of the current resource
+
+### `.map(Class<T> clazz)`
+
+Transform the whole collection to a new `Iterable<T>` object, invoking `adaptTo(clazz)` method on each resource. If some resource can't be adapted to the class (eg. `adaptTo()` returns `null`), it will be skipped. Example:
+
+ for (Page page : $(resource).parents("cq:Page").map(Page.class)) {
+ // display breadcrumbs
+ }
+
+### `.next([selector])`
+
+Return the next sibling for each resource in the collection and optionally filter it by a selector. If the selector is given, but the sibling doesn't match it, empty collection will be returned.
+
+ // let's assume that resource have 3 children: child1, child2 and child3
+ $(resource).children().first().next(); // return child2
+
+### `.nextAll([selector])`
+
+Return all following siblings for each resource in the collection, optionally filtering them by a selector.
+
+ // let's assume that resource have 3 children: child1, child2 and child3
+ $(resource).children().first().nextAll(); // return child2 and child3
+
+### `.nextUntil(selector)`
+
+Return all following siblings for each resource in the collection up to, but not including, resource matched by a selector.
+
+ // let's assume that resource have 4 children: child1, child2, child3 and child4
+ // additionaly, child4 has property jcr:title=Page
+ $(resource).children().first().nextUntil("[jcr:title=Page]"); // return child2 and child3
+
+### `.not(selector)`
+
+Remove elements from the collection.
+
+ $(resource).children().not("cq:Page"); // remove all cq:Pages from the collection
+ $(resource).children().not(":first").not(":last"); // remove the first and the last element of the collection
+
+### `.parent()`
+
+Replace each element in the collection with its parent.
+
+ $(resource).find("cq:PageContent[jcr:title=My page]:first").parent(); // find the parent of the first `cq:PageContent` resource with given attribute in the subtree
+
+### `.parents([selector])`
+
+For each element in the collection find all of its ancestors, optionally filtering them by a selector.
+
+ ($resource).parents("cq:Page"); // create page breadcrumbs for the given resources
+
+### `.parentsUntil(selector)`
+
+For each element in the collection find all of its ancestors until a resource matching the selector is found.
+
+ ($currentResource).parentsUntil("cq:Page"); // find all ancestor components on the current page
+
+### `.prev([selector])`
+
+Return the previous sibling for each resource in the collection and optionally filter it by a selector. If the selector is given, but the sibling doesn't match it, empty collection will be returned.
+
+ // let's assume that resource have 3 children: child1, child2 and child3
+ $(resource).children().last().prev(); // return child2
+
+### `.prevAll([selector])`
+
+Return all preceding siblings for each resource in the collection, optionally filtering them by a selector.
+
+ // let's assume that resource have 3 children: child1, child2 and child3
+ $(resource).children().last().prevAll(); // return child1 and child2
+
+### `.prevUntil(selector)`
+
+Return all preceding siblings for each resource in the collection up to, but not including, resource matched by a selector.
+
+ // let's assume that resource have 4 children: child1, child2, child3 and child4
+ // additionally, child1 has property jcr:title=Page
+ $(resource).children().last().prevUntil("[jcr:title=Page]"); // return child2 and child3
+
+### `.searchStrategy(strategy)`
+
+Select new search strategy, which will be used in following [`find()`](#findselector) and [`has()`](#hasselector) function invocations. There 3 options:
+
+* `SearchStrategy.DFS` - [depth-first search](http://en.wikipedia.org/wiki/Depth-first_search)
+* `SearchStrategy.BFS` - [breadth-first search](http://en.wikipedia.org/wiki/Breadth-first_search)
+* `SearchStrategy.QUERY` - use JCR SQL2 query (default since 1.4.0)
+
+DFS and BFS iterate through descendants using appropriate algorithm. QUERY strategy tries to transform SlingQuery selector into a SQL2 query and invokes it. Because there are SlingQuery operations that can't be translated (eg. `:has()` modifier), the SQL2 query result is treated as a initial collection that needs further processing.
+
+### `.siblings([selector])`
+
+Return siblings for the given resources, optionally filtered by a selector.
+
+ $(resource).closest("cq:Page").siblings("cq:Page"); // return all sibling pages
+
+### `.slice(from[, to])`
+
+Reduce the collection to a sub-collection specified by a given range. Both `from` and `to` are inclusive and 0-based indices. If the `to` parameter is not specified, the whole sub-collection starting with `from` will be returned.
+
+ // let's assume that resource have 4 children: child1, child2, child3 and child4
+ $(resource).children().slice(1, 2); // return child1 and child2
+
http://git-wip-us.apache.org/repos/asf/sling-site/blob/e7c2d03c/src/main/jbake/content/documentation/bundles/sling-query/modifiers.md
----------------------------------------------------------------------
diff --git a/src/main/jbake/content/documentation/bundles/sling-query/modifiers.md b/src/main/jbake/content/documentation/bundles/sling-query/modifiers.md
new file mode 100644
index 0000000..ab20dca
--- /dev/null
+++ b/src/main/jbake/content/documentation/bundles/sling-query/modifiers.md
@@ -0,0 +1,61 @@
+Title: Modifiers
+
+### `:eq(index)`
+
+Reduce the set of matched elements to the one at the specified 0-based index. Example:
+
+ $(...).find("foundation/components/richtext:eq(2)"); // find the third richtext in the subtree
+
+### `:even`
+
+Reduce the set of matched elements to those which indexes are even numbers:
+
+ $(...).children("cq:Page:even"); // get even children pages for each resource in the collection
+
+### `:first`
+
+Reduce the set of matched elements to the first one:
+
+ $(...).find("foundation/components/richtext:first"); // find the first richtext in the subtree
+
+### `:gt(index)`
+
+Reduce the set of matched elements to those which indexes are greater than the argument:
+
+ $(...).children("cq:Page:gt(2)"); // filter out first 3 pages
+
+### `:has(selector)`
+
+Reduce the set of the matched elements to those which have descendant matching the selector:
+
+ $(...).children("cq:Page:has(foundation/components/richtext)]"); // get children pages containing richtext component
+
+### `:last`
+
+Reduce the set of matched elements to the last one:
+
+ $(...).find("foundation/components/richtext:last"); // find the last richtext in the subtree
+
+### `:lt(index)`
+
+Reduce the set of matched elements to those which indexes are lesser than the argument:
+
+ $(...).children("cq:Page:lt(3)"); // get first 3 matches
+
+### `:not(selector)`
+
+Reduce the set of matched elements to those which doesn't match the selector. The selector may contain other modifiers as well, however in this case the function will be evaluated eagerly:
+
+ $(...).find(":not(:parent)"); // ancestor resources that doesn't contain any children
+
+### `:odd`
+
+Reduce the set of matched elements to those which indexes are odd numbers:
+
+ $(...).children("cq:Page:odd"); // get odd children pages for each resource in the collection
+
+### `:parent`
+
+Reduce the set of the matched elements to those which have any descendant resource.
+
+ $(...).children(":parent]"); // get children resources containing any resource
http://git-wip-us.apache.org/repos/asf/sling-site/blob/e7c2d03c/src/main/jbake/content/documentation/bundles/sling-query/operators.md
----------------------------------------------------------------------
diff --git a/src/main/jbake/content/documentation/bundles/sling-query/operators.md b/src/main/jbake/content/documentation/bundles/sling-query/operators.md
new file mode 100644
index 0000000..6787c75
--- /dev/null
+++ b/src/main/jbake/content/documentation/bundles/sling-query/operators.md
@@ -0,0 +1,47 @@
+Title: Operators
+
+### Contains `[name*=value]`
+
+Select resources that have property `name` containing `value`:
+
+ // select children pages titled 'foo', 'foo bar', 'bar foo bar', 'foofoofoo', etc.
+ $(resources).children("cq:Page[jcr:content/jcr:title*=foo]")
+
+### Contains a word `[name~=value]`
+
+Select resources that have property `name` containing word `value` delimited with spaces:
+
+ // select children pages titled 'foo', 'foo bar', 'bar foo bar', but not 'foofoofoo'
+ $(resources).children("cq:Page[jcr:content/jcr:title~=foo]")
+
+### Ends with `[name$=value]`
+
+Select resources that have property `name` ending with `value`:
+
+ // select children pages titled 'foo', 'bar foo', etc.
+ $(resources).children("cq:Page[jcr:content/jcr:title$=foo]")
+
+### Equals `[name=value]`
+
+Select resources that have property `name` that equals to `value`:
+
+ $(resources).children("cq:Page[jcr:content/jcr:title=foo]")
+
+### Not equal `[name!=value]`
+
+Select resources that have property `name` that not equals to `value`:
+
+ $(resources).children("cq:Page[jcr:content/jcr:title!=foo]")
+
+### Starts with `[name^=value]`
+
+Select resources that have property `name` starting with `value`:
+
+ // select children pages titled 'foo', 'foo bar', etc.
+ $(resources).children("cq:Page[jcr:content/jcr:title^=foo]")
+
+### Has attribute `[name]`
+
+Select resources that have property `name`:
+
+ $(resources).find("[markerProperty]")
http://git-wip-us.apache.org/repos/asf/sling-site/blob/e7c2d03c/src/main/jbake/content/documentation/bundles/sling-query/selectors.md
----------------------------------------------------------------------
diff --git a/src/main/jbake/content/documentation/bundles/sling-query/selectors.md b/src/main/jbake/content/documentation/bundles/sling-query/selectors.md
new file mode 100644
index 0000000..1f06d16
--- /dev/null
+++ b/src/main/jbake/content/documentation/bundles/sling-query/selectors.md
@@ -0,0 +1,67 @@
+Title: Selectors
+
+Selector string are something between filters and content descriptors. Selector can filter resources by their [type](#resource-type), [name](#resource-name), [attributes](#attributes) and [additional modifiers](#modifiers). They can be also [chained together](#joining-selectors) to describe more sophisticated hierarchy structure or [combined with comma](#combining-selectors).
+
+## Syntax
+
+Selector consists of four parts:
+
+### Resource type
+
+Resource type, which could be a `sling:resourceType`, like `foundation/components/richtext` or the underlying JCR node type, like `cq:Page` or `nt:unstructured`. In the latter case, SlingQuery takes types hierarchy into consideration (eg. `nt:base` matches everything). JCR mixin types could be used as well.
+
+### Resource name
+
+Resource name can be defined with a hash `#` character, after the resource type (or instead of it):
+
+ $(resource).children("cq:Page#some-name")
+
+If the desired resource name contains colon (`:`) character, the whole string should be escaped with apostrophes:
+
+ $(resource).children("#'jcr:content'[jcr:title=My title]")
+
+### Attributes
+
+After the resource type and resource name one could pass a number of filtering attributes. Each attribute has following form: `[property=value]`. Passing multiple attributes will match only those resources that have all of them set. Property name could contain `/`. In this case property will be taken from the child resource, eg.:
+
+ $(resource).children("cq:Page[jcr:content/jcr:title=My title]")
+
+will return only children of type `cq:Page` that have sub-resource called `jcr:content` with property `jcr:title` set to `My title`. Besides the `=` you may use other operators like `*=`, which means *contains*:
+
+ $(resource).children("cq:Page[jcr:content/jcr:title*=title]")
+
+See the [fulll list of operators](operators.html).
+
+### Modifiers
+
+At the end of the selector one could define any number of modifiers that will be used to filter out the resources matched by the resource type and attributes. Each modifier starts with colon, some of them accepts a parameter set in parentheses. Example:
+
+ $(resource).children("cq:Page:first");
+ $(resource).children("cq:Page:eq(0)"); // the same
+ $(resource).children(":first"); // modifier can be used alone
+
+It is important that modifier filters out sub-collection created for each node, before it is merged. Eg.:, there is a difference between:
+
+ $(resource1, resource2).children().first();
+
+and
+
+ $(resource1, resource2).children(":first");
+
+In the first case we create a new collection consisting of children of the `resource1` and `resource2` and then we get the first element of the merged collection. On the other hand, the second example takes *first child* of each resource and creates a collection from them.
+
+See the [full list of modifiers](modifiers.html).
+
+## Joining selectors
+
+Selectors can be joined together using [hierarchy operators](hierarchy-operators.html). This feature enables the developer to create sophisticated filters describing desired resource structure, eg.:
+
+ $(resource).children("cq:Page foundation/components/parsys > foundation/components/richtext")
+
+will all `cq:Page`s containing paragraph systems with a richtext inside.
+
+## Combining selectors
+
+You may specify any number of selectors to combine into a single result. Use comma to join a few conditions. Comma is treated as `OR` statement:
+
+ $(resource).children("#en, #de, #fr"); // return all direct children named `en` or `de` or `fr`.
http://git-wip-us.apache.org/repos/asf/sling-site/blob/e7c2d03c/src/main/jbake/content/documentation/bundles/sling-query/vs-jcr.md
----------------------------------------------------------------------
diff --git a/src/main/jbake/content/documentation/bundles/sling-query/vs-jcr.md b/src/main/jbake/content/documentation/bundles/sling-query/vs-jcr.md
new file mode 100644
index 0000000..58f5764
--- /dev/null
+++ b/src/main/jbake/content/documentation/bundles/sling-query/vs-jcr.md
@@ -0,0 +1,17 @@
+Title: Sling Query vs JCR
+
+Sling Query is not meant to replace JCR queries (XPath, JCR-SQL, JCR-SQL2). It doesn't use indexes and generally in queries traversing large subtrees (like `/` or `/content` or `/content/mysite/en`) it'll be much slower than well written JCR query.
+
+Purpose of the SlingQuery is to provide a convenient way to traverse resource tree. All SlingQuery operations are eventually transformed into a series of `listChildren()` and `getParent()` operations [1].
+
+As a rule of thumb - if you have a complex Java loop reading resource children or parents and processing them somehow, rewritting it to SlingQuery will be a good choice. If you have a recursive method trying to get some resource ancestor, using SlingQuery will be a good choice. On the other hand, if you have a large resource subtree and want to find all `cq:Page`s, using SlingQuery is a bad choice.
+
+| Description | JCR query | SlingQuery |
+| ------------------------------------------------------|-----------|------------|
+| You have a complex logic using Sling Resource API | - | Yes! |
+| You want to find resource ancestor | - | Yes! |
+| You want to find all descendants with given attribute | Yes! | - |
+| You want to find all descendants of given type | Yes! | - |
+| You'd like to get ordered results | Yes! | - |
+
+[1] - Actually, the `find()` operation uses QUERY strategy by default, which means that the selector string is transformed to a SQL2 query. However, the transformation process is very naïve and simply skips all conditions that can't be easily transformed to SQL2 (eg. selector `[jcr:content/jcr:title=some title]` won't be transformed as it contains some subresource reference). The result of this query is then filtere manually. See [searchStrategy](methods.html#searchstrategystrategy) for more details.
http://git-wip-us.apache.org/repos/asf/sling-site/blob/e7c2d03c/src/main/jbake/content/documentation/development/jsr-305.md
----------------------------------------------------------------------
diff --git a/src/main/jbake/content/documentation/development/jsr-305.md b/src/main/jbake/content/documentation/development/jsr-305.md
index 962b9fc..157a53b 100644
--- a/src/main/jbake/content/documentation/development/jsr-305.md
+++ b/src/main/jbake/content/documentation/development/jsr-305.md
@@ -13,11 +13,13 @@ The annotations used within Sling are based on the [JSR-305](https://jcp.org/en/
Due to the fact that Eclipse and FindBugs are interpreting annotations differently ([Findbugs-1355](https://sourceforge.net/p/findbugs/bugs/1355/)). Sling only uses the following two different annotations which are supported by both tools:
-1. `javax.annotation.CheckForNull`
-1. `javax.annotation.Nonnull`
+1. `javax.annotation.CheckForNull` (only on return values which may be `null`)
+1. `javax.annotation.Nonnull` (on return values and arguments which are never supposed to be `null`)
Annotations which support setting the default null semantics of return values and or parameters on a package level cannot be leveraged for that reason.
+In case no annotations have been set on method arguments those accept `null` as a value. Return values should always be explicitly annotated, as from both cases checks can be derived.
+
The annotations have a retention policy of `runtime`, therefore bundles using these automatically have a `Import-Package` header listing `javax.annotation`. That package is by default exported by the system bundle (as this package is also part of the [JRE](https://docs.oracle.com/javase/7/docs/api/javax/annotation/package-summary.html)). To be able to resolve the bundle through this exported package from the system bundle you should use the `com.google.code.findbugs:jsr305` artifact in version 3.0.0 as that exports the package `javax.annotation` in no specific version. Newer versions use version directives which automatically restrict the version range for the generated `Import-Package` header to `[3,4)` [which usually cannot be resolved at run time](https://github.com/amaembo/jsr-305/issues/31).
# Use With Eclipse