0
# Framework Integration
1

2
Native integration with popular Java frameworks including Hibernate ORM and JNDI environments for seamless adoption in enterprise applications.
3

4
## Capabilities
5

6
### Hibernate Integration
7

8
Native integration with Hibernate ORM providing connection pooling for Hibernate-based applications.
9

10
```java { .api }
11
/**
12
 * Connection provider for Hibernate 4.3+. This provider is deprecated in favor of
13
 * the official Hibernate HikariCP provider available in Hibernate 4.3.6+.
14
 */
15
public class HikariConnectionProvider implements ConnectionProvider, Configurable, Stoppable {
16
    /**
17
     * Default constructor
18
     */
19
    public HikariConnectionProvider();
20
}
21
```
22

23
**ConnectionProvider Methods:**
24

25
```java { .api }
26
/**
27
 * Get a connection from the HikariCP pool
28
 * @return Connection from the pool
29
 * @throws SQLException if unable to obtain connection
30
 */
31
public Connection getConnection() throws SQLException;
32

33
/**
34
 * Close/return a connection to the pool
35
 * @param conn the connection to close
36
 * @throws SQLException if error occurs closing connection
37
 */
38
public void closeConnection(Connection conn) throws SQLException;
39

40
/**
41
 * HikariCP does not support aggressive connection release
42
 * @return false - aggressive release not supported
43
 */
44
public boolean supportsAggressiveRelease();
45

46
/**
47
 * Check if this provider can be unwrapped to the specified type
48
 * @param unwrapType the type to check for unwrapping
49
 * @return true if unwrappable to the specified type
50
 */
51
public boolean isUnwrappableAs(Class unwrapType);
52

53
/**
54
 * Unwrap this provider to the specified type
55
 * @param unwrapType the type to unwrap to
56
 * @return unwrapped object
57
 * @throws UnknownUnwrapTypeException if unwrapping is not supported
58
 */
59
public <T> T unwrap(Class<T> unwrapType);
60
```
61

62
**Configuration Methods:**
63

64
```java { .api }
65
/**
66
 * Configure the connection provider from Hibernate properties
67
 * @param props Map of Hibernate configuration properties
68
 * @throws HibernateException if configuration fails
69
 */
70
public void configure(Map props) throws HibernateException;
71

72
/**
73
 * Stop the connection provider and close the data source
74
 */
75
public void stop();
76
```
77

78
**Usage Examples:**
79

80
```java
81
// Hibernate configuration (hibernate.cfg.xml)
82
/*
83
<hibernate-configuration>
84
    <session-factory>
85
        <!-- Database connection settings -->
86
        <property name="hibernate.connection.provider_class">
87
            com.zaxxer.hikari.hibernate.HikariConnectionProvider
88
        </property>
89
        <property name="hibernate.connection.driver_class">org.postgresql.Driver</property>
90
        <property name="hibernate.connection.url">jdbc:postgresql://localhost:5432/mydb</property>
91
        <property name="hibernate.connection.username">user</property>
92
        <property name="hibernate.connection.password">password</property>
93
        
94
        <!-- HikariCP specific settings -->
95
        <property name="hibernate.hikari.maximumPoolSize">20</property>
96
        <property name="hibernate.hikari.minimumIdle">5</property>
97
        <property name="hibernate.hikari.connectionTimeout">30000</property>
98
        <property name="hibernate.hikari.idleTimeout">600000</property>
99
        <property name="hibernate.hikari.maxLifetime">1800000</property>
100
        <property name="hibernate.hikari.leakDetectionThreshold">60000</property>
101
        
102
        <!-- DataSource properties -->
103
        <property name="hibernate.hikari.dataSource.cachePrepStmts">true</property>
104
        <property name="hibernate.hikari.dataSource.prepStmtCacheSize">250</property>
105
        <property name="hibernate.hikari.dataSource.prepStmtCacheSqlLimit">2048</property>
106
    </session-factory>
107
</hibernate-configuration>
108
*/
109

110
// Programmatic configuration
111
Properties hibernateProps = new Properties();
112
hibernateProps.setProperty("hibernate.connection.provider_class", 
113
    "com.zaxxer.hikari.hibernate.HikariConnectionProvider");
114
hibernateProps.setProperty("hibernate.connection.driver_class", "org.postgresql.Driver");
115
hibernateProps.setProperty("hibernate.connection.url", "jdbc:postgresql://localhost:5432/mydb");
116
hibernateProps.setProperty("hibernate.connection.username", "user");
117
hibernateProps.setProperty("hibernate.connection.password", "password");
118

119
// HikariCP settings
120
hibernateProps.setProperty("hibernate.hikari.maximumPoolSize", "20");
121
hibernateProps.setProperty("hibernate.hikari.minimumIdle", "5");
122
hibernateProps.setProperty("hibernate.hikari.connectionTimeout", "30000");
123

124
Configuration configuration = new Configuration();
125
configuration.setProperties(hibernateProps);
126
SessionFactory sessionFactory = configuration.buildSessionFactory();
127
```
128

