0
# Auto-Configuration
1

2
Auto-configuration functionality that automatically sets up jOOQ components in your Spring Boot application based on the presence of dependencies and configuration.
3

4
## Capabilities
5

6
### JooqAutoConfiguration
7

8
Main auto-configuration class that conditionally creates jOOQ beans when appropriate dependencies are detected.
9

10
```java { .api }
11
/**
12
 * Auto-configuration for jOOQ that sets up DSLContext, Configuration, and supporting beans
13
 * Activates when DSLContext is on classpath and DataSource bean is available
14
 */
15
@AutoConfiguration(after = { DataSourceAutoConfiguration.class, TransactionAutoConfiguration.class })
16
@ConditionalOnClass(DSLContext.class)
17
@ConditionalOnBean(DataSource.class)
18
@EnableConfigurationProperties(JooqProperties.class)
19
public class JooqAutoConfiguration {
20
    
21
    /**
22
     * Creates DataSource-based connection provider wrapped with transaction awareness
23
     * @param dataSource the application's primary DataSource
24
     * @return DataSourceConnectionProvider configured with TransactionAwareDataSourceProxy
25
     */
26
    @Bean
27
    @ConditionalOnMissingBean(ConnectionProvider.class)
28
    public DataSourceConnectionProvider dataSourceConnectionProvider(DataSource dataSource);
29
    
30
    /**
31
     * Creates Spring transaction provider for jOOQ when PlatformTransactionManager is available
32
     * @param txManager Spring's transaction manager
33
     * @return SpringTransactionProvider that integrates jOOQ with Spring transactions
34
     */
35
    @Bean
36
    @ConditionalOnBean(PlatformTransactionManager.class)
37
    @ConditionalOnMissingBean(TransactionProvider.class)
38
    public SpringTransactionProvider transactionProvider(PlatformTransactionManager txManager);
39
    
40
    /**
41
     * Creates execute listener provider for exception translation
42
     * @param exceptionTranslatorExecuteListener the exception translator listener
43
     * @return DefaultExecuteListenerProvider configured with exception translation
44
     */
45
    @Bean
46
    @Order(0)
47
    public DefaultExecuteListenerProvider jooqExceptionTranslatorExecuteListenerProvider(
48
        ExceptionTranslatorExecuteListener exceptionTranslatorExecuteListener);
49
    
50
    /**
51
     * Creates default exception translator execute listener
52
     * @return Default implementation of ExceptionTranslatorExecuteListener
53
     */
54
    @Bean
55
    @ConditionalOnMissingBean
56
    public ExceptionTranslatorExecuteListener jooqExceptionTranslator();
57
    
58
    /**
59
     * Creates the main jOOQ DSL context for performing database operations
60
     * @param configuration jOOQ configuration with all dependencies
61
     * @return DefaultDSLContext ready for dependency injection
62
     */
63
    @Bean
64
    @ConditionalOnMissingBean(DSLContext.class)
65
    public DefaultDSLContext dslContext(org.jooq.Configuration configuration);
66
    
67
    /**
68
     * Creates jOOQ configuration with all necessary components
69
     * @param properties configuration properties from spring.jooq.*
70
     * @param connectionProvider database connection provider
71
     * @param dataSource primary data source for SQL dialect detection
72
     * @param transactionProvider optional Spring transaction provider
73
     * @param executeListenerProviders collection of execute listener providers
74
     * @param configurationCustomizers collection of configuration customizers
75
     * @param settingsProvider optional jOOQ settings
76
     * @return Fully configured DefaultConfiguration
77
     */
78
    @Bean
79
    @ConditionalOnMissingBean(org.jooq.Configuration.class)
80
    DefaultConfiguration jooqConfiguration(JooqProperties properties, 
81
                                          ConnectionProvider connectionProvider,
82
                                          DataSource dataSource, 
83
                                          ObjectProvider<TransactionProvider> transactionProvider,
84
                                          ObjectProvider<ExecuteListenerProvider> executeListenerProviders,
85
                                          ObjectProvider<DefaultConfigurationCustomizer> configurationCustomizers,
86
                                          ObjectProvider<Settings> settingsProvider);
87
    
88
    /**
89
     * Creates jOOQ Settings from external configuration file when spring.jooq.config is specified
90
     * @param properties configuration properties containing config file location
91
     * @return Settings loaded from XML configuration file
92
     * @throws IOException if config file cannot be read
93
     * @throws JaxbNotAvailableException if JAXB is not available for XML parsing
94
     */
95
    @Bean
96
    @ConditionalOnProperty("spring.jooq.config")
97
    @ConditionalOnMissingBean(Settings.class)
98
    Settings settings(JooqProperties properties) throws IOException;
99
}
100
```
101

102
**Usage Examples:**
103

