0
# Configuration and Setup
1

2
Configuration classes and annotations for enabling and setting up ShedLock in Spring applications.
3

4
## @EnableSchedulerLock Annotation
5

6
The main configuration annotation that enables ShedLock integration in Spring applications.
7

8
```java { .api }
9
@Target(ElementType.TYPE)
10
@Retention(RetentionPolicy.RUNTIME)
11
@Import(SchedulerLockConfigurationSelector.class)
12
public @interface EnableSchedulerLock {
13
    
14
    enum InterceptMode {
15
        @Deprecated(forRemoval = true)
16
        PROXY_SCHEDULER,  // Wraps TaskScheduler in proxy
17
        PROXY_METHOD      // Proxies scheduled methods directly (recommended)
18
    }
19
    
20
    InterceptMode interceptMode() default InterceptMode.PROXY_METHOD;
21
    String defaultLockAtMostFor();                    // Required
22
    String defaultLockAtLeastFor() default "PT0S";   // Optional
23
    AdviceMode mode() default AdviceMode.PROXY;       // Spring AOP mode
24
    boolean proxyTargetClass() default false;        // Use CGLIB proxies
25
    int order() default Ordered.LOWEST_PRECEDENCE;   // Advisor order
26
}
27
```
28

29
### Parameters
30

31
- **interceptMode**: Determines how locking is applied
32
  - `PROXY_METHOD` (recommended): Intercepts method calls directly
33
  - `PROXY_SCHEDULER` (deprecated): Intercepts TaskScheduler calls
34
- **defaultLockAtMostFor**: Default maximum lock duration (required)
35
- **defaultLockAtLeastFor**: Default minimum lock duration (optional, defaults to "PT0S")
36
- **mode**: Spring AOP advice mode (PROXY or ASPECTJ)
37
- **proxyTargetClass**: Whether to use CGLIB proxies instead of JDK proxies
38
- **order**: Execution order when multiple advisors are present
39

40
### Usage Example
41

42
```java
43
@Configuration
44
@EnableSchedulerLock(
45
    interceptMode = InterceptMode.PROXY_METHOD,
46
    defaultLockAtMostFor = "PT30M",
47
    defaultLockAtLeastFor = "PT1M"
48
)
49
public class ShedLockConfig {
50
    
51
    @Bean
52
    public LockProvider lockProvider() {
53
        return new JdbcTemplateLockProvider(dataSource);
54
    }
55
}
56
```
57

58
## Configuration Infrastructure
59

60
### SchedulerLockConfigurationSelector
61

62
Selects appropriate configuration classes based on the intercept mode.
63

64
```java { .api }
65
public class SchedulerLockConfigurationSelector implements ImportSelector {
66
    public String[] selectImports(AnnotationMetadata metadata);
67
}
68
```
69

70
Imports different configuration classes based on `interceptMode`:
71
- `PROXY_METHOD`: Imports `MethodProxyLockConfiguration`
72
- `PROXY_SCHEDULER`: Imports `SchedulerProxyLockConfiguration`
73

74
### AbstractLockConfiguration
75

76
Base class for lock configuration beans that processes `@EnableSchedulerLock` metadata.
77

78
```java { .api }
79
public abstract class AbstractLockConfiguration implements ImportAware {
80
    protected AnnotationAttributes annotationAttributes;
81
    
82
    public void setImportMetadata(AnnotationMetadata importMetadata);
83
    protected int getOrder();
84
}
85
```
86

87
### Method Proxy Configuration
88

89
Configuration for method-level lock interception.
90

91
```java { .api }
92
@Configuration
93
@Role(BeanDefinition.ROLE_INFRASTRUCTURE)
94
public class MethodProxyLockConfiguration extends AbstractLockConfiguration {
95
    
96
    @Bean
97
    @Role(BeanDefinition.ROLE_INFRASTRUCTURE)
98
    public MethodProxyScheduledLockAdvisor proxyScheduledLockAopBeanPostProcessor(
99
        ListableBeanFactory beanFactory, 
100
        @Lazy ExtendedLockConfigurationExtractor lockConfigurationExtractor
101
    );
102
}
103
```
104

105
### Scheduler Proxy Configuration
106

107
Configuration for scheduler-level lock interception (deprecated mode).
108

109
```java { .api }
110
@Configuration
111
@Role(BeanDefinition.ROLE_INFRASTRUCTURE) 
112
public class SchedulerProxyLockConfiguration extends AbstractLockConfiguration {
113
    
114
    @Bean
115
    @Role(BeanDefinition.ROLE_INFRASTRUCTURE)
116
    public SchedulerProxyScheduledLockAdvisor proxyScheduledLockAopBeanPostProcessor(
117
        ListableBeanFactory listableBeanFactory,
118
        @Lazy ExtendedLockConfigurationExtractor lockConfigurationExtractor
119
    );
120
}
121
```
122

123
### Lock Configuration Extractor Configuration
124

125
Defines the `ExtendedLockConfigurationExtractor` bean that handles lock configuration extraction.
126

127
```java { .api }
128
@Configuration
129
public class LockConfigurationExtractorConfiguration extends AbstractLockConfiguration 
130
    implements EmbeddedValueResolverAware, BeanFactoryAware {
131
    
132
    @Bean
133
    public ExtendedLockConfigurationExtractor lockConfigurationExtractor();
134
    
135
    public void setEmbeddedValueResolver(StringValueResolver resolver);
136
    public void setBeanFactory(BeanFactory beanFactory) throws BeansException;
137
}
138
```
139

140
## Duration Format Support
141

142
ShedLock supports multiple duration formats through the `StringToDurationConverter`:
143

144
### ISO8601 Duration Format
145
```java
146
"PT30S"   // 30 seconds
147
"PT10M"   // 10 minutes  
148
"PT1H"    // 1 hour
149
"PT24H"   // 24 hours
150
```
151

152
### Simple Duration Format
153
```java
154
"30s"     // 30 seconds
155
"10m"     // 10 minutes
156
"1h"      // 1 hour  
157
"1d"      // 1 day
158
"500ms"   // 500 milliseconds
159
"1000us"  // 1000 microseconds
160
"1000ns"  // 1000 nanoseconds
161
```
162

163
### String to Duration Converter
164

165
```java { .api }
166
public class StringToDurationConverter implements Converter<String, Duration> {
167
    public static final StringToDurationConverter INSTANCE;
168
    
169
    public Duration convert(String source);
170
}
171
```
172

173
The converter automatically detects the format and converts accordingly. Invalid formats throw `IllegalStateException`.
174

175
## Default Task Scheduler Registration
176

177
When using `PROXY_SCHEDULER` mode, a default `TaskScheduler` is automatically registered if none exists.
178

179
```java { .api }
180
@Component
181
public class RegisterDefaultTaskSchedulerPostProcessor 
182
    implements BeanDefinitionRegistryPostProcessor, Ordered, BeanFactoryAware {
183
    
184
    public void postProcessBeanDefinitionRegistry(BeanDefinitionRegistry registry) throws BeansException;
185
    public int getOrder(); // Returns LOWEST_PRECEDENCE
186
    public void setBeanFactory(BeanFactory beanFactory) throws BeansException;
187
}
188
```
189

190
This processor:
191
1. Checks if any `TaskScheduler` beans exist
192
2. If none found, registers a `ConcurrentTaskScheduler` 
193
3. If a single `ScheduledExecutorService` exists, uses it for the scheduler
194
4. Logs warnings for multiple `ScheduledExecutorService` beans