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 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 SpEL expression used to acquire the lock. To learn more about Spring aliases visit 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

@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:

1. keys from SpEL expression cannot be resolved

2. another method acquired the lock

3. Lock implementation threw an exception

Examples

Locking a method with the name aliased in the document called lock in MongoDB:

@MongoLocked(expression = "'aliased'", storeId = "distributed_lock")
public void runLockedWithMongo() {
    // locked code
}

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

@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:

@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 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.

Table 1. Mongo lock implementations

Implementation	Alias	Multiple key support
SimpleJdbcLock	@JdbcLocked	No

Include @EnableJdbcDistributedLock to enable JDBC locks. This will also include @EnableDistributedLock for you.

@Configuration
@EnableJdbcDistributedLock
public class LockConfiguration {
}

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

Example how to create table:

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.

Table 2. Mongo lock implementations

Implementation	Alias	Multiple key support
SimpleMongoLock	@MongoLocked	No

Include @EnableMongoDistributedLock to enable MongoDB locks. This will also include @EnableDistributedLock for you.

@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.

Table 3. 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.

@Configuration
@EnableRedisDistributedLock
public class LockConfiguration {
}

Importing into your project

Maven

Add the JitPack repository into your pom.xml.

<repositories>
  <repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
  </repository>
</repositories>

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 <dependencies>:

<dependencies>
  <dependency>
    <groupId>com.github.alturkovic.distributed-lock</groupId>
    <artifactId>distributed-lock-redis</artifactId>
    <version>[insert latest version here]</version>
  </dependency>
</dependencies>

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 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<String> and all other values will be wrapped with Collections.singletonList. Elements of Iterable or array will also be converted to Strings using the ConversionService. Custom converters can be registered. More about Spring conversion can be found 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