0
# Data Sources
1

2
DataSource implementations for connection pooling, XA transactions, and enterprise application server integration with comprehensive JNDI support.
3

4
## Capabilities
5

6
### Basic DataSource
7

8
Standard DataSource implementation supporting connection pooling and XA transactions.
9

10
```java { .api }
11
/**
12
 * MariaDB DataSource implementation
13
 * Implements DataSource, ConnectionPoolDataSource, and XADataSource
14
 */
15
public class MariaDbDataSource implements DataSource, ConnectionPoolDataSource, XADataSource {
16
  /**
17
   * Get a connection to the database
18
   * @return Connection instance
19
   * @throws SQLException if connection fails
20
   */
21
  public Connection getConnection() throws SQLException;
22
  
23
  /**
24
   * Get a connection with specific credentials
25
   * @param username Database username
26
   * @param password Database password
27
   * @return Connection instance
28
   * @throws SQLException if connection fails
29
   */
30
  public Connection getConnection(String username, String password) throws SQLException;
31
  
32
  /**
33
   * Get a pooled connection
34
   * @return PooledConnection instance
35
   * @throws SQLException if connection fails
36
   */
37
  public PooledConnection getPooledConnection() throws SQLException;
38
  
39
  /**
40
   * Get a pooled connection with specific credentials
41
   * @param username Database username
42
   * @param password Database password
43
   * @return PooledConnection instance
44
   * @throws SQLException if connection fails
45
   */
46
  public PooledConnection getPooledConnection(String username, String password) throws SQLException;
47
  
48
  /**
49
   * Get an XA connection for distributed transactions
50
   * @return XAConnection instance
51
   * @throws SQLException if connection fails
52
   */
53
  public XAConnection getXAConnection() throws SQLException;
54
  
55
  /**
56
   * Get an XA connection with specific credentials
57
   * @param username Database username
58
   * @param password Database password
59
   * @return XAConnection instance
60
   * @throws SQLException if connection fails
61
   */
62
  public XAConnection getXAConnection(String username, String password) throws SQLException;
63
  
64
  // Configuration methods
65
  public void setUrl(String url);
66
  public String getUrl();
67
  public void setUser(String user);
68
  public String getUser();
69
  public void setPassword(String password);
70
  public void setDatabaseName(String databaseName);
71
  public String getDatabaseName();
72
  public void setServerName(String serverName);
73
  public String getServerName();
74
  public void setPort(int port);
75
  public int getPort();
76
  public void setLoginTimeout(int seconds) throws SQLException;
77
  public int getLoginTimeout() throws SQLException;
78
}
79
```
80

81
**Usage Examples:**
82

83
```java
84
// Basic DataSource configuration
85
MariaDbDataSource dataSource = new MariaDbDataSource();
86
dataSource.setUrl("jdbc:mariadb://localhost:3306/mydb");
87
dataSource.setUser("myuser");
88
dataSource.setPassword("mypass");
89

90
// Get connection from DataSource
91
Connection conn = dataSource.getConnection();
92

93
// Alternative: specify credentials at connection time
94
Connection conn2 = dataSource.getConnection("otheruser", "otherpass");
95

96
// For enterprise applications with connection pooling
97
PooledConnection pooledConn = dataSource.getPooledConnection();
98
Connection conn3 = pooledConn.getConnection();
99

100
// For distributed transactions
101
XAConnection xaConn = dataSource.getXAConnection();
102
Connection conn4 = xaConn.getConnection();
103
XAResource xaResource = xaConn.getXAResource();
104
```
105

106
### Pooled DataSource
107

108
DataSource with built-in connection pooling for high-performance applications.
109

110
```java { .api }
111
/**
112
 * MariaDB DataSource with built-in connection pooling
113
 * Extends MariaDbDataSource with pooling capabilities
114
 */
115
public class MariaDbPoolDataSource extends MariaDbDataSource implements Closeable, AutoCloseable {
116
  /**
117
   * Close the connection pool and all its connections
118
   * @throws SQLException if closing fails
119
   */
120
  public void close() throws SQLException;
121
  
122
  // Inherits all methods from MariaDbDataSource
123
  // Pool configuration through URL parameters or setUrl()
124
}
125
```
126

