1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
5 *
6 * The contents of this file are subject to the terms of either the GNU
7 * General Public License Version 2 only ("GPL") or the Common Development
8 * and Distribution License("CDDL") (collectively, the "License"). You
9 * may not use this file except in compliance with the License. You can obtain
10 * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
11 * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
12 * language governing permissions and limitations under the License.
13 *
14 * When distributing the software, include this License Header Notice in each
15 * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
16 * Sun designates this particular file as subject to the "Classpath" exception
17 * as provided by Sun in the GPL Version 2 section of the License file that
18 * accompanied this code. If applicable, add the following below the License
19 * Header, with the fields enclosed by brackets [] replaced by your own
20 * identifying information: "Portions Copyrighted [year]
21 * [name of copyright owner]"
22 *
23 * Contributor(s):
24 *
25 * If you wish your version of this file to be governed by only the CDDL or
26 * only the GPL Version 2, indicate your decision by adding "[Contributor]
27 * elects to include this software in this distribution under the [CDDL or GPL
28 * Version 2] license." If you don't indicate a single choice of license, a
29 * recipient has the option to distribute your version of this file under
30 * either the CDDL, the GPL Version 2 or to extend the choice of license to
31 * its licensees as provided above. However, if you add GPL Version 2 code
32 * and therefore, elected the GPL Version 2 license, then the option applies
33 * only if the new code is made subject to such option by the copyright
34 * holder.
35 */
36
37 package javax.resource.spi;
38
39 import javax.security.auth.Subject;
40 import javax.transaction.xa.XAResource;
41 import javax.resource.ResourceException;
42
43 /** ManagedConnection instance represents a physical connection
44 * to the underlying EIS.
45 *
46 * <p>A ManagedConnection instance provides access to a pair of
47 * interfaces: <code>javax.transaction.xa.XAResource</code> and
48 * <code>javax.resource.spi.LocalTransaction</code>.
49 *
50 * <p><code> XAResource</code> interface is used by the transaction
51 * manager to associate and dissociate a transaction with the underlying
52 * EIS resource manager instance and to perform two-phase commit
53 * protocol. The ManagedConnection interface is not directly used
54 * by the transaction manager. More details on the XAResource
55 * interface are described in the JTA specification.
56 *
57 * <p>The LocalTransaction interface is used by the application server
58 * to manage local transactions.
59 *
60 * @version 0.5
61 * @author Rahul Sharma
62 * @see javax.resource.spi.ManagedConnectionFactory
63 * @see javax.transaction.xa.XAResource
64 * @see javax.resource.spi.LocalTransaction
65 **/
66
67 public interface ManagedConnection {
68
69 /** Creates a new connection handle for the underlying physical connection
70 * represented by the ManagedConnection instance. This connection handle
71 * is used by the application code to refer to the underlying physical
72 * connection. This connection handle is associated with its
73 * ManagedConnection instance in a resource adapter implementation
74 * specific way.</P>
75 *
76 * <P>The ManagedConnection uses the Subject and additional ConnectionRequest
77 * Info (which is specific to resource adapter and opaque to application
78 * server) to set the state of the physical connection.</p>
79 *
80 * @param subject security context as JAAS subject
81 * @param cxRequestInfo ConnectionRequestInfo instance
82 * @return generic Object instance representing the connection
83 * handle. For CCI, the connection handle created by a
84 * ManagedConnection instance is of the type
85 * javax.resource.cci.Connection.
86 *
87 * @throws ResourceException generic exception if operation fails
88 * @throws ResourceAdapterInternalException
89 * resource adapter internal error condition
90 * @throws SecurityException security related error condition
91 * @throws CommException failed communication with EIS instance
92 * @throws EISSystemException internal error condition in EIS instance
93 * - used if EIS instance is involved in
94 * setting state of ManagedConnection
95 *
96 **/
97 public
98 Object getConnection(Subject subject,
99 ConnectionRequestInfo cxRequestInfo)
100 throws ResourceException;
101
102 /** Destroys the physical connection to the underlying resource manager.
103 *
104 * <p>To manage the size of the connection pool, an application server can
105 * explictly call ManagedConnection.destroy to destroy a
106 * physical connection. A resource adapter should destroy all allocated
107 * system resources for this ManagedConnection instance when the method
108 * destroy is called.
109 *
110 * @throws ResourceException generic exception if operation failed
111 * @throws IllegalStateException illegal state for destroying connection
112 **/
113
114 public
115 void destroy() throws ResourceException;
116
117 /** Application server calls this method to force any cleanup on the
118 * ManagedConnection instance.
119 *
120 * <p>The method ManagedConnection.cleanup initiates a cleanup of the
121 * any client-specific state as maintained by a ManagedConnection instance.
122 * The cleanup should invalidate all connection handles that had been
123 * created using this ManagedConnection instance. Any attempt by an application
124 * component to use the connection handle after cleanup of the underlying
125 * ManagedConnection should result in an exception.
126 *
127 * <p>The cleanup of ManagedConnection is always driven by an application
128 * server. An application server should not invoke ManagedConnection.cleanup
129 * when there is an uncompleted transaction (associated with a
130 * ManagedConnection instance) in progress.
131
132 * <p>The invocation of ManagedConnection.cleanup method on an already
133 * cleaned-up connection should not throw an exception.
134 *
135 * <p>The cleanup of ManagedConnection instance resets its client specific
136 * state and prepares the connection to be put back in to a connection
137 * pool. The cleanup method should not cause resource adapter to close
138 * the physical pipe and reclaim system resources associated with the
139 * physical connection.
140 *
141 * @throws ResourceException generic exception if operation fails
142 * @throws ResourceAdapterInternalException
143 * resource adapter internal error condition
144 * @throws IllegalStateException Illegal state for calling connection
145 * cleanup. Example - if a localtransaction
146 * is in progress that doesn't allow
147 * connection cleanup
148 *
149 **/
150 public
151 void cleanup() throws ResourceException;
152
153 /** Used by the container to change the association of an
154 * application-level connection handle with a ManagedConneciton
155 * instance. The container should find the right ManagedConnection
156 * instance and call the associateConnection method.
157 *
158 * <p>The resource adapter is required to implement the associateConnection
159 * method. The method implementation for a ManagedConnection should
160 * dissociate the connection handle (passed as a parameter) from its
161 * currently associated ManagedConnection and associate the new
162 * connection handle with itself.
163 *
164 * @param connection Application-level connection handle
165 *
166 * @throws ResourceException Failed to associate the connection
167 * handle with this ManagedConnection
168 * instance
169 * @throws IllegalStateException Illegal state for invoking this
170 * method
171 * @throws ResourceAdapterInternalException
172 * Resource adapter internal error
173 * condition
174 *
175 **/
176 public
177 void associateConnection(Object connection)
178 throws ResourceException;
179
180
181
182 /** Adds a connection event listener to the ManagedConnection
183 * instance.
184 *
185 * <p>The registered ConnectionEventListener instances are notified of
186 * connection close and error events, also of local transaction related
187 * events on the Managed Connection.
188 *
189 * @param listener a new ConnectionEventListener to be registered
190 **/
191 public
192 void addConnectionEventListener(ConnectionEventListener listener);
193
194 /** Removes an already registered connection event listener from the
195 * ManagedConnection instance.
196 *
197 * @param listener already registered connection event listener to be
198 * removed
199 **/
200 public
201 void removeConnectionEventListener(
202 ConnectionEventListener listener);
203
204 /** Returns an <code>javax.transaction.xa.XAresource</code> instance.
205 * An application server enlists this XAResource instance with the
206 * Transaction Manager if the ManagedConnection instance is being used
207 * in a JTA transaction that is being coordinated by the Transaction
208 * Manager.
209 *
210 * @return XAResource instance
211 *
212 * @throws ResourceException generic exception if operation fails
213 * @throws NotSupportedException if the operation is not supported
214 * @throws ResourceAdapterInternalException
215 * resource adapter internal error condition
216 **/
217 public
218 XAResource getXAResource() throws ResourceException;
219
220 /** Returns an <code>javax.resource.spi.LocalTransaction</code> instance.
221 * The LocalTransaction interface is used by the container to manage
222 * local transactions for a RM instance.
223 *
224 * @return LocalTransaction instance
225 *
226 * @throws ResourceException generic exception if operation fails
227 * @throws NotSupportedException if the operation is not supported
228 * @throws ResourceAdapterInternalException
229 * resource adapter internal error condition
230 **/
231 public
232 LocalTransaction getLocalTransaction() throws ResourceException;
233
234 /** <p>Gets the metadata information for this connection's underlying
235 * EIS resource manager instance. The ManagedConnectionMetaData
236 * interface provides information about the underlying EIS instance
237 * associated with the ManagedConenction instance.
238 *
239 * @return ManagedConnectionMetaData instance
240 *
241 * @throws ResourceException generic exception if operation fails
242 * @throws NotSupportedException if the operation is not supported
243 **/
244 public
245 ManagedConnectionMetaData getMetaData() throws ResourceException;
246
247 /** Sets the log writer for this ManagedConnection instance.
248 *
249 * <p>The log writer is a character output stream to which all logging and
250 * tracing messages for this ManagedConnection instance will be printed.
251 * Application Server manages the association of output stream with the
252 * ManagedConnection instance based on the connection pooling
253 * requirements.</p>
254 *
255 * <p>When a ManagedConnection object is initially created, the default
256 * log writer associated with this instance is obtained from the
257 * ManagedConnectionFactory. An application server can set a log writer
258 * specific to this ManagedConnection to log/trace this instance using
259 * setLogWriter method.</p>
260 *
261 * @param out Character Output stream to be associated
262 *
263 * @throws ResourceException generic exception if operation fails
264 * @throws ResourceAdapterInternalException
265 * resource adapter related error condition
266 **/
267 public
268 void setLogWriter(java.io.PrintWriter out) throws ResourceException;
269
270 /** Gets the log writer for this ManagedConnection instance.
271 *
272 * <p>The log writer is a character output stream to which all logging and
273 * tracing messages for this ManagedConnection instance will be printed.
274 * ConnectionManager manages the association of output stream with the
275 * ManagedConnection instance based on the connection pooling
276 * requirements.</p>
277 *
278 * <p>The Log writer associated with a ManagedConnection instance can be
279 * one set as default from the ManagedConnectionFactory (that created
280 * this connection) or one set specifically for this instance by the
281 * application server.</p>
282 *
283 * @return Character ourput stream associated with this Managed-
284 * Connection instance
285 *
286 * @throws ResourceException generic exception if operation fails
287 **/
288 public
289 java.io.PrintWriter getLogWriter() throws ResourceException;
290 }
Save This Page