| Rather than configure the connection manager factory-related MBeans discussed in the previous section via an MBean services deployment descriptor, you can use the simplified datasource-centric descriptor that JBoss provides. This is transformed into the standard jboss-service.xml MBean services deployment descriptor by using a XSL transform applied by the org.jboss.deployment.XSLSubDeployer included in the jboss-jca.sar deployment. The simplified configuration descriptor is deployed the same as other deployable components. The descriptor must be named by using a *-ds.xml pattern in order to be recognized by the XSLSubDeployer. Figure 7.6 shows the schema for the top-level datasource elements of the *-ds.xml configuration deployment file. Figure 7.6. The simplified JCA datasource configuration descriptor top-level schema elements. 
You can specify multiple datasource configurations in a configuration deployment file. These are the child elements of the datasources root element: mbean You can specify any number of mbean elements to define MBean services that should be included in the jboss-service.xml descriptor that results from the transformation. You can use this element to configure services used by the data-sources. no-tx-datasource You use this element to specify the (org.jboss.resource.connectionmanager) NoTxConnectionManager service configuration. NoTxConnectionManager is a JCA connection manager with no transaction support. The no-tx-datasource child element schema is shown in Figure 7.7. Figure 7.7. The non-transactional DataSource configuration schema. 
local-tx-datasource You use this element to specify the (org.jboss.resource.connectionmanager) LocalTx-ConnectionManager service configuration. LocalTxConnectionManager implements a ConnectionEventListener that implements XAResource to manage transactions through the transaction manager. To ensure that all work in a local transaction occurs over the same ManagedConnection, it includes an XID-to-ManagedConnection map. When a connection is requested or a transaction is started with a connection handle in use, it checks to see if a ManagedConnection already exists, enrolled in the global transaction, and it uses it if found. Otherwise, a free ManagedConnection has its LocalTransaction started and is used. The local-tx-datasource child element schema is shown in Figure 7.8. Figure 7.8. The non-XA DataSource configuration schema. 
xa-datasource You use this element to specify the (org.jboss.resource.connectionmanager) XATxConnectionManager service configuration. XATxConnectionManager implements a ConnectionEventListener that obtains the XAResource to manage transactions through the transaction manager from the adaptor ManagedConnection. To ensure that all work in a local transaction occurs over the same ManagedConnection, it includes an XID-to-ManagedConnection map. When a connection is requested or a transaction is started with a connection handle in use, it checks to see if a ManagedConnection already exists, enrolled in the global transaction, and it uses it if found. Otherwise, a free ManagedConnection has its LocalTransaction started and is used. The XADataSource child element schema is shown in Figure 7.9. Figure 7.9. The XADataSource configuration schema. 
Elements that are common to all datasources include the following: jndi-name This is the JNDI name under which the DataSource wrapper will be bound. Note that this name is relative to the java:/ context, unless use-java-context is set to false. DataSource wrappers are not usable outside the server VM, so they are normally bound under java:/, which isn't shared outside the local VM. use-java-context If this is set to false, the datasource will be bound in the global JNDI context rather than the java: context. user-name This element specifies the default username that is used when creating a new connection. The actual username may be overridden by the application code getConnection parameters or the connection creation context JAAS Subject. password This element specifies the default password that is used when creating a new connection. The actual password may be overridden by the application code getConnection parameters or the connection creation context JAAS Subject. application-managed-security Specifying this element indicates that connections in the pool should be distinguished by parameters supplied by application code, such as from getConnection(user,pw). security-domain Specifying this element indicates that connections in the pool should be distinguished by JAAS Subject-based information. The content of the security-domain is the name of the JAAS security manager that will handle authentication. This name correlates to the JAAS login-config.xml descriptor application-policy/name attribute. security-domain-and-application Specifying this element indicates that connections in the pool should be distinguished both by application code-supplied parameters and JAAS Subject-based information. The content of the security-domain is the name of the JAAS security manager that will handle authentication. This name correlates to the JAAS login-config.xml descriptor application-policy/name attribute. min-pool-size This element specifies the minimum number of connections a pool should hold. These pool instances are not created until an initial request for a connection is made. The default is 0. max-pool-size This element specifies the maximum number of connections for a pool. No more than the max-pool-size number of connections will be created in a pool. The default is 20. blocking-timeout-millis This element specifies the maximum time, in milliseconds, to block while waiting for a connection before throwing an exception. Note that this blocks only while waiting for a permit for a connection, and it will never throw an exception if creating a new connection takes an inordinately long time. The default is 5000. idle-timeout-minutes This element specifies the maximum time, in minutes, a connection may be idle before being closed. The actual maximum time also depends on the IdleRemover scan time, which is half the smallest idle-timeout-minutes of any pool. new-connection-sql This SQL statement should be executed when a new connection is created. You can use this element to configure a connection with database-specific settings that are not configurable via connection properties. check-valid-connection-sql This SQL statement should be run on a connection before it is returned from the pool to test its validity to test for stale pool connections. An example of a statement is selectcount(*)fromx. exception-sorter-class-name This specifies a class that implements the org.jboss.resource.adapter.jdbc.ExceptionSorter interface to filter SQLExceptions to determine whether a connection error event should be generated. Current implementations include the following: org.jboss.resource.adapter .jdbc.vendor.OracleExceptionSorter org.jboss.resource.adapter .jdbc.vendor.SybaseExceptionSorter
valid-connection-checker-class-name This specifies a class that implements the org.jboss.resource.adapter.jdbc.ValidConnectionChecker interface to provide a SQLExceptionisValidConnection(Connection e) method that is called with a connection that is to be returned from the pool to test its validity. This overrides check-valid-connection-sql when present. Current implementations include the following: org.jboss.resource.adapter.jdbc.vendor.OracleValidConnectionChecker
track-statements This Boolean element specifies whether to check for unclosed statements when a connection is returned to the pool. If it is true, a warning message is issued for each unclosed statement. If the log4j category org.jboss.resource.adapter.jdbc.WrappedConnection has trace level enabled, a stack trace of the connection close call is logged as well. This is a debug feature that can be turned off in production. prepared-statement-cache-size This element specifies the number of prepared statements per connection in an LRU cache, which is keyed by the SQL query. Setting this to 0 disables the cache. depends The depends element specifies the JMX ObjectName string of a service that the connection manager services depend on. The connection manager service will not be started until the dependent services have been started. type-mapping This element declares a default type mapping for this datasource. The type mapping should match a type-mapping/name element from standardjbosscmp-jdbc.xml.
Additional common child elements for both no-tx-datasource and local-tx-datasource include the following: connection-url This is the JDBC driver connection URL string (for example, jdbc:hsqldb:hsql://localhost:1701). driver-class This is the fully qualified name of the JDBC driver class (for example, org.hsqldb.jdbcDriver). connection-property This element allows you to pass arbitrary connection properties to the java.sql.Driver.connect(url,props) method. Each connection-property specifies a string name/value pair with the property name coming from the name attribute and the value coming from the element content.
The local-tx-datasource and xa-datasource have the following elements in common: transaction-isolation This element specifies the java.sql.Connection transaction isolation level to use. The constants defined in the Connection interface are the possible element content values and include the following: TRANSACTION_READ_UNCOMMITTED TRANSACTION_READ_COMMITTED TRANSACTION_REPEATABLE_READ TRANSACTION_SERIALIZABLE TRANSACTION_NONE
no-tx-separate-pools The presence of this element indicates that two connection pools are required to isolate connections used with a JTA transaction from those used without a JTA transaction. The pools are lazily constructed on first use. The use case for this element is for Oracle (and possibly other vendors) XA implementations that don't like using an XA connection with and without a JTA transaction.
The following are the unique xa-datasource child elements: track-connection-by-tx Specifying a true value for this element makes the connection manager keep an XID-to-connection map and put the connection back in the pool only when the transaction completes and all the connection handles are closed or disassociated (by the method calls returning). As a side effect, you never suspend and resume the XID on the connection's XAResource. This is the same connection tracking behavior used for local transactions. The XA specification implies that any connection may be enrolled in any transaction, using any XID for that transaction at any time from any thread (suspending other transactions, if necessary). The original JCA implementation assumed this and aggressively delisted connections and put them back in the pool as soon as control left the EJB they were used in or handles were closed. Because some other transaction can be using the connection the next time work needs to be done on the original transaction, there is no way to get the original connection back. It turns out that most XADataSource driver vendors do not support this, and require that all work done under a particular XID go through the same connection. xa-datasource-class This is the fully qualified name of the javax.sql.XADataSource implementation class (for example, com.informix.jdbcx.IfxXADataSource). xa-datasource-property The xa-datasource-property element allows for specification of the properties to assign to the XADataSource implementation class. Each property is identified by the name attribute, and the property value is given by the xa-datasource-property element content. The property is mapped onto the XADataSource implementation by looking for a JavaBeans-style getter method for the property name. If one is found, the value of the property is set by using the JavaBeans setter, with the element text translated to the true property type, using the java.beans.PropertyEditor for the type. isSameRM-override-value This Boolean flag allows you to override the behavior of the javax.transaction.xa.XAResource.isSameRM(XAResource xaRes) method behavior on the XA managed connection. If specified, this value is used unconditionally as the isSameRM(xaRes) return value, regardless of the xaRes parameter.
Examples of configurations for many third-party JDBC drivers are included in the JBOSS_DIST/docs/examples/jca directory. Current example configurations include the following: asapxcess -jb3.2-ds.xml cicsr9s-service.xml db2-ds.xml db2-xa-ds.xml facets-ds.xml fast-objects-jboss32-ds.xml firebird-ds.xml
Connectors on JBoss include the following: firstsql-ds.xml firstsql-xa-ds.xml generic-ds.xml hsqldb-ds.xml informix-ds.xml informix-xa-ds.xml jdatastore-ds.xml jms-ds.xml j sql-ds.xml lido-versant-service.xml mimer-ds.xml mimer-xa-ds.xml msaccess-ds.xml mssql-ds.xml mssql-xa-ds.xml mysql-ds.xml oracle-ds.xml oracle-xa-ds.xml postgres-ds.xml sapdb-ds.xml sapr3-ds.xml solid-ds.xml sybase-ds.xml
|
