docs: align README (main and sub-modules) with existing code

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");
 ```

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<LockHandle> - 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<LockHandle> 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<LockHandle> action) {
@@ -34,20 +42,27 @@ 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<R> - Result of the function if lock acquired, empty if not.
+     * @param action            the function to execute while holding the lock
+     * @param <R>               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 <R> Optional<R> tryLock(String lockKey, long expirationSeconds, Function<LockHandle, R> action) {
         // ...
     }
 
     /**
-     * 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);
 }

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)