This is an automated email from the ASF dual-hosted git repository.
radu pushed a commit to branch master
in repository
https://gitbox.apache.org/repos/asf/sling-org-apache-sling-servlets-resolver-api.git
The following commit(s) were added to refs/heads/master by this push:
new f791401 trivial: updated readme
f791401 is described below
commit f7914017d40421d80a02f05b970f47356afb2c6c
Author: Radu Cotescu <[email protected]>
AuthorDate: Fri Jan 29 10:46:27 2021 +0100
trivial: updated readme
---
README.md | 74 ++++++---------------------------------------------------------
1 file changed, 7 insertions(+), 67 deletions(-)
diff --git a/README.md b/README.md
index 2726a91..56ec79b 100644
--- a/README.md
+++ b/README.md
@@ -1,76 +1,16 @@
[](https://sling.apache.org)
- [](https://ci-builds.apache.org/job/Sling/job/modules/job/sling-org-apache-sling-servlets-resolver/job/master/) [](https://ci-builds.apache.org/job/Sling/job/modules/job/sling-or
[...]
+ [](https://ci-builds.apache.org/job/Sling/job/modules/job/sling-org-apache-sling-servlets-resolver-api/job/master/) [](https://ci-builds.apache.org/job/Sling/job/modules/
[...]
-# Apache Sling Servlet Resolver
+# Apache Sling Servlets Resolver API
This module is part of the [Apache Sling](https://sling.apache.org) project.
-Bundle implementing the Sling API ServletResolver.
+The bundle currently provides the
`org.apache.sling.servlets.resolver.bundle.tracker` API, which allows the
+[Apache Sling Servlets
Resolver](https://github.com/apache/sling-org-apache-sling-servlets-resolver)
and the
+[Apache Sling Scripting
Core](https://github.com/apache/sling-org-apache-sling-scripting-core) to wire
up and
+execute bundled scripts (precompiled or not) in order to render HTTP requests.
-## Bundled scripts
-Version 2.7.0 of this bundle has added support for executing bundled scripts
(precompiled or not), through the
-`org.apache.sling.servlets.resolver.bundle.tracker` API.
-
-Although traditionally scripts are deployed as content stored in the search
paths of a Sling instance, this leaves very little
-room for script evolution in a backwards compatible way. Furthermore,
versioning scripts is a difficult process if the only
-mechanism to do this is the `sling:resourceType` property, since consumers
(content nodes or other resource types) have then to
-explicitly mention the version expected to be executed.
-
-Scripts should not be considered content, since their only purpose is to
actually generate the rendering for a certain content
-structure. They are not consumed by users, but rather by the Sling Engine
itself and have very little meaning outside this
-context. As such, scripts should be handled like code:
-
- 1. they _provide an HTTP API_;
- 2. they can evolve in a _semantical_ [1] way;
- 3. they have a _developer audience_.
-
-### How
-Being built around a `BundleTrackerCustomizer` [2], the
`org.apache.sling.servlets.resolver.bundle.tracker.internal.BundledScriptTracker`
-monitors the instance's bundles wired to the
`org.apache.sling.servlets.resolver` bundle and scans the ones providing a
`sling.servlet`
-capability [3]. The wiring is created by placing a `Require-Capability` header
in the bundles that provide the `sling.servlet` capability:
-
-```
-osgi.extender;filter:="(&(osgi.extender=sling.scripting)(version>=1.0.0)(!(version>=2.0.0)))"
-```
-
-A `sling.servlet` capability has almost the same attributes as the properties
required to register a servlet on the Sling platform [4]:
-
- 1. `sling.servlet.resourceTypes:List` - mandatory; defines the provided
resource type; its value is a list of resource types
- 2. `sling.servlet.selectors:List` - optional; defines the list of selectors
that this resource type can handle;
- 3. `sling.servlet.extensions:List` - optional; defines the list of
extensions that this resource type can handle;
- 4. `sling.servlet.methods:List` - optional; defines the list of HTTP methods
that this resource type can handle;
- 5. `version:Version` - optional; defines the version of the provided
`resourceType`;
- 6. `extends:String` - optional; defines which resource type it extends; the
version range of the extended resource type is defined in a
- `Require-Capability`.
-
-The `BundledScriptTracker` will register a Sling Servlet with the appropriate
properties for each `sling.servlet` capability. The
-servlets will be registered using the bundle context of the bundle providing
the `sling.servlet` capability, making
-sure to expose the different versions of a resource type as part of the
registered servlet's properties. On top of this, a plain resource
-type bound servlet will also be registered, which will be automatically wired
to the highest version of the `resourceType`. All the
-mentioned service registrations are managed automatically by the
`BundledScriptTracker`.
-
-### So how do I deploy my scripts?
-Short answer: exactly like you deploy your code, preferably right next to it.
Pack your scripts using the following conventions:
-
- 1. create a `src/main/resources/javax.script` folder in your bundle (if you
want to embed the scripts as they are) or just put the
- scripts in `src/main/scripts` if you want to precompiled them (e.g. JSP and
HTL);
- 2. each folder under the above folders will identify a `resourceType`;
- 3. inside each `resourceType` folder you can optionally create a `Version`
folder; this has to follow the Semantic Versioning
- constraints described at [1];
- 4. add your scripts, using the same naming conventions that you were used to
from before [5];
- 5. manually define your provide and require capabilities; just kidding; add
the
-
[`scriptingbundle-maven-plugin`](https://github.com/apache/sling-scriptingbundle-maven-plugin)
to your build section and add its required
- properties in the `maven-bundle-plugin`'s instructions (check [these
examples](https://github.com/apache/sling-org-apache-sling-scripting-bundle-tracker-it/tree/master/examples/));
- 6. `mvn clean sling:install`.
-
-### Integration Tests
+## Integration Tests
The integration tests for bundled scripts are provided by the
[`org.apache.sling.scripting.bundle.tracker.it`](https://github.com/apache/sling-org-apache-sling-scripting-bundle-tracker-it)
project.
-
-## Resources
-[1] - https://semver.org/
-[2] -
https://osgi.org/javadoc/r6/core/org/osgi/util/tracker/BundleTrackerCustomizer.html
-[3] - https://osgi.org/download/r6/osgi.core-6.0.0.pdf, Page 41, section 3.3.3
"Bundle Capabilities"
-[4] -
https://sling.apache.org/documentation/the-sling-engine/servlets.html#servlet-registration-1
-[5] -
https://sling.apache.org/documentation/the-sling-engine/url-to-script-resolution.html
