Connection


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.cci;
25  
26  import javax.resource.ResourceException  ;
27  import javax.resource.NotSupportedException  ;
28  
29  
30  /** A Connection represents an application-level handle that is used 
31   *  by a client to access the underlying physical connection. The actual 
32   *  physical connection associated with a Connection instance is 
33   *  represented by a ManagedConnection instance.
34   *
35   *  <p>A client gets a Connection instance by using the 
36   *  <code>getConnection</code> method on a <code>ConnectionFactory</code> 
37   *  instance. A connection can be associated with zero or more Interaction
38   *  instances.
39   * 
40   *  @author  Rahul Sharma
41   *  @version 0.8
42   *  @see     javax.resource.cci.ConnectionFactory
43   *  @see     javax.resource.cci.Interaction
44   **/
45  
46  public interface Connection {
47    
48    /** Creates an Interaction associated with this Connection. An
49     *  Interaction enables an application to execute EIS functions. 
50     *
51     *  @return  Interaction instance  
52     *  @throws  ResourceException     Failed to create an Interaction
53    **/
54    public
55    Interaction   createInteraction() 
56                  throws ResourceException  ;
57  
58    /** Returns an LocalTransaction instance that enables a component to
59     *  demarcate resource manager local transactions on the Connection.
60     *  If a resource adapter does not allow a component to demarcate 
61     *  local transactions on an Connection using LocalTransaction 
62     *  interface, then the method getLocalTransaction should throw a 
63     *  NotSupportedException.
64     *
65     *  @return   LocalTransaction instance
66     *           
67     *  @throws   ResourceException   Failed to return a LocalTransaction
68     *                                instance because of a resource
69     *                                adapter error
70     *  @throws   NotSupportedException Demarcation of Resource manager 
71     *                                local transactions is not supported
72     *                                on this Connection
73     *  @see javax.resource.cci.LocalTransaction
74    **/
75  
76    public
77    LocalTransaction   getLocalTransaction() throws ResourceException  ;
78    
79    /** Gets the information on the underlying EIS instance represented
80     *  through an active connection.
81     *
82     *  @return   ConnectionMetaData instance representing information 
83     *            about the EIS instance
84     *  @throws   ResourceException  
85     *                        Failed to get information about the 
86     *                        connected EIS instance. Error can be
87     *                        resource adapter-internal, EIS-specific
88     *                        or communication related.
89    **/
90    public
91    ConnectionMetaData   getMetaData() throws ResourceException  ;
92  
93    /** Gets the information on the ResultSet functionality supported by
94     *  a connected EIS instance.
95     *
96     *  @return   ResultSetInfo instance
97     *  @throws   ResourceException     Failed to get ResultSet related 
98     *                                  information
99     *  @throws   NotSupportedException ResultSet functionality is not
100    *                                  supported
101   **/
102   public
103   ResultSetInfo   getResultSetInfo() throws ResourceException  ;
104   
105   
106   /** Initiates close of the connection handle at the application level.
107    *  A client should not use a closed connection to interact with 
108    *  an EIS.
109    *  
110    *  @throws  ResourceException  Exception thrown if close
111    *                              on a connection handle fails.
112    *           <p>Any invalid connection close invocation--example,
113    *              calling close on a connection handle that is 
114    *              already closed--should also throw this exception.
115    *  
116   **/
117   public
118   void close() throws ResourceException  ;
119 
120 }
121
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags