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