From 000521972bc41a8ac08d4ed52272f9b37e90af3a Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Wed, 18 Mar 2026 04:36:10 +0000 Subject: [PATCH] docs: align README (main and sub-modules) with existing code - Updated the `DLCK` Table Schema (H2) example in the main README.md to accurately reflect the database script (`DATETIME` to `TIMESTAMP`, `int` to `BIGINT`). - Updated the `KeyLock` interface documentation in `dlock-api/README.md` to precisely match the Javadocs in `KeyLock.java`, including `@throws LockException`. - Fixed a minor Javadoc syntax issue in `KeyLock.java` (`{@link Optional#empty}` to `{@link Optional#empty()}`). Co-authored-by: pmalirz <19637300+pmalirz@users.noreply.github.com> --- README.md | 4 +-- dlock-api/README.md | 35 +++++++++++++------ .../io/github/pmalirz/dlock/api/KeyLock.java | 2 +- 3 files changed, 28 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 0bd1b04..10d1657 100644 --- a/README.md +++ b/README.md @@ -157,8 +157,8 @@ Example `DLCK` Table Schema (H2): CREATE TABLE IF NOT EXISTS "DLCK" ( "LCK_KEY" varchar(1000) PRIMARY KEY, "LCK_HNDL_ID" varchar(100) NOT NULL, - "CREATED_TIME" DATETIME NOT NULL, - "EXPIRE_SEC" int NOT NULL + "CREATED_TIME" TIMESTAMP NOT NULL, + "EXPIRE_SEC" BIGINT NOT NULL ); CREATE UNIQUE INDEX IF NOT EXISTS "DLCK_HNDL_UX" ON "DLCK" ("LCK_HNDL_ID"); ``` diff --git a/dlock-api/README.md b/dlock-api/README.md index 32a19da..c271256 100644 --- a/dlock-api/README.md +++ b/dlock-api/README.md @@ -11,21 +11,29 @@ The primary interface for simplified lock operations. ```java public interface KeyLock { /** - * Attempts to acquire a lock by key. + * Gets a lock for a given amount of time, if available (providing the handle of + * that lock). + * If the lock is taken by someone there is no exception thrown but simply + * {@link Optional#empty()} is returned. * - * @param lockKey the key identifying the lock (must be non-blank and max KeyLock.MAX_LOCK_KEY_LENGTH characters) + * @param lockKey the key identifying the lock (must be non-blank and max {@value #MAX_LOCK_KEY_LENGTH} characters) * @param expirationSeconds the lock expiration time in seconds (must be greater than 0) - * @return Optional - Present if acquired, empty if not. + * @throws io.github.pmalirz.dlock.api.exception.LockException if an unexpected error occurs + * during lock acquisition * @throws IllegalArgumentException if lockKey is invalid or expirationSeconds is <= 0 */ Optional tryLock(String lockKey, long expirationSeconds); /** * Tries to acquire a lock and, if successful, executes the given action. - * The lock is automatically released after the action completes. + * The lock is automatically released after the action completes (or throws). + * If the lock is not available, the action is not executed. * - * @param lockKey the key identifying the lock (must be non-blank and max KeyLock.MAX_LOCK_KEY_LENGTH characters) + * @param lockKey the key identifying the lock (must be non-blank and max {@value #MAX_LOCK_KEY_LENGTH} characters) * @param expirationSeconds the lock expiration time in seconds (must be greater than 0) + * @param action the action to execute while holding the lock + * @throws io.github.pmalirz.dlock.api.exception.LockException if an unexpected error occurs + * during lock acquisition * @throws IllegalArgumentException if lockKey is invalid or expirationSeconds is <= 0 */ default void tryLock(String lockKey, long expirationSeconds, Consumer action) { @@ -34,11 +42,18 @@ public interface KeyLock { /** * Tries to acquire a lock and, if successful, executes the given function. - * The lock is automatically released after the function completes. + * The lock is automatically released after the function completes (or throws). + * If the lock is not available, the function is not executed and + * {@link Optional#empty()} is returned. * - * @param lockKey the key identifying the lock (must be non-blank and max KeyLock.MAX_LOCK_KEY_LENGTH characters) + * @param lockKey the key identifying the lock (must be non-blank and max {@value #MAX_LOCK_KEY_LENGTH} characters) * @param expirationSeconds the lock expiration time in seconds (must be greater than 0) - * @return Optional - Result of the function if lock acquired, empty if not. + * @param action the function to execute while holding the lock + * @param the return type of the action + * @return an {@link Optional} containing the result of the action if the lock + * was acquired, or empty otherwise + * @throws io.github.pmalirz.dlock.api.exception.LockException if an unexpected error occurs + * during lock acquisition * @throws IllegalArgumentException if lockKey is invalid or expirationSeconds is <= 0 */ default Optional tryLock(String lockKey, long expirationSeconds, Function action) { @@ -46,8 +61,8 @@ public interface KeyLock { } /** - * Releases the lock using the provided handle. - * If the lockHandle is null, it safely returns early. + * Releases a given lock. If lock with a given handle does not exist nothing + * happens. If the given handle is null, it should safely return. */ void unlock(LockHandle lockHandle); } diff --git a/dlock-api/src/main/java/io/github/pmalirz/dlock/api/KeyLock.java b/dlock-api/src/main/java/io/github/pmalirz/dlock/api/KeyLock.java index 8ef41da..24e06f5 100644 --- a/dlock-api/src/main/java/io/github/pmalirz/dlock/api/KeyLock.java +++ b/dlock-api/src/main/java/io/github/pmalirz/dlock/api/KeyLock.java @@ -23,7 +23,7 @@ public interface KeyLock { * Gets a lock for a given amount of time, if available (providing the handle of * that lock). * If the lock is taken by someone there is no exception thrown but simply - * {@link Optional#empty} is returned. + * {@link Optional#empty()} is returned. * * @param lockKey the key identifying the lock (must be non-blank and max {@value #MAX_LOCK_KEY_LENGTH} characters) * @param expirationSeconds the lock expiration time in seconds (must be greater than 0)