129
### Hibernate Configuration Utility
130

131
Utility class for mapping Hibernate properties to HikariCP configuration.
132

133
```java { .api }
134
/**
135
 * Utility class to map Hibernate properties to HikariCP configuration properties
136
 */
137
public class HikariConfigurationUtil {
138
    /** Configuration prefix for HikariCP properties in Hibernate */
139
    public static final String CONFIG_PREFIX = "hibernate.hikari.";
140
    
141
    /** Configuration prefix for DataSource properties in Hibernate */
142
    public static final String CONFIG_PREFIX_DATASOURCE = "hibernate.hikari.dataSource.";
143
    
144
    /**
145
     * Create/load a HikariConfig from Hibernate properties
146
     * @param props a map of Hibernate properties
147
     * @return a HikariConfig instance
148
     */
149
    public static HikariConfig loadConfiguration(Map props);
150
}
151
```
152

153
**Usage Examples:**
154

155
```java
156
// Custom Hibernate configuration loading
157
Map<String, String> hibernateProperties = new HashMap<>();
158
hibernateProperties.put("hibernate.connection.driver_class", "org.postgresql.Driver");
159
hibernateProperties.put("hibernate.connection.url", "jdbc:postgresql://localhost:5432/mydb");
160
hibernateProperties.put("hibernate.connection.username", "user");
161
hibernateProperties.put("hibernate.connection.password", "password");
162

163
// HikariCP specific properties
164
hibernateProperties.put("hibernate.hikari.maximumPoolSize", "25");
165
hibernateProperties.put("hibernate.hikari.minimumIdle", "5");
166
hibernateProperties.put("hibernate.hikari.connectionTimeout", "20000");
167

168
// DataSource specific properties
169
hibernateProperties.put("hibernate.hikari.dataSource.cachePrepStmts", "true");
170
hibernateProperties.put("hibernate.hikari.dataSource.prepStmtCacheSize", "250");
171

172
// Load HikariConfig from Hibernate properties
173
HikariConfig hikariConfig = HikariConfigurationUtil.loadConfiguration(hibernateProperties);
174

175
// Use with HikariDataSource directly
176
HikariDataSource dataSource = new HikariDataSource(hikariConfig);
177
```
178

179
### Property Mapping
180

181
Standard Hibernate properties are automatically mapped to HikariCP equivalents:
182

183
| Hibernate Property | HikariCP Property |
184
|-------------------|-------------------|
185
| `hibernate.connection.isolation` | `transactionIsolation` |
186
| `hibernate.connection.autocommit` | `autoCommit` |
187
| `hibernate.connection.driver_class` | `driverClassName` |
188
| `hibernate.connection.url` | `jdbcUrl` |
189
| `hibernate.connection.username` | `username` |
190
| `hibernate.connection.password` | `password` |
191
192
## JNDI Integration
193

194
Factory class for creating HikariDataSource instances through JNDI lookup.
195

196
```java { .api }
197
/**
198
 * A JNDI factory that produces HikariDataSource instances
199
 */
200
public class HikariJNDIFactory implements ObjectFactory {
201
    /**
202
     * Create a HikariDataSource instance from JNDI reference
203
     * @param obj the JNDI reference object
204
     * @param name the JNDI name
205
     * @param nameCtx the naming context
206
     * @param environment the environment hashtable
207
     * @return HikariDataSource instance or null if not applicable
208
     * @throws Exception if creation fails
209
     */
210
    public Object getObjectInstance(Object obj, Name name, Context nameCtx, 
211
                                  Hashtable<?, ?> environment) throws Exception;
212
}
213
```
214

215
**Usage Examples:**
216

