0
# ShedLock Spring Integration
1

2
ShedLock Spring Integration provides Spring Framework support for the ShedLock distributed locking library. It enables annotation-based distributed locking for scheduled tasks, ensuring they execute at most once across multiple application nodes. The library offers AOP-based integration with Spring's task scheduling infrastructure.
3

4
## Package Information
5

6
- **Package Name**: shedlock-spring
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>net.javacrumbs.shedlock</groupId>
13
    <artifactId>shedlock-spring</artifactId>
14
    <version>6.6.0</version>
15
  </dependency>
16
  ```
17
- **Required Dependencies**: This package requires `shedlock-core` and a compatible lock provider implementation
18
- **Common Provider Dependencies**:
19
  ```xml
20
  <!-- For JDBC/database locking -->
21
  <dependency>
22
    <groupId>net.javacrumbs.shedlock</groupId>
23
    <artifactId>shedlock-provider-jdbc-template</artifactId>
24
    <version>6.6.0</version>
25
  </dependency>
26
  
27
  <!-- For Redis locking -->
28
  <dependency>
29
    <groupId>net.javacrumbs.shedlock</groupId>
30
    <artifactId>shedlock-provider-redis-spring</artifactId>
31
    <version>6.6.0</version>
32
  </dependency>
33
  ```
34

35
## Core Imports
36

37
Spring-specific annotations and classes:
38
```java
39
import net.javacrumbs.shedlock.spring.annotation.EnableSchedulerLock;
40
import net.javacrumbs.shedlock.spring.annotation.SchedulerLock;
41
import net.javacrumbs.shedlock.spring.annotation.LockProviderToUse;
42
import net.javacrumbs.shedlock.spring.LockableTaskScheduler;
43
```
44

45
Core ShedLock interfaces and classes:
46
```java
47
import net.javacrumbs.shedlock.core.LockProvider;
48
import net.javacrumbs.shedlock.core.LockManager;
49
import net.javacrumbs.shedlock.core.LockConfiguration;
50
import net.javacrumbs.shedlock.core.SimpleLock;
51
```
52

53
Common lock provider implementations:
54
```java
55
// For JDBC/database locking
56
import net.javacrumbs.shedlock.provider.jdbctemplate.JdbcTemplateLockProvider;
57

58
// For Redis locking  
59
import net.javacrumbs.shedlock.provider.redis.spring.RedisLockProvider;
60
```
61

62
## Basic Usage
63

64
```java
65
import net.javacrumbs.shedlock.spring.annotation.EnableSchedulerLock;
66
import net.javacrumbs.shedlock.spring.annotation.SchedulerLock;
67
import net.javacrumbs.shedlock.core.LockProvider;
68
import net.javacrumbs.shedlock.provider.jdbctemplate.JdbcTemplateLockProvider;
69
import org.springframework.context.annotation.Bean;
70
import org.springframework.context.annotation.Configuration;
71
import org.springframework.scheduling.annotation.Scheduled;
72
import org.springframework.stereotype.Component;
73

74
@Configuration
75
@EnableSchedulerLock(defaultLockAtMostFor = "10m")
76
public class SchedulerConfig {
77
    
78
    @Bean
79
    public LockProvider lockProvider() {
80
        // Configure your lock provider (e.g., database, Redis)
81
        return new JdbcTemplateLockProvider(dataSource);
82
    }
83
}
84

85
@Component
86
public class ScheduledTasks {
87
    
88
    @Scheduled(cron = "0 */5 * * * *")
89
    @SchedulerLock(name = "scheduledTaskName", lockAtMostFor = "4m", lockAtLeastFor = "1m")
90
    public void scheduledTask() {
91
        // This method will be locked across multiple instances
92
        doWork();
93
    }
94
}
95
```
96

97
## Architecture
98

99
ShedLock Spring Integration is built around several key components:
100

101
- **Annotation-Based Configuration**: `@EnableSchedulerLock` for configuration and `@SchedulerLock` for method-level locking
102
- **AOP Infrastructure**: Method and scheduler proxying for transparent lock application
103
- **Configuration Extraction**: Spring-specific lock configuration extraction with SpEL support
104
- **Integration Modes**: Support for both method-level and scheduler-level interception
105
- **Lock Provider Abstraction**: Flexible lock provider selection and configuration
106

107
## Capabilities
108

109
### Configuration and Setup
110

111
Core annotations and configuration classes for enabling and configuring ShedLock in Spring applications.
112

113
```java { .api }
114
@EnableSchedulerLock(
115
    interceptMode = InterceptMode.PROXY_METHOD,
116
    defaultLockAtMostFor = "PT30M", 
117
    defaultLockAtLeastFor = "PT0S",
118
    mode = AdviceMode.PROXY,
119
    proxyTargetClass = false,
120
    order = Ordered.LOWEST_PRECEDENCE
121
)
122
public @interface EnableSchedulerLock {
123
    enum InterceptMode {
124
        PROXY_SCHEDULER, // Deprecated
125
        PROXY_METHOD
126
    }
127
}
128
```
129

130
[Configuration and Setup](./configuration.md)
131

132
### Method-Level Locking
133

134
Annotations and mechanisms for applying distributed locks directly to scheduled methods.
135

136
```java { .api }
137
@SchedulerLock(
138
    name = "lockName",
139
    lockAtMostFor = "PT10M",
140
    lockAtLeastFor = "PT0S" 
141
)
142
public @interface SchedulerLock {}
143

