This is an automated email from the ASF dual-hosted git repository. reschke pushed a commit to branch SLING-12641 in repository https://gitbox.apache.org/repos/asf/sling-site.git
commit f495293b3d5501212db7eb9d6b0cc6b1a0e14c74 Author: Julian Reschke <[email protected]> AuthorDate: Fri Jan 31 10:22:26 2025 +0100 SLING-12641: Site: update alias/vanityPath documentation --- .../the-sling-engine/mappings-for-resource-resolution.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/src/main/jbake/content/documentation/the-sling-engine/mappings-for-resource-resolution.md b/src/main/jbake/content/documentation/the-sling-engine/mappings-for-resource-resolution.md index f6d6c3da3..0a8dc0d22 100644 --- a/src/main/jbake/content/documentation/the-sling-engine/mappings-for-resource-resolution.md +++ b/src/main/jbake/content/documentation/the-sling-engine/mappings-for-resource-resolution.md @@ -265,13 +265,15 @@ The String Interpolation works with any part of the etc-map tree. The property `sling:alias` may be set on any resource to indicate an alias name for the resource. For example the resource `/content/visitors` may have the `sling:alias` property set to `besucher` allowing the resource to be addressed in an URL as `/content/besucher` as well as the original path `/content/visitors`. The property `sling:alias` may have multiple values. The first value is used for outgoing mapping, i.e. is the *preferred name* used in links generated by Sling. +Aliases are roughly similar to POSIX hard links, restricted to simple names (no paths). + The following characters are not allowed in `sling:alias` values: `/?#`. Using any of those characters somewhere in the value makes Sling disregard the alias mapping. In addition the aliases `.`, `..` and the empty string are invalid. Invalid aliases are logged with WARN level. ### Impact of Alias Handling In general, the number of aliases have a direct impact on the performance of the resource resolution - as basically all possible permutations of paths for a resource have to be tested against the incoming request path. By default a cache is used to speed up handling aliases during resolving resources. It is highly recommended to have this cache enabled to avoid slowing down request performance. However, the cache might have an impact on startup time and on the alias update time if the nu [...] -The cache can be disabled by setting the property `resource.resolver.optimize.alias.resolution` of the OSGi configuration `org.apache.sling.jcr.resource.internal.JcrResourceResolverFactoryImpl` to `false`. +The cache can be disabled by setting the property `resource.resolver.optimize.alias.resolution` of the OSGi configuration `org.apache.sling.jcr.resource.internal.JcrResourceResolverFactoryImpl` to `false`. Note that this is not recommended because of the aforementioned performance issues and also minor differences in behavior (see [SLING-12025](https://issues.apache.org/jira/browse/SLING-12025)). ### Limitation of `sling:alias` for Principal with a limited access @@ -289,16 +291,16 @@ Instead if the `sling:alias` property is set in any resource under `/content` (e While an alias can provide a variation for a resource name, a vanity path can provide an alternative path for a resource. The following properties can be set on a resource: * `sling:vanityPath` – This property when set on any resource defines an alternative path to address the resource. -* `sling:redirect` – This boolean property when set to `true` on a resource with a vanity path causes a redirect response to be sent to the client, which causes the client to send in a new request with the modified location. The value of the `sling:vanityPath` property is applied to the actual request and sent back as the value of the `Location` response header field. +* `sling:redirect` – This boolean property when set to `true` on a resource with a vanity path causes an HTTP redirect response to be sent to the client, which causes the client to send in a new request with the modified location. The value of the `sling:vanityPath` property is applied to the actual request and sent back as the value of the `Location` response header field. * `sling:redirectStatus` – This property defines the HTTP status code sent to the client with the `sling:redirect` response. If this property is not set, it defaults to 302 (Found). Other status codes supported are 300 (Multiple Choices), 301 (Moved Permanently), 303 (See Other), 307 (Temporary Redirect), and 308 (Permanent Redirect). * `sling:vanityOrder` – It might happen that several resources in the resource tree specify the same vanity path. In that case the one with the highest order is used. This property can be used to set such an order. +Vanity Paths are similar to symbolic links in POST systems. + ### Rebuilding The Vanity Bloom Filter [SLING-4216](https://issues.apache.org/jira/browse/SLING-4216) introduced the usage of a bloom filter in order to resolve long startup time with many vanityPath entries. -The bloom filter is handled automatically by the Sling framework. In some cases though, as changing the maximum number of vanity bloom filter bytes, a rebuild of the vanity bloom filter is needed. - -In order to rebuild vanity bloom filter you need to stop and restart Apache Sling (this might take few minutes, depending on how many vanity path entries are present) +The bloom filter is handled automatically by the Sling framework. ## Interactions between mappings and authentication requirements
