This is an automated email from the ASF dual-hosted git repository.
kwin pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sling-site.git
The following commit(s) were added to refs/heads/master by this push:
new 8e38cdf SLING-7975 document ordering of resources (#72)
8e38cdf is described below
commit 8e38cdf6c10d00dc12500a095a9c5ff3c22cdafb
Author: Konrad Windszus <[email protected]>
AuthorDate: Thu Nov 4 15:26:13 2021 +0100
SLING-7975 document ordering of resources (#72)
---
.../bundles/resource-access-security.md | 86 +++++++++++-----------
.../the-sling-engine/sling-api-crud-support.md | 66 +++++++++++------
2 files changed, 85 insertions(+), 67 deletions(-)
diff --git
a/src/main/jbake/content/documentation/bundles/resource-access-security.md
b/src/main/jbake/content/documentation/bundles/resource-access-security.md
index f19e9f5..c7901ad 100644
--- a/src/main/jbake/content/documentation/bundles/resource-access-security.md
+++ b/src/main/jbake/content/documentation/bundles/resource-access-security.md
@@ -3,52 +3,42 @@ type=page
status=published
tags=security
~~~~~~
-Notice: Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
- .
- http://www.apache.org/licenses/LICENSE-2.0
- .
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-## Summary
-The ResourceAccessSecurity service allows it to restrict access to resources.
The access can be granted or denied for read, create, update and delete actions.
+# Summary
-The ResourceAccessSecurity defines a service API which is used in two
different context: for securing resource providers which have no own access
control and on the application level to further restrict the access to
resources in general.
+The `ResourceAccessSecurity` service allows to restrict access to resources.
The access can be granted or denied for read, create, update, delete and order
resources actions.
-A resource access security service is registered with the service property
“context”. Allowed values are “application” and “provider”. If the value is
missing or invalid, the service will be ignored.
+The `ResourceAccessSecurity` interface defines a service API which is used in
two different context:
-In the context of resource providers, this service might be used for
implementations of resource providers where the underlying persistence layer
does not implement access control. The goal is to make it easy to implement a
lightweight access control for such providers. For example, a JCR resource
providers should not use the provider context resource access security - in a
JCR context, security is fully delegated to the underlying repository, and
mixing security models would be a bad idea.
+1. for securing resource providers which have no own access control and
+2. on the application level to further restrict the access to resources in
general.
-In the context of the application, this service might be used to add
additional or temporary constraints across the whole resource tree.
+A resource access security service is registered with the service property
`context`. Allowed values are `application` and `provider`. If the value is
missing or invalid, the service will be ignored.
-## How to use ResourceAccessSecurity
-To use the ResourceAccessSecurity service you don’t have to implement the
interface ResourceAccessSecurity. Simply add the resourceaccesssecurity bundle
to your sling instance. This adds an implementation of the
ResourceAccessSecurity service for the provider context (“provider”) and also
the application context (“application”).
+In the context of resource providers, this service might be used for those
providers where the underlying persistence layer does not implement access
control. The goal is to make it easy to implement a lightweight access control
for such providers. On the other hand a JCR resource providers should not use
the provider context resource access security - in a JCR context, security is
fully delegated to the underlying repository, and mixing security models would
be a bad idea.
-Furthermore the implementation of ResourceAccessSecurity defines a service
provider interface named ResourceAccessGate. This is the service interface
which you can implement and register to control the access to the resources.
+In the context of the application, this service might be used to add
additional or temporary constraints across the whole resource tree. It is
automatically called by the Resource Resolver implementation.
-The ResourceAccessGate defines a service API which can be used to make some
restrictions to accessing resources. Implementations of this service interface
must be registered like ResourceProvider with a path (like provider.roots but
with the property name “path”). If different ResourceAccessGate services match
a path, not only the ResourceAccessGate with the longest path will be called,
but all of them, that's in contrast to the ResourceProvider, but in this case
more logical (and secure [...]
+# Default Implementation
-### Service properties
+To use the `ResourceAccessSecurity` service just rely on the default
implementation provided by the [`resourceaccesssecurity
`bundle][resourceaccesssecurity]. This adds an implementation of the
`ResourceAccessSecurity` service for the provider context (`provider`) and also
the application context (`application`).
-Property name | description
------------------ | -----------------------
-Path | regexp to define on which paths the service should be
called (default .*)
-operations | set of operations on which the service should be called
("read,create,update,delete,execute", default all of them)
-finaloperations | set of operations on which the service answer is final and
no further service should be called (default none of them), except the
GateResult is GateResult.CANT_DECIDE
-context | “provider” or “application”. The resource access gate can
either have the context “provider”, in this case the gate is only applied to
resource providers requesting the security checks. Or the context can be
“application”. In this case the access gate is invoked for the whole resource
tree. This is indicated by the required service property “context”. If the
property is missing or invalid, the service is ignored.
+Furthermore this implementation of `ResourceAccessSecurity` defines a service
provider interface (SPI) named `ResourceAccessGate`. This is the service
interface which you can implement and register to control the access to
particular resources.
-### How to implement ResourceAccessGate
-The implementation is straightforward. The easiest way is to extend `
AllowingResourceAccessGate ` which is exported by the resourceaccesssecurity
bundle and does not deny any access. So if you wan’t restrict access on
resources for read operations you have to implement to following two methods:
+The `ResourceAccessGate` interface defines an SPI which can be used to make
some restrictions for accessing resources. Implementations of this service
interface must be registered like `ResourceProvider`s with a path (like
`provider.roots` but with the property name `path`). If multiple
`ResourceAccessGate` services match a path, not only the `ResourceAccessGate`
with the longest path will be called, but all of them. That is different from
the ResourceProvider logic, but in this case mor [...]
+
+## Service properties for `ResourceAccessGate` services
+
+Name | Description | Default
+----------------- | -------------| -----
+`path` | Regular expression to restrict on which paths the
service should be called | `.*`
+`operations` | Set of operations on which the service should be called.
Allowed string values:
`read`,`create`,`update`,`delete`,`execute`,`order-children`. The value
`order-children` is only supported since version 1.1.0
([SLING-7975](https://issues.apache.org/jira/browse/SLING-7975)) | `{
"read","create","update","delete","execute","order-children"}` (all operations)
+`finaloperations` | Set of operations on which the service answer is final
and no further service should be called, except the GateResult is
GateResult.CANT_DECIDE. Allows the same values as `operations`. | (none)
+`context` | The resource access gate can either have the context
`provider` in which case the gate is only applied to resource providers
requesting the security checks or the context `application` in which case the
access gate is invoked for the whole resource tree. If the property is missing
or invalid, the service is ignored. | (none)
+
+## How to implement `ResourceAccessGate`
+
+The implementation is straightforward: The easiest way is to extend `
AllowingResourceAccessGate ` which is exported by the `resourceaccesssecurity`
bundle and does not deny any access. So if you want to restrict access on
resources for read operations you have to implement to following two methods:
::java
@Override
@@ -69,18 +59,28 @@ The implementation is straightforward. The easiest way is
to extend ` AllowingRe
return returnValue;
}
-And you have to register the ResourceAccessGate with the path where you wan’t
to restrict access and the operation property set to “read”. Furthermore you
have to decide if the ResourceAccessGate should operate on all resource
providers (context=”application”) or only on the resourceproviders flagged with
the property useResourceAccessSecurity=true (context=”provider”).
+You have to register the `ResourceAccessGate` with service properties outlined
above.
Tip: We do not recommend to mix up application and provider context in the
same application. This can lead to confusing configurations in the
ResourceAccessGate implementations.
-### GateResult
+## GateResult
+
GateResult does have three states:
- - GateResult.GRANTED
- - GateResult.DENIED
- - GateResult.CANT_DECIDE
+ 1. `GateResult.GRANTED`
+ 2. `GateResult.DENIED`
+ 3. `GateResult.CANT_DECIDE`
+
+The first two of them are self-explanatory. `CANT_DECIDE` means that the
actual gate neither can grant nor deny the access. If no other gate does return
`GRANTED` or `DENIED` the access to the resource will be denied for security
reasons. `CANT_DECIDE` comes handy if you declare `finaloperations` (where no
other gate will be called after this gate). If such a gate returns
`CANT_DECIDE`, further gates will be called regardless of the `finaloperations`
property.
+
+## `ResourceAccessGates` Implementations
+
+There is an implementation of `ResourceAccessGate` provided by [bundle
`org.apache.sling.jcr.resourcesecurity`][jcr-resourcesecurity] which
grants/denies access based on the permissions set on a JCR node. *This should
only be used for paths not provided by the JCR Resource Provider*. It is
implemented as service factory so each OSGi configuration provides a dedicated
`ResourceAccessGate` service.
+
+## Limitations
+
+By now the implementation is complete for securing access on resource level
for CRUD operations. It is not yet ready to allow fine granular access rights
on properties/values of a resource. So at the moment the `canReadValue,
canUpdateValue, canDeleteValue` and `canCreateValue` on `ResourceAccessGate`
methods are ignored
([SLING-10906](https://issues.apache.org/jira/browse/SLING-10906)).
-The first two of them are self-explanatory. CANT_DECIDE means that the actual
gate neither can grant nor deny the access. If no other gate does return
GRANTED or DENIED the access to the resource will be denied for security
reasons. CANT-DECIDE comes handy if you declare finaloperations (where no other
gate will be called after this gate). If such a gate returns CANT_DECIDE,
further gates will be called regardless of the setted finaloperations property.
-## Actual state of ResourceAccessSecurity
-By now the implementation is complete for securing access on resource level
for CRUD operations. It is not yet ready to allow fine granular access rights
on values of a resource. So at the moment the `canReadValue, canUpdateValue,
canDeleteValue` and `canCreateValue` on `ResourceAccessGate` methods are
ignored.
+[jcr-resourcesecurity]:
https://github.com/apache/sling-org-apache-sling-jcr-resourcesecurity
+[resourceaccesssecurity]:
https://github.com/apache/sling-org-apache-sling-resourceaccesssecurity
\ No newline at end of file
diff --git
a/src/main/jbake/content/documentation/the-sling-engine/sling-api-crud-support.md
b/src/main/jbake/content/documentation/the-sling-engine/sling-api-crud-support.md
index 3d6fd1e..771ce2a 100644
---
a/src/main/jbake/content/documentation/the-sling-engine/sling-api-crud-support.md
+++
b/src/main/jbake/content/documentation/the-sling-engine/sling-api-crud-support.md
@@ -6,26 +6,27 @@ tags=api,core
[TOC]
-## Apache Sling API Support
+# Apache Sling API Support
As of version 2.3.0, the Sling API provides full Create Read Update Delete
(CRUD) features. CRUD support is provided by the addition of the following
methods to the ResourceResolver:
- * [void delete(Resource resource) throws
PersistenceException](https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#delete-org.apache.sling.api.resource.Resource-)
- * [Resource create(Resource parent, String name, Map<String, Object>
properties) throws
PersistenceException](https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#create-org.apache.sling.api.resource.Resource-java.lang.String-java.util.Map-)
- * [void
revert()](https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#revert--)
- * [void commit() throws
PersistenceException](https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#commit--)
- * [boolean
hasChanges()](https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#hasChanges--)
- * [void
refresh()](https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#refresh--)
+ * [`void delete(Resource resource) throws
PersistenceException`](https://sling.apache.org/apidocs/sling11/org/apache/sling/api/resource/ResourceResolver.html#delete-org.apache.sling.api.resource.Resource-)
+ * [`Resource create(Resource parent, String name, Map<String, Object>
properties) throws
PersistenceException`](https://sling.apache.org/apidocs/sling11/org/apache/sling/api/resource/ResourceResolver.html#create-org.apache.sling.api.resource.Resource-java.lang.String-java.util.Map-)
+ * [`void
revert()`](https://sling.apache.org/apidocs/sling11/org/apache/sling/api/resource/ResourceResolver.html#revert--)
+ * [`void commit()` throws
PersistenceException](https://sling.apache.org/apidocs/sling11/org/apache/sling/api/resource/ResourceResolver.html#commit--)
+ * [`boolean
hasChanges()`](https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#hasChanges--)
+ * [`void
refresh()`](https://sling.apache.org/apidocs/sling11/org/apache/sling/api/resource/ResourceResolver.html#refresh--)
+ * `orderBefore(Resource parent, String name, String followingSiblingName)
throws UnsupportedOperationException, PersistenceException,
IllegalArgumentException`(since [API
2.24.0](https://issues.apache.org/jira/browse/SLING-7975))
-Which provide the ability to create and delete resources as well as the
addition of the ModifiableValueMap interface which is similar to the ValueMap
interface, but allows for updating properties on a resource.
+Those methods provide the ability to create and delete resources as well. In
addition you can adapt a `Resource` to a `ModifiableValueMap` interface which
is similar to the `ValueMap` interface, but allows for updating properties on a
resource.
-## Comparing Sling API CRUD to Sling Post Servlet
+# Examples
Here are some examples of common operations performed using the Sling Post
Servlet and Sling API CRUD support. Note, the examples are derived from the
cheat sheet in Adobe's AEM documentation at
[https://experienceleague.adobe.com/docs/experience-manager-cloud-service/implementing/developing/full-stack/sling-cheatsheet.html](https://experienceleague.adobe.com/docs/experience-manager-cloud-service/implementing/developing/full-stack/sling-cheatsheet.html).
-### Updating a Property
+## Updating a Property
-Update /myresource, setting the title and body:
+Update `/myresource`, setting the title and body:
**Sling Post Servlet**
@@ -42,9 +43,9 @@ Update /myresource, setting the title and body:
properties.put("body", {BODY});
resourceResolver.commit();
-### Create New Resource
+## Create New Resource
-Create a new resource below /myresource
+Create a new resource below `/myresource`
**Sling Post Servlet**
@@ -61,7 +62,7 @@ Create a new resource below /myresource
Resource dummy = resourceResolver.create(myResource, "dummy", properties);
resourceResolver.commit();
-### Remove a Property
+## Remove a Property
Remove the property title
@@ -78,9 +79,9 @@ Remove the property title
properties.remove("title");
resourceResolver.commit();
-### Copy a Resource
+## Copy a Resource
-Copy the resource /myresource to /myresource2
+Copy the resource `/myresource` to `/myresource2`
**Sling Post Servlet**
@@ -96,9 +97,9 @@ Copy the resource /myresource to /myresource2
Resource myResource2 = resourceResolver.create(null, "myresource2",
properties);
resourceResolver.commit();
-### Move a Resource
+## Move a Resource
-Move the resource /myresource2 to /myresource3
+Move the resource `/myresource2` to `/myresource3`
**Sling Post Servlet**
@@ -115,7 +116,7 @@ Move the resource /myresource2 to /myresource3
resourceResolver.delete(myResource2);
resourceResolver.commit();
-### Setting non-String Value
+## Setting non-String Value
Set the property date to a particular date
@@ -134,9 +135,9 @@ Set the property date to a particular date
properties.put("date", calendar);
resourceResolver.commit();
-### Delete a Resource
+## Delete a Resource
-Delete the resource /myresource
+Delete the resource `/myresource`
**Sling Post Servlet**
@@ -150,18 +151,35 @@ Delete the resource /myresource
resourceResolver.delete(myResource);
resourceResolver.commit();
-## Value Class Support
+## Order a Resource
+
+Reorder the resource `/myresource` before sibling node `child1`
+
+**Sling Post Servlet**
+
+ <form action="/myresource" method="POST">
+ <input type="hidden" name=":order" value="before child1">
+ </form>
+
+**Sling API CRUD**
+
+ Resource myResource = resourceResolver.getResource("/");
+ resourceResolver.orderBefore(myResource, "myresource", "child1");
+ resourceResolver.commit();
+
+
+# Value Class Support
<div class="info">
Please note, this information is specific to the Sling JCR Resource
implementation provided by the Apache Sling project. Other implementations may
have different value class support.
</div>
-The Classes implementing the following types are supported directly when
setting properties:
+The classes implementing the following types are supported directly when
setting properties:
* [Calendar](http://docs.oracle.com/javase/8/docs/api/java/util/Calendar.html)
*
[InputStream](http://docs.oracle.com/javase/8/docs/api/java/io/InputStream.html)
- *
[Node](http://www.day.com/maven/javax.jcr/javadocs/jcr-2.0/javax/jcr/Node.html)
+ * [Node](https://s.apache.org/jcr-2.0-javadoc/javax/jcr/Node.html)
*
[BigDecimal](http://docs.oracle.com/javase/8/docs/api/java/math/BigDecimal.html)
* [Long](http://docs.oracle.com/javase/8/docs/api/java/lang/Long.html)
* [Short](http://docs.oracle.com/javase/8/docs/api/java/lang/Short.html)