104
```java
105
// Auto-configured DSLContext is available for injection
106
@Service
107
public class BookService {
108
    
109
    @Autowired
110
    private DSLContext dsl;
111
    
112
    public List<Book> findBooksByAuthor(String author) {
113
        return dsl.selectFrom(BOOK)
114
                  .where(BOOK.AUTHOR.eq(author))
115
                  .fetchInto(Book.class);
116
    }
117
}
118

119
// Custom configuration can be provided via customizer
120
@Component
121
public class MyJooqCustomizer implements DefaultConfigurationCustomizer {
122
    
123
    @Override
124
    public void customize(DefaultConfiguration configuration) {
125
        // Add custom configuration like converters, listeners, etc.
126
        configuration.set(new MyCustomExecuteListener());
127
    }
128
}
129
```
130

131
### Auto-Configuration Conditions
132

133
The auto-configuration activates under these conditions:
134

135
- `DSLContext.class` must be on the classpath (provided by jOOQ dependency)
136
- A `DataSource` bean must be available in the application context
137
- Runs after `DataSourceAutoConfiguration` and `TransactionAutoConfiguration`
138

139
### Bean Creation Order
140

141
1. `DataSourceConnectionProvider` - Wraps DataSource with transaction awareness
142
2. `SpringTransactionProvider` - If PlatformTransactionManager is available
143
3. `ExceptionTranslatorExecuteListener` - Default exception translator
144
4. `DefaultExecuteListenerProvider` - Wraps exception translator
145
5. `Settings` - If spring.jooq.config property is specified
146
6. `DefaultConfiguration` - Combines all components
147
7. `DefaultDSLContext` - Main API entry point
148

149
### Overriding Auto-Configuration
150

151
You can override any auto-configured bean by providing your own:
152

153
```java
154
@Configuration
155
public class CustomJooqConfiguration {
156
    
157
    // Override default DSLContext
158
    @Bean
159
    @Primary
160
    public DSLContext customDslContext(org.jooq.Configuration configuration) {
161
        return new DefaultDSLContext(configuration);
162
    }
163
    
164
    // Override connection provider
165
    @Bean
166
    @Primary
167
    public ConnectionProvider customConnectionProvider(DataSource dataSource) {
168
        return new DataSourceConnectionProvider(dataSource);
169
    }
170
}
171

172
### Database Initialization Integration
173

174
Integration component that ensures jOOQ beans depend on database initialization completion.
175

176
```java { .api }
177
/**
178
 * DependsOnDatabaseInitializationDetector for jOOQ
179
 * Ensures DSLContext beans wait for database initialization to complete
180
 */
181
class JooqDependsOnDatabaseInitializationDetector extends AbstractBeansOfTypeDependsOnDatabaseInitializationDetector {
182
    
183
    /**
184
     * Returns the bean types that depend on database initialization
185
     * @return Set containing DSLContext.class
186
     */
187
    @Override
188
    protected Set<Class<?>> getDependsOnDatabaseInitializationBeanTypes();
189
}
190
```
191

192
This detector is automatically registered and ensures that jOOQ's `DSLContext` beans wait for database schema initialization (like Flyway or Liquibase migrations) to complete before being created.
193

194
### JAXB Settings Loader
195

196
Internal component that securely loads jOOQ settings from XML configuration files when `spring.jooq.config` property is specified.
197

198
```java { .api }
199
/**
200
 * Internal loader for jOOQ Settings from XML configuration files
201
 * Implements XML External Entity Prevention security measures
202
 * Used when spring.jooq.config property points to an XML configuration file
203
 */
204
private static final class JaxbSettingsLoader {
205
    
206
    /**
207
     * Load Settings from InputStream with secure XML parsing
208
     * @param inputStream the input stream containing XML configuration
209
     * @return Settings object parsed from XML
210
     * @throws IllegalStateException if XML parsing fails
211
     */
212
    private Settings load(InputStream inputStream);
213
    
214
    /**
215
     * Create secure SAX parser factory with security features enabled
216
     * @return SAXParserFactory configured for secure XML processing
217
     * @throws ParserConfigurationException if parser configuration fails
218
     * @throws SAXNotRecognizedException if security features not supported
219
     * @throws SAXNotSupportedException if security features not supported
220
     */
221
    private SAXParserFactory createParserFactory() 
222
        throws ParserConfigurationException, SAXNotRecognizedException, SAXNotSupportedException;
223
}
224
```
225

226
**Security Features:**
227
- Disables DOCTYPE declarations to prevent XXE attacks
228
- Enables XML secure processing feature
229
- Namespace aware parsing
230
- Disables XInclude processing for security
231

232
**Usage Example:**
233

234
```java
235
// This configuration will ensure proper ordering
236
@Configuration
237
public class DatabaseConfig {
238
    
239
    @Bean
240
    @FlywayDataSource
241
    public DataSource dataSource() {
242
        return new HikariDataSource();
243
    }
244
    
245
    // DSLContext will automatically wait for Flyway migrations
246
    // No additional configuration needed - handled by detector
247
    @Autowired
248
    private DSLContext dsl; // Available after migrations complete
249
}
250
```