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.

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

@Configuration
@EnableJdbcDistributedLock
public class LockConfiguration {
}

create table lock (
    id int not null auto_increment primary key,
    lock_key varchar(255) unique,
    token varchar(255),
    expireAt timestamp,
);

MongoDB locks

@Configuration
@EnableMongoDistributedLock
public class LockConfiguration {
}

Redis locks

@Configuration
@EnableRedisDistributedLock
public class LockConfiguration {
}

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

1.2.2

1.2.1

1.2.0

Compatibility

Maven

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

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

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.

Lock refresh

Manually controlled locks

@Component
public class Example {

    @Qualifier("simpleRedisLock")
    private Lock lock;

    // other fields...

    private void manuallyLocked() {
        // code before locking...

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

        // check if you acquired a token
        if (StringUtils.isEmpty(token)) {
            throw new IllegalStateException("Lock not acquired!");
        }

        // code after locking...

        lock.release(keys, token, storeId);

        // code after releasing the lock...
    }
}

Unsuccessful locks

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

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

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:

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

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.