1. /*
  2. * Copyright 2002 Sun Microsystems, Inc. All rights reserved.
  3. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  4. */
  5. package javax.resource.spi;
  6. import java.util.EventListener;
  7. import javax.resource.ResourceException;
  8. /** The <code>ConnectionEventListener</code> interface provides an event
  9. * callback mechanism to enable an application server to receive
  10. * notifications from a <code>ManagedConnection</code> instance.
  11. *
  12. * <p>An application server uses these event notifications to manage
  13. * its connection pool, to clean up any invalid or terminated connections
  14. * and to manage local transactions.
  15. *
  16. * <p>An application server implements the
  17. * <code>ConnectionEventListener</code> interface. It registers a connection
  18. * listener with a <code>ManagedConnection</code> instance by using
  19. * <code>ManagedConnection.addConnectionEventListener</code> method.
  20. *
  21. * @version 0.5
  22. * @author Rahul Sharma
  23. *
  24. * @see javax.resource.spi.ConnectionEvent
  25. **/
  26. public interface ConnectionEventListener
  27. extends java.util.EventListener {
  28. /** Notifies that an application component has closed the connection.
  29. *
  30. * <p>A ManagedConnection instance notifies its registered set of
  31. * listeners by calling ConnectionEventListener.connectionClosed method
  32. * when an application component closes a connection handle. The
  33. * application server uses this connection close event to put the
  34. * ManagedConnection instance back in to the connection pool.
  35. *
  36. * @param event event object describing the source of
  37. * the event
  38. */
  39. public
  40. void connectionClosed(ConnectionEvent event);
  41. /** Notifies that a Resource Manager Local Transaction was started on
  42. * the ManagedConnection instance.
  43. *
  44. * @param event event object describing the source of
  45. * the event
  46. */
  47. public
  48. void localTransactionStarted(ConnectionEvent event);
  49. /** Notifies that a Resource Manager Local Transaction was committed
  50. * on the ManagedConnection instance.
  51. *
  52. * @param event event object describing the source of
  53. * the event
  54. */
  55. public
  56. void localTransactionCommitted(ConnectionEvent event);
  57. /** Notifies that a Resource Manager Local Transaction was rolled back
  58. * on the ManagedConnection instance.
  59. *
  60. * @param event event object describing the source of
  61. * the event
  62. */
  63. public
  64. void localTransactionRolledback(ConnectionEvent event);
  65. /** Notifies a connection related error.
  66. * The ManagedConnection instance calls the method
  67. * ConnectionEventListener.connectionErrorOccurred to notify
  68. * its registered listeners of the occurrence of a physical
  69. * connection-related error. The event notification happens
  70. * just before a resource adapter throws an exception to the
  71. * application component using the connection handle.
  72. *
  73. * The connectionErrorOccurred method indicates that the
  74. * associated ManagedConnection instance is now invalid and
  75. * unusable. The application server handles the connection
  76. * error event notification by initiating application
  77. * server-specific cleanup (for example, removing ManagedConnection
  78. * instance from the connection pool) and then calling
  79. * ManagedConnection.destroy method to destroy the physical
  80. * connection.
  81. *
  82. * @param event event object describing the source of
  83. * the event
  84. */
  85. public
  86. void connectionErrorOccurred(ConnectionEvent event);
  87. }