Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/alturkovic/distributed-lock

Distributed locking with Spring
https://github.com/alturkovic/distributed-lock

distributed-locking java spring

Last synced: 15 days ago
JSON representation

Distributed locking with Spring

Awesome Lists containing this project

README 

        
image:https://img.shields.io/badge/Java-17%2B-ED8B00?style=for-the-badge&labelColor=ED8B00&logo=java&color=808080[Java] image:https://img.shields.io/jitpack/v/github/alturkovic/distributed-lock?style=for-the-badge&labelColor=007ec5&color=808080&logo=Git&logoColor=white[JitPack] image:https://img.shields.io/badge/Spring%20Boot-3.1.5-ED8B00?style=for-the-badge&labelColor=6db33f&color=808080&logo=Spring%20Boot&logoColor=white[Spring Boot] image:https://img.shields.io/github/license/alturkovic/distributed-lock?style=for-the-badge&color=808080&logo=Open%20Source%20Initiative&logoColor=white[License]



= Distributed Lock



Distributed lock ensures your method cannot be run in parallel from multiple JVMs (cluster of servers, microservices, ...).

It uses a common store to keep track of used locks and your method needs to acquire one or more locks to run.



By default, locks follow methods lifecycle.They are obtained at the start of the method and released at the end of the method.

Manual controlling is supported and explained later in this document.



All locks acquired by lock implementations in this project will expire after 10 seconds, timeout after 1 second if unable to acquire lock and sleep for 50 ms between retries.

These options are customizable per annotation.



== Using locks



To lock your methods you need to first enable locking as described in the previous section.



Spring `https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/beans/factory/config/BeanPostProcessor.html[BeanPostProcessor]` will handle all `@Locked` methods including

their aliases. The `type` field describes which implementation of the lock to use.

To prevent repeating yourself if you plan on using the same implementation (as most people usually will), I've added alias support.

They wrap the `@Locked` annotation and define the type used.



Each lock needs to define a https://docs.spring.io/spring/docs/current/spring-framework-reference/html/expressions.html[SpEL] expression used to acquire the lock.

To learn more about Spring aliases visit https://github.com/spring-projects/spring-framework/wiki/Spring-Annotation-Programming-Model[this] link.



By default, upon failure to acquire the lock `@Locked` will throw `DistributedLockException`. If you need to only log this failure without raising the exception add `throwing = false` to your

`@Locked` annotation. Using this option on non-void methods will make the method return null - using primitives as return type with this option is not advised. This is useful if you need to lock

an action across multiple application instances, for example cron.



=== Lock refresh



Locks can be refreshed automatically on a regular interval. This allows methods that occasionally need to run longer than their expiration.

Refreshing the lock periodically prolongs the expiration of its key(s). This means that the lock cannot be acquired by another resource as long as the resource using the lock does not

end successfully. In case the resource holding the lock fails unexpectedly without releasing the lock, the lock will expire according to the last expiration that was written (that the last refresh

has set).



=== Manually controlled locks



Sometimes you might want lock to be acquired when calling a specific method and get released only when it expires (throttling).



To acquire a lock that doesn't get released automatically set `manuallyReleased` to `true` on `@Locked` annotation.



For more grained control (e.g., locking in the middle of the method and releasing later in the code), inject the lock in your service and acquire the lock manually.



==== Example



[source,java]

----

@Component

public class Example {



    @Autowired

    @Qualifier("simpleRedisLock")

    private Lock lock;



    // other fields...



    private void manuallyLocked() {

        // code before locking...



        final String token = lock.acquire(keys, storeId, expiration);



        // check if you acquired a token

        if (StringUtils.isEmpty(token)) {

            throw new IllegalStateException("Lock not acquired!");

        }



        // code after locking...



        lock.release(keys, storeId, token);



        // code after releasing the lock...

    }

}

----



=== Unsuccessful locks



If method cannot be locked, `DistributedLockException` will be thrown.



Method might not acquire the lock if:



. keys from SpEL expression cannot be resolved

. another method acquired the lock

. Lock implementation threw an exception



== Examples



Locking a method with the name _aliased_ in the document called _lock_ in MongoDB:



[source,java]

----

@MongoLocked(expression = "'aliased'", storeId = "distributed_lock")

public void runLockedWithMongo() {

    // locked code

}

----



Locking with multiple keys determined in runtime, use SpEL, for an example:



[source,java]

----

