1 /*
2 * #%L
3 * This file is part of a universal JDBC Connection factory.
4 * %%
5 * Copyright (C) 2014 - 2015 Michael Beiter <michael@beiter.org>
6 * %%
7 * All rights reserved.
8 * .
9 * Redistribution and use in source and binary forms, with or without
10 * modification, are permitted provided that the following conditions are met:
11 * * Redistributions of source code must retain the above copyright
12 * notice, this list of conditions and the following disclaimer.
13 * * Redistributions in binary form must reproduce the above copyright
14 * notice, this list of conditions and the following disclaimer in the
15 * documentation and/or other materials provided with the distribution.
16 * * Neither the name of the copyright holder nor the names of the
17 * contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
19 * .
20 * .
21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
22 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY
25 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
26 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
27 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
28 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
30 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 * #L%
32 */
33 package org.beiter.michael.db;
34
35 import org.apache.commons.dbcp2.DriverManagerConnectionFactory;
36 import org.apache.commons.dbcp2.PoolableConnection;
37 import org.apache.commons.dbcp2.PoolableConnectionFactory;
38 import org.apache.commons.dbcp2.PoolingDataSource;
39 import org.apache.commons.lang3.Validate;
40 import org.apache.commons.pool2.impl.GenericObjectPool;
41 import org.apache.commons.pool2.impl.GenericObjectPoolConfig;
42 import org.slf4j.Logger;
43 import org.slf4j.LoggerFactory;
44
45 import javax.naming.Context;
46 import javax.naming.InitialContext;
47 import javax.naming.NamingException;
48 import javax.sql.DataSource;
49 import java.sql.Connection;
50 import java.sql.SQLException;
51 import java.util.Properties;
52 import java.util.concurrent.ConcurrentHashMap;
53 import java.util.concurrent.ConcurrentMap;
54
55 /**
56 * This class creates and manages JDBC Connection instances from:
57 * <ul>
58 * <li>A named JNDI managed connection</li>
59 * <li>A connection pool that is maintained by this factory</li>
60 * </ul>
61 */
62 public final class ConnectionFactory {
63
64 /**
65 * The logger object for this class
66 */
67 private static final Logger LOG = LoggerFactory.getLogger(ConnectionFactory.class);
68
69
70 /**
71 * This hash map stores the generated pools per connection
72 */
73 private static final ConcurrentHashMap<String, PoolingDataSource<PoolableConnection>> CONNECTION_POOLS =
74 new ConcurrentHashMap<>();
75
76 /**
77 * A private constructor to prevent instantiation of this class
78 */
79 private ConnectionFactory() {
80 }
81
82 /**
83 * Return a Connection instance for a JNDI managed JDBC connection.
84 *
85 * @param jndiName The JNDI connection name
86 * @return a JDBC connection
87 * @throws FactoryException When the connection cannot be retrieved from JNDI
88 */
89 public static Connection getConnection(final String jndiName)
90 throws FactoryException {
91
92 Validate.notBlank(jndiName);
93
94 try {
95 // the initial context is created from the provided JNDI settings
96 final Context context = new InitialContext();
97
98 // retrieve a data source object, close the context as it is no longer needed, and return the connection
99 final Object namedObject = context.lookup(jndiName);
100 if (DataSource.class.isInstance(namedObject)) {
101 final DataSource dataSource = (DataSource) context.lookup(jndiName);
102 context.close();
103
104 return dataSource.getConnection();
105 } else {
106 final String error = "The JNDI name '" + jndiName + "' does not reference a SQL DataSource."
107 + " This is a configuration issue.";
108 LOG.warn(error);
109 throw new FactoryException(error);
110 }
111 } catch (SQLException | NamingException e) {
112 final String error = "Error retrieving JDBC connection from JNDI: " + jndiName;
113 LOG.warn(error);
114 throw new FactoryException(error, e);
115 }
116 }
117
118 /**
119 * Return a Connection instance from a pool that manages JDBC driver based connections.
120 * <p/>
121 * The driver-based connection are managed in a connection pool. The pool is created using the provided properties
122 * for both the connection and the pool spec. Once the pool has been created, it is cached (based on URL and
123 * username), and can no longer be changed. Subsequent calls to this method will return a connection from the
124 * cached pool, and changes in the pool spec (e.g. changes to the size of the pool) will be ignored.
125 *
126 * @param poolSpec A connection pool spec that has the driver and url configured as non-empty strings
127 * @return a JDBC connection
128 * @throws FactoryException When the connection cannot be retrieved from the pool, or the pool cannot be created
129 */
130 public static Connection getConnection(final ConnectionProperties poolSpec)
131 throws FactoryException {
132
133 Validate.notNull(poolSpec);
134 Validate.notBlank(poolSpec.getDriver());
135 Validate.notBlank(poolSpec.getUrl());
136
137 // no need for defensive copies of Strings
138
139 final String driver = poolSpec.getDriver();
140 final String url = poolSpec.getUrl();
141 // CHECKSTYLE:OFF
142 // this particular set of inline conditions is easy to read :-)
143 final String username = poolSpec.getUsername() == null ? "" : poolSpec.getUsername();
144 final String password = poolSpec.getPassword() == null ? "" : poolSpec.getPassword();
145 // CHECKSTYLE:OFF
146
147 // Load the database driver (if not already done)
148 loadDriver(driver);
149
150 // create the hash map required for the connection pool username + password
151 final ConcurrentMap<String, String> properties = new ConcurrentHashMap<>();
152 properties.put("user", username);
153 properties.put("password", password);
154
155 // we keep a separate pool per connection
156 // a connection is identified by the URL, the username, and the password
157 final String key = String.format("%s:%s", url, username);
158
159 // avoid if possible to create the pool multiple times, and store the data source pool for later use
160 if (!CONNECTION_POOLS.containsKey(key)) {
161 synchronized (ConnectionFactory.class) {
162 if (!CONNECTION_POOLS.containsKey(key)) {
163
164 // this call is thread safe even without the double if check and extra synchronization. However, it
165 // might happen that the pool is created multiple times. While additional copies would be simply
166 // thrown away, we might run into problems in case that, for instance, the number of connections
167 // from the same user / machine are restricted on the DB server.
168 // While this does not happen a lot (it only happens if there is not already an entry and multiple
169 // threads race this block and lose), it could still lead to a failure, and we must take this double
170 // sync workaround. There is a solution for Java 8 - see below.
171 CONNECTION_POOLS.putIfAbsent(key, getPoolingDataSource(url, properties, poolSpec));
172 }
173 }
174 }
175 // This would solve the problem of multiple pools being created and all but one being throws away, but it
176 // does not work before Java 8 because the "computeIfAbsent()" method with the lambda function is not
177 // available before Java 8:
178 // TODO: add the pooled data source with the "computeIfAbsent()" method to improve performance in Java 8
179 //CONNECTION_POOLS.computeIfAbsent(key, k -> getPoolingDataSource(url, properties, poolSpec));
180
181 try {
182 return CONNECTION_POOLS.get(key).getConnection();
183 } catch (SQLException e) {
184 final String error = "Error retrieving JDBC connection from pool: " + key;
185 LOG.warn(error);
186 throw new FactoryException(error, e);
187 }
188 }
189
190 /**
191 * Resets the internal state of the factory.
192 * <p/>
193 * <strong>This method does not release any resources that have been borrowed from the connection pools managed
194 * by this factory.</strong> To avoid resource leaks, you <strong>must</strong> close / return all connections to
195 * their pools before calling this method.
196 */
197 public static void reset() {
198
199 // Unset the cached connections
200 CONNECTION_POOLS.clear();
201 }
202
203 /**
204 * Make sure that the database driver exists
205 *
206 * @param driver The JDBC driver class to load
207 * @throws FactoryException When the driver cannot be loaded
208 */
209 private static void loadDriver(final String driver) throws FactoryException {
210
211 // assert in private method
212 assert driver != null : "The driver cannot be null";
213
214 LOG.debug("Loading the database driver '" + driver + "'");
215
216 // make sure the driver is available
217 try {
218 Class.forName(driver);
219 } catch (ClassNotFoundException e) {
220 final String error = "Error loading JDBC driver class: " + driver;
221 LOG.warn(error, e);
222 throw new FactoryException(error, e);
223 }
224 }
225
226 /**
227 * Get a pooled data source for the provided connection parameters.
228 *
229 * @param url The JDBC database URL of the form <code>jdbc:subprotocol:subname</code>
230 * @param properties A list of key/value configuration parameters to pass as connection arguments. Normally at
231 * least a "user" and "password" property should be included
232 * @param poolSpec A connection pool spec
233 * @return A pooled database connection
234 */
235 private static PoolingDataSource<PoolableConnection> getPoolingDataSource(final String url,
236 final ConcurrentMap<String, String> properties,
237 final ConnectionProperties poolSpec) {
238
239 // assert in private method
240 assert url != null : "The url cannot be null";
241 assert properties != null : "The properties cannot be null";
242 assert poolSpec != null : "The pol spec cannot be null";
243
244 LOG.debug("Creating new pooled data source for '" + url + "'");
245
246 // convert the properties hashmap to java properties
247 final Properties props = new Properties();
248 props.putAll(properties);
249
250 // create a Apache DBCP pool configuration from the pool spec
251 final GenericObjectPoolConfig poolConfig = new GenericObjectPoolConfig();
252 poolConfig.setMaxTotal(poolSpec.getMaxTotal());
253 poolConfig.setMaxIdle(poolSpec.getMaxIdle());
254 poolConfig.setMinIdle(poolSpec.getMinIdle());
255 poolConfig.setMaxWaitMillis(poolSpec.getMaxWaitMillis());
256 poolConfig.setTestOnCreate(poolSpec.isTestOnCreate());
257 poolConfig.setTestOnBorrow(poolSpec.isTestOnBorrow());
258 poolConfig.setTestOnReturn(poolSpec.isTestOnReturn());
259 poolConfig.setTestWhileIdle(poolSpec.isTestWhileIdle());
260 poolConfig.setTimeBetweenEvictionRunsMillis(poolSpec.getTimeBetweenEvictionRunsMillis());
261 poolConfig.setNumTestsPerEvictionRun(poolSpec.getNumTestsPerEvictionRun());
262 poolConfig.setMinEvictableIdleTimeMillis(poolSpec.getMinEvictableIdleTimeMillis());
263 poolConfig.setSoftMinEvictableIdleTimeMillis(poolSpec.getSoftMinEvictableIdleTimeMillis());
264 poolConfig.setLifo(poolSpec.isLifo());
265
266
267 // create the pool and assign the factory to the pool
268 final org.apache.commons.dbcp2.ConnectionFactory connFactory = new DriverManagerConnectionFactory(url, props);
269 final PoolableConnectionFactory poolConnFactory = new PoolableConnectionFactory(connFactory, null);
270 poolConnFactory.setDefaultAutoCommit(poolSpec.isDefaultAutoCommit());
271 poolConnFactory.setDefaultReadOnly(poolSpec.isDefaultReadOnly());
272 poolConnFactory.setDefaultTransactionIsolation(poolSpec.getDefaultTransactionIsolation());
273 poolConnFactory.setCacheState(poolSpec.isCacheState());
274 poolConnFactory.setValidationQuery(poolSpec.getValidationQuery());
275 poolConnFactory.setMaxConnLifetimeMillis(poolSpec.getMaxConnLifetimeMillis());
276 final GenericObjectPool<PoolableConnection> connPool = new GenericObjectPool<>(poolConnFactory, poolConfig);
277 poolConnFactory.setPool(connPool);
278
279 // create a new pooled data source
280 return new PoolingDataSource<>(connPool);
281 }
282 }