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 23 * questions. 24 */ 25 package javax.sql; 26 27 import java.sql.*; 28 29 /** 30 * An object that provides support for distributed transactions. An 31 * {@code XAConnection} object may be enlisted in a distributed transaction 32 * by means of an {@code XAResource} object. A transaction manager, usually 33 * part of a middle tier server, manages an {@code XAConnection} object 34 * through the {@code XAResource} object. 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 }