1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.dbcp2;
18
19 import java.sql.Connection;
20 import java.sql.SQLException;
21
22 /**
23 * Defines the attributes and methods that will be exposed via JMX for {@link PoolableConnection} instances.
24 *
25 * @since 2.0
26 */
27 public interface PoolableConnectionMXBean {
28
29 /**
30 * Clears the cached state. Call when you know that the underlying connection may have been accessed directly.
31 */
32 void clearCachedState();
33
34 /**
35 * See {@link Connection#clearWarnings()}.
36 *
37 * @throws SQLException See {@link Connection#clearWarnings()}.
38 */
39 void clearWarnings() throws SQLException;
40
41 /**
42 * Returns this instance to my containing pool.
43 *
44 * @throws SQLException Throw if this instance cannot be returned.
45 */
46 void close() throws SQLException;
47
48 /**
49 * See {@link Connection#getAutoCommit()}.
50 *
51 * @return See {@link Connection#getAutoCommit()}.
52 * @throws SQLException See {@link Connection#getAutoCommit()}.
53 */
54 boolean getAutoCommit() throws SQLException;
55
56 /**
57 * Gets whether to cache properties. The cached properties are:
58 * <ul>
59 * <li>auto-commit</li>
60 * <li>catalog</li>
61 * <li>schema</li>
62 * <li>read-only</li>
63 * </ul>
64 *
65 * @return The value for the state caching flag.
66 */
67 boolean getCacheState();
68
69 /**
70 * See {@link Connection#getCatalog()}.
71 *
72 * @return See {@link Connection#getCatalog()}.
73 * @throws SQLException See {@link Connection#getCatalog()}.
74 */
75 String getCatalog() throws SQLException;
76
77 /**
78 * See {@link Connection#getHoldability()}.
79 *
80 * @return See {@link Connection#getHoldability()}.
81 * @throws SQLException See {@link Connection#getHoldability()}.
82 */
83 int getHoldability() throws SQLException;
84
85 /**
86 * See {@link Connection#getSchema()}.
87 *
88 * @return See {@link Connection#getSchema()}.
89 * @throws SQLException See {@link Connection#getSchema()}.
90 */
91 String getSchema() throws SQLException;
92
93 /**
94 * Gets the value of the {@link Object#toString()} method via a bean getter, so it can be read as a property via JMX.
95 *
96 * @return the value of the {@link Object#toString()}.
97 */
98 String getToString();
99
100 /**
101 * See {@link Connection#getTransactionIsolation()}.
102 *
103 * @return See {@link Connection#getTransactionIsolation()}.
104 * @throws SQLException See {@link Connection#getTransactionIsolation()}.
105 */
106 int getTransactionIsolation() throws SQLException;
107
108 /**
109 * See {@link Connection#isClosed()}.
110 *
111 * @return See {@link Connection#isClosed()}.
112 * @throws SQLException See {@link Connection#isClosed()}.
113 */
114 boolean isClosed() throws SQLException;
115
116 /**
117 * See {@link Connection#isReadOnly()}.
118 *
119 * @return See {@link Connection#isReadOnly()}.
120 * @throws SQLException See {@link Connection#isReadOnly()}.
121 */
122 boolean isReadOnly() throws SQLException;
123
124 /**
125 * Closes the underlying {@link Connection}.
126 *
127 * @throws SQLException Thrown if the connection can be closed.
128 */
129 void reallyClose() throws SQLException;
130
131 /**
132 * See {@link Connection#setAutoCommit(boolean)}.
133 *
134 * @param autoCommit See {@link Connection#setAutoCommit(boolean)}.
135 * @throws SQLException See {@link Connection#setAutoCommit(boolean)}.
136 */
137 void setAutoCommit(boolean autoCommit) throws SQLException;
138
139 /**
140 * Sets whether to cache properties. The cached properties are:
141 * <ul>
142 * <li>auto-commit</li>
143 * <li>catalog</li>
144 * <li>schema</li>
145 * <li>read-only</li>
146 * </ul>
147 *
148 * @param cacheState The new value for the state caching flag
149 */
150 void setCacheState(boolean cacheState);
151
152 /**
153 * See {@link Connection#setCatalog(String)}.
154 *
155 * @param catalog See {@link Connection#setCatalog(String)}.
156 * @throws SQLException See {@link Connection#setCatalog(String)}.
157 */
158 void setCatalog(String catalog) throws SQLException;
159
160 /**
161 * See {@link Connection#setHoldability(int)}.
162 *
163 * @param holdability {@link Connection#setHoldability(int)}.
164 * @throws SQLException See {@link Connection#setHoldability(int)}.
165 */
166 void setHoldability(int holdability) throws SQLException;
167
168 /**
169 * See {@link Connection#setReadOnly(boolean)}.
170 *
171 * @param readOnly See {@link Connection#setReadOnly(boolean)}.
172 * @throws SQLException See {@link Connection#setReadOnly(boolean)}.
173 */
174 void setReadOnly(boolean readOnly) throws SQLException;
175
176 /**
177 * See {@link Connection#setSchema(String)}.
178 *
179 * @param schema See {@link Connection#setSchema(String)}.
180 * @throws SQLException See {@link Connection#setSchema(String)}.
181 */
182 void setSchema(String schema) throws SQLException;
183
184 /**
185 * See {@link Connection#setTransactionIsolation(int)}.
186 *
187 * @param level See {@link Connection#setTransactionIsolation(int)}.
188 * @throws SQLException See {@link Connection#setTransactionIsolation(int)}.
189 */
190 void setTransactionIsolation(int level) throws SQLException;
191 }