1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
|
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* <p>
* Database Connection Pool API.
* </p>
*
* <b>Overview in Dialog Form</b>
* <p>
* Q: How do I use the DBCP package?
* </p><p>
* A: There are two primary ways to access the DBCP pool, as a
* {@link java.sql.Driver Driver}, or as a {@link javax.sql.DataSource DataSource}.
* You'll want to create an instance of {@link org.apache.tomcat.dbcp.dbcp2.PoolingDriver} or
* {@link org.apache.tomcat.dbcp.dbcp2.PoolingDataSource}. When using one of these
* interfaces, you can just use your JDBC objects the way you normally would.
* Closing a {@link java.sql.Connection} will simply return it to its pool.
* </p>
* <p>
* Q: But {@link org.apache.tomcat.dbcp.dbcp2.PoolingDriver PoolingDriver} and
* {@link org.apache.tomcat.dbcp.dbcp2.PoolingDataSource PoolingDataSource} both expect an
* {@link org.apache.tomcat.dbcp.pool2.ObjectPool ObjectPool} as an input. Where do I
* get one of those?
* </p><p>
* A: The {@link org.apache.tomcat.dbcp.pool2.ObjectPool ObjectPool} interface is defined
* in Commons Pool. You can use one of the provided implementations such as
* {@link org.apache.tomcat.dbcp.pool2.impl.GenericObjectPool GenericObjectPool} or
* {@link org.apache.tomcat.dbcp.pool2.impl.SoftReferenceObjectPool SoftReferenceObjectPool}
* or you can create your own.
* </p>
* <p>
* Q: Ok, I've found an {@link org.apache.tomcat.dbcp.pool2.ObjectPool ObjectPool}
* implementation that I think suits my connection pooling needs. But it wants
* a {@link org.apache.tomcat.dbcp.pool2.PooledObjectFactory PooledObjectFactory}.
* What should I use for that?
* </p><p>
* A: The DBCP package provides a class for this purpose. It's called
* {@link org.apache.tomcat.dbcp.dbcp2.PoolableConnectionFactory}.
* It implements the factory and lifecycle methods of
* {@link org.apache.tomcat.dbcp.pool2.PooledObjectFactory}
* for {@link java.sql.Connection}s. But it doesn't create the actual database
* {@link java.sql.Connection}s itself, it uses a
* {@link org.apache.tomcat.dbcp.dbcp2.ConnectionFactory} for that.
* The {@link org.apache.tomcat.dbcp.dbcp2.PoolableConnectionFactory} will take
* {@link java.sql.Connection}s created by the {@link org.apache.tomcat.dbcp.dbcp2.ConnectionFactory}
* and wrap them with classes that implement the pooling behaviour.
* </p><p>
* Several implementations of {@link org.apache.tomcat.dbcp.dbcp2.ConnectionFactory} are
* provided--one that uses {@link java.sql.DriverManager} to create connections
* ({@link org.apache.tomcat.dbcp.dbcp2.DriverManagerConnectionFactory}),
* one that uses a {@link java.sql.Driver} to create connections
* ({@link org.apache.tomcat.dbcp.dbcp2.DriverConnectionFactory}),
* one that uses a {@link javax.sql.DataSource} to create connections
* ({@link org.apache.tomcat.dbcp.dbcp2.DataSourceConnectionFactory}).
* </p>
* <p>
* Q: I think I'm starting to get it, but can you walk me though it again?
* </p><p>
* A: Sure. Let's assume you want to create a {@link javax.sql.DataSource}
* that pools {@link java.sql.Connection}s. Let's also assume that
* those pooled {@link java.sql.Connection}s should be obtained from
* the {@link java.sql.DriverManager}.
* You'll want to create a {@link org.apache.tomcat.dbcp.dbcp2.PoolingDataSource}.
* </p><p>
* The {@link org.apache.tomcat.dbcp.dbcp2.PoolingDataSource} uses an underlying
* {@link org.apache.tomcat.dbcp.pool2.ObjectPool} to create and store its
* {@link java.sql.Connection}.
* </p><p>
* To create a {@link org.apache.tomcat.dbcp.pool2.ObjectPool}, you'll need
* a {@link org.apache.tomcat.dbcp.pool2.PooledObjectFactory} that creates
* the actual {@link java.sql.Connection}s. That's what
* {@link org.apache.tomcat.dbcp.dbcp2.PoolableConnectionFactory} is for.
* </p><p>
* To create the {@link org.apache.tomcat.dbcp.dbcp2.PoolableConnectionFactory},
* you'll need at least two things:
* <ol>
* <li>
* A {@link org.apache.tomcat.dbcp.dbcp2.ConnectionFactory} from which
* the actual database {@link java.sql.Connection}s will be obtained.
* </li>
* <li>
* An empty and factory-less {@link org.apache.tomcat.dbcp.pool2.ObjectPool}
* in which the {@link java.sql.Connection}s will be stored.
* <br></br>
* When you pass an {@link org.apache.tomcat.dbcp.pool2.ObjectPool} into the
* {@link org.apache.tomcat.dbcp.dbcp2.PoolableConnectionFactory}, it will
* automatically register itself as the {@link org.apache.tomcat.dbcp.pool2.PooledObjectFactory}
* for that pool.
* </li>
* </ol>
* </p><p>
* In code, that might look like this:
* <pre>GenericObjectPool connectionPool = new GenericObjectPool(null);
* ConnectionFactory connectionFactory = new DriverManagerConnectionFactory("jdbc:some:connect:string", "username", "password");
* PoolableConnectionFactory poolableConnectionFactory = new PoolableConnectionFactory(connectionFactory,connectionPool,null,null,false,true);
* PoolingDataSource dataSource = new PoolingDataSource(connectionPool);</pre>
* </p><p>
* To create a {@link org.apache.tomcat.dbcp.dbcp2.PoolingDriver}, we do the same thing,
* except that instead of creating a {@link javax.sql.DataSource} on the last line,
* we create a {@link org.apache.tomcat.dbcp.dbcp2.PoolingDriver}, and register the
* {@code connectionPool} with it. E.g.,:
* <pre>GenericObjectPool connectionPool = new GenericObjectPool(null);
* ConnectionFactory connectionFactory = new DriverManagerConnectionFactory("jdbc:some:connect:string", "username", "password");
* PoolableConnectionFactory poolableConnectionFactory = new PoolableConnectionFactory(connectionFactory,connectionPool,null,null,false,true);
* PoolingDriver driver = new PoolingDriver();
* driver.registerPool("example",connectionPool);</pre>
* </p><p>
* Since the {@link org.apache.tomcat.dbcp.dbcp2.PoolingDriver} registers itself
* with the {@link java.sql.DriverManager} when it is created, now you can just
* go to the {@link java.sql.DriverManager} to create your {@link java.sql.Connection}s,
* like you normally would:
* <pre>Connection conn = DriverManager.getConnection("jdbc:apache:commons:dbcp:example");</pre>
* </p>
*/
package org.apache.tomcat.dbcp.dbcp2;
|
