KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > resource > cci > 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 JavaDoc;
27 import javax.resource.NotSupportedException JavaDoc;
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 JavaDoc createInteraction()
56                 throws ResourceException JavaDoc;
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 JavaDoc getLocalTransaction() throws ResourceException JavaDoc;
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 JavaDoc getMetaData() throws ResourceException JavaDoc;
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 JavaDoc getResultSetInfo() throws ResourceException JavaDoc;
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 JavaDoc;
119
120 }
121
Popular Tags