127
**Usage Examples:**
128

129
```java
130
// Create pooled DataSource
131
MariaDbPoolDataSource poolDataSource = new MariaDbPoolDataSource();
132
poolDataSource.setUrl("jdbc:mariadb://localhost:3306/mydb?pool=true&maxPoolSize=20&minPoolSize=5");
133
poolDataSource.setUser("myuser");
134
poolDataSource.setPassword("mypass");
135

136
try {
137
    // Use pooled connections
138
    Connection conn1 = poolDataSource.getConnection();
139
    Connection conn2 = poolDataSource.getConnection();
140
    
141
    // Connections are managed by the pool
142
    conn1.close(); // Returns to pool
143
    conn2.close(); // Returns to pool
144
    
145
} finally {
146
    // Close entire pool when done
147
    poolDataSource.close();
148
}
149

150
// Try-with-resources for automatic cleanup
151
try (MariaDbPoolDataSource poolDataSource = new MariaDbPoolDataSource()) {
152
    poolDataSource.setUrl("jdbc:mariadb://localhost:3306/mydb?pool=true");
153
    poolDataSource.setUser("user");
154
    poolDataSource.setPassword("pass");
155
    
156
    Connection conn = poolDataSource.getConnection();
157
    // Use connection...
158
} // Pool automatically closed
159
```
160

161
### Pooled Connection
162

163
Individual pooled connection with event notification support.
164

165
```java { .api }
166
/**
167
 * Pooled connection implementation
168
 * Implements both PooledConnection and XAConnection interfaces
169
 */
170
public class MariaDbPoolConnection implements PooledConnection, XAConnection {
171
  /**
172
   * Get the underlying database connection
173
   * @return Connection instance
174
   * @throws SQLException if connection retrieval fails
175
   */
176
  public Connection getConnection() throws SQLException;
177
  
178
  /**
179
   * Close the pooled connection
180
   * @throws SQLException if closing fails
181
   */
182
  public void close() throws SQLException;
183
  
184
  /**
185
   * Add listener for connection events
186
   * @param listener Event listener
187
   */
188
  public void addConnectionEventListener(ConnectionEventListener listener);
189
  
190
  /**
191
   * Remove connection event listener
192
   * @param listener Event listener to remove
193
   */
194
  public void removeConnectionEventListener(ConnectionEventListener listener);
195
  
196
  /**
197
   * Add listener for statement events
198
   * @param listener Statement event listener
199
   */
200
  public void addStatementEventListener(StatementEventListener listener);
201
  
202
  /**
203
   * Remove statement event listener
204
   * @param listener Statement event listener to remove
205
   */
206
  public void removeStatementEventListener(StatementEventListener listener);
207
  
208
  // XA transaction support
209
  /**
210
   * Get XA resource for distributed transactions
211
   * @return XAResource instance
212
   * @throws SQLException if XA resource retrieval fails
213
   */
214
  public XAResource getXAResource() throws SQLException;
215
}
216
```
217

218
**Usage Examples:**
219

220
```java
221
// Using pooled connections with event listeners
222
PooledConnection pooledConn = dataSource.getPooledConnection();
223

224
// Add connection event listener
225
pooledConn.addConnectionEventListener(new ConnectionEventListener() {
226
    public void connectionClosed(ConnectionEvent event) {
227
        System.out.println("Connection closed");
228
    }
229
    
230
    public void connectionErrorOccurred(ConnectionEvent event) {
231
        System.out.println("Connection error: " + event.getSQLException().getMessage());
232
    }
233
});
234

235
// Get and use the underlying connection
236
Connection conn = pooledConn.getConnection();
237
// Use connection...
238
conn.close(); // Triggers connectionClosed event
239

240
// For XA transactions
241
XAConnection xaConn = (XAConnection) pooledConn;
242
XAResource xaResource = xaConn.getXAResource();
243

244
// Distributed transaction management
245
Xid xid = new MariaDbXid(1, "global".getBytes(), "branch".getBytes());
246
xaResource.start(xid, XAResource.TMNOFLAGS);
247
// Perform database operations
248
Connection conn2 = xaConn.getConnection();
249
Statement stmt = conn2.createStatement();
250
stmt.executeUpdate("INSERT INTO table VALUES (1, 'data')");
251
xaResource.end(xid, XAResource.TMSUCCESS);
252
xaResource.prepare(xid);
253
xaResource.commit(xid, false);
254
```
255

256
### Pinned Pool Connection
257

258
Extended pooled connection for global transactions requiring connection affinity.
259

260
```java { .api }
261
/**
262
 * Pinned pooled connection for global transactions
263
 * Maintains connection affinity for transaction consistency
264
 */
265
public class MariaDbPoolPinnedConnection extends MariaDbPoolConnection {
266
  // Inherits all PooledConnection and XAConnection methods
267
  // Provides connection pinning for global transaction contexts
268
}
269
```
270

271
## JNDI Configuration
272

273
DataSources can be configured in application servers using JNDI:
274

275
```xml
276
<!-- In application server configuration (e.g., Tomcat context.xml) -->
277
<Resource name="jdbc/MariaDB"
278
          auth="Container"
279
          type="javax.sql.DataSource"
280
          factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
281
          driverClassName="org.mariadb.jdbc.Driver"
282
          url="jdbc:mariadb://localhost:3306/mydb"
283
          username="myuser"
284
          password="mypass"
285
          maxActive="20"
286
          maxIdle="10"
287
          minIdle="5"
288
          initialSize="5"
289
          maxWait="10000" />
290
```
291

292
```java
293
// Lookup DataSource from JNDI
294
InitialContext ctx = new InitialContext();
295
DataSource dataSource = (DataSource) ctx.lookup("java:comp/env/jdbc/MariaDB");
296
Connection conn = dataSource.getConnection();
297
```
298

299
## Spring Framework Integration
300

301
```java
302
// Spring configuration
303
@Configuration
304
public class DatabaseConfig {
305
    
306
    @Bean
307
    @Primary
308
    public DataSource dataSource() {
309
        MariaDbDataSource dataSource = new MariaDbDataSource();
310
        dataSource.setUrl("jdbc:mariadb://localhost:3306/mydb");
311
        dataSource.setUser("myuser");
312
        dataSource.setPassword("mypass");
313
        return dataSource;
314
    }
315
    
316
    @Bean
317
    public DataSource pooledDataSource() {
318
        MariaDbPoolDataSource dataSource = new MariaDbPoolDataSource();
319
        dataSource.setUrl("jdbc:mariadb://localhost:3306/mydb?pool=true&maxPoolSize=20");
320
        dataSource.setUser("myuser");
321
        dataSource.setPassword("mypass");
322
        return dataSource;
323
    }
324
}
325

326
// Using in Spring components
327
@Service
328
public class UserService {
329
    
330
    @Autowired
331
    private DataSource dataSource;
332
    
333
    public List<User> getUsers() throws SQLException {
334
        try (Connection conn = dataSource.getConnection();
335
             Statement stmt = conn.createStatement();
336
             ResultSet rs = stmt.executeQuery("SELECT * FROM users")) {
337
            
338
            List<User> users = new ArrayList<>();
339
            while (rs.next()) {
340
                users.add(new User(rs.getString("name"), rs.getString("email")));
341
            }
342
            return users;
343
        }
344
    }
345
}
346
```
347

348
## Connection Pool Configuration
349

350
Connection pools can be configured through URL parameters:
351

352
```java
353
// Pool configuration parameters
354
String poolUrl = "jdbc:mariadb://localhost:3306/mydb?" +
355
    "pool=true&" +                    // Enable pooling
356
    "poolName=MyPool&" +              // Pool name for JMX
357
    "maxPoolSize=25&" +               // Maximum connections
358
    "minPoolSize=5&" +                // Minimum connections
359
    "maxIdleTime=600&" +              // Max idle time (seconds)
360
    "poolValidMinDelay=1000&" +       // Validation delay (ms)
361
    "registerJmxPool=true";           // Enable JMX monitoring
362

363
MariaDbPoolDataSource poolDataSource = new MariaDbPoolDataSource();
364
poolDataSource.setUrl(poolUrl);
365
poolDataSource.setUser("user");
366
poolDataSource.setPassword("password");
367
```