Network Server XA Support

[Kathey Marsden]

I wrote up a functional description of Network Server XA support.  I put
it in HTML as the straight text email version just seemed kind of hard
to read.  I hope that is ok.

Please post any input.  It would also be great to identify folks who
might be early users of this feature.

Thanks

Kathey

Overview The Derby embedded driver provides XA support. This project will extend XA support to Network Server. Network Server will be enhanced to provide DRDA XAMGR level 7 support so that DRDA clients supporting XAMGR level 7 can send XA requests to Network Server. Initial testing will be done with the IBM DB2 Universal JDBC driver using the com.ibm.db2.jcc.DB2XADataSource to get XA Connections. Functionality The XAMGR level 7 support is described in the XAMGROV section of the Distributed Data Management Architecture Specification DRDA V3, Vol 3. http://www.opengroup.org/publications/catalog/c045.htm. Other relevant sections are XAMGR, XID, XAFLAGS, XIDCNT, SYNCCTL SYNCCRD and PRPHRCLST. DRDA support is based on The XA+ Specification, also available from the Open Group at http://www.opengroup.org/publications/catalog/s423.htm . Below is a excerpt from the XAMGROV section of the DDM Specification which Network Server will support. DDM Transactional Processing Support XAMGR level 7 is a manager object of DDM that provides a connection architecture that will allow the application to perform the operations involved in protecting a DRDA resource. The DRDA functionality is summarized below: SYNCCTL(New Unit of Work) Provides the application with the ability to register/start a transaction with the DBMS and associate the connection with the transaction’s XID. A valid XID represents a Global Transaction that requires two-phase protection, while a NULL XID represents an unprotected transaction. The functionality also provides the application with the ability to join or resume existing transaction branches at the application server. A timeout value is also specified, that allows the transaction to be rolled back when it exceeds the timeout limit. SYNCCTL(End association) An application uses this functionality to inform the application server that it is ending a Global Transaction and is dissociating the XID from the connection. It also provides the application with the ability to suspend or fail a transaction branch. Suspend with migrate gives the application the capability of moving the resources associated with a transaction branch from one connection to another. SYNCCTL(Prepare to Commit) Provides the application with the ability to perform the first phase of the two-phase protocol, which involves informing a DBMS to prepare the transaction branch for commit. SYNCCTL(Commit) Provides the application with the ability to carry out the second phase of the two-phase protocol, which involves committing the Global Transaction. The function also allows the application to perform a one-phase optimization. SYNCCTL(Rollback) Provides the application with the ability to roll back a Global Transaction. The function also allows the application to perform a one-phase optimization. SYNCCTL(Return Indoubt List) At any given time, the application can use this function to obtain a list of Prepared and Heuristically completed Transactions at the DBMS. The application can then compare the list with its own and commit and roll back the transaction branches accordingly. SYNCCTL(Forget) A DBMS will keep the knowledge of a heuristically completed transaction branch until it is authorized by the application to forget the transaction branch. The application uses this DRDA function to inform the DBMS which heuristically completed transaction branch it should forget. . The following elements of the XAMGR level 7 support will not be supported by Network Server at this time . The ability to migrate cursors, RDB protected resources (for example, temp tables), and external savepoints from one XA protected connection to another. Support for the RLSCONV parameter to release a connection to a different application Support for the timeout instance variable on the SYNCCTL codepoint as currently the embedded XA Resource does not support setTimeout() Usage with the DB2 Universal JDBC Driver XA support for Network Server can be accessed using the DB2 Universal JDBC Driver's XA DataSource (com.ibm.db2.jcc.DB2XADataSource). An example of obtaining an XA connection with the DB2 Universal JDBC Driver. XAConnection xaConnection = null; Connection conn = null; String driver = "com.ibm.db2.jcc.DB2DataSource”; DB2XADataSource ds = new DB2XADataSource(); ds.setDatabaseName(dbname + ";create=true"); ds.setRetrieveMessagesFromServerOnGetMessage(true); ds.setServerName("localhost"); ds.setPortNumber(1527); ds.setDriverType(4); // Network Server requires JDBC type 4 driver Class.forName(driver); xaConnection = ds.getXAConnection("auser", "shhhh"); connection = xaConnection.getConnection(); ij ij currently has unpublished syntax that is used solely for XA testing. This support will be extended to support Network server so that tests develeloped using the ij xa syntax can be used for network server testing. Ij will support the framework property setting DerbyNet to indicate that the test should be run against Network Server. Since this support is just for testing, ij will always connect to localhost, port 1527 with the xa_datasource command. An example usage of ij will be as follows: java –Dframework=DerbyNet org.apache.derby.tools.ij ij> xa_datasource ‘wombat’; ij> xa_connect; ij> xa_start xa_noflags 1; Dependencies IBM DB2 Universal JDBC Driver. Some changes may be required for the IBM DB2 Universal JDBC Driver, so XA support may require a later version than 2.4 javax.transaction.xa package In order to use the Network Server XA functionality, the server must be running with a jdk with javax.transaction.xa suppport so will not be supported in JSR 169 configurations. Quality Existing embedded XA tests will be run against Network Server. Performance Changes to support XA connections should not affect performance of non-XA connections. XA performance will be measured in comparison to embedded performance to ensure that Network XA Connections do not have a significant performance impact. We will compare to embedded to ensure that the XA performance ratio embedded/network server is comparable to to the tests with non-XA connections. Design Overview We will add two new classes to org.apache.derby.drda. DRDAXADatabase This class will extend the existing Database class which holds all of the connection information for a database connection. DRDAXADatabase will have additional fields to hold the XAResource and XAConnection and will override the Database class's makeConnection method to make an XA connection instead. On connection initialization, the DRDAProtocol class will create a new XADatabase if the client sends XAMGR level 7 in the mgr levels. DRDAXAProtocol This class will extend DRDAProtocol and will have all of the XA Specific protocol to handle the SYNCCTL requests and send appropriate responses. In XAMGR level 7 there is a one to one mapping of the XAResource methods to the SYNCCTL commands sent and the xaflags. So generally for XA connections, the SYNCCTL calls translate directly into embedded XA calls and returns either XAResource.XA_OK on success or the XAException errorcode on failure. If the XID has formatID -1 this indicates a local connection and is handled accordingly. Other changes will include adding an isXARequester() to the AppRequester, adding the new Codepoints and SYNCCTL values to the Codepoint class and other miscellaneous support. Note, The one flag that does not seem to be defined for DRDA is XAResource.TMONEPHASE. Currently JCC sends XAResource.TMONEPHASE in the event of a one phase commit, and Network Server recognizes this, but it is not clear whether this is standard.