@RedisMultiLocked(expression = "T(com.example.MyUtils).getNamesWithId(#p0)")

public void runLockedWithRedis(final int id) {

    // locked code

}

----



This means that the `runLockedWithRedis` method will execute only if all keys evaluated by expression were acquired.



Locking with a custom lock implementation based on value of integer field `count`:



[source,java]

----

@Locked(type = MyCustomLock.class, expression = "getCount", prefix = "using:")

public void runLockedWithMyCustomLock() {

    // locked code

}

----



== Enabling locking



The project contains several configurations and annotations to help you enable locking and customize it.



To enable locking you must first include `@EnableDistributedLock`.

This will import the configuration that will autoconfigure the

`https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/beans/factory/config/BeanPostProcessor.html[BeanPostProcessor]` required for locking.



Project provides the following out-of-the-box lock implementations:



* JDBC

* Mongo

* Redis



=== JDBC locks



JDBC locks are provided in the `distributed-lock-jdbc` project.



.Mongo lock implementations

|===

|Implementation |Alias |Multiple key support



|`SimpleJdbcLock`

|`@JdbcLocked`

|No

|===



Include `@EnableJdbcDistributedLock` to enable JDBC locks.

This will also include `@EnableDistributedLock` for you.



[source,java]

----

@Configuration

@EnableJdbcDistributedLock

public class LockConfiguration {

}

----



[NOTE]

====

Make sure you create the table and configure the table ID incrementer.

====



Example how to create table:

[source, sql]

----

CREATE TABLE IF NOT EXISTS `distributed_lock` (

    id       INT NOT NULL AUTO_INCREMENT,

    lock_key VARCHAR(255),

    token    VARCHAR(255),

    expireAt TIMESTAMP,

    PRIMARY KEY(`id`),

    UNIQUE KEY `uk_lock_lock_key` (`lock_key`)

);

----



=== MongoDB locks



MongoDB locks are provided in the `distributed-lock-mongo` project.



.Mongo lock implementations

|===

|Implementation |Alias |Multiple key support



|`SimpleMongoLock`

|`@MongoLocked`

|No

|===



Include `@EnableMongoDistributedLock` to enable MongoDB locks.

This will also include `@EnableDistributedLock` for you.



[source,java]

----

@Configuration

@EnableMongoDistributedLock

public class LockConfiguration {

}

----



[NOTE]

====

Make sure you create TTL index in your `@Locked#storeId()` collection on `expireAt` field to enable lock expiration.

====



=== Redis locks



Redis locks are provided in the `distributed-lock-redis` project.



.Redis lock implementations

|===

|Implementation |Alias |Multiple key support



|`SimpleRedisLock`

|`@RedisLocked`

|No



|`MultiRedisLock`

|`@RedisMultiLocked`

|Yes

|===



Include `@EnableRedisDistributedLock` to enable Redis locks.

This will also include `@EnableDistributedLock` for you.



[source,java]

----

@Configuration

@EnableRedisDistributedLock

public class LockConfiguration {

}

----



== Importing into your project



=== Maven



Add the JitPack repository into your `pom.xml`.



[source,xml]

----



  

    jitpack.io

    https://jitpack.io

  



----



JitPack builds multi-modules by appending the repo name in the `groupId`.

To add the Redis dependency for an example, add the following under your ``:



[source,xml]

----



  

    com.github.alturkovic.distributed-lock

    distributed-lock-redis

    [insert latest version here]

  



----



=== Compatibility



Fully compatible with Spring 3. For earlier version support check the compatibility table below.

Older versions will not be maintained or bugfixed.



|===

|Version |Spring Boot version



|2.0.0+

|3.1.5



|1.4.1+

|2.4.3



|1.3.0+

|2.2.7.RELEASE



|1.2.0+

|2.1.0.RELEASE



|1.1.8+

|2.0.4.RELEASE



|1.1.7+

|2.0.3.RELEASE



|1.1.6-

|1.5.6.RELEASE



|===



== SpEL key generator



This is the default key generator the advice uses. If you wish to use your own, simply write your own and define it as a `@Bean`.



The default key generator has access to the currently executing context, meaning you can access your fields and methods from SpEL.

It uses the `https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/core/DefaultParameterNameDiscoverer.html[DefaultParameterNameDiscoverer]` to discover parameter names, so you can access your parameters in several different ways:



1. using `p#` syntax, where `#` is the position of the parameter, for an example: `p0` for the first parameter

