Merge pull request #50 from bkoehm/bkoehm.5.0.x

Grails 7 #46: update documentation
grails · Dec 9, 2024 · dfc6776 · dfc6776
2 parents 67f313d + 9145751
commit dfc6776
Show file tree

Hide file tree

Showing 21 changed files with 151 additions and 85 deletions.
diff --git a/README.md b/README.md
@@ -8,4 +8,45 @@ See [documentation](https://grails-plugins.github.io/grails-spring-security-acl/
 
 To run the tests exeucte: 
 
-`./gradlew -Dgeb.env=chromeHeadless check`
+`./gradlew -Dgeb.env=chromeHeadless check`
+
+## v5.0.0 changes
+
+### Caching
+
+The default cache manager has changed to
+[JCacheCacheManager](https://docs.spring.io/spring-framework/docs/6.2.0/javadoc-api/org/springframework/cache/jcache/JCacheCacheManager.html).
+
+### Method parameter discovery
+
+The behavior of parameter discovery has changed to align with
+[Spring Security 6 default](https://docs.spring.io/spring-security/site/docs/6.4.1/api//org/springframework/security/core/parameters/DefaultSecurityParameterNameDiscoverer.html)
+behavior.  This may require code changes if you are utilizing ACL
+annotations that reference method parameters.  You will need to add the
+[P](https://docs.spring.io/spring-security/site/docs/6.4.1/api/org/springframework/security/core/parameters/P.html)
+annotation to reference method parameters.  This is documented in the
+Spring Security reference doc under the
+[Using Method Parameters](https://docs.spring.io/spring-security/reference/servlet/authorization/method-security.html#using_method_parameters)
+section.
+
+Previously if you had code similar to:
+```
+@PreAuthorize("hasPermission(#contract, 'write')")
+public void updateContact(Contact contact) {
+    ...
+}
+```
+
+This should be changed to:
+
+```
+import org.springframework.security.core.parameters.P
+
+@PreAuthorize("hasPermission(#contract, 'write')")
+public void updateContact(@P("contract") Contact contact) {
+    ...
+}
+```
+
+Since parameter `contract` is referenced in the `@PreAuthorize` annotation, it
+should now be annotated with `@P`.
diff --git a/docs/build.gradle b/docs/build.gradle
@@ -54,6 +54,10 @@ asciidoctor {
     }
     outputDir = new File(buildDir, 'docs')
     attributes asciidoctorAttributes
+    executionMode = 'JAVA_EXEC'
+    forkOptions {
+        jvmArgs "--add-opens", "java.base/sun.nio.ch=ALL-UNNAMED", "--add-opens", "java.base/java.io=ALL-UNNAMED"
+    }
 }
 
 asciidoctorPdf {
@@ -63,6 +67,10 @@ asciidoctorPdf {
         include 'index.adoc'
     }
     outputDir = new File(buildDir, 'docs')
+    executionMode = 'JAVA_EXEC'
+    forkOptions {
+        jvmArgs "--add-opens", "java.base/sun.nio.ch=ALL-UNNAMED", "--add-opens", "java.base/java.io=ALL-UNNAMED"
+    }
 
     asciidoctorj {
         requires 'rouge'
@@ -77,6 +85,10 @@ asciidoctorEpub {
         include 'index.adoc'
     }
     outputDir = new File(buildDir, 'docs')
+    executionMode = 'JAVA_EXEC'
+    forkOptions {
+        jvmArgs "--add-opens", "java.base/sun.nio.ch=ALL-UNNAMED", "--add-opens", "java.base/java.io=ALL-UNNAMED"
+    }
 
     asciidoctorj {
         requires 'rouge'

diff --git a/docs/src/docs/AclUtilService/addPermission.adoc b/docs/src/docs/AclUtilService/addPermission.adoc
@@ -7,7 +7,7 @@ Grant a permission on a domain object instance to a recipient.
 
 .Examples
 
-[source,java]
+[source,groovy]
 ----
 aclUtilService.addPermission Report, 1124, 'user123', BasePermission.WRITE
 
@@ -18,7 +18,7 @@ aclUtilService.addPermission reportInstance, 'user123', BasePermission.WRITE
 
 `addPermission` has three signatures:
 
-[source,java]
+[source,groovy]
 ----
 void addPermission(Class<?> domainClass, long id, recipient, Permission permission)
 

diff --git a/docs/src/docs/AclUtilService/changeOwner.adoc b/docs/src/docs/AclUtilService/changeOwner.adoc
@@ -7,14 +7,14 @@ Change the ACL owner for a domain class instance.
 
 .Examples
 
-[source,java]
+[source,groovy]
 ----
 aclUtilService.changeOwner reportInstance, 'user123'
 ----
 
 .Description
 
-[source,java]
+[source,groovy]
 ----
 void changeOwner(domainObject, String newUsername)
 ----

diff --git a/docs/src/docs/AclUtilService/deleteAcl.adoc b/docs/src/docs/AclUtilService/deleteAcl.adoc
@@ -7,14 +7,14 @@ Deletes the ACL for a domain class instance.
 
 .Examples
 
-[source,java]
+[source,groovy]
 ----
 aclUtilService.deleteAcl reportInstance
 ----
 
 .Description
 
-[source,java]
+[source,groovy]
 ----
 void deleteAcl(domainObject)
 ----

diff --git a/docs/src/docs/AclUtilService/deletePermission.adoc b/docs/src/docs/AclUtilService/deletePermission.adoc
@@ -7,7 +7,7 @@ Removes a granted permission.
 
 .Examples
 
-[source,java]
+[source,groovy]
 ----
 aclUtilService.deletePermission Report, 42, 'user123', BasePermission.WRITE
 
@@ -16,7 +16,7 @@ aclUtilService.deletePermission reportInstance, 'user123', BasePermission.WRITE
 
 .Description
 
-[source,java]
+[source,groovy]
 ----
 void deletePermission(domainObject, recipient, Permission permission)
 

diff --git a/docs/src/docs/AclUtilService/hasPermission.adoc b/docs/src/docs/AclUtilService/hasPermission.adoc
@@ -7,7 +7,7 @@ Check if the authentication has grants for the specified permission(s) on the do
 
 .Examples
 
-[source,java]
+[source,groovy]
 ----
 if (aclUtilService.hasPermission(auth, reportInstance, BasePermission.WRITE)) {
    ...
@@ -16,7 +16,7 @@ if (aclUtilService.hasPermission(auth, reportInstance, BasePermission.WRITE)) {
 
 .Description
 
-[source,java]
+[source,groovy]
 ----
 boolean hasPermission(Authentication authentication, domainObject, Permission... permissions)
 

diff --git a/docs/src/docs/AclUtilService/readAcl.adoc b/docs/src/docs/AclUtilService/readAcl.adoc
@@ -7,7 +7,7 @@ Retrieves the ACL for a domain class instance.
 
 .Examples
 
-[source,java]
+[source,groovy]
 ----
 def acl = aclUtilService.readAcl(reportInstance)
 
@@ -16,7 +16,7 @@ def acl = aclUtilService.readAcl(Report, 42)
 
 .Description
 
-[source,java]
+[source,groovy]
 ----
 Acl readAcl(domainObject)
 

diff --git a/docs/src/docs/TagLibraries/notPermitted.adoc b/docs/src/docs/TagLibraries/notPermitted.adoc
@@ -9,7 +9,7 @@ Renders the body if the user is not granted the specified permission(s)
 
 Single String:
 
-[source,html]
+[source,xml]
 ----
 <sec:notPermitted className='com.foo.Report' id='${reportId}' permission='read'>
 
@@ -20,7 +20,7 @@ the body content
 
 Multiple String:
 
-[source,html]
+[source,xml]
 ----
 <sec:notPermitted className='com.foo.Report' id='${reportId}' permission='read,write'>
 
@@ -31,7 +31,7 @@ the body content
 
 Single Permission:
 
-[source,html]
+[source,xml]
 ----
 <%@ page import="org.springframework.security.acls.domain.BasePermission" %>
 
@@ -44,7 +44,7 @@ the body content
 
 List of Permission:
 
-[source,html]
+[source,xml]
 ----
 <%@ page import="org.springframework.security.acls.domain.BasePermission" %>
 
@@ -57,7 +57,7 @@ the body content
 
 Single mask int:
 
-[source,html]
+[source,xml]
 ----
 <sec:notPermitted className='com.foo.Report' id='${reportId}' permission='${1}'>
 
@@ -68,7 +68,7 @@ the body content
 
 Multiple mask int:
 
-[source,html]
+[source,xml]
 ----
 <sec:notPermitted className='com.foo.Report' id='${reportId}' permission='2,1'>
 

diff --git a/docs/src/docs/TagLibraries/permitted.adoc b/docs/src/docs/TagLibraries/permitted.adoc
@@ -9,7 +9,7 @@ Renders the body if the user is granted the specified permission(s)
 
 Single String:
 
-[source,html]
+[source,xml]
 ----
 <sec:permitted className='com.foo.Report' id='${reportId}' permission='read'>
 
@@ -20,7 +20,7 @@ the body content
 
 Multiple String:
 
-[source,html]
+[source,xml]
 ----
 <sec:permitted className='com.foo.Report' id='${reportId}' permission='write,read'>
 
@@ -31,7 +31,7 @@ the body content
 
 Single Permission:
 
-[source,html]
+[source,xml]
 ----
 <%@ page import="org.springframework.security.acls.domain.BasePermission" %>
 
@@ -44,7 +44,7 @@ the body content
 
 List of Permission:
 
-[source,html]
+[source,xml]
 ----
 <%@ page import="org.springframework.security.acls.domain.BasePermission" %>
 
@@ -57,7 +57,7 @@ the body content
 
 Single mask int:
 
-[source,html]
+[source,xml]
 ----
 <sec:permitted className='com.foo.Report' id='${reportId}' permission='${1}'>
 
@@ -68,7 +68,7 @@ the body content
 
 Multiple mask int:
 
-[source,html]
+[source,xml]
 ----
 <sec:permitted className='com.foo.Report' id='${reportId}' permission='2,1'>
 

diff --git a/docs/src/docs/installing.adoc b/docs/src/docs/installing.adoc
@@ -9,20 +9,31 @@ Add an entry in the dependencies block of your `build.gradle file, changing the
 ----
 dependencies {
    ...
-   compile 'org.grails.plugins:spring-security-acl:{projectVersion}'
+   implementation 'org.grails.plugins:spring-security-acl:{projectVersion}'
    ...
 ----
 
 Different Branches are built for different versions of Grails
 
-* master: Grails 4
-* 3.3.x: Grails 3.3+
+* 5.0.x: Grails 7
+* 4.0: Grails 4 through Grails 6
+* 3.3.x: Grails 3.3
 * grails_32: Grails 3.2
 * 2.x: Grails 2
 
 
-Current version (master) is for Grails 4 only.
-Previous version (3.3.x) is only compatible with Grails 3.3.x or higher.
+Current version (5.0.x) is for Grails 7 only.
+
+For Grails 3.3.x use:
+
+[source, groovy]
+.build.gradle
+----
+dependencies {
+   ...
+   implementation 'org.grails.plugins:spring-security-acl:3.2.1'
+   ...
+----
 
 For previous Grails 3 versions ( 3.0.x, 3.1.x and 3.2.x ) use:
 
@@ -31,7 +42,7 @@ For previous Grails 3 versions ( 3.0.x, 3.1.x and 3.2.x ) use:
 ----
 dependencies {
    ...
-   compile 'org.grails.plugins:spring-security-acl:3.1.1'
+   implementation 'org.grails.plugins:spring-security-acl:3.1.1'
    ...
 ----
 

diff --git a/docs/src/docs/installing/distribution.adoc b/docs/src/docs/installing/distribution.adoc
@@ -1,5 +1,5 @@
 [[Distribution]]
 === Distribution
 
-Grails Spring Security ACL plugin is https://bintray.com/grails/plugins/spring-security-acl[distributed in bintray].
+Grails Spring Security ACL plugin is https://repo.grails.org/ui/native/core/org/grails/plugins/spring-security-acl/[distributed in repo.grails.org].
 
diff --git a/docs/src/docs/installing/snapshots.adoc b/docs/src/docs/installing/snapshots.adoc
@@ -1,11 +1,11 @@
 [[Snapshots]]
 === Snapshots
 
-Snapshots are published automatically to https://oss.jfrog.org/[Artifactory OSS] on every successful build.
+Snapshots are published automatically to https://repo.grails.org/ui/native/core/org/grails/plugins/spring-security-acl/[repo.grails.org] on every successful build.
 You can use them by defining this Maven repository inside
 the `repositories` block in your `build.gradle`:
 
 [source, groovy]
 ----
-maven { url "https://oss.jfrog.org/artifactory/oss-snapshot-local" }
+maven { url "https://repo.grails.org/grails/core" }
 ----
diff --git a/docs/src/docs/introduction.adoc b/docs/src/docs/introduction.adoc
@@ -1,10 +1,10 @@
 [[introduction]]
 == Introduction to the Spring Security ACL Plugin
 
-The ACL plugin adds Domain Object Security support to a Grails application that uses Spring Security. It depends on the http://grails.org/plugin/spring-security-core[Spring Security Core plugin].
+The ACL plugin adds Domain Object Security support to a Grails application that uses Spring Security. It depends on the https://github.com/grails/grails-spring-security-core[Spring Security Core plugin].
 
 The core plugin and other extension plugins support restricting access to URLs via rules that include checking a user's authentication status, roles, etc. and the ACL plugin extends this by adding support for restricting access to individual domain class instances. The access can be very fine-grained and can define which actions can be taken on an object - these typically include Read, Create, Write, Delete, and Administer but you're free to define whatever actions you like.
 
 To learn about using ACLs in Grails, you can follow the <<tutorial>> and in addition you can download and run a complete Grails application that uses the plugin. Installing and running the application are described in <<sampleApp>>.
 
-In addition to this document, you should read the http://docs.spring.io/spring-security/site/docs/5.0.x/reference/htmlsingle/#domain-acls[Spring Security documentation].
+In addition to this document, you should read the https://docs.spring.io/spring-security/reference/servlet/authorization/acls.html[Spring Security documentation].