Class OpenFileLock

java.lang.Object

cloud.opencode.base.io.lock.OpenFileLock

public final class OpenFileLock
extends Object

File Locking Utility Class 文件锁定工具类

Provides file locking utilities for cross-process synchronization using NIO FileChannel locks.

提供基于 NIO FileChannel 锁的跨进程同步文件锁定工具。

Features | 主要功能:

• Exclusive and shared locks - 独占锁和共享锁
• Try-lock with timeout - 带超时的尝试锁定
• Lock file pattern for coordination - 锁文件模式用于协调
• AutoCloseable for try-with-resources - AutoCloseable 支持 try-with-resources

Usage Examples | 使用示例:

// Exclusive lock with try-with-resources
try (var lock = OpenFileLock.lock(path)) {
    // Exclusive access to file
}

// Shared (read) lock
try (var lock = OpenFileLock.lockShared(path)) {
    // Shared read access
}

// Try lock with timeout
Optional<FileLockHandle> lock = OpenFileLock.tryLock(path, Duration.ofSeconds(5));
if (lock.isPresent()) {
    try (var handle = lock.get()) {
        // Got the lock
    }
}

// Execute with lock
String result = OpenFileLock.withLock(path, () -> {
    return readAndProcessFile(path);
});

Security | 安全性:

• Thread-safe: Yes, uses NIO FileChannel locks for cross-process safety - 线程安全: 是，使用NIO FileChannel锁实现跨进程安全
• Null-safe: No, path must not be null - 空值安全: 否，路径不可为null

Since:

JDK 25, opencode-base-io V1.0.0

Author:

Leon Soo www.LeonSoo.com

See Also:

• OpenCode.cloud

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	OpenFileLock.FileLockHandle	File Lock Handle 文件锁句柄

Field Summary

Fields

Modifier and Type	Field	Description
static final String	LOCK_FILE_SUFFIX	Default lock file suffix 默认锁文件后缀

Method Summary

Modifier and Type	Method	Description
static Path	getLockFilePath(Path path)	Get lock file path for a resource 获取资源的锁文件路径
static boolean	isExclusivelyLocked(Path path)	Check if file is locked with shared lock 检查文件是否被共享锁定
static boolean	isLocked(Path path)	Check if file is locked 检查文件是否被锁定
static OpenFileLock.FileLockHandle	lock(Path path)	Acquire exclusive lock on file 获取文件的独占锁
static OpenFileLock.FileLockHandle	lock(Path path, boolean shared)	Acquire lock on file 获取文件锁
static OpenFileLock.FileLockHandle	lockFile(Path path)	Create a lock file for coordination 创建用于协调的锁文件
static OpenFileLock.FileLockHandle	lockShared(Path path)	Acquire shared (read) lock on file 获取文件的共享（读）锁
static Optional<OpenFileLock.FileLockHandle>	tryLock(Path path)	Try to acquire exclusive lock without blocking 尝试获取独占锁（不阻塞）
static Optional<OpenFileLock.FileLockHandle>	tryLock(Path path, boolean shared)	Try to acquire lock without blocking 尝试获取锁（不阻塞）
static Optional<OpenFileLock.FileLockHandle>	tryLock(Path path, Duration timeout)	Try to acquire lock with timeout 尝试在超时时间内获取锁
static Optional<OpenFileLock.FileLockHandle>	tryLock(Path path, Duration timeout, boolean shared)	Try to acquire lock with timeout 尝试在超时时间内获取锁
static Optional<OpenFileLock.FileLockHandle>	tryLockFile(Path path, Duration timeout)	Try to create a lock file with timeout 尝试在超时时间内创建锁文件
static <T> Optional<T>	tryWithLock(Path path, Duration timeout, Supplier<T> action)	Try to execute action with lock, with timeout 尝试在超时时间内持有锁执行操作
static void	withLock(Path path, Runnable action)	Execute action with exclusive lock (no return value) 持有独占锁执行操作（无返回值）
static <T> T	withLock(Path path, Supplier<T> action)	Execute action with exclusive lock 持有独占锁执行操作
static <T> T	withSharedLock(Path path, Supplier<T> action)	Execute action with shared lock 持有共享锁执行操作

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

LOCK_FILE_SUFFIX

public static final String LOCK_FILE_SUFFIX

Default lock file suffix 默认锁文件后缀

See Also:

• Constant Field Values

Method Details

lock

public static OpenFileLock.FileLockHandle lock(Path path)

Acquire exclusive lock on file 获取文件的独占锁

Parameters:

path - the file path | 文件路径

Returns:

lock handle | 锁句柄

Throws:

OpenIOOperationException - if lock cannot be acquired | 如果无法获取锁

lock

public static OpenFileLock.FileLockHandle lock(Path path,
 boolean shared)

Acquire lock on file 获取文件锁

Parameters:

path - the file path | 文件路径

shared - true for shared lock, false for exclusive | true 为共享锁，false 为独占锁

Returns:

lock handle | 锁句柄

Throws:

OpenIOOperationException - if lock cannot be acquired | 如果无法获取锁

lockShared

public static OpenFileLock.FileLockHandle lockShared(Path path)

Acquire shared (read) lock on file 获取文件的共享（读）锁

Parameters:

path - the file path | 文件路径

Returns:

lock handle | 锁句柄

Throws:

OpenIOOperationException - if lock cannot be acquired | 如果无法获取锁

tryLock

public static Optional<OpenFileLock.FileLockHandle> tryLock(Path path)

Try to acquire exclusive lock without blocking 尝试获取独占锁（不阻塞）

Parameters:

path - the file path | 文件路径

Returns:

lock handle if acquired, empty otherwise | 如果获取成功返回锁句柄，否则返回空

tryLock

public static Optional<OpenFileLock.FileLockHandle> tryLock(Path path,
 boolean shared)

Try to acquire lock without blocking 尝试获取锁（不阻塞）

Parameters:

path - the file path | 文件路径

shared - true for shared lock | true 为共享锁

Returns:

lock handle if acquired, empty otherwise | 如果获取成功返回锁句柄，否则返回空

tryLock

public static Optional<OpenFileLock.FileLockHandle> tryLock(Path path,
 Duration timeout)

Try to acquire lock with timeout 尝试在超时时间内获取锁

Parameters:

path - the file path | 文件路径

timeout - maximum wait time | 最大等待时间

Returns:

lock handle if acquired, empty otherwise | 如果获取成功返回锁句柄，否则返回空

tryLock

public static Optional<OpenFileLock.FileLockHandle> tryLock(Path path,
 Duration timeout,
 boolean shared)

Try to acquire lock with timeout 尝试在超时时间内获取锁

Parameters:

path - the file path | 文件路径

timeout - maximum wait time | 最大等待时间

shared - true for shared lock | true 为共享锁

Returns:

lock handle if acquired, empty otherwise | 如果获取成功返回锁句柄，否则返回空

lockFile

public static OpenFileLock.FileLockHandle lockFile(Path path)

Create a lock file for coordination 创建用于协调的锁文件

Parameters:

path - the resource path to protect | 要保护的资源路径

Returns:

lock handle for the lock file | 锁文件的锁句柄

tryLockFile

public static Optional<OpenFileLock.FileLockHandle> tryLockFile(Path path,
 Duration timeout)

Try to create a lock file with timeout 尝试在超时时间内创建锁文件

Parameters:

path - the resource path to protect | 要保护的资源路径

timeout - maximum wait time | 最大等待时间

Returns:

lock handle if acquired, empty otherwise | 如果获取成功返回锁句柄，否则返回空

getLockFilePath

public static Path getLockFilePath(Path path)

Get lock file path for a resource 获取资源的锁文件路径

Parameters:

path - the resource path | 资源路径

Returns:

lock file path | 锁文件路径

withLock

public static <T> T withLock(Path path,
 Supplier<T> action)

Execute action with exclusive lock 持有独占锁执行操作

Type Parameters:

T - return type | 返回类型

Parameters:

path - the file path | 文件路径

action - action to execute | 要执行的操作

Returns:

action result | 操作结果

withLock

public static void withLock(Path path,
 Runnable action)

Execute action with exclusive lock (no return value) 持有独占锁执行操作（无返回值）

Parameters:

path - the file path | 文件路径

action - action to execute | 要执行的操作

withSharedLock

public static <T> T withSharedLock(Path path,
 Supplier<T> action)

Execute action with shared lock 持有共享锁执行操作

Type Parameters:

T - return type | 返回类型

Parameters:

path - the file path | 文件路径

action - action to execute | 要执行的操作

Returns:

action result | 操作结果

tryWithLock

public static <T> Optional<T> tryWithLock(Path path,
 Duration timeout,
 Supplier<T> action)

Try to execute action with lock, with timeout 尝试在超时时间内持有锁执行操作

Type Parameters:

T - return type | 返回类型

Parameters:

path - the file path | 文件路径

timeout - maximum wait time | 最大等待时间

action - action to execute | 要执行的操作

Returns:

action result if lock acquired, empty otherwise | 如果获取锁返回结果，否则返回空

isLocked

public static boolean isLocked(Path path)

Check if file is locked 检查文件是否被锁定

Parameters:

path - the file path | 文件路径

Returns:

true if locked by another process | 如果被其他进程锁定返回 true

isExclusivelyLocked

public static boolean isExclusivelyLocked(Path path)

Check if file is locked with shared lock 检查文件是否被共享锁定

Parameters:

path - the file path | 文件路径

Returns:

true if exclusively locked | 如果被独占锁定返回 true