This section describes JDBC considerations for the JRun administrator. The JRun administrator is responsible for ensuring that JRun data sources are defined for all applications running in a JRun server. At run time, JRun creates these data sources and stores them in JNDI. Applications then use an InitialContext.lookup method to access the data source.
A JRun data source provides the following features:
Support for any JDBC-compliant driver
Connection pooling, even if unsupported by the driver
XA support, even if unsupported by the driver
JRun ships with Type 4 JDBC drivers that you can use to access a variety of relational databases. For more information, see the DataDirect Connect JDBC User's Guide and Reference, distributed with the JRun documentation.
Defining JRun data sources
Use the JMC to define JDBC data sources for a JRun server. When defining a JRun JDBC data source, you specify the following settings:
Setting
Description
JNDI name
The name that applications use when looking up the data source. This name is also used in the JRun deployment descriptor for CMP EJBs. This name can include slashes and does not have to begin with /jdbc.
Driver class name
The name of the driver's class file; for example, com.pointbase.jdbc.jdbcUniversalDriver. The JMS determines the class name automatically for most commonly used JDBC drivers.
Database URL
The URL that points to the database; for example, jdbc:pointbase:server://127.0.0.1:9292/compass. This is different for each DBMS and JDBC driver. The JMC determines the URL automatically from other specifications made when you define the data source.
Additional settings
Other JDBC settings, Including the following:
native-results Set to true to use the cachable, scrollable, updatable JRun ResultSet implementation. Set to false to use the ResultSet returned by the underlying JDBC driver.
initial-connections Set the number of connections that JRun creates when the pool is instantiated.
pool-statements Set to true to pool PreparedStatements instead of recreating them with each invocation.
minimum-size Set the minimum number of objects that JRun retains in the pool.
maximum-size Set the maximum number of objects that JRun maintains in the pool.
maximum-soft Set to true to have the connection pool create new emergency objects if the maximum size of a pool is reached but requests are still waiting on objects. This temporarily increases the size of the pool, but the pool shrinks back down to an acceptable size automatically when the skimmer activates. Set to false to force the requests to wait until an object is available.
disable-pooling Disables JDBC connection pooling.
connection-timeout The of seconds that JRun lets a connection remain dormant before destroying it.
user-timeout The number of seconds that a user must keep a connection before it is automatically returned to the pool.
skimmer-frequency The number of seconds that the pool skimmer waits between reap cycles. During each reap cycle, the skimmer evaluates all connections (both checked in and checked out) to determine whether to automatically return them to the pool or to destroy them if they have timed out.
shrink-by Set the maximum number of objects that can be removed from the pool in any one reap cycle. JRun checks this value each time the pool is sized down by the skimmer. It prevents JRun's connection pooling mechanism from backing off the pool too quickly at peak times.
debugging Set to true to enable verbose logging information.
cache-enabled Set to true to enable the query/ResultSet cache.
cache-size Set the maximum number of query/ResultSet pairs that the cache can contain.
cache-refresh-interval The number of seconds between the cache's reloading of its ResultSets from the database.
remove-on-exceptions Set to true to remove a Connection from the pool if there is a SQLException.
The JMC provides driver-specific defaults for the driver class names, URLs, ports, and other settings of many popular JDBC drivers. You can also modify these settings and use other JDBC drivers, as necessary. For more information, see the JMC online Help.
For complete information on the driver class name and database URL, see the documentation for your JDBC driver.
JRun stores data source settings in the jrun_root/servers/jrun_server/SERVER-INF/jrun-resources.xml file. For more information on jrun-resources.xml settings, see "Resources: the jrun-resources.xml file" or the online descriptor documentation, available from the JRun documentation home page.
Updating the JRun classpath
In addition to defining the data source in JRun, you must also ensure that the JDBC driver's JAR file is in the JRun server's classpath. One simple way to do this is to copy the JAR file to the jrun_root/servers/lib directory, which ensures that it is available to all JRun servers. You can also add the JAR file to the classpath for an individual server by using the JMC's Java VM Settings panel.
In addition to being used in servlets and JSPs, JRun EJB deployment descriptors for CMP entity beans specify a JRun data source. JRun EJB deployment descriptors can either specify a data source explicitly or can specify defaultdatasource, which causes JRun to use the first data source bound at startup.
Comments
admin
said on
Aug 24, 2002
at
6:43 AM :
make it more descriptive with example for different dat source configuration pls.
rnielsen
said on
Oct 21, 2002
at
6:30 PM :
The native-results description is wrong. It should be something like:
Setting native-results to true will cause JRun to use the JDBC driver's ResultSet. Setting it to false will use the JRunResultSet.
ilmyggo
said on
Sep 24, 2002
at
4:14 PM :
Why is it not possible to set additional DataSource properties in the JMC? Is this only possible by editing the XML directly?
The "examples" listed above are the default values. How about some "real world" examples?
CFSMITA
said on
Apr 27, 2005
at
2:24 PM :
I have created couple of JDBC datasources under Cfusion server. For some reason, the most recently created datasource vanishes everytime the coldfusion service is restarted. I checked jrun-resources.xml and notice that the same datasource has been created multiple time. There is no consistency to this problem, on one of the server the created datasource stays ok and on another server it vanishes. Is the Jrun Management Console buggy in CFMX 6.1? Are we supposed to edit the jrun-resources.xml manually? Please help.
manik_1
said on
Jun 5, 2005
at
4:53 AM :
I tried to create datasource using intitial context from java.
Here is the code for creating datasource Hashtable hashtable = new Hashtable(); hashtable.put( Context.INITIAL_CONTEXT_FACTORY, "jrun.naming.JRunContextFactory"); hashtable.put(Context.PROVIDER_URL,localhost:2920); initialContext = new InitialContext(hashtable); Object object = initialContext.lookup("testDataSource");
dataSource = (javax.sql.DataSource)object; dataSource.getConnection(); But when I call getConnection method in datasource I'm getting UndeclaredThrowableException . Please help me
jrunrandy
said on
Jul 5, 2005
at
11:20 AM :
I think you need to put the getConnection into a variable. Something like:
dbConnection = dataSource.getConnection();
AWhitford
said on
Sep 12, 2005
at
7:19 AM :
For the "maximum-size" setting, you say "set the maximum number of objects that JRun maintains in the pool." Is this limiting Database Connection objects, or other objects too? (I'm looking for a way to Limit Connections like in Cold Fusion's Data Source screen.)
Comments
admin said on Aug 24, 2002 at 6:43 AM : rnielsen said on Oct 21, 2002 at 6:30 PM : ilmyggo said on Sep 24, 2002 at 4:14 PM : No screen name said on Oct 16, 2003 at 12:40 PM : dovrosenberg said on Nov 6, 2003 at 11:49 AM : jrunrandy said on Dec 9, 2003 at 1:34 PM : EMiles said on Aug 4, 2004 at 8:06 AM : CFSMITA said on Apr 27, 2005 at 2:24 PM : manik_1 said on Jun 5, 2005 at 4:53 AM :