C3P0ProxyStatement


1   /*
2    * Distributed as part of c3p0 v.0.9.1
3    *
4    * Copyright (C) 2005 Machinery For Change, Inc.
5    *
6    * Author: Steve Waldman <swaldman@mchange.com>
7    *
8    * This library is free software; you can redistribute it and/or modify
9    * it under the terms of the GNU Lesser General Public License version 2.1, as 
10   * published by the Free Software Foundation.
11   *
12   * This software is distributed in the hope that it will be useful,
13   * but WITHOUT ANY WARRANTY; without even the implied warranty of
14   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15   * GNU Lesser General Public License for more details.
16   *
17   * You should have received a copy of the GNU Lesser General Public License
18   * along with this software; see the file LICENSE.  If not, write to the
19   * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
20   * Boston, MA 02111-1307, USA.
21   */
22  
23  
24  package com.mchange.v2.c3p0;
25  
26  import java.sql.Statement  ;
27  import java.sql.SQLException  ;
28  import java.lang.reflect.Method  ;
29  import java.lang.reflect.InvocationTargetException  ;
30  
31  /**
32   *  <p><b>Most clients need never use or know about this interface -- c3p0-provided Statements
33   *  can be treated like any other Statement.</b></p>
34   *
35   *  <p>An interface implemented by proxy Connections returned
36   *  by c3p0 PooledDataSources. It provides protected access to the underlying
37   *  dbms-vendor specific Connection, which may be useful if you want to
38   *  access non-standard API offered by your jdbc driver.
39   */
40  public interface C3P0ProxyStatement extends Statement  
41  {
42      /**
43       *  A token representing an unwrapped, unproxied jdbc Connection
44       *  for use in {@link #rawStatementOperation}
45       */
46      public final static Object   RAW_STATEMENT = new Object  ();
47      
48      /**
49       *  <p>Allows one to work with the unproxied, raw vendor-provided Statement . Some 
50       *  database companies never got over the "common interfaces mean
51       *  no more vendor lock-in!" thing, and offer non-standard API
52       *  on their Statements. This method permits you to "pierce" the
53       *  connection-pooling layer to call non-standard methods on the
54       *  original Statement, or to pass the original Statement to 
55       *  functions that are not implementation neutral.</p>
56       *
57       *  <p>To use this functionality, you'll need to cast a Statement
58       *  retrieved from a c3p0-provided Connection to a 
59       *  C3P0ProxyStatement.</p>
60       *
61       *  <p>This method works by making a reflective call of method <tt>m</tt> on
62       *  Object <tt>target</tt> (which may be null for static methods), passing
63       *  and argument list <tt>args</tt>. For the method target, or for any argument,
64       *  you may substitute the special token <tt>C3P0ProxyStatement.RAW_STATEMENT</tt></p>
65       *
66       *  <p>Any ResultSets returned by the operation will be proxied
67       *  and c3p0-managed, meaning that these resources will be automatically closed 
68       *  if the user does not close them first when this Statement is closed or checked
69       *  into the statement cache. <b>Any other resources returned by the operation are the user's
70       *  responsibility to clean up!</b></p>
71       *
72       *  <p>If you have turned statement pooling on, incautious use of this method can corrupt the 
73       *  PreparedStatement cache, by breaking the invariant
74       *  that all cached PreparedStatements should be equivalent to a PreparedStatement newly created
75       *  with the same arguments to prepareStatement(...) or prepareCall(...). If your vendor supplies API
76       *  that allows you to modify the state or configuration of a Statement in some nonstandard way,
77       *  and you do not undo this modification prior to closing the Statement or the Connection that
78       *  prepared it, future preparers of the same Statement may or may not see your modification,
79       *  depending on your use of the cache. Thus, it is inadvisable to use this method to call
80       *  nonstandard mutators on PreparedStatements if statement pooling is turned on.. 
81       */
82      public Object   rawStatementOperation(Method   m, Object   target, Object  [] args)
83      throws IllegalAccessException  , IllegalArgumentException  , InvocationTargetException  , SQLException  ;
84  }
85
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags