https://github.com/sanyarnd/applocker
Provides file-based locking mechanism with inter-process communication support
https://github.com/sanyarnd/applocker
desktop java jvm library single-instance
Last synced: about 1 month ago
JSON representation
Provides file-based locking mechanism with inter-process communication support
- Host: GitHub
- URL: https://github.com/sanyarnd/applocker
- Owner: sanyarnd
- License: apache-2.0
- Created: 2019-05-14T13:49:32.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2022-11-12T01:59:56.000Z (over 3 years ago)
- Last Synced: 2025-07-23T13:02:51.737Z (7 months ago)
- Topics: desktop, java, jvm, library, single-instance
- Language: Java
- Homepage: https://sanyarnd.github.io/applocker
- Size: 784 KB
- Stars: 4
- Watchers: 2
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# AppLocker
[](https://sonarcloud.io/summary/new_code?id=io.github.sanyarnd%3Aapp-locker)
AppLocker is a small library which provides the often missing single instance functionality.
# Features
* Safe: based on file channel locking, lock will be released even in case of power outage
* An arbitrary `AppLocker` has the ability to communicate with the `AppLocker` which currently owns the lock
* Lightweight (~20kb)
* No transitive dependencies
* JDK8+ support
# Quick Start
The usage flow typically looks like this:
* Acquire an instance of `AppLocker` class
* Invoke `AppLocker#lock`
* Handle possible errors
To get the `AppLocker` you must invoke static `AppLocker#create` method.
This call will return `AppLocker.Builder` instance with a set of `#set` and `#on` methods.
All methods are optional and have sane defaults.
`#set` methods allow congiguring interactions with filesystem and how `AppLocker` will handle incoming messages in case it was able to successfully acquire the lock.
```java
AppLocker locker = AppLocker.create("lockID")
.setPath(Paths.get("")) // where to store locks (default: "")
.setIdEncoder(this::encode) // map `lockID` to filesystem name (default: "SHA-1")
.setMessageHandler(msg -> process(msg)) // handle messages (default: NULL)
```
`#on` methods allow handling errors that may occur during the `AppLocker#lock` call.
```java
AppLocker locker = AppLocker.create("lockID")
.onSuccess(this::logLocking) // success callback (default: NULL)
.onBusy(message, this::logAndExit) // send message to the instance which currently owns the lock and invoke callback (default: NULL)
.onFail(this::logErrorAndExit) // serious error happened during the lock (default: re-throw exception)
```
Invoke `#build` method to finish the building procedure and retrieve `AppLocker`:
```java
AppLocker locker = AppLocker.create("lockID").build();
```
If you don't want to use the `#on` methods, you can handle exceptions directly:
```java
AppLocker locker = AppLocker.create("lockID").build();
try {
locker.lock();
} catch (LockingBusyException ex) {
} catch (LockingException ex) {
}
```
More details can be found in [JavaDocs](https://sanyarnd.github.io/applocker/apidocs/index.html).
# Download
Maven:
```xml
io.github.sanyarnd
app-locker
1.2.0
```
Gradle:
```gradle
compile 'io.github.sanyarnd:app-locker:1.1.2'
```
Standalone jars are available on [releases](https://github.com/sanyarnd/applocker/releases) page.
More download options available in [Bintray](https://bintray.com/sanya-rnd/maven-projects/applocker) repository.
# Changelog
See [CHANGELOG.md](CHANGELOG.md).