Package: ManagedConnection

ManagedConnection

Coverage

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