Class DataSource

java.lang.Object
org.apache.tomcat.jdbc.pool.DataSourceProxy
org.apache.tomcat.jdbc.pool.DataSource
All Implemented Interfaces:
Wrapper, MBeanRegistration, CommonDataSource, ConnectionPoolDataSource, DataSource, ConnectionPoolMBean, PoolConfiguration
Direct Known Subclasses:
XADataSource
public class DataSource extends DataSourceProxy implements DataSource, MBeanRegistration, ConnectionPoolMBean, ConnectionPoolDataSource
A DataSource that can be instantiated through IoC and implements the DataSource interface since the DataSourceProxy is used as a generic proxy. The DataSource simply wraps a ConnectionPool in order to provide a standard interface to the user.

A JMX registration made before the pool exists publishes nothing, because there is no pool MBean to publish. Create the pool before registering the data source, or register it again after the pool has been created, to have the pool monitored.

Deregistering a published data source releases the pool MBean and the connection and interceptor MBeans published below it, but it does not close the pool. A JMX-enabled pool that is no longer wanted must therefore be closed before the data source is dropped: while the pool MBean is registered it holds the pool, and the connection MBeans hold the pooled connections. Abandoning a registered pool without close(boolean) keeps the pool, its pooled sessions and its JDBC driver class loader reachable for the life of the JVM.

  • Field Details

    • oname

      protected volatile ObjectName oname
      The JMX ObjectName for the connection pool MBean. Written only by a completed publish, cleared only when that MBean is released, and accessed under this data source's monitor.

  • Constructor Details

    • DataSource

      public DataSource()
      Constructor for reflection only. A default set of pool properties will be created.

    • DataSource

      public DataSource(PoolConfiguration poolProperties)
      Constructs a DataSource object wrapping a connection
      Parameters:
      poolProperties - The pool properties

  • Method Details

    • close

      public void close(boolean all)
      Unregisters the connection pool MBean before closing the pool, so a pool under teardown does not keep reporting statistics under a live object name (and does not pin the closing pool, its credentials and its JDBC driver class loader in the MBean server). Monitoring stops with this call, whichever way the close goes: with all=false a connection that is currently borrowed keeps its database session and stays usable until its holder returns it, but it is no longer reported by the pool MBean.
      Close the connection pool. If a pool creation is in flight, this method does not wait for it - the driver connects of the creation's initial pre-load can block for an unbounded, uninterruptible time against a hung database - it marks this data source closed and returns: the creation observes the closure at its publication step and closes the pool it built instead of publishing it. The same reason keeps the teardown outside the monitor: the physical disconnect of every pooled session is as unbounded against a hung database as the connect is, and it must not park the paths that need the monitor meanwhile - a later borrow's publication step, or the container's JMX lifecycle callbacks.
      Overrides:
      close in class DataSourceProxy
      Parameters:
      all - if true close all connections, otherwise only idle ones

    • postDeregister

      public void postDeregister()
      Unregisters the underlying connection pool mbean.
      Specified by:
      postDeregister in interface MBeanRegistration

    • postRegister

      public void postRegister(Boolean registrationDone)
      Releases the pool MBean published by this registration when the MBean server did not complete it. A failed registration does not run postDeregister(), so this is the only chance to undo a publish this registration made. A registration that published nothing releases nothing.
      Specified by:
      postRegister in interface MBeanRegistration

    • preDeregister

      public void preDeregister() throws Exception
      no-op
      Specified by:
      preDeregister in interface MBeanRegistration
      Throws:
      Exception

    • preRegister

      public ObjectName preRegister(MBeanServer server, ObjectName name) throws Exception
      If the connection pool MBean exists, it is registered during this operation. A second registration is refused while this data source already holds a publication.
      Specified by:
      preRegister in interface MBeanRegistration
      Throws:
      Exception

    • createObjectName

      public ObjectName createObjectName(ObjectName original) throws MalformedObjectNameException
      Creates the ObjectName for the ConnectionPoolMBean object to be registered
      Parameters:
      original - the ObjectName for the DataSource
      Returns:
      the ObjectName for the ConnectionPoolMBean
      Throws:
      MalformedObjectNameException - Invalid object name

    • registerJmx

      protected void registerJmx()
      Registers the ConnectionPoolMBean under a unique name derived from the DataSource's ObjectName. A pool that has not been created, or a publish the server refused, is skipped without disturbing a handle this data source already holds.

    • publishJmx

      protected ConnectionPool publishJmx()
      Publishes the pool MBean under this data source's monitor and returns the pool whose connections must then be published, or null when nothing was published. The caller must hold this monitor; the connection sweep is the caller's to run outside it.
      Returns:
      the pool whose connections need publishing, or null

    • unregisterJmx

      protected void unregisterJmx(ObjectName name)
      Unregisters the ConnectionPoolMBean published under the given name. The name is the registration handle captured by the caller, which holds this data source's monitor: the handle is checked, cleared and released as one step there, so it never reaches this method twice and a name this data source never published is never released.
      Parameters:
      name - the ObjectName the pool MBean was published under, or null to release nothing