You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@accumulo.apache.org by ct...@apache.org on 2024/02/13 23:23:57 UTC
(accumulo-access) branch main updated: Fix and simplify javadoc for AccessEvaluator (#52)
This is an automated email from the ASF dual-hosted git repository.
ctubbsii pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/accumulo-access.git
The following commit(s) were added to refs/heads/main by this push:
new 96896b2 Fix and simplify javadoc for AccessEvaluator (#52)
96896b2 is described below
commit 96896b2ea5824ad0150b50c57483954f31b59191
Author: Christopher Tubbs <ct...@apache.org>
AuthorDate: Tue Feb 13 18:23:51 2024 -0500
Fix and simplify javadoc for AccessEvaluator (#52)
* Put class description in first javadoc sentence, followed by example,
followed by note, eliminating unnecessary closing paragraph tags not
needed for HTML5-based javadocs
* Update POM versions and remove multi-module POM stuff, and add
dependency analysis
* Add missing plugin execution for mavanagaiata
---
pom.xml | 69 ++++++++++++++--------
.../apache/accumulo/access/AccessEvaluator.java | 28 ++++-----
2 files changed, 59 insertions(+), 38 deletions(-)
diff --git a/pom.xml b/pom.xml
index 35da9bb..94016ba 100644
--- a/pom.xml
+++ b/pom.xml
@@ -87,6 +87,7 @@
<url>https://github.com/apache/accumulo-access/actions</url>
</ciManagement>
<properties>
+ <extraTestArgs>--add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.util=ALL-UNNAMED --add-opens java.base/java.io=ALL-UNNAMED --add-opens java.base/java.net=ALL-UNNAMED --add-opens java.management/java.lang.management=ALL-UNNAMED --add-opens java.management/sun.management=ALL-UNNAMED --add-opens java.base/java.security=ALL-UNNAMED --add-opens java.base/java.lang.reflect=ALL-UNNAMED --add-opens java.base/java.util.concurrent=ALL-UNNAMED --add-opens java.base/java.ut [...]
<maven.compiler.release>11</maven.compiler.release>
<maven.compiler.source>11</maven.compiler.source>
<maven.compiler.target>11</maven.compiler.target>
@@ -95,7 +96,7 @@
<minimalJavaBuildVersion>17</minimalJavaBuildVersion>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<version.errorprone>2.24.1</version.errorprone>
- <version.jmh>1.36</version.jmh>
+ <version.jmh>1.37</version.jmh>
</properties>
<dependencies>
<dependency>
@@ -113,7 +114,7 @@
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter-api</artifactId>
- <version>5.9.2</version>
+ <version>5.10.2</version>
<scope>test</scope>
</dependency>
<dependency>
@@ -134,12 +135,12 @@
<plugin>
<groupId>com.mycila</groupId>
<artifactId>license-maven-plugin</artifactId>
- <version>4.2</version>
+ <version>4.3</version>
<configuration>
<licenseSets>
<licenseSet>
<header>src/build/license-header.txt</header>
- <excludes combine.children="append">
+ <excludes>
<exclude>contrib/antlr4/src/main/antlr4/Abnf.g4</exclude>
<exclude>**/DEPENDENCIES</exclude>
<exclude>**/LICENSE</exclude>
@@ -148,7 +149,7 @@
</excludes>
</licenseSet>
</licenseSets>
- <mapping combine.children="append">
+ <mapping>
<!-- general mappings; module-specific mappings appear in their respective pom -->
<abnf>SEMICOLON_STYLE</abnf>
<g4>SLASHSTAR_STYLE</g4>
@@ -250,10 +251,27 @@
<javaVersion>${maven.compiler.target}</javaVersion>
</configuration>
</plugin>
+ <plugin>
+ <groupId>com.github.koraktor</groupId>
+ <artifactId>mavanagaiata</artifactId>
+ <version>1.0.1</version>
+ <executions>
+ <execution>
+ <id>git-commit</id>
+ <goals>
+ <goal>commit</goal>
+ </goals>
+ <phase>validate</phase>
+ <configuration>
+ <skipNoGit>true</skipNoGit>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
<plugin>
<groupId>com.github.spotbugs</groupId>
<artifactId>spotbugs-maven-plugin</artifactId>
- <version>4.8.3.0</version>
+ <version>4.8.3.1</version>
<configuration>
<excludeFilterFile>src/build/ci/spotbugs-exclude.xml</excludeFilterFile>
<xmlOutput>true</xmlOutput>
@@ -261,7 +279,7 @@
<failOnError>true</failOnError>
<includeTests>true</includeTests>
<maxRank>20</maxRank>
- <plugins combine.children="append">
+ <plugins>
<plugin>
<groupId>com.h3xstream.findsecbugs</groupId>
<artifactId>findsecbugs-plugin</artifactId>
@@ -278,6 +296,25 @@
</execution>
</executions>
</plugin>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-dependency-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>analyze</id>
+ <goals>
+ <goal>analyze-only</goal>
+ </goals>
+ <configuration>
+ <failOnWarning>true</failOnWarning>
+ <ignoredUnusedDeclaredDependencies>
+ <!-- ignore runtime test dependency for benchmark -->
+ <unused>org.openjdk.jmh:jmh-generator-annprocess:jar:*</unused>
+ </ignoredUnusedDeclaredDependencies>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-checkstyle-plugin</artifactId>
@@ -377,7 +414,7 @@
<dependency>
<groupId>com.puppycrawl.tools</groupId>
<artifactId>checkstyle</artifactId>
- <version>10.12.6</version>
+ <version>10.13.0</version>
</dependency>
</dependencies>
<executions>
@@ -416,9 +453,6 @@
<Sealed>true</Sealed>
</manifestEntries>
</archive>
- <excludes>
- <exclude>**/log4j2-test.properties</exclude>
- </excludes>
</configuration>
</plugin>
<plugin>
@@ -450,7 +484,7 @@
<groupId>org.apache.rat</groupId>
<artifactId>apache-rat-plugin</artifactId>
<configuration>
- <excludes combine.children="append">
+ <excludes>
<exclude>contrib/antlr4/src/main/antlr4/Abnf.g4</exclude>
<exclude>src/test/resources/testdata.json</exclude>
<exclude>**/target/</exclude>
@@ -500,7 +534,6 @@
</property>
</activation>
<properties>
- <accumulo.skip>true</accumulo.skip>
<apilyzer.skip>true</apilyzer.skip>
<checkstyle.skip>true</checkstyle.skip>
<formatter.skip>true</formatter.skip>
@@ -512,7 +545,6 @@
<skipTests>true</skipTests>
<sort.skip>true</sort.skip>
<spotbugs.skip>true</spotbugs.skip>
- <warbucks.skip>true</warbucks.skip>
</properties>
</profile>
<profile>
@@ -700,14 +732,5 @@
</plugins>
</build>
</profile>
- <profile>
- <id>jdk17</id>
- <activation>
- <jdk>[17,)</jdk>
- </activation>
- <properties>
- <extraTestArgs>--add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.util=ALL-UNNAMED --add-opens java.base/java.io=ALL-UNNAMED --add-opens java.base/java.net=ALL-UNNAMED --add-opens java.management/java.lang.management=ALL-UNNAMED --add-opens java.management/sun.management=ALL-UNNAMED --add-opens java.base/java.security=ALL-UNNAMED --add-opens java.base/java.lang.reflect=ALL-UNNAMED --add-opens java.base/java.util.concurrent=ALL-UNNAMED --add-opens java.base/jav [...]
- </properties>
- </profile>
</profiles>
</project>
diff --git a/src/main/java/org/apache/accumulo/access/AccessEvaluator.java b/src/main/java/org/apache/accumulo/access/AccessEvaluator.java
index bb59621..1ea4d23 100644
--- a/src/main/java/org/apache/accumulo/access/AccessEvaluator.java
+++ b/src/main/java/org/apache/accumulo/access/AccessEvaluator.java
@@ -21,31 +21,29 @@ package org.apache.accumulo.access;
import java.util.Collection;
/**
- * <p>
- * Used to decide if an entity with one more sets of authorizations can access zero or more access
- * expressions.
- * </p>
- * <p>
- * Note: For performance improvements, especially in cases where expressions are expected to repeat,
- * it's recommended to wrap this evaluator with an external caching mechanism, such as Guava's
- * cache, to leverage its extensive caching options. Caching is only safe under the assumption that
- * for an AccessEvaluator instance, evaluating the same expression multiple times will always yield
- * the same result. When considering caching, any environmental factors that might change this
- * assumption may need to be mitigated.
- * </p>
+ * This class is used to decide if an entity with a given set of authorizations can access
+ * subsequent access expressions.
*
- * Below is an example that should print false and then print true.
+ * <p>
+ * For example:
*
* <pre>
* {@code
* var evaluator = AccessEvaluator.of("ALPHA", "OMEGA");
*
- * System.out.println(evaluator.canAccess("ALPHA&BETA"));
- * System.out.println(evaluator.canAccess("(ALPHA|BETA)&(OMEGA|EPSILON)"));
+ * System.out.println(evaluator.canAccess("ALPHA&BETA")); // should print 'false'
+ * System.out.println(evaluator.canAccess("(ALPHA|BETA)&(OMEGA|EPSILON)")); // should print 'true'
* }
* </pre>
*
* <p>
+ * Note: for performance, especially in cases where expressions are expected to repeat, it's
+ * recommended to cache the results of these evaluations. Caching is only safe under the assumption
+ * that for an AccessEvaluator instance, evaluating the same expression multiple times will always
+ * yield the same result. When considering caching, any environmental factors that might change this
+ * assumption may need to be mitigated.
+ *
+ * <p>
* Instances of this class are thread-safe.
*
* <p>