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 javax.security.auth.Subject;
  7. import javax.transaction.xa.XAResource;
  8. import javax.resource.ResourceException;
  9. /** ManagedConnection instance represents a physical connection
  10. * to the underlying EIS.
  11. *
  12. * <p>A ManagedConnection instance provides access to a pair of
  13. * interfaces: <code>javax.transaction.xa.XAResource</code> and
  14. * <code>javax.resource.spi.LocalTransaction</code>.
  15. *
  16. * <p><code> XAResource</code> interface is used by the transaction
  17. * manager to associate and dissociate a transaction with the underlying
  18. * EIS resource manager instance and to perform two-phase commit
  19. * protocol. The ManagedConnection interface is not directly used
  20. * by the transaction manager. More details on the XAResource
  21. * interface are described in the JTA specification.
  22. *
  23. * <p>The LocalTransaction interface is used by the application server
  24. * to manage local transactions.
  25. *
  26. * @version 0.5
  27. * @author Rahul Sharma
  28. * @see javax.resource.spi.ManagedConnectionFactory
  29. * @see javax.transaction.xa.XAResource
  30. * @see javax.resource.spi.LocalTransaction
  31. **/
  32. public interface ManagedConnection {
  33. /** Creates a new connection handle for the underlying physical connection
  34. * represented by the ManagedConnection instance. This connection handle
  35. * is used by the application code to refer to the underlying physical
  36. * connection. A connection handle is tied to its ManagedConnection instance
  37. * in a resource adapter implementation specific way.</P>
  38. *
  39. * <P>The ManagedConnection uses the Subject and additional ConnectionRequest
  40. * Info (which is specific to resource adapter and opaque to application
  41. * server) to set the state of the physical connection.</p>
  42. *
  43. * @param Subject security context as JAAS subject
  44. * @param cxRequestInfo ConnectionRequestInfo instance
  45. * @return generic Object instance representing the connection
  46. * handle. For CCI, the connection handle created by a
  47. * ManagedConnection instance is of the type
  48. * javax.resource.cci.Connection.
  49. *
  50. * @throws ResourceException generic exception if operation fails
  51. * @throws ResourceAdapterInternalException
  52. * resource adapter internal error condition
  53. * @throws SecurityException security related error condition
  54. * @throws CommException failed communication with EIS instance
  55. * @throws EISSystemException internal error condition in EIS instance
  56. * - used if EIS instance is involved in
  57. * setting state of ManagedConnection
  58. *
  59. **/
  60. public
  61. Object getConnection(Subject subject,
  62. ConnectionRequestInfo cxRequestInfo)
  63. throws ResourceException;
  64. /** Destroys the physical connection to the underlying resource manager.
  65. *
  66. * <p>To manage the size of the connection pool, an application server can
  67. * explictly call ManagedConnection.destroy to destroy a
  68. * physical connection. A resource adapter should destroy all allocated
  69. * system resources for this ManagedConnection instance when the method
  70. * destroy is called.
  71. *
  72. * @throws ResourceException generic exception if operation failed
  73. * @throws IllegalStateException illegal state for destroying connection
  74. **/
  75. public
  76. void destroy() throws ResourceException;
  77. /** Application server calls this method to force any cleanup on the
  78. * ManagedConnection instance.
  79. *
  80. * <p>The method ManagedConnection.cleanup initiates a cleanup of the
  81. * any client-specific state as maintained by a ManagedConnection instance.
  82. * The cleanup should invalidate all connection handles that had been
  83. * created using this ManagedConnection instance. Any attempt by an application
  84. * component to use the connection handle after cleanup of the underlying
  85. * ManagedConnection should result in an exception.
  86. *
  87. * <p>The cleanup of ManagedConnection is always driven by an application
  88. * server. An application server should not invoke ManagedConnection.cleanup
  89. * when there is an uncompleted transaction (associated with a
  90. * ManagedConnection instance) in progress.
  91. * <p>The invocation of ManagedConnection.cleanup method on an already
  92. * cleaned-up connection should not throw an exception.
  93. *
  94. * <p>The cleanup of ManagedConnection instance resets its client specific
  95. * state and prepares the connection to be put back in to a connection
  96. * pool. The cleanup method should not cause resource adapter to close
  97. * the physical pipe and reclaim system resources associated with the
  98. * physical connection.
  99. *
  100. * @throws ResourceException generic exception if operation fails
  101. * @throws ResourceAdapterInternalException
  102. * resource adapter internal error condition
  103. * @throws IllegalStateException Illegal state for calling connection
  104. * cleanup. Example - if a localtransaction
  105. * is in progress that doesn't allow
  106. * connection cleanup
  107. *
  108. **/
  109. public
  110. void cleanup() throws ResourceException;
  111. /** Used by the container to change the association of an
  112. * application-level connection handle with a ManagedConneciton
  113. * instance. The container should find the right ManagedConnection
  114. * instance and call the associateConnection method.
  115. *
  116. * <p>The resource adapter is required to implement the associateConnection
  117. * method. The method implementation for a ManagedConnection should
  118. * dissociate the connection handle (passed as a parameter) from its
  119. * currently associated ManagedConnection and associate the new
  120. * connection handle with itself.
  121. *
  122. * @param connection Application-level connection handle
  123. *
  124. * @throws ResourceException Failed to associate the connection
  125. * handle with this ManagedConnection
  126. * instance
  127. * @throws IllegalStateException Illegal state for invoking this
  128. * method
  129. * @throws ResourceAdapterInternalException
  130. * Resource adapter internal error
  131. * condition
  132. *
  133. **/
  134. public
  135. void associateConnection(Object connection)
  136. throws ResourceException;
  137. /** Adds a connection event listener to the ManagedConnection
  138. * instance.
  139. *
  140. * <p>The registered ConnectionEventListener instances are notified of
  141. * connection close and error events, also of local transaction related
  142. * events on the Managed Connection.
  143. *
  144. * @param listener a new ConnectionEventListener to be registered
  145. **/
  146. public
  147. void addConnectionEventListener(ConnectionEventListener listener);
  148. /** Removes an already registered connection event listener from the
  149. * ManagedConnection instance.
  150. *
  151. * @param listener already registered connection event listener to be
  152. * removed
  153. **/
  154. public
  155. void removeConnectionEventListener(
  156. ConnectionEventListener listener);
  157. /** Returns an <code>javax.transaction.xa.XAresource</code> instance.
  158. * An application server enlists this XAResource instance with the
  159. * Transaction Manager if the ManagedConnection instance is being used
  160. * in a JTA transaction that is being coordinated by the Transaction
  161. * Manager.
  162. *
  163. * @return XAResource instance
  164. *
  165. * @throws ResourceException generic exception if operation fails
  166. * @throws NotSupportedException if the operation is not supported
  167. * @throws ResourceAdapterInternalException
  168. * resource adapter internal error condition
  169. **/
  170. public
  171. XAResource getXAResource() throws ResourceException;
  172. /** Returns an <code>javax.resource.spi.LocalTransaction</code> instance.
  173. * The LocalTransaction interface is used by the container to manage
  174. * local transactions for a RM instance.
  175. *
  176. * @return LocalTransaction instance
  177. *
  178. * @throws ResourceException generic exception if operation fails
  179. * @throws NotSupportedException if the operation is not supported
  180. * @throws ResourceAdapterInternalException
  181. * resource adapter internal error condition
  182. **/
  183. public
  184. LocalTransaction getLocalTransaction() throws ResourceException;
  185. /** <p>Gets the metadata information for this connection's underlying
  186. * EIS resource manager instance. The ManagedConnectionMetaData
  187. * interface provides information about the underlying EIS instance
  188. * associated with the ManagedConenction instance.
  189. *
  190. * @return ManagedConnectionMetaData instance
  191. *
  192. * @throws ResourceException generic exception if operation fails
  193. * @throws NotSupportedException if the operation is not supported
  194. **/
  195. public
  196. ManagedConnectionMetaData getMetaData() throws ResourceException;
  197. /** Sets the log writer for this ManagedConnection instance.
  198. *
  199. * <p>The log writer is a character output stream to which all logging and
  200. * tracing messages for this ManagedConnection instance will be printed.
  201. * Application Server manages the association of output stream with the
  202. * ManagedConnection instance based on the connection pooling
  203. * requirements.</p>
  204. *
  205. * <p>When a ManagedConnection object is initially created, the default
  206. * log writer associated with this instance is obtained from the
  207. * ManagedConnectionFactory. An application server can set a log writer
  208. * specific to this ManagedConnection to log/trace this instance using
  209. * setLogWriter method.</p>
  210. *
  211. * @param out Character Output stream to be associated
  212. *
  213. * @throws ResourceException generic exception if operation fails
  214. * @throws ResourceAdapterInternalException
  215. * resource adapter related error condition
  216. **/
  217. public
  218. void setLogWriter(java.io.PrintWriter out) throws ResourceException;
  219. /** Gets the log writer for this ManagedConnection instance.
  220. *
  221. * <p>The log writer is a character output stream to which all logging and
  222. * tracing messages for this ManagedConnection instance will be printed.
  223. * ConnectionManager manages the association of output stream with the
  224. * ManagedConnection instance based on the connection pooling
  225. * requirements.</p>
  226. *
  227. * <p>The Log writer associated with a ManagedConnection instance can be
  228. * one set as default from the ManagedConnectionFactory (that created
  229. * this connection) or one set specifically for this instance by the
  230. * application server.</p>
  231. *
  232. * @return Character ourput stream associated with this Managed-
  233. * Connection instance
  234. *
  235. * @throws ResourceException generic exception if operation fails
  236. **/
  237. public
  238. java.io.PrintWriter getLogWriter() throws ResourceException;
  239. }