raducotescu commented on a change in pull request #67:
URL: https://github.com/apache/sling-site/pull/67#discussion_r689668763
##########
File path: src/main/jbake/content/documentation/bundles/scripting.md
##########
@@ -67,9 +67,143 @@ Mapping `html` to Thymeleaf 3.0:
"html=Thymeleaf:3.0"
]
+## Scripts are Servlets
+
+The Sling API defines a `SlingScript` interface which is used to represent
(executable) scripts inside of Sling. This interface is implemented in the
[Scripting Core bundle][8] in the `DefaultSlingScript` class which also
implements the `javax.servlet.Servlet`.
+
+To further simplify the access to scripts from the Resource tree, the
`scripting/core` bundle registers an `AdapterFactory` to adapt Resources to
Scripts and Servlets (the `SlingScriptAdapterFactory`). In fact the adapter
factory returns instances of the `DefaultSlingScript` class for both Scripts
and Servlets.
+
+From the perspective of the [Servlet resolver][7], scripts and servlets are
handled exactly the same. In fact, internally, Sling only deals with Servlets,
whereas scripts are packed inside a Servlet wrapping and representing the
script.
+
+## Resource Scripts
+
+Scripts are looked up in a series of resource resolver locations defined by
the `ResourceResolver.getSearchPath()` and the resource type (and resource
super types) of the requested resource:
+
+ {scriptPathPrefix}/{resourceTypePath}
+
+The pseudo code for iterating the locations would be something like:
+
+
+ var type = resource.getResourceType();
+ while (type != null) {
+ for (String root: resourceResolver.getSearchPath()) {
+ String path = root + type.toPath();
+ findScriptsIn(path);
+ }
+
+ if (type == defaultServlet) {
+ type = null;
+ } else {
+ type = getResourceSuperType(type);
+ if (type == null) {
+ type = defaultServlet;
+ }
+ }
+ }
+
+### Resource script naming conventions
+
+Depending on whether request selectors are considered, a script may have two
forms:
+
+1. Ignoring request selectors (e.g. there are none in the request URI):
`{resourceTypeLabel}.{requestExtension}.{requestMethod}.{scriptExtension}`
+2. Handling request selectors:
`{selectorStringPath}.{requestExtension}.{requestMethod}.{scriptExtension}`
+
+The constituents of these script names are as follows:
+
+* `{resourceTypeLabel}` - The last path segment of the path created from the
resource type. This part is optional if the `{requestExtension}` is used in the
script name. The resource type might either be set via the `sling:resourceType`
property on the accessed node or if that property is not there its primary node
type (property `jcr:primaryType`) is taken as fall-back.
+* `{requestExtension}` - The request extension. This part may be omitted if
the request extension is `html`, otherwise this part is required. If this part
is omitted, the `{resourceTypeLabel}` is required in the case of ignoring the
selectors.
+* `{requestMethod}` - The request's HTTP method. This part may be omitted if
the script is meant for a `GET` or a `HEAD` request. This part is required for
any other HTTP method.
+* `{scriptExtension}` - The extension identifying the scripting language used.
This part is mandatory. For more details about the available Script Engines and
their registered extensions check the [Sling
Scripting](/documentation/bundles/scripting.html) page.
+* `{selectorStringPath}` - The selector string converted to a path, along the
lines of `selectorString.replace('.', '/')`. If less selectors are specified in
the script name than given in the request, the script will only be taken into
consideration if the given selectors are the **first** selectors in the
request. This means *sel1/sel2.html.jsp* will be a candidate for the request
url */content/test.sel1.sel2.sel3.html* but not for
*/content/test.sel3.sel1.sel2.html*. So the order of selectors is relevant!
+
+
## Bundled Scripts
-Scripts may also be provided in OSGi bundles (precompiled or embedded) since
[Sling Servlet Resolver
2.7.0](https://github.com/apache/sling-org-apache-sling-servlets-resolver#bundled-scripts).
+Scripts may also be provided in OSGi bundles (precompiled or embedded) since
[Sling Servlet Resolver
2.7.0](https://github.com/apache/sling-org-apache-sling-servlets-resolver#bundled-scripts)
through the org.apache.sling.servlets.resolver.bundle.tracker API in addition
to classical Resource based scripts.
+
+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_;
Review comment:
@oliverlietz, a script or collection of scripts create an HTTP API once
we map a certain content resource to the `resourceType` that would call those
scripts. The HTTP API is defined by:
1. the resource (endpoint) that is accessible:
- the resource path + at least the default extension
- the resource path + any combination of allowed selectors
2. for scripts which can handle more than just the `GET` request, you're
also creating a RESTful API
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