217
```java
218
// JNDI Resource configuration (web.xml or context.xml)
219
/*
220
<Resource name="jdbc/MyDB"
221
          auth="Container"
222
          type="javax.sql.DataSource"
223
          factory="com.zaxxer.hikari.HikariJNDIFactory"
224
          jdbcUrl="jdbc:postgresql://localhost:5432/mydb"
225
          username="user"
226
          password="password"
227
          maximumPoolSize="20"
228
          minimumIdle="5"
229
          connectionTimeout="30000"
230
          idleTimeout="600000"
231
          maxLifetime="1800000" />
232
*/
233

234
// Application code using JNDI lookup
235
Context initContext = new InitialContext();
236
Context envContext = (Context) initContext.lookup("java:/comp/env");
237
DataSource dataSource = (DataSource) envContext.lookup("jdbc/MyDB");
238

239
// Use DataSource normally
240
try (Connection conn = dataSource.getConnection()) {
241
    // Database operations
242
}
243

244
// Alternative direct lookup
245
DataSource dataSource = (DataSource) new InitialContext().lookup("java:/comp/env/jdbc/MyDB");
246
```
247

248
### JNDI with DataSource Reference
249

250
Configure HikariCP to wrap an existing JNDI DataSource:
251

252
**Usage Examples:**
253

254
```java
255
// JNDI configuration with DataSource reference
256
/*
257
<Resource name="jdbc/MyDB"
258
          auth="Container"
259
          type="javax.sql.DataSource"
260
          factory="com.zaxxer.hikari.HikariJNDIFactory"
261
          dataSourceJNDI="java:/comp/env/jdbc/UnderlyingDataSource"
262
          maximumPoolSize="20"
263
          minimumIdle="5"
264
          connectionTimeout="30000" />
265

266
<Resource name="jdbc/UnderlyingDataSource"
267
          auth="Container"
268
          type="javax.sql.DataSource"
269
          driverClassName="org.postgresql.Driver"
270
          url="jdbc:postgresql://localhost:5432/mydb"
271
          username="user"
272
          password="password" />
273
*/
274

275
// This configuration will:
276
// 1. Look up the underlying DataSource from JNDI
277
// 2. Wrap it with HikariCP connection pooling
278
// 3. Make the pooled DataSource available via JNDI
279
```
280

281
## Spring Framework Integration
282

283
While HikariCP doesn't provide Spring-specific classes, it integrates seamlessly with Spring's DataSource configuration.
284

285
**Usage Examples:**
286

287
```java
288
// Spring Boot application.properties
289
/*
290
spring.datasource.type=com.zaxxer.hikari.HikariDataSource
291
spring.datasource.hikari.jdbc-url=jdbc:postgresql://localhost:5432/mydb
292
spring.datasource.hikari.username=user
293
spring.datasource.hikari.password=password
294
spring.datasource.hikari.maximum-pool-size=20
295
spring.datasource.hikari.minimum-idle=5
296
spring.datasource.hikari.connection-timeout=30000
297
spring.datasource.hikari.idle-timeout=600000
298
spring.datasource.hikari.max-lifetime=1800000
299
spring.datasource.hikari.pool-name=MyAppPool
300
*/
301

302
// Spring XML configuration
303
/*
304
<bean id="dataSource" class="com.zaxxer.hikari.HikariDataSource" destroy-method="close">
305
    <property name="jdbcUrl" value="jdbc:postgresql://localhost:5432/mydb"/>
306
    <property name="username" value="user"/>
307
    <property name="password" value="password"/>
308
    <property name="maximumPoolSize" value="20"/>
309
    <property name="minimumIdle" value="5"/>
310
    <property name="connectionTimeout" value="30000"/>
311
    <property name="idleTimeout" value="600000"/>
312
    <property name="maxLifetime" value="1800000"/>
313
</bean>
314
*/
315

316
// Spring Java Configuration
317
@Configuration
318
public class DatabaseConfig {
319
    
320
    @Bean(destroyMethod = "close")
321
    public DataSource dataSource() {
322
        HikariConfig config = new HikariConfig();
323
        config.setJdbcUrl("jdbc:postgresql://localhost:5432/mydb");
324
        config.setUsername("user");
325
        config.setPassword("password");
326
        config.setMaximumPoolSize(20);
327
        config.setMinimumIdle(5);
328
        config.setConnectionTimeout(30000);
329
        config.setIdleTimeout(600000);
330
        config.setMaxLifetime(1800000);
331
        config.setPoolName("MyAppPool");
332
        
333
        return new HikariDataSource(config);
334
    }
335
    
336
    @Bean
337
    public JdbcTemplate jdbcTemplate(DataSource dataSource) {
338
        return new JdbcTemplate(dataSource);
339
    }
340
}
341

342
// Spring Boot Configuration Class
343
@Configuration
344
@ConfigurationProperties(prefix = "spring.datasource.hikari")
345
public class HikariConfigProperties extends HikariConfig {
346
    // Spring Boot will automatically populate this from application.properties
347
}
348

349
@Configuration
350
public class DataSourceConfig {
351
    
352
    @Bean
353
    @Primary
354
    public DataSource dataSource(HikariConfigProperties hikariConfig) {
355
        return new HikariDataSource(hikariConfig);
356
    }
357
}
358
```
359

