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
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Language" content="en-gb">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<meta http-equiv="Expires" content="-1">
<meta http-equiv="Pragma" content="no-cache">
<title>Proxool 0.9.0RC3</title>
<link href="proxool.css" type="text/css" rel="stylesheet">
</head>
<body>
<div style="max-width: 1200px;">
<table border="0" style="min-height: 100%;" cellpadding="0" cellspacing="0" width="100%">
<tbody>
<tr>
<td valign="bottom" width="150">
</td>
<td colspan="2" height="50">
<div class="bannerFinal">
<table cellpadding="0" cellspacing="0" border="0" width="100%">
<tr>
<td height="50">
<span class="titleCaption" style="font-size: 110%; padding: 4px;">
Experimental DataSource Implemetation
</span>
</td>
<td valign="middle" height="50">
<div>
<div style="float: right; margin-right: 8px;">
<img src="images/dots.gif" width="80" height="20" border="0" alt="...">
<a href="http://sourceforge.net/projects/proxool"><img src="images/sflogo.png" width="88" height="31" border="0" alt="SourceForge.net Logo"></a>
</div>
</div>
</td>
</tr>
</table>
</div>
<td width="10"> </td>
</tr>
<tr>
<td valign="top" width="150">
<br/>
<br/>
<table
cellpadding="0"
cellspacing="0"
border="0"
width="100%"
>
<tbody>
<tr>
<td valign="top">
<div class="menuBox" >
<div class="menu-inactive"><a class="menu-inactive" href="index.html">Home</a></div>
<div class="menu-inactive"><a class="menu-inactive" href="news.html">News</a></div>
<div class="menu-inactive"><a class="menu-inactive" href="faq.html">FAQ</a></div>
<div class="menu-inactive"><a class="menu-inactive" href="tips.html">Tips</a></div>
<div class="menu-inactive"><a class="menu-inactive" href="changelog.html">Changes</a></div>
<div class="menu-inactive"><a class="menu-inactive" href="future.html">The Future</a></div>
<div class="menu-active"><a class="menu-active" href="user.html">User Guide</a></div>
<div class="menu-inactive"><a class="menu-inactive" href="dev.html">Developer Guide</a></div>
<div class="menu-inactive"><a class="menu-inactive" href="licence.html">Licence</a></div>
<div class="menu-inactive"><a class="menu-inactive" href="credits.html">Credits</a></div>
<div class="menu-separater">User Guide:</div>
<div style="margin-left: 8px">
<div class="menu-inactive"><a class="menu-inactive" href="user.html">Introduction</a></div>
<div class="menu-inactive"><a class="menu-inactive" href="quickStart.html">Quick start</a></div>
<div class="menu-inactive"><a class="menu-inactive" href="properties.html">Properties</a></div>
<div class="menu-inactive"><a class="menu-inactive" href="configure.html">Configuration</a></div>
<div class="menu-inactive"><a class="menu-inactive" href="logging.html">Logging</a></div>
<div class="menu-inactive"><a class="menu-inactive" href="admin.html">Admin</a></div>
<div class="menu-inactive"><a class="menu-inactive" href="adminServlet.html">AdminServlet</a></div>
<div class="menu-inactive"><a class="menu-inactive" href="listen.html">Events</a></div>
<div class="menu-inactive"><a class="menu-inactive" href="servlets.html">Servlets</a></div>
<div class="menu-inactive"><a class="menu-inactive" href="api/index.html">Simple API</a></div>
<div class="menu-inactive"><a class="menu-inactive" href="howitworks.html">How it works</a></div>
<div class="menu-active"><a class="menu-active" href="datasource.html">DataSource</a></div>
<div class="menu-inactive"><a class="menu-inactive" href="injectableInterfaces.html">Injectable Interfaces</a></div>
</div>
</div>
</td>
<td> </td>
</tr>
<tr>
<td>
<table cellpadding="0" cellspacing="0" border="0" summary="">
<tbody>
<tr><td>
<div class="rightItem">
<div class="rightItemHeader">Version 0.9.0RC3</div>
<div class="rightItemContent">
The latest version of this documentation and software is available on our web site:
<br/><a href="http://proxool.sf.net">proxool.sf.net</a>
</div>
</div>
<div class="rightItem">
<div class="rightItemHeader">Donations</div>
<div class="rightItemContent">
You can donate to Proxool in the usual way:
<br/><a href="http://sourceforge.net/project/project_donations.php?group_id=53958">sourceforge.net</a>
</div>
</div>
</td></tr>
<tr>
<td>
<div class="footer">
last updated: 10-Jan-2007
</div>
</td>
</tr>
</tbody>
</table>
</td>
<td> </td>
</tr>
</tbody>
</table>
</td>
<td valign="top" colspan="2">
<table cellpadding="0" cellspacing="0" border="0" width="100%" summary="">
<tbody>
<tr>
<td class="contents" valign="top">
<H1>Proxool DataSource support</H1>
<P>
1. <A href="#intro">Introduction</A> <BR>
2. <A href="#about">About the DataSource</A> <BR>
3. <A href="#deploy">DataSource deployment</A><BR>
4. <A href="#conf">ProxoolDataSource configuration</A><BR>
5. <A href="#examples">Configuration example for Tomcat</A> <BR>
6. <A href="#resources">Resources</A>
</P>
<A name=intro></A>
<H2>1. Introduction</H2>
<P> Community feedback suggests that JDBC DataSource support has been the
most sorely missed feature amongst Proxool users. The JDBC JavaDoc documentation
also states that "the use of a DataSource object is the preferred means of connecting
to a data source", so we have endeavoured to implement a
simple DataSource implementation for Proxool.</P>
<P><STRONG>Be warned</STRONG>:<BR>ProxoolDataSource is a simple DataSource
implementation. It does not currently implement PooledDataSource or support
distributed transactions. Also, it does not integrate directly with your
container, so do not use ProxoolDataSource if you are using Container Manged
Persistance etc. unless your container explicitly allows you to swap to a third
party DataSource implementation.</P>
<A name=about></A>
<H2>2. About the DataSource</H2>
<P>Like the <code>java.sql.DriverManager</code> the <code>javax.sql.DataSource</code> is a factory for
<code>java.sql.Connection</code> instances. The application must
include specific configuration information about the data source (e.g. a
connection url) when obtaining
a connection from the <code>DriverManger</code>
. This
creates a somewhat explicit coupling between your application and the data source. </P>
<P>A DataSource however is configured outside of your application and retrieved
through a naming service (JNDI). This makes the configuration of the DataSource
completely decoupled from your code. </P>
<A name=deploy></A>
<H2>3. DataSource deployment</H2>
<P> DataSources are normally deployed within a Servlet or J2EE container.
The J2EE 1.4 specification recommends that the DataSources are placed in the 'jdbc'
subcontext of the application component's JNDI environment
(java:comp/env/). For example: the full JNDI name of a DataSource named 'UserDB'
would be "java:comp/env/jdbc/UserDB". The specification also states that
applications must declare the DataSources they are using in 'resource-ref'
elements in their deployment descriptor. </P>
<P>The java:comp/env/ environment is read-only at runtime, and the spec states
that the container vendor must "provide a deployment tool that allows the
Deployer to set and modify the values of the application component's environment
entries." This is where the spec ends and implementation specifics begin. </P>
<P> Most containers come with their own DataSource
implementation that can be configured and deployed with a tool or through
vendor specific configuration files. The support for plugging
in a third party DataSource implementation like Proxool is extremely varied. Some
vendors have direct support for this, while others make it almost impossible
to deploy a foreign DataSource into the java:comp/env/jdbc/ namespace. Remember:
this is outside of the spec and there is no common way to achieve it. Because of this we have made the ProxoolDataSource
configurable in a number of different ways. The next section describes
these ways.</P>
<A name=conf></A>
<H2>4. ProxoolDataSource configuration</H2>
<P>We have made it possible to configure ProxoolDatasource
in three different ways to make it useful in as many deployment scenarios as
possible.</P>
<A name=factory></A>
<H3>ObjectFactory configuration</H3>
<P>ProxoolDataSource implements the
javax.naming.spi.ObjectFactory interface. This is the standard way of providing
a factory for object implementations in JNDI. In such a scenario
ProxoolDatasource functions as a ObjectFactory for DataSource instances. It is a
practical way of deploying a ProxoolDataSource into the JNDI environment
for containers that supports this idiom. You configure the
ProxoolDataSource ObjectFactory by handing it the Proxool <A
href="http://proxool.sourceforge.net/properties.html"
target=_blank>properties</A> plus properties for the underlying JDBC
Driver. The Proxool properties must be prefixed with 'proxool.'. Properties not
prefixed with 'proxool.' will be passed on to the underlying JDBC driver ('delegate driver'
in Proxool parlance).</P>
<H3>JavaBean configuration</H3>
<P>ProxoolDataSource exposes its configuration properties
as JavaBean getters and setters. This is useful for containers that offer the
posibility of configuring and deploying JavaBeans into the JNDI
environment. It also makes it possible to deploy ProxoolDataSources through
component frameworks like the Spring Framework. Since a lot of the Proxool
propery names are illegal bean property names we have applied the following
translation: '-<lower case letter>' is translated to <upper case
letter>. E.g.:<BR>
'maximum-connection-count' becomes 'maximumConnectionCount'.</P>
<P>All properties that are to be passed to the
underlying JDBC driver are set with the 'driverProperties' property as a comma
separated property string.
E.g.:<BR>proxoolDataSource.setDriverProperties("user=testUser,
password=testPassword, loglevel=WARN");<BR>
</P>
<H3>Self-deployed configuration</H3>
<P> In this scenario Proxool
itself instantiates ProxoolDataSources and binds them to JNDI names. This is the
least standard-conformant way of deploying a ProxoolDataSource. It is also the only way that
is garanteed to work in any setting as long as there is a writable JNDI
name available for the Proxool process when it starts up. You configure Proxool
as you would when using it through the DriverManager. In addition you use the new
'jndi-name' configuration property to tell Proxool to wrap a pool in a
ProxoolDataSource and bind it to JNDI. In addition any properties you
prefix with 'jndi-' will be passed on the JNDI InitialContext used to bind
Proxool. E.g:<BR>
</P>
<div class="code"><pre>
<span class="xml-tag"><proxool></span>
<span class="xml-tag"><alias></span>jndi-test<span class="xml-tag"></alias></span>
<span class="xml-tag"><driver-url></span>jdbc:hsqldb:.<span class="xml-tag"></driver-url></span>
<span class="xml-tag"><driver-class></span>org.hsqldb.jdbcDriver<span class="xml-tag"></driver-class></span>
<span class="xml-tag"><driver-class></span>org.hsqldb.jdbcDriver<span class="xml-tag"></driver-class></span>
<span class="xml-tag"><driver-properties></span>
<span class="xml-tag"><property name=<span class="xml-quote">"user"</span> value=<span class="xml-quote">"sa"</span>/></span>
<span class="xml-tag"><property name=<span class="xml-quote">"password"</span> value=<span class="xml-quote">""</span>/></span>
<span class="xml-tag"></driver-properties></span>
<b><span class="xml-tag"><jndi-name></span>/datasources/UserDB<span class="xml-tag"></jndi-name></span></b>
<b><span class="xml-tag"><jndi-java.naming.factory.initial></span>com.caucho.naming.InitialContextFactoryImpl<span class="xml-tag"></jndi-java.naming.factory.initial></span></b>
<b><span class="xml-tag"><jndi-java.naming.provider.url></span>localhost:1099<span class="xml-tag"></jndi-java.naming.provider.url></span></b>
<span class="xml-tag"></proxool></span></pre></div>
<P>Make sure that jndi-name is actually writable. Remember that the
java:comp/env/ environment is read-only at runtime, so your ProxoolDataSources
need to go somewhere else in this configuration scenario.</P>
<P>Also remember that with this configuration option Proxool
needs to be explicitly initialised, for example using the <A
href="http://proxool.sourceforge.net/servlets.html" target=_blank>ServletConfigurator</A>.</P>
<P></P>
<A name=examples></A>
<H2>5. Configuration example for Tomcat</H2>
<P>Configuration method: <A href="#factory">ObjectFactory</A> </P>
<P>Configure a resource with ProxoolDataSource as the factory in server.xml (or the other places a context element can exist): </P>
<P>
</P>
<div class="code"><pre>
<context>
<Resource
name="jdbc/mydatasource"
auth="Container"
type="javax.sql.DataSource"
factory="org.logicalcobwebs.proxool.ProxoolDataSource"
proxool.alias="hrs"
user="joe"
password="******"
delegateProperties="foo=bar"
proxool.driver-url="jdbc:oracle:thin:@127.0.0.1:1521:DB"
proxool.driver-class="oracle.jdbc.driver.OracleDriver"/>
</context>
</pre></div>
<P> </P>
<P></P>
<A name=resources></A>
<H2>6. Resources</H2>
<UL>
<LI>
J2SE 1.4.2
DataSource interface <A
href="http://java.sun.com/j2se/1.4.2/docs/api/javax/sql/DataSource.html"
target=_blank>JavaDoc</A>.
<LI>Chapter 9.4 "The DataSource Interface" of the <A
href="http://java.sun.com/products/jdbc/download.html#corespec30"
target=_blank>JDBC 3.0 specification</A>.
<LI>The Sun <A href="http://java.sun.com/products/jndi/tutorial/index.html"
target=_blank>JNDI tutorial</A>.
<LI>Chapter 5.4 "Resource Manager Connection Factory
References" of the <A href="http://java.sun.com/j2ee/j2ee-1_4-fr-spec.pdf"
target=_blank>J2EE 1.4 specification</A>.
<LI>J2SE 1.4.2 ObjectFactory interface <A
href="http://java.sun.com/j2se/1.4.2/docs/api/javax/naming/spi/ObjectFactory.html"
target=_blank>JavaDoc</A>.
<LI>The <A
href="http://java.sun.com/j2se/1.4.2/docs/api/javax/naming/spi/ObjectFactory.html"
target=_blank>Spring</A> Framework.</LI>
</UL>
</td>
</tr>
</tbody>
</table>
</td>
</tr>
</tbody>
</table>
</div>
</body>
<head>
<meta http-equiv="Expires" content="-1">
<meta http-equiv="Pragma" content="no-cache">
</head>
</html>
|