2. using `a#` syntax, where `#` is the position of the parameter, for an example: `a2` for the third parameter

3. using the parameter name, for an example, `#message` -- *REQUIRES `-parameters` compiler flag*



A special variable named `executionPath` is used to define the method called.

This is the default `expression` used to describe the annotated method.



All validated expressions that result in an `Iterable` or an array will be converted to `List` and all other values will be wrapped with `Collections.singletonList`.

Elements of `Iterable` or array will also be converted to Strings using the

`https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/core/convert/ConversionService.html[ConversionService]`.

Custom converters can be registered.

More about Spring conversion can be found https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#core-convert[here].



For more examples, take a look at `com.github.alturkovic.lock.key.SpelKeyGeneratorTest`.



== Customization



If you want to use custom lock implementations, simply implement `Lock` interface and register it in a configuration.

You can also create an alias for your lock so you don't have to specify `@Locked` type field.



== Changelog



Started tracking the changes since 1.2.0 so no changelogs available for earlier versions.



==== 2.1.0



- FEATURE: Added option `throwing` to `@Locked` annotations



==== 2.0.0



- CHANGE: Upgraded Spring Boot version to 3.1.5



==== 1.5.5



- BUGFIX: Add initial refresh delay to avoid calling `refresh` immediately

- BUGFIX: Changed default `storeId` to `distributed_lock`



==== 1.5.4



- BUGFIX: Do not execute locked method if token is not acquired after all retries



==== 1.5.3



- BUGFIX: `RetriableLock` should return `null` if lock is not acquired after the last retry



==== 1.5.2



- BUGFIX: Use dedicated task scheduler for DistributedLock, avoid trying to override custom default scheduler



==== 1.5.1



- BUGFIX: Removed semicolon from SQL statements for PSQL compatibility



==== 1.5.0



- CHANGE: Changed the default SQL table name from `lock` to `distributed_lock` to avoid issues with reserved database keywords



==== 1.4.4



- BUGFIX: No retries will be attempted if `retry` or `timeout` are zero or negative

- BUGFIX: Handle Redis interruptions in Redis locks better

- BUGFIX: SQL script updated in README



==== 1.4.3



- BUGFIX: Use Spring scheduler if enabled instead of overriding

- BUGFIX: Escape `lock` keyword in SQL locks since MySQL uses it as a keyword



==== 1.4.2



- CHANGE: `KeyGenerator` will not declare `ConversionService` but reuse the shared instance if missing



==== 1.4.1



- CHANGE: Upgraded Spring Boot version to 2.4.3

- CHANGE: Migrated test to JUnit 5

- CHANGE: Migrated Redis tests to use Docker container

- BUGFIX: Injecting the user-defined `LockTypeResolver` properly

- BUGFIX: Fixed `BeanPostProcessor` initialization warning messages

- BUGFIX: Minor javadoc fix



==== 1.4.0



- CHANGE: Switched back to Java 1.8 from 11 since most projects don't yet use 11



==== 1.3.0



- CHANGE: Updated Java from 1.8 to 11

- CHANGE: Refactored lots of coupled code

- CHANGE: Extracted lots of reusable components such as retriable locks for easier manual control of locks

- BUGFIX: `LockBeanPostProcessor` will now fire after existing advisors to support transactional advisors



==== 1.2.2



- CHANGE: Removed explicit `ParameterNameDiscoverer` from `SpelKeyGenerator` which now uses the one provided by the `CachedExpressionEvaluator`

- CHANGE: Used `AopUtils` once and passed the evaluated method to `SpelKeyGenerator` so it doesn't have to evaluate the same thing as `LockMethodInterceptor`



==== 1.2.1



- FEATURE: Lock refreshing has been added. Check the 'Lock refresh' chapter for more details

- BUGFIX: `@RedisMultiLocked` was using `#executionPath` as prefix instead of an expression

- BUGFIX: `@RedisMultiLocked` was using `expiration` and `timeout` in milliseconds instead of seconds



==== 1.2.0

- FEATURE: Added a JavaDoc description to `com.github.alturkovic.lock.Lock.release()` method

- CHANGE: Rearranged the parameters of the `com.github.alturkovic.lock.Lock.release()` method to be more consistent

- CHANGE: Rearranged the parameters of the `com.github.alturkovic.lock.jdbc.service.JdbcLockSingleKeyService` methods to be more consistent

- CHANGE: `EvaluationConvertException` and `LockNotAvailableException` now extend the `DistributedLockException`