001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.dbcp2;
018
019import java.sql.Connection;
020import java.sql.SQLException;
021
022/**
023 * Defines the attributes and methods that will be exposed via JMX for {@link PoolableConnection} instances.
024 *
025 * @since 2.0
026 */
027public interface PoolableConnectionMXBean {
028
029    /**
030     * Clears the cached state. Call when you know that the underlying connection may have been accessed directly.
031     */
032    void clearCachedState();
033
034    /**
035     * See {@link Connection#clearWarnings()}.
036     *
037     * @throws SQLException See {@link Connection#clearWarnings()}.
038     */
039    void clearWarnings() throws SQLException;
040
041    /**
042     * Returns this instance to my containing pool.
043     *
044     * @throws SQLException Throw if this instance cannot be returned.
045     */
046    void close() throws SQLException;
047
048    /**
049     * See {@link Connection#getAutoCommit()}.
050     *
051     * @return See {@link Connection#getAutoCommit()}.
052     * @throws SQLException See {@link Connection#getAutoCommit()}.
053     */
054    boolean getAutoCommit() throws SQLException;
055
056    /**
057     * Gets whether to cache properties. The cached properties are:
058     * <ul>
059     * <li>auto-commit</li>
060     * <li>catalog</li>
061     * <li>schema</li>
062     * <li>read-only</li>
063     * </ul>
064     *
065     * @return The value for the state caching flag.
066     */
067    boolean getCacheState();
068
069    /**
070     * See {@link Connection#getCatalog()}.
071     *
072     * @return See {@link Connection#getCatalog()}.
073     * @throws SQLException See {@link Connection#getCatalog()}.
074     */
075    String getCatalog() throws SQLException;
076
077    /**
078     * See {@link Connection#getHoldability()}.
079     *
080     * @return See {@link Connection#getHoldability()}.
081     * @throws SQLException See {@link Connection#getHoldability()}.
082     */
083    int getHoldability() throws SQLException;
084
085    /**
086     * See {@link Connection#getSchema()}.
087     *
088     * @return See {@link Connection#getSchema()}.
089     * @throws SQLException See {@link Connection#getSchema()}.
090     */
091    String getSchema() throws SQLException;
092
093    /**
094     * Gets the value of the {@link Object#toString()} method via a bean getter, so it can be read as a property via JMX.
095     *
096     * @return the value of the {@link Object#toString()}.
097     */
098    String getToString();
099
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}