Upgrade to Java 21 and Remove asciidoclet

.github/workflows/codeql-legacy.yml

@@ -0,0 +1,39 @@
+name: "CodeQL Legacy"
+
+on:
+  push:
+    branches: [ "1.0", "2.0", "2.1", "2.2", "2.3", "2.4", "2.4.1", "2.4.2", "3.0", "3.0.1", "3.1" ]
+  schedule:
+    - cron: "42 11 * * 6"
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ java ]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: ${{ matrix.language }}
+          queries: +security-and-quality
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v3
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3
+        with:
+          category: "/language:${{ matrix.language }}"

.github/workflows/codeql.yml

@@ -2,7 +2,7 @@ name: "CodeQL"
 
 on:
   push:
-    branches: [ "main", "1.0", "2.0", "2.1", "2.2", "2.3", "2.4", "2.4.1", "2.4.2", "3.0", "3.0.1", "3.1" ]
+    branches: [ "main" ]
   pull_request:
     branches: [ "main" ]
   schedule:
@@ -25,17 +25,23 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v3
+      - uses: actions/[email protected]
+      - name: Set up Java
+        uses: actions/[email protected]
+        with:
+          java-version: '21'
+          distribution: 'zulu'
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v2
+        uses: github/codeql-action/init@v3
         with:
           languages: ${{ matrix.language }}
           queries: +security-and-quality
 
       - name: Autobuild
-        uses: github/codeql-action/autobuild@v2
+        uses: github/codeql-action/autobuild@v3
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v2
+        uses: github/codeql-action/analyze@v3
         with:
           category: "/language:${{ matrix.language }}"

.github/workflows/maven.yml

@@ -14,7 +14,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        java-version: [11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22]
+        java-version: [21, 22]
     runs-on: ubuntu-latest
     steps:
     - uses: actions/[email protected]
@@ -32,7 +32,7 @@ jobs:
       - name: Set up Java
         uses: actions/[email protected]
         with:
-          java-version: '11'
+          java-version: '21'
           distribution: 'zulu'
       - name: Build with Maven
         run: ./mvnw verify package site -B

.github/workflows/release.yml

@@ -16,7 +16,7 @@ jobs:
       - uses: actions/[email protected]
         with:
           distribution: 'zulu'
-          java-version: '11'
+          java-version: '21'
           server-id: 'ossrh'
           server-username: SONATYPE_USERNAME
           server-password: SONATYPE_TOKEN

README.adoc

@@ -68,7 +68,7 @@ We recommend https://github.com/ben-manes/caffeine[Caffeine] for object caching.
 
 === Installing
 
-Stormpot 3.1 only depends on Java 11 or newer.
+Stormpot 3.2 only depends on Java 11 or newer.
 Add it as a Maven dependency to your projects:
 
 [source,xml]
@@ -81,6 +81,7 @@ Add it as a Maven dependency to your projects:
 ----
 
 You can also build the latest snapshot from source with `mvn clean install`.
+Note that Stormpot 4 require Java 21 or newer.
 
 === Getting Started
 

pom.xml

@@ -38,9 +38,8 @@
   </developers>
 
   <properties>
-    <outputEncoding>UTF-8</outputEncoding>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    <java.version>11</java.version>
+    <java.version>21</java.version>
     <jacoco.version>0.8.12</jacoco.version>
     <javadoc.version>3.7.0</javadoc.version>
     <asciidoclet.version>2.0.0</asciidoclet.version>
@@ -105,8 +104,7 @@
         <artifactId>maven-compiler-plugin</artifactId>
         <version>3.13.0</version>
         <configuration>
-          <source>${java.version}</source>
-          <target>${java.version}</target>
+          <release>${java.version}</release>
           <compilerArgument>-Xlint:all</compilerArgument>
           <showWarnings>true</showWarnings>
         </configuration>
@@ -240,15 +238,11 @@
           </execution>
         </executions>
         <configuration>
-          <additionalJOptions>
-            <additionalJOption>-J--add-exports=jdk.javadoc/jdk.javadoc.internal.tool=ALL-UNNAMED</additionalJOption>
-            <additionalJOption>-Xdoclint:all,-html,-accessibility</additionalJOption>
-            <additionalJOption>--base-dir</additionalJOption>
-            <additionalJOption>${project.basedir}</additionalJOption>
-          </additionalJOptions>
-          <doclet>org.asciidoctor.asciidoclet.Asciidoclet</doclet>
+          <additionalOptions>
+            <additionalOption>--snippet-path</additionalOption>
+            <additionalOption>${build.testSourceDirectory}/examples/</additionalOption>
+          </additionalOptions>
           <detectJavaApiLink>true</detectJavaApiLink>
