001package io.ebean.datasource;
002
003import javax.sql.DataSource;
004import java.sql.SQLException;
005
006/**
007 * DataSource pool API.
008 */
009public interface DataSourcePool extends DataSource {
010
011  /**
012   * Return the dataSource name.
013   */
014  String getName();
015
016  /**
017   * Return the current size of the pool. This includes both busy and idle connections.
018   */
019  int size();
020
021  /**
022   * Return true if the pool defaults to using autocommit.
023   */
024  boolean isAutoCommit();
025
026  /**
027   * Return true if the DataSource is online.
028   * <p>
029   * Effectively the same as (synonym for) {@link #isDataSourceUp()}.
030   */
031  boolean isOnline();
032
033  /**
034   * Bring the DataSource online ensuring min connections and start heart beat checking.
035   */
036  void online() throws SQLException;
037
038  /**
039   * Take the DataSource offline closing all connections and stopping heart beat checking.
040   */
041  void offline();
042
043  /**
044   * Shutdown the pool.
045   * <p>
046   * This is functionally the same as {@link #offline()} but generally we expect to only
047   * shutdown the pool once where as we can expect to making many calls to offline() and
048   * online().
049   */
050  void shutdown();
051
052  /**
053   * Return the current status of the connection pool.
054   * <p>
055   * This is cheaper than getStatistics() in that it just the counts of free, busy,
056   * wait etc and does not included times (total connection time etc).
057   * <p>
058   * If you pass reset = true then the counters are reset.
059   */
060  PoolStatus getStatus(boolean reset);
061
062  /**
063   * Returns false when the dataSource is down.
064   * <p>
065   * Effectively the same as (synonym for) {@link #isOnline()}.
066   */
067  boolean isDataSourceUp();
068
069  /**
070   * Returns the reason, why the dataSource is down.
071   */
072  SQLException getDataSourceDownReason();
073
074  /**
075   * Set a new maximum size. The pool should respect this new maximum
076   * immediately and not require a restart. You may want to increase the
077   * maxConnections if the pool gets large and hits the warning level.
078   */
079  void setMaxSize(int max);
080
081  /**
082   * Set a new maximum size. The pool should respect this new maximum immediately
083   * and not require a restart. You may want to increase the maxConnections if the
084   * pool gets large and hits the warning and or alert levels.
085   */
086  void setWarningSize(int warningSize);
087
088  /**
089   * Return the warning size. When the pool hits this size it can send a
090   * notify message to an administrator.
091   */
092  int getWarningSize();
093
094}