    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 *      https://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}