-          <docletPath>${project.basedir}/build/asciidoclet-2.0.0-shaded.jar</docletPath>
         </configuration>
       </plugin>
       <plugin>
@@ -424,15 +418,11 @@
         <artifactId>maven-javadoc-plugin</artifactId>
         <version>${javadoc.version}</version>
         <configuration>
-          <additionalJOptions>
-            <additionalJOption>-J--add-exports=jdk.javadoc/jdk.javadoc.internal.tool=ALL-UNNAMED</additionalJOption>
-            <additionalJOption>-Xdoclint:all,-html,-accessibility</additionalJOption>
-            <additionalJOption>--base-dir</additionalJOption>
-            <additionalJOption>${project.basedir}</additionalJOption>
-          </additionalJOptions>
-          <doclet>org.asciidoctor.asciidoclet.Asciidoclet</doclet>
+          <additionalOptions>
+            <additionalOption>--snippet-path</additionalOption>
+            <additionalOption>${build.testSourceDirectory}/examples/</additionalOption>
+          </additionalOptions>
           <detectJavaApiLink>true</detectJavaApiLink>
-          <docletPath>${project.basedir}/build/asciidoclet-2.0.0-shaded.jar</docletPath>
         </configuration>
         <reportSets>
           <reportSet>

src/main/java/module-info.java

