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 true if the pool defaults to using autocommit.
018   */
019  boolean isAutoCommit();
020
021  /**
022   * Return true if the DataSource is online.
023   * <p>
024   * Effectively the same as (synonym for) {@link #isDataSourceUp()}.
025   */
026  boolean isOnline();
027
028  /**
029   * Bring the DataSource online ensuring min connections and start heart beat checking.
030   */
031  void online() throws SQLException;
032
033  /**
034   * Take the DataSource offline closing all connections and stopping heart beat checking.
035   */
036  void offline();
037
038  /**
039   * Shutdown the pool.
040   * <p>
041   * This is functionally the same as {@link #offline()} but generally we expect to only
042   * shutdown the pool once where as we can expect to making many calls to offline() and
043   * online().
044   */
045  void shutdown();
046
047  /**
048   * Shutdown the pool with the option to deregister the driver.
049   */
050  void shutdown(boolean deregisterDriver);
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   * <p>
059   * If you pass reset = true then the counters are reset.
060   * </p>
061   */
062  PoolStatus getStatus(boolean reset);
063
064  /**
065   * Return the aggregated execution statistics collected on all the connections in the pool.
066   * <p>
067   * If reset is set to true the counters are reset once the statistics have been collected.
068   * </p>
069   */
070  PoolStatistics getStatistics(boolean reset);
071
072  /**
073   * Returns false when the dataSource is down.
074   * <p>
075   * Effectively the same as (synonym for) {@link #isOnline()}.
076   */
077  boolean isDataSourceUp();
078
079  /**
080   * Returns the reason, why the dataSource is down.
081   */
082  SQLException getDataSourceDownReason();
083
084  /**
085   * Set a new maximum size. The pool should respect this new maximum
086   * immediately and not require a restart. You may want to increase the
087   * maxConnections if the pool gets large and hits the warning level.
088   */
089  void setMaxSize(int max);
090
091  /**
092   * Set a new maximum size. The pool should respect this new maximum immediately
093   * and not require a restart. You may want to increase the maxConnections if the
094   * pool gets large and hits the warning and or alert levels.
095   */
096  void setWarningSize(int warningSize);
097
098  /**
099   * Return the warning size. When the pool hits this size it can send a
100   * notify message to an administrator.
101   */
102  int getWarningSize();
103
104}