Author: jhalliday
Date: 2008-05-22 09:38:36 -0400 (Thu, 22 May 2008)
New Revision: 73589
Added:
projects/integration/trunk/jboss-transaction-spi/src/main/org/jboss/tm/XAResourceRecovery.java
projects/integration/trunk/jboss-transaction-spi/src/main/org/jboss/tm/XAResourceRecoveryRegistry.java
Log:
Added new interfaces to transactions SPI for transaction recovery, in line with discussions at http://www.jboss.com/index.html?module=bb&op=viewtopic&t=100435&start=30#4132941 http://jira.jboss.com/jira/browse/JBAS-5541 and http://jira.jboss.com/jira/browse/JBTM-335
Added: projects/integration/trunk/jboss-transaction-spi/src/main/org/jboss/tm/XAResourceRecovery.java
===================================================================
--- projects/integration/trunk/jboss-transaction-spi/src/main/org/jboss/tm/XAResourceRecovery.java (rev 0)
+++ projects/integration/trunk/jboss-transaction-spi/src/main/org/jboss/tm/XAResourceRecovery.java 2008-05-22 13:38:36 UTC (rev 73589)
@@ -0,0 +1,52 @@
+/*
+ * JBoss, Home of Professional Open Source
+ * Copyright 2008, JBoss Inc., and individual contributors as indicated
+ * by the @authors tag. See the copyright.txt in the distribution for a
+ * full listing of individual contributors.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+ */
+package org.jboss.tm;
+
+import javax.transaction.xa.XAResource;
+
+/**
+ * During recovery of crashed XA transactions, the transaction system may use instances
+ * of this interface to obtain XAResources on which to perform recovery calls.
+ * Resource managers should register instances of this interface with the transaction
+ * recovery system via an XAResourceRecoveryRegistry.
+ *
+ * @author Jonathan Halliday (jonathan.halliday at redhat.com)
+ * @version $Revision$
+ * @see XAResourceRecoveryRegistry
+ */
+public interface XAResourceRecovery
+{
+ /**
+ * Provides XAResource(s) to the transaction system for recovery purposes.
+ *
+ * @return An array of XAResource objects for use in transaction recovery
+ * In most cases the implementation will need to return only a single XAResource in the array.
+ * For more sophisticated cases, such as where multiple different connection types are supported,
+ * it may be necessary to return more than one.
+ *
+ * The Resource should be instantiated in such a way as to carry the necessary permissions to
+ * allow transaction recovery. For some deployments it may therefore be necessary or desirable to
+ * provide resource(s) based on e.g. database connection parameters such as username other than those
+ * used for the regular application connections to the same resource manager.
+ */
+ public XAResource[] getXAResources();
+}
Added: projects/integration/trunk/jboss-transaction-spi/src/main/org/jboss/tm/XAResourceRecoveryRegistry.java
===================================================================
--- projects/integration/trunk/jboss-transaction-spi/src/main/org/jboss/tm/XAResourceRecoveryRegistry.java (rev 0)
+++ projects/integration/trunk/jboss-transaction-spi/src/main/org/jboss/tm/XAResourceRecoveryRegistry.java 2008-05-22 13:38:36 UTC (rev 73589)
@@ -0,0 +1,77 @@
+/*
+ * JBoss, Home of Professional Open Source
+ * Copyright 2008, JBoss Inc., and individual contributors as indicated
+ * by the @authors tag. See the copyright.txt in the distribution for a
+ * full listing of individual contributors.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+ */
+package org.jboss.tm;
+
+/**
+ * The transaction management system may require assistance from resource
+ * managers in order to recover crashed XA transactions. By registering
+ * an XAResourceRecovery instance with the XAResourceRecoveryRegistry,
+ * resource manager connectors provide a way for the recovery system to
+ * callback to them and obtain the necessary information.
+ *
+ * This is useful for e.g. JDBC connection pools or JCA connectors that
+ * don't want to expose connection parameters to the transaction system.
+ * The connectors are responsible for instantiating a connection and
+ * using it to instantiate a set of XAResources. These are then exposed to
+ * the recovery system via the registered XAResourceRecovery instance.
+ *
+ * @author Jonathan Halliday (jonathan.halliday at redhat.com)
+ * @version $Revision$
+ * @see XAResourceRecovery
+ */
+public interface XAResourceRecoveryRegistry
+{
+ /*
+ Implementor's note:
+ Although the transaction manager in JBossAS is pluggable, reading the JBossTS
+ recovery documentation may give some insight into the design of this
+ recovery system interface. The forum thread at
+ http://www.jboss.com/index.html?module=bb&op=viewtopic&t=100435
+ may also be of interest.
+ */
+
+
+ /**
+ * Register an XAResourceRecovery instance with the transaction recovery system.
+ * This should be called by deployers that are deploying a new XA aware
+ * module that needs recovery support. For example, a database
+ * connection pool, JMS adapter or JCA connector.
+ *
+ * @param recovery The XAResourceRecovery instance to register.
+ */
+ void addXAResourceRecovery(XAResourceRecovery recovery);
+
+ /**
+ * Unregister an XAResourceRecovery instance from the transaction recovery system.
+ * This should be called when an XA aware module is undeployed, to inform the
+ * recovery system that recovery is no longer required or supported.
+ *
+ * Note this method may block whilst an ongoing recovery operation is completed.
+ * Recovery behavior is undefined if the undeployment does not wait for this
+ * operation to complete.
+ *
+ * @param recovery The XAResourceRecovery instance to unregister.
+ * Implementations should fail silent if an attempt is made to unregister
+ * an XAResourceRecovery instance that is not currently registered.
+ */
+ void removeXAResourceRecovery(XAResourceRecovery recovery);
+}