ManagedConnection


1   /*
2    * The contents of this file are subject to the terms 
3    * of the Common Development and Distribution License 
4    * (the License).  You may not use this file except in
5    * compliance with the License.
6    * 
7    * You can obtain a copy of the license at 
8    * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9    * glassfish/bootstrap/legal/CDDLv1.0.txt.
10   * See the License for the specific language governing 
11   * permissions and limitations under the License.
12   * 
13   * When distributing Covered Code, include this CDDL 
14   * Header Notice in each file and include the License file 
15   * at glassfish/bootstrap/legal/CDDLv1.0.txt.  
16   * If applicable, add the following below the CDDL Header, 
17   * with the fields enclosed by brackets [] replaced by
18   * you own identifying information: 
19   * "Portions Copyrighted [year] [name of copyright owner]"
20   * 
21   * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22   */
23  
24  package javax.resource.spi;
25  
26  import javax.security.auth.Subject  ;
27  import javax.transaction.xa.XAResource  ;
28  import javax.resource.ResourceException  ;
29  
30  /** ManagedConnection instance represents a physical connection
31   *  to the underlying EIS.
32   *
33   *  <p>A ManagedConnection instance provides access to a pair of 
34   *  interfaces: <code>javax.transaction.xa.XAResource</code> and 
35   *  <code>javax.resource.spi.LocalTransaction</code>.
36   *
37   *  <p><code> XAResource</code> interface is used by the transaction 
38   *  manager to associate and dissociate a transaction with the underlying 
39   *  EIS resource manager instance and to perform two-phase commit 
40   *  protocol. The ManagedConnection interface is not directly used 
41   *  by the transaction manager. More details on the XAResource 
42   *  interface are described in the JTA specification.
43   *
44   *  <p>The LocalTransaction interface is used by the application server
45   *  to manage local transactions.
46   *
47   *  @version     0.5
48   *  @author      Rahul Sharma
49   *  @see         javax.resource.spi.ManagedConnectionFactory
50   *  @see         javax.transaction.xa.XAResource
51   *  @see         javax.resource.spi.LocalTransaction
52  **/
53  
54  public interface ManagedConnection {
55    
56    /** Creates a new connection handle for the underlying physical connection 
57     *  represented by the ManagedConnection instance. This connection handle
58     *  is used by the application code to refer to the underlying physical 
59     *  connection. This connection handle is associated with its 
60     *  ManagedConnection instance in a resource adapter implementation 
61     *  specific way.</P>
62     *
63     *  <P>The ManagedConnection uses the Subject and additional ConnectionRequest
64     *  Info (which is specific to resource adapter and opaque to application
65     *  server) to set the state of the physical connection.</p>
66     *
67     *  @param        subject        security context as JAAS subject
68     *  @param        cxRequestInfo  ConnectionRequestInfo instance
69     *  @return       generic Object instance representing the connection 
70     *                handle. For CCI, the connection handle created by a 
71     *                ManagedConnection instance is of the type 
72     *                javax.resource.cci.Connection.
73     *
74     *  @throws  ResourceException     generic exception if operation fails
75     *  @throws  ResourceAdapterInternalException
76     *                                 resource adapter internal error condition
77     *  @throws  SecurityException     security related error condition
78     *  @throws  CommException         failed communication with EIS instance
79     *  @throws  EISSystemException    internal error condition in EIS instance
80     *                                 - used if EIS instance is involved in
81     *                                   setting state of ManagedConnection
82     *
83     **/
84    public 
85    Object   getConnection(Subject   subject, 
86                 ConnectionRequestInfo   cxRequestInfo) 
87                   throws ResourceException  ;
88  
89    /** Destroys the physical connection to the underlying resource manager.
90     *
91     *  <p>To manage the size of the connection pool, an application server can 
92     *  explictly call ManagedConnection.destroy to destroy a  
93     *  physical connection. A resource adapter should destroy all allocated 
94     *  system resources for this ManagedConnection instance when the method 
95     *  destroy is called.
96     *  
97     *  @throws    ResourceException     generic exception if operation failed
98     *  @throws    IllegalStateException illegal state for destroying connection
99     **/
100 
101   public 
102   void destroy() throws ResourceException  ;
103 
104   /** Application server calls this method to force any cleanup on the 
105    *  ManagedConnection instance.
106    *  
107    *  <p>The method ManagedConnection.cleanup initiates a cleanup of the
108    *  any client-specific state as maintained by a ManagedConnection instance.
109    *  The cleanup should invalidate all connection handles that had been 
110    *  created using this ManagedConnection instance. Any attempt by an application 
111    *  component to use the connection handle after cleanup of the underlying
112    *  ManagedConnection should result in an exception.
113    *
114    *  <p>The cleanup of ManagedConnection is always driven by an application
115    *  server. An application server should not invoke ManagedConnection.cleanup
116    *  when there is an uncompleted transaction (associated with a 
117    *  ManagedConnection instance) in progress. 
118 
119    *  <p>The invocation of ManagedConnection.cleanup method on an already 
120    *  cleaned-up connection should not throw an exception.
121    *
122    *  <p>The cleanup of ManagedConnection instance resets its client specific
123    *  state and prepares the connection to be put back in to a connection
124    *  pool. The cleanup method should not cause resource adapter to close
125    *  the physical pipe and reclaim system resources associated with the
126    *  physical connection.
127    *  
128    *  @throws    ResourceException     generic exception if operation fails
129    *  @throws    ResourceAdapterInternalException
130    *                                   resource adapter internal error condition
131    *  @throws    IllegalStateException Illegal state for calling connection
132    *                                   cleanup. Example - if a localtransaction 
133    *                                   is in progress that doesn't allow 
134    *                                   connection cleanup
135    *
136    **/
137   public 
138   void cleanup() throws ResourceException  ;  
139 
140   /** Used by the container to change the association of an 
141    *  application-level connection handle with a ManagedConneciton 
142    *  instance. The container should find the right ManagedConnection 
143    *  instance and call the associateConnection method.
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 JTA 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     NotSupportedException if the operation is not supported
201    *  @throws     ResourceAdapterInternalException
202    *                                    resource adapter internal error condition
203   **/
204   public 
205   XAResource   getXAResource() throws ResourceException  ;
206 
207   /** Returns an <code>javax.resource.spi.LocalTransaction</code> instance. 
208    *  The LocalTransaction interface is used by the container to manage
209    *  local transactions for a RM instance.
210    *
211    *  @return     LocalTransaction instance
212    *
213    *  @throws     ResourceException     generic exception if operation fails
214    *  @throws     NotSupportedException if the operation is not supported
215    *  @throws     ResourceAdapterInternalException
216    *                                    resource adapter internal error condition
217   **/
218   public 
219   LocalTransaction   getLocalTransaction() throws ResourceException  ;
220 
221   /** <p>Gets the metadata information for this connection's underlying 
222    *  EIS resource manager instance. The ManagedConnectionMetaData 
223    *  interface provides information about the underlying EIS instance 
224    *  associated with the ManagedConenction instance.
225    *
226    *  @return     ManagedConnectionMetaData instance
227    *
228    *  @throws     ResourceException     generic exception if operation fails
229    *  @throws     NotSupportedException if the operation is not supported
230   **/
231   public 
232   ManagedConnectionMetaData   getMetaData() throws ResourceException  ;
233 
234   /** Sets the log writer for this ManagedConnection instance.
235    *
236    *  <p>The log writer is a character output stream to which all logging and
237    *  tracing messages for this ManagedConnection instance will be printed.
238    *  Application Server manages the association of output stream with the
239    *  ManagedConnection instance based on the connection pooling 
240    *  requirements.</p>
241    *  
242    *  <p>When a ManagedConnection object is initially created, the default
243    *  log writer associated with this instance is obtained from the 
244    *  ManagedConnectionFactory. An application server can set a log writer
245    *  specific to this ManagedConnection to log/trace this instance using
246    *  setLogWriter method.</p>
247    *  
248    *  @param      out        Character Output stream to be associated
249    *
250    *  @throws     ResourceException  generic exception if operation fails
251    *  @throws     ResourceAdapterInternalException
252    *                                 resource adapter related error condition
253    **/
254   public
255   void setLogWriter(java.io.PrintWriter   out) throws ResourceException  ;
256 
257   /** Gets the log writer for this ManagedConnection instance.
258    *
259    *  <p>The log writer is a character output stream to which all logging and
260    *  tracing messages for this ManagedConnection instance will be printed.
261    *  ConnectionManager manages the association of output stream with the
262    *  ManagedConnection instance based on the connection pooling 
263    *  requirements.</p>
264    *
265    *  <p>The Log writer associated with a ManagedConnection instance can be
266    *  one set as default from the ManagedConnectionFactory (that created
267    *  this connection) or one set specifically for this instance by the 
268    *  application server.</p>
269    *
270    *  @return   Character ourput stream associated with this Managed-
271    *            Connection instance
272    *     
273    *  @throws     ResourceException     generic exception if operation fails
274   **/
275   public 
276   java.io.PrintWriter   getLogWriter() throws ResourceException  ;
277 }
278
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags