5.3.3. XADataSources

JDBC 2.0 connections are created from appropriate DataSources. Those connections, which participate within distributed transactions, are obtained from XADataSources. JBossJTA uses the appropriate DataSource when a connection to the database is made. It then obtains XAResources and registers them with the transaction using the JTA interfaces. The transaction service uses these XAResources when the transaction terminates, triggering the database to either commit or rollback the changes made via the JDBC connection.
The JBossJTA JDBC 2.0 driver can obtain XADataSources in one of two ways. For simplicity, it is assumed that the JDBC 2.0 driver is instantiated directly by the application.

5.3.3.1. Java Naming and Directory Interface (JNDI)

JNDI is used so that JDBC drivers can use arbitrary DataSources without knowing implementations-specific details. You can create a specific (XA)DataSource and register it with an appropriate JNDI implementation, which allows either the application or the JDBC driver to bind to and use it. Since JNDI only allows the application to see the (XA)DataSource as an instance of the interface, rather than as an instance of the implementation class, the application is not limited to only using a specific (XA)DataSource implementation.
To make the TransactionalDriver class use a JNDI registered XADataSource you need to create the XADataSource instance and store it in an appropriate JNDI implementation.
XADataSource ds = MyXADataSource();
Hashtable env = new Hashtable();
String initialCtx = PropertyManager.getProperty("Context.INITIAL_CONTEXT_FACTORY");
	  
env.put(Context.INITIAL_CONTEXT_FACTORY, initialCtx);
	  
initialContext ctx = new InitialContext(env);
	  
ctx.bind("jdbc/foo", ds);
The Context.INITIAL_CONTEXT_FACTORY property is how JNDI specifies the type of JNDI implementation to use.
The next step is for the application must pass an appropriate connection URL to the JDBC 2.0 driver.
Properties dbProps = new Properties();
	  
dbProps.setProperty(TransactionalDriver.userName, "user");
dbProps.setProperty(TransactionalDriver.password, "password");
	  
TransactionalDriver arjunaJDBC2Driver = new TransactionalDriver();
Connection connection = arjunaJDBC2Driver.connect("jdbc:arjuna:jdbc/foo", dbProps);
The JNDI URL must begin with jdbc:arjuna: in order for the ArjunaJDBC2Driver interface to recognize that the DataSource needs to participate within transactions and be driven accordingly.