144
@LockProviderToUse("lockProviderBeanName")
145
public @interface LockProviderToUse {}
146
```
147

148
[Method-Level Locking](./method-locking.md)
149

150
### TaskScheduler Integration
151

152
Classes and utilities for integrating with Spring's TaskScheduler infrastructure.
153

154
```java { .api }
155
public class LockableTaskScheduler implements TaskScheduler, DisposableBean {
156
    public LockableTaskScheduler(TaskScheduler taskScheduler, LockManager lockManager);
157
    public ScheduledFuture<?> schedule(Runnable task, Trigger trigger);
158
    public ScheduledFuture<?> scheduleAtFixedRate(Runnable task, long period);
159
    public ScheduledFuture<?> scheduleWithFixedDelay(Runnable task, long delay);
160
}
161
```
162

163
[TaskScheduler Integration](./task-scheduler.md)
164

165
### Advanced Configuration
166

167
Extended configuration extraction and AOP infrastructure for advanced use cases.
168

169
```java { .api }
170
public interface ExtendedLockConfigurationExtractor extends LockConfigurationExtractor {
171
    Optional<LockConfiguration> getLockConfiguration(Object object, Method method, Object[] parameterValues);
172
}
173

174
public class SpringLockConfigurationExtractor implements ExtendedLockConfigurationExtractor {
175
    public SpringLockConfigurationExtractor(
176
        Duration defaultLockAtMostFor,
177
        Duration defaultLockAtLeastFor, 
178
        StringValueResolver embeddedValueResolver,
179
        Converter<String, Duration> durationConverter,
180
        BeanFactory beanFactory
181
    );
182
}
183
```
184

185
[Advanced Configuration](./advanced-configuration.md)
186

187
## Core ShedLock Types
188

189
Essential interfaces and classes from `shedlock-core` that are used throughout the Spring integration:
190

191
### LockProvider Interface
192
```java { .api }
193
public interface LockProvider {
194
    /**
195
     * @return Optional containing SimpleLock if lock was acquired, empty if not acquired
196
     */
197
    Optional<SimpleLock> lock(LockConfiguration lockConfiguration);
198
}
199
```
200

201
### SimpleLock Interface
202
```java { .api }
203
public interface SimpleLock {
204
    /**
205
     * Unlocks the lock. Once unlocked, no other operations can be called.
206
     */
207
    void unlock();
208
    
209
    /**
210
     * Extends the lock duration. Returns new lock or empty if extension failed.
211
     * Not supported by all providers.
212
     */
213
    default Optional<SimpleLock> extend(Duration lockAtMostFor, Duration lockAtLeastFor) {
214
        throw new UnsupportedOperationException();
215
    }
216
}
217
```
218

219
### LockConfiguration Class
220
```java { .api }
221
public class LockConfiguration {
222
    public LockConfiguration(Instant createdAt, String name, Duration lockAtMostFor, Duration lockAtLeastFor);
223
    
224
    public String getName();
225
    public Instant getLockAtMostUntil();
226
    public Instant getLockAtLeastUntil();
227
    public Instant getUnlockTime();
228
    public Duration getLockAtMostFor();
229
    public Duration getLockAtLeastFor();
230
}
231
```
232

233
### LockManager Interface
234
```java { .api }
235
public interface LockManager {
236
    /**
237
     * Executes a callback with an acquired lock.
238
     */
239
    void executeWithLock(Runnable task, LockConfiguration lockConfiguration);
240
    
241
    /**
242
     * Executes a callback with an acquired lock, returning result.
243
     */
244
    <T> T executeWithLock(Supplier<T> task, LockConfiguration lockConfiguration);
245
}
246
```
247

248
## Common Types
249

250
```java { .api }
251
// Duration formats supported
252
// ISO8601: "PT30S", "PT10M", "PT1H"
253
// Simple: "30s", "10m", "1h", "1d"
254

255
// Intercept modes
256
enum InterceptMode {
257
    PROXY_METHOD,      // Recommended: Intercepts method calls
258
    PROXY_SCHEDULER    // Deprecated: Intercepts scheduler calls
259
}
260

261
// Spring AOP modes  
262
enum AdviceMode {
263
    PROXY,    // Standard proxy-based AOP
264
    ASPECTJ   // AspectJ weaving
265
}
266
```
267

268
## Error Handling
269

270
```java { .api }
271
public class LockingNotSupportedException extends LockException {
272
    // Thrown when locking is not supported (e.g., primitive return types)
273
}
274

275
public class NoUniqueBeanDefinitionException extends BeansException {
276
    // Thrown when multiple LockProviders exist without @LockProviderToUse
277
}
278
```