Upgrade to Java 21 and Remove asciidoclet

We now require Java 21 because of javadoc code snippets, which was the last feature we were really using from Asciidoclet.

This also improves javadoc rendering in Intellij, as a side-effect, even though Intellij doesn't know about our snippet path configuration.

.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.
  *

src/main/java/stormpot/Completion.java

@@ -22,7 +22,8 @@
  * cancellation or returning a result. Indeed, you cannot even precisely tell
  * if the task has already completed, but the await methods will return
  * immediately if that is the case.
- * @author Chris Vest <[email protected]>
+ *
+ * @author Chris Vest
  * @see Pool#shutdown()
  */
 public interface Completion {
@@ -31,28 +32,28 @@ public interface Completion {
    * Causes the current thread to wait until the completion is finished,
    * or the thread is {@link Thread#interrupt() interrupted}, or the specified
    * waiting time elapses.
-   *
+   * <p>
    * If the task represented by this completion has already completed,
-   * the method immediately returns `true`.
-   *
+   * the method immediately returns {@code true}.
+   * <p>
    * If the current thread already has its interrupted status set upon entry
    * to this method, or the thread is interrupted while waiting, then an
    * {@link InterruptedException} is thrown and the current threads interrupted
    * status is cleared.
-   *
-   * If the specified waiting time elapses, then the method returns `false`.
+   * <p>
+   * If the specified waiting time elapses, then the method returns {@code false}.
    *
    * @param timeout The timeout delimiting the maximum time to wait for the
    * task to complete. Timeouts with zero or negative values will cause the
    * method to return immediately.
-   * @return `true` if the task represented by this completion
+   * @return {@code true} if the task represented by this completion
    * completed within the specified waiting time, or was already complete upon
-   * entry to this method; or `false` if the specified Timeout
-   * elapsed before the task could finished.
+   * entry to this method; or {@code false} if the specified Timeout
+   * elapsed before the task could finish.
    * @throws InterruptedException if the current thread is interrupted while
    * waiting.
-   * @throws IllegalArgumentException if the provided `timeout` parameter is
-   * `null`.
+   * @throws IllegalArgumentException if the provided {@code timeout} parameter is
+   * {@code null}.
    */
   boolean await(Timeout timeout) throws InterruptedException;
 }