Menu
▾
▴
[Proxool-cvs] proxool-doc datasource.html,NONE,1.1
|
From: <ch...@us...> - 2004-09-29 14:59:46
|
Update of /cvsroot/proxool/proxool-doc In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv18496 Added Files: datasource.html Log Message: Saving here so it is not lost. --- NEW FILE: datasource.html --- <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <html> <head> <title>Untitled</title> <style type="text/css"> .code { margin-top: 4px; margin-bottom: 4px; padding: 5px 5px 5px 5px; color: inherit; background-color: #eeeeee; border: 1px dotted #003366; font-family: courier, courier new, monospace; font-size: 12px; line-height: 100%; white-space: pre; width: 98%; overflow: auto; /*overflow: scroll -moz-scrollbars-horizontal; overflow-x: auto;*/ } .xml-tag { color: #0000aa; background-color: inherit; } .xml-quote { color: #000000; background-color: inherit; } </style> </head> <body> <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 examples</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 examples</H2> <P>TODO</P> <H3>Resin 2.x</H3> <P>TODO</P> <H3>Resin 3.x</H3> <P>TODO</P> <H3>Tomcat 4.x</H3> <P>TODO</P> <H3>Tomcat 5.x</H3> <P>Configuration method: <A href="#factory">ObjectFactory</A> </P> <P>Configure a resource with ProxoolDataSource as the factory in server.xml: </P> <P> </P> <div class="code"><pre> <span class="xml-tag"><Context path=<span class="xml-quote">"/dstest"</span>></span> <span class="xml-tag"><Resource name=<span class="xml-quote">"jdbc/ObjectFactoryDS"</span> auth=<span class="xml-quote">"Container"</span> type=<span class="xml-quote">"org.logicalcobwebs.proxool.ProxoolDataSource"</span> /></span> <span class="xml-tag"><ResourceParams name=<span class="xml-quote">"jdbc/ObjectFactoryDS"</span>></span> <span class="xml-tag"><parameter></span> <span class="xml-tag"><name></span>factory<span class="xml-tag"></name></span> <span class="xml-tag"><value></span>org.logicalcobwebs.proxool.ProxoolDataSource<span class="xml-tag"></value></span> <span class="xml-tag"></parameter></span> <span class="xml-tag"><parameter></span> <span class="xml-tag"><name></span>proxool.alias<span class="xml-tag"></name></span> <span class="xml-tag"><value></span>ObjectFactoryDS<span class="xml-tag"></value></span> <span class="xml-tag"></parameter></span> <span class="xml-tag"><parameter></span> <span class="xml-tag"><name></span>proxool.driver-url<span class="xml-tag"></name></span> <span class="xml-tag"><value></span>jdbc:mckoi://localhost/<span class="xml-tag"></value></span> <span class="xml-tag"></parameter></span> <span class="xml-tag"><parameter></span> <span class="xml-tag"><name></span>proxool.driver-class<span class="xml-tag"></name></span> <span class="xml-tag"><value></span>com.mckoi.JDBCDriver<span class="xml-tag"></value></span> <span class="xml-tag"></parameter></span> <span class="xml-tag"><parameter></span> <span class="xml-tag"><name></span>user<span class="xml-tag"></name></span> <span class="xml-tag"><value></span>admin<span class="xml-tag"></value></span> <span class="xml-tag"></parameter></span> <span class="xml-tag"><parameter></span> <span class="xml-tag"><name></span>password<span class="xml-tag"></name></span> <span class="xml-tag"><value></span>admin<span class="xml-tag"></value></span> <span class="xml-tag"></parameter></span> <span class="xml-tag"></ResourceParams></span> <span class="xml-tag"></Context></span></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> </body> </html> |