360
## Application Server Integration
361

362
Integration patterns for various application servers.
363

364
**Usage Examples:**
365

366
```java
367
// Tomcat context.xml
368
/*
369
<Context>
370
    <Resource name="jdbc/MyDB"
371
              auth="Container"
372
              type="javax.sql.DataSource"
373
              factory="com.zaxxer.hikari.HikariJNDIFactory"
374
              jdbcUrl="jdbc:postgresql://localhost:5432/mydb"
375
              username="user"
376
              password="password"
377
              maximumPoolSize="20" />
378
</Context>
379
*/
380

381
// WildFly/JBoss standalone.xml datasource
382
/*
383
<datasource jndi-name="java:/jdbc/MyDB" pool-name="MyDBPool">
384
    <connection-url>jdbc:postgresql://localhost:5432/mydb</connection-url>
385
    <driver>postgresql</driver>
386
    <security>
387
        <user-name>user</user-name>
388
        <password>password</password>
389
    </security>
390
    <pool>
391
        <min-pool-size>5</min-pool-size>
392
        <max-pool-size>20</max-pool-size>
393
    </pool>
394
</datasource>
395
*/
396

397
// WebLogic data source configuration (programmatic)
398
public class WebLogicDataSourceConfig {
399
    public DataSource createHikariDataSource() throws NamingException {
400
        HikariConfig config = new HikariConfig();
401
        config.setJdbcUrl("jdbc:postgresql://localhost:5432/mydb");
402
        config.setUsername("user");  
403
        config.setPassword("password");
404
        config.setMaximumPoolSize(20);
405
        config.setMinimumIdle(5);
406
        
407
        HikariDataSource dataSource = new HikariDataSource(config);
408
        
409
        // Bind to JNDI for application access
410
        Context context = new InitialContext();
411
        context.bind("java:comp/env/jdbc/MyDB", dataSource);
412
        
413
        return dataSource;
414
    }
415
}
416
```
417

418
### Enterprise Application Integration
419

420
Patterns for enterprise application integration with connection pooling.
421

422
**Usage Examples:**
423

424
```java
425
// Enterprise application lifecycle management
426
public class ApplicationDataSourceManager {
427
    private HikariDataSource dataSource;
428
    private HikariPoolMXBean poolMBean;
429
    
430
    @PostConstruct
431
    public void initialize() {
432
        // Load configuration from enterprise configuration system
433
        HikariConfig config = loadConfigFromEnterprise();
434
        
435
        // Enable JMX for monitoring
436
        config.setRegisterMbeans(true);
437
        config.setPoolName("EnterpriseAppPool");
438
        
439
        // Create data source
440
        dataSource = new HikariDataSource(config);
441
        poolMBean = dataSource.getHikariPoolMXBean();
442
        
443
        // Register with enterprise monitoring
444
        registerWithMonitoringSystem();
445
    }
446
    
447
    @PreDestroy
448
    public void shutdown() {
449
        if (dataSource != null && !dataSource.isClosed()) {
450
            // Graceful shutdown
451
            poolMBean.suspendPool();
452
            
453
            // Wait for active connections to finish
454
            int attempts = 0;
455
            while (poolMBean.getActiveConnections() > 0 && attempts < 30) {
456
                try {
457
                    Thread.sleep(1000);
458
                    attempts++;
459
                } catch (InterruptedException e) {
460
                    Thread.currentThread().interrupt();
461
                    break;
462
                }
463
            }
464
            
465
            dataSource.close();
466
        }
467
    }
468
    
469
    public DataSource getDataSource() {
470
        return dataSource;
471
    }
472
    
473
    private HikariConfig loadConfigFromEnterprise() {
474
        // Load from enterprise configuration system
475
        // This could be from LDAP, database, config server, etc.
476
        return new HikariConfig();
477
    }
478
    
479
    private void registerWithMonitoringSystem() {
480
        // Register with enterprise monitoring system
481
        // This could be with JMX, custom monitoring, etc.
482
    }
483
}
484
```