spring-distributed-locks

Core interfaces of a distributed mutex locking library for Spring Boot

License

License

GroupId

GroupId

com.budjb
ArtifactId

ArtifactId

spring-distributed-locks
Last Version

Last Version

2.1.2
Release Date

Release Date

Type

Type

jar
Description

Description

spring-distributed-locks
Core interfaces of a distributed mutex locking library for Spring Boot
Project URL

Project URL

https://github.com/budjb/spring-distributed-locks
Source Code Management

Source Code Management

https://github.com/budjb/spring-distributed-locks

Download spring-distributed-locks

How to add to project

<!-- https://jarcasting.com/artifacts/com.budjb/spring-distributed-locks/ -->
<dependency>
    <groupId>com.budjb</groupId>
    <artifactId>spring-distributed-locks</artifactId>
    <version>2.1.2</version>
</dependency>
// https://jarcasting.com/artifacts/com.budjb/spring-distributed-locks/
implementation 'com.budjb:spring-distributed-locks:2.1.2'
// https://jarcasting.com/artifacts/com.budjb/spring-distributed-locks/
implementation ("com.budjb:spring-distributed-locks:2.1.2")
'com.budjb:spring-distributed-locks:jar:2.1.2'
<dependency org="com.budjb" name="spring-distributed-locks" rev="2.1.2">
  <artifact name="spring-distributed-locks" type="jar" />
</dependency>
@Grapes(
@Grab(group='com.budjb', module='spring-distributed-locks', version='2.1.2')
)
libraryDependencies += "com.budjb" % "spring-distributed-locks" % "2.1.2"
[com.budjb/spring-distributed-locks "2.1.2"]

Dependencies

compile (1)

Group / Artifact Type Version
org.springframework.boot : spring-boot-starter jar

Project Modules

There are no modules declared in this project.

Spring Distributed Locks

Introduction

The distributed locks library is an abstraction of Java’s Lock system intended for use with distributed/clustered applications. It is useful in situations where applications need to synchronize access to a resource or process but they do not share the same runtime environment.

Quick Start

Using Gradle, make sure the following dependencies are included:

build.gradle
repositories {
    jcenter()
}

dependencies {
    compile "com.budjb:spring-distributed-locks:0.1.8.BETA"
}

To use a distributed lock, inject the distributedLockProvider bean, from which a distributed lock can be requested.

@Component
public class Example {
    private final DistributedLockProvider distributedLockProvider;

    public Example(DistributedLockProvider distributedLockProvider) {
        this.distributedLockProvider = distributedLockProvider;
    }

    public String go() {
        Lock lock = distributedLockProvider.getDistributedLock("foo");

        if (lock.tryLock()) {
            try {
                // lock acquired
            }
            finally {
                lock.unlock();
            }
        }
        else {
            // lock could not be acquired
        }
    }
}

Libraries

There are various implementations of the library, depending on the backend being used. Besides the core library, the other implementations expose the distributedLockProvider bean with their own specific implementation logic.

Library Description

com.budjb:spring-distributed-locks:0.1.8.BETA

The core implementation of the library, containing a local, non-distributed implementation useful for local development and testing.

com.budjb:spring-distributed-locks-hazelcast:0.1.8.BETA

An implementation of the distributed locks library backed by Hazelcast.

Hazelcast

The Hazelcast library uses the existing Hazelcast functionality built into Spring Boot, and will utilize the hazelcastInstance bean that Spring Boot builds. This means that the same configuration can be used, and the Hazelcast implementation of the distributed locks library can be used simply by dropping it into a project.

You can find more details regarding to use and configure Hazelcast with Spring Boot in the official documentation.

Custom Implementations

If a custom implementation is required, two interfaces need to be implemented: DistributedLockProvider and DistributedLock.

The DistributedLock extends Java’s Lock, and custom implementations must create their own concrete implementation of this interface. These concrete classes are typically decorators for an underlying Lock interface, but the specifics of how locks are managed is up to the implementation.

Tip
AbstractDistributedLock can be used a super-class for implementations which merely wrap an existing Lock . If lease support is desired, simply override the default implementation of those methods.

The DistributedLockProvider acts as a factory class for a DistributedLock, and solely responsible for creating DistributedLock instances. Locks are mapped to names, so that a single provider may provide distinct locks for different names that do not interfere with one another.

Lock Extensions

The DistributedLock also adds for support for leases, which defines the lifetime that a lease may be valid for before expiring. Leases are supported on both lock and tryLock methods. Some underlying Lock implementations may not supports leases, however, and so lease support is optional and can be queried via the leasesSupported method.

When providing a lease time, the lock is only considered acquired during that time period. If a lease expires, the lock should be considered available even if it is flagged as currently locked. If the previous holder of the lock attempts to unlock the lock, the operation should seem successful but not actually unlock the lock, since it may have been subsequently acquired by another process.

Versions

Version
2.1.2
2.1.1
2.1.0
0.1.7.BETA
0.1.6.BETA
0.1.5.BETA