Class StatementFacade

java.lang.Object
org.apache.tomcat.jdbc.pool.JdbcInterceptor
org.apache.tomcat.jdbc.pool.interceptor.AbstractCreateStatementInterceptor
org.apache.tomcat.jdbc.pool.StatementFacade
All Implemented Interfaces:
InvocationHandler
public class StatementFacade extends AbstractCreateStatementInterceptor
Facade that creates statement and result set proxies.

The handles this facade hands out implement only the standard JDBC interfaces, as do the proxies of the interceptors that wrap statements beneath it, so the driver's own statement and result set classes are never visible to the application through a cast. Every result set a pooled statement hands back, and every result set that one of those handles hands back in turn, reaches the application as one of these handles, whatever the method that returned it was called: a cursor that arrives as a plain object - a REF cursor OUT-parameter read through CallableStatement.getObject(int), or the nested cursor a ResultSet.getObject(int) column value hands out - is sealed to the borrow like the ones the standard result set methods return. The Wrapper methods are delegated to the driver, and unwrap is the supported way to reach driver-specific methods through every layer. An unwrapped driver object, however, is a driver object rather than a pooled handle: retiring these handles at the end of the borrow does not retire what was already unwrapped, and only tracking the statements with StatementFinalizer (or the application closing them) keeps the statements underneath from outliving the borrow - unless an interceptor recycles them for the next borrow, as a statement cache does.

The rule that decides what is sealed is a type rule, and its boundary is the type. A value a handle hands back that is not itself a result set is passed through as it came (what a statement handle reports as its connection is the pool's own handle, not the driver's), and a cursor that rides inside such a value reaches the application over that same unsealed path: the Array read for an ARRAY column or an ARRAY OUT-parameter hands out its cursors through Array.getResultSet(), a Struct through its attributes, and the deprecated Ref a getRef call hands back is itself the driver's object; the Blob, Clob and SQLXML locators are the same shape without a cursor in them. None of that is sealed to the borrow, just as what unwrap() hands back is not: this facade seals the result sets a pooled statement hands out and the result sets those handles hand out in turn, not cursors that arrive inside values of another type - the REF cursor OUT-parameter and the nested cursor named above are themselves result sets, which is why they are sealed and these composites are not. Whether a driver object kept past the borrow still reads, and over what session, is the driver's affair; no handle of this facade retires it.

  • Constructor Details

    • StatementFacade

      protected StatementFacade(JdbcInterceptor interceptor)
      Constructs a StatementFacade.
      Parameters:
      interceptor - the next interceptor in the chain

  • Method Details

    • closeInvoked

      public void closeInvoked()
      Marks the borrow as ended, which closes every statement and result set handle this facade handed out. Called before the connection is handed back, so a handle cannot outlive the borrow and end up driving the session of the next borrower. A borrow that is abandoned instead never runs this method, but the pool destroys an abandoned session rather than lending it again, so those handles only fail at the driver.
      Specified by:
      closeInvoked in class AbstractCreateStatementInterceptor

    • createStatement

      public Object createStatement(Object proxy, Method method, Object[] args, Object statement, long time)
      Creates a statement interceptor to monitor query response times
      Specified by:
      createStatement in class AbstractCreateStatementInterceptor
      Parameters:
      proxy - the actual proxy object
      method - the method that was called. It will be one of the methods defined in AbstractCreateStatementInterceptor.STATEMENT_TYPES
      args - the arguments to the method
      statement - the statement that the underlying connection created
      time - Elapsed time
      Returns:
      a Statement object