@@ -13,6 +13,20 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * <h2>Stormpot</h2>
+ * Stormpot is a generic, thread-safe and fast object pooling library.
+ * <p>
+ * The object pools themselves implement the {@link stormpot.Pool} interface.
+ * The things you actually want to pool must all implement the
+ * {@link stormpot.Poolable} interface, and you must also provide an
+ * implementation of the {@link stormpot.Allocator} interface as a factory to
+ * create your pooled objects.
+ * <p>
+ * See the online
+ * <a href="http://chrisvest.github.io/stormpot/usage.html">Usage Guide</a>
+ * for a tutorial.
+ */
 module stormpot {
   requires transitive java.management;
   requires static java.sql; // For testing only.

src/main/java/stormpot/Allocator.java

@@ -18,10 +18,10 @@
 /**
  * An Allocator is responsible for the creation and destruction of
  * {@link Poolable} objects.
- *
+ * <p>
  * This is where the objects in the Pool comes from. Clients of the Stormpot
  * library needs to provide their own Allocator implementations.
- *
+ * <p>
  * Implementations of this interface must be thread-safe, because there is no
  * knowing whether pools will try to access it concurrently or not. The easiest
  * way to achieve this is to just make the
@@ -32,75 +32,77 @@
  * very slow allocations by allocating in more than one thread, but
  * synchronizing the {@link #allocate(Slot)} method will render that strategy
  * ineffective.
- *
+ * <p>
  * A better approach to thread-safety is to not have any shared mutable state
  * in the allocator, if at all possible.
- *
+ * <p>
  * Implementations must also be interruption-safe.
  * When a pool is {@linkplain Pool#shutdown() shut down}, its background
  * allocation thread may be interrupted, and this thread may be interacting
  * with the allocator instance when this happens.
  * 
- * @author Chris Vest <[email protected]>
+ * @author Chris Vest
  * @see stormpot.Reallocator
  * @param <T> any type that implements Poolable.
  */
 public interface Allocator<T extends Poolable> {
 
   /**
    * Create a fresh new instance of T for the given slot.
-   *
+   * <p>
    * The returned {@link Poolable} must obey the contract that, when
    * {@link Poolable#release()} is called on it, it must delegate
    * the call onto the {@link Slot#release(Poolable)} method of the here
    * given slot object.
-   *
+   * <p>
    * Exceptions thrown by this method may propagate out through the
    * {@link Pool#claim(Timeout) claim} method of a pool, in the form of being
    * wrapped inside a {@link PoolException}. Pools must be able to handle these
    * exceptions in a sane manner, and are guaranteed to return to a working
    * state if an Allocator stops throwing exceptions from its allocate method.
+   *
    * @param slot The slot the pool wish to allocate an object for.
    * Implementers do not need to concern themselves with the details of a
    * pools slot objects. They just have to call release on them as the
    * protocol demands.
-   * @return A newly created instance of T. Never `null`.
+   * @return A newly created instance of T. Never {@code null}.
    * @throws Exception If the allocation fails.
    */
   T allocate(Slot slot) throws Exception;
 
   /**
    * Deallocate, if applicable, the given Poolable and free any resources
    * associated with it.
-   *
+   * <p>
    * This is an opportunity to close any connections or files, flush buffers,
    * empty caches or what ever might need to be done to completely free any
    * resources represented by this Poolable.
-   *
+   * <p>
    * Note that a Poolable must never touch its slot object after it has been
    * deallocated.
-   *
+   * <p>
    * Pools, on the other hand, will guarantee that the same object is never
    * deallocated more than once.
-   *
+   * <p>
    * Note that pools will always silently swallow exceptions thrown by the
    * deallocate method. They do this because there is no knowing whether the
    * deallocation of an object will be done synchronously by a thread calling
    * {@link Poolable#release() release} on a Poolable, or asynchronously by
    * a clean-up thread inside the pool.
-   *
+   * <p>
    * Deallocation from the release of an expired object, and deallocation from
-   * the shut down procedure of a {@link Pool} behave the same way in this
+   * the shutdown procedure of a {@link Pool} behave the same way in this
    * regard. They will both silently swallow any exception thrown.
-   *
+   * <p>
    * On the other hand, pools are guaranteed to otherwise correctly deal with
-   * any exception that might be thrown. The shut down procedure will still
+   * any exception that might be thrown. The shutdown procedure will still
    * complete, and release will still maintain the internal data structures of
    * the pool to make the slot available for new allocations.
-   *
+   * <p>
    * If you need to somehow specially deal with the exceptions thrown by the
    * deallocation of objects, then you should do this in the allocator itself,
    * or in a wrapper around your allocator.
+   *
    * @param poolable The non-null Poolable instance to be deallocated.
    * @throws Exception if the deallocation encounters an error.
    */

src/main/java/stormpot/BasePoolable.java

@@ -19,7 +19,7 @@
 
 /**
  * A basic implementation of the {@link Poolable} interface, which can be extended directly.
- *
+ * <p>
  * It is not strictly necessary to extend this class in order to implement the {@link Poolable}
  * interface, but doing so may make your code simpler.
  */
@@ -32,7 +32,8 @@ public class BasePoolable implements Poolable {
   protected final Slot slot;
 
   /**
-   * Build a `BasePoolable` for the given slot.
+   * Build a {@link BasePoolable} for the given slot.
+   *
    * @param slot The {@link Slot} that represents this objects place in the pool.
    */
   public BasePoolable(Slot slot) {

src/main/java/stormpot/BlazePool.java

@@ -23,19 +23,19 @@
  * BlazePool is a highly optimised {@link Pool} implementation that consists of
  * a queues of Poolable instances, the access to which is made faster with
  * clever use of ThreadLocals.
- *
+ * <p>
  * Object allocation always happens in a dedicated thread, off-loading the
  * cost of allocating the pooled objects. This leads to reduced deviation
  * in the times it takes claim method to complete, provided the pool is not
  * depleted.
- *
+ * <p>
  * BlazePool optimises for the case where the same threads need to claim and
  * release objects over and over again. On the other hand, if the releasing
  * thread tends to differ from the claiming thread, then the major optimisation
  * in BlazePool is defeated, and performance regresses to a slow-path that is
  * limited by contention on a blocking queue.
  *
- * @author Chris Vest <[email protected]>
+ * @author Chris Vest
  * @param <T> The type of {@link Poolable} managed by this pool.
  */
 final class BlazePool<T extends Poolable>

src/main/java/stormpot/BlazePoolThreadLocalTap.java

@@ -20,7 +20,7 @@
  * caching and TLR-claiming in the pool itself. However, instead of relying on
  * a thread-local for the object caching, we instead directly use a field of
  * the pool tap instance.
- *
+ * <p>
  * This has two advantages: 1) a field load is faster than a thread-local
  * lookup, and 2) there is no thread-local "leaking" or contamination.
  *