1 /*
2 * Copyright (c) 2000, 2015, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
35 * <P>
36 * An application programmer does not use this interface directly; rather, it is
37 * used by a transaction manager working in the middle tier server.
38 *
39 * @since 1.4
40 */
41 public interface XAConnection extends PooledConnection {
42
43 /**
44 * Retrieves an {@code XAResource} object that the transaction manager
45 * will use to manage this {@code XAConnection} object's participation
46 * in a distributed transaction.
47 *
48 * @return the {@code XAResource} object
49 * @exception SQLException if a database access error occurs
50 * @exception SQLFeatureNotSupportedException if the JDBC driver does not
51 * support this method
52 * @since 1.4
53 */
54 javax.transaction.xa.XAResource getXAResource() throws SQLException;
55
56 // JDBC 4.3
57
58 /**
59 * Sets and validates the sharding keys for this connection.
60 *
61 * @implSpec The default implementation will throw a
62 * {@code SQLFeatureNotSupportedException}.
63 *
64 * @apiNote This method validates that the sharding keys are valid for the
65 * {@code Connection}. The timeout value indicates how long the driver
66 * should wait for the {@code Connection} to verify that the sharding key is
67 * valid before {@code setShardingKeyIfValid} returns false.
68 * @param shardingKey the sharding key to be validated against this
69 * connection
70 * @param superShardingKey the super sharding key to be validated against
71 * this connection. The super sharding key may be {@code null}.
72 * @param timeout time in seconds before which the validation process is
73 * expected to be completed, otherwise the validation process is aborted. A
74 * value of 0 indicates the validation process will not time out.
75 * @return true if the connection is valid and the sharding keys are valid
76 * and set on this connection; false if the sharding keys are not valid or
77 * the timeout period expires before the operation completes.
78 * @throws SQLException if an error occurs while performing this validation;
79 * the {@code shardingkey} is {@code null}; a {@code superSharedingKey} is specified
80 * without a {@code shardingKey}; this method is called on a closed
81 * {@code connection}; or the {@code timeout} value is less than 0.
82 * @throws SQLFeatureNotSupportedException if the driver does not support
83 * sharding
84 * @since 1.9
85 * @see ShardingKey
86 * @see ShardingKeyBuilder
87 */
88 default boolean setShardingKeyIfValid(ShardingKey shardingKey,
89 ShardingKey superShardingKey, int timeout)
90 throws SQLException {
91 throw new SQLFeatureNotSupportedException("setShardingKeyIfValid not implemented");
92 }
93
94 /**
95 * Sets and validates the sharding key for this connection.
96 * @implSpec
97 * The default implementation will throw a
98 * {@code SQLFeatureNotSupportedException}.
99 * @apiNote
100 * This method validates that the sharding key is valid for the
101 * {@code Connection}. The timeout value indicates how long the driver
102 * should wait for the {@code Connection} to verify that the sharding key
103 * is valid before {@code setShardingKeyIfValid} returns false.
104 * @param shardingKey the sharding key to be validated against this connection
105 * @param timeout time in seconds before which the validation process is expected to
106 * be completed,else the validation process is aborted. A value of 0 indicates
107 * the validation process will not time out.
108 * @return true if the connection is valid and the sharding key is valid to be
109 * set on this connection; false if the sharding key is not valid or
110 * the timeout period expires before the operation completes.
111 * @throws SQLException if there is an error while performing this validation;
112 * this method is called on a closed {@code connection}; the {@code shardingkey}
113 * is {@code null}; or the {@code timeout} value is less than 0.
114 * @throws SQLFeatureNotSupportedException if the driver does not support sharding
115 * @since 1.9
116 * @see ShardingKey
117 * @see ShardingKeyBuilder
118 */
119 default boolean setShardingKeyIfValid(ShardingKey shardingKey, int timeout)
120 throws SQLException {
121 throw new SQLFeatureNotSupportedException("setShardingKeyIfValid not implemented");
122 }
123
124 /**
125 * Specifies a shardingKey and superShardingKey to use with this Connection
126 * @implSpec
127 * The default implementation will throw a
128 * {@code SQLFeatureNotSupportedException}.
129 * @apiNote
130 * This method sets the specified sharding keys but does not require a
131 * round trip to the database to validate that the sharding keys are valid
132 * for the {@code Connection}.
133 * @param shardingKey the sharding key to set on this connection.
134 * @param superShardingKey the super sharding key to set on this connection.
135 * The super sharding key may be {@code null}
136 * @throws SQLException if an error occurs setting the sharding keys;
137 * this method is called on a closed {@code connection};
138 * the {@code shardingkey} is {@code null}; or
139 * a {@code superSharedingKey} is specified without a {@code shardingKey}
140 * @throws SQLFeatureNotSupportedException if the driver does not support sharding
141 * @since 1.9
142 * @see ShardingKey
143 * @see ShardingKeyBuilder
144 */
145 default void setShardingKey(ShardingKey shardingKey, ShardingKey superShardingKey)
146 throws SQLException {
147 throw new SQLFeatureNotSupportedException("setShardingKey not implemented");
148 }
149
150 /**
151 * Specifies a shardingKey to use with this Connection
152 * @implSpec
153 * The default implementation will throw a
154 * {@code SQLFeatureNotSupportedException}.
155 * @apiNote
156 * This method sets the specified sharding key but does not require a
157 * round trip to the database to validate that the sharding key is valid
158 * for the {@code Connection}.
159 * @param shardingKey the sharding key to set on this connection.
160 * @throws SQLException if an error occurs setting the sharding key;
161 * this method is called on a closed {@code connection}; or the
162 * {@code shardkingKey} is {@code null}
163 * @throws SQLFeatureNotSupportedException if the driver does not support sharding
164 * @since 1.9
165 * @see ShardingKey
166 * @see ShardingKeyBuilder
167 */
168 default void setShardingKey(ShardingKey shardingKey)
169 throws SQLException {
170 throw new SQLFeatureNotSupportedException("setShardingKey not implemented");
171 }
172 }
|
1 /*
2 * Copyright (c) 2000, 2016, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
35 * <P>
36 * An application programmer does not use this interface directly; rather, it is
37 * used by a transaction manager working in the middle tier server.
38 *
39 * @since 1.4
40 */
41 public interface XAConnection extends PooledConnection {
42
43 /**
44 * Retrieves an {@code XAResource} object that the transaction manager
45 * will use to manage this {@code XAConnection} object's participation
46 * in a distributed transaction.
47 *
48 * @return the {@code XAResource} object
49 * @exception SQLException if a database access error occurs
50 * @exception SQLFeatureNotSupportedException if the JDBC driver does not
51 * support this method
52 * @since 1.4
53 */
54 javax.transaction.xa.XAResource getXAResource() throws SQLException;
55 }
|