C3P0ProxyConnection


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.Connection  ;
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 Connections
33   *  can be treated like any other Connection.</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 C3P0ProxyConnection extends Connection  
41  {
42      /**
43       *  A token representing an unwrapped, unproxied jdbc Connection
44       *  for use in {@link #rawConnectionOperation}
45       */
46      public final static Object   RAW_CONNECTION = new Object  ();
47      
48      /**
49       *  <p>Allows one to work with the unproxied, raw Connection. 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 Connections. This method permits you to "pierce" the
53       *  connection-pooling layer to call non-standard methods on the
54       *  original Connection, or to pass the original Connections to 
55       *  functions that are not implementation neutral.</p>
56       *
57       *  <p>To use this functionality, you'll need to cast a Connection
58       *  retrieved from a c3p0 PooledDataSource to a 
59       *  C3P0ProxyConnection.</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>C3P0ProxyConnection.RAW_CONNECTION</tt></p>
65       *
66       *  <p>Any Statements or 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 Connection is checked back
69       *  into the pool. <b>Any other resources returned by the operation are the user's
70       *  responsibility to clean up!</b></p>
71       *
72       *  <p>Incautious use of this method can corrupt the Connection pool, by breaking the invariant
73       *  that all checked-in Connections should be equivalent. If your vendor supplies API
74       *  that allows you to modify the state or configuration of a Connection in some nonstandard way,
75       *  you might use this method to do so, and then check the Connection back into the pool.
76       *  When you fetch another Connection from the PooledDataSource, it will be undefined
77       *  whether the Connection returned will have your altered configuration, or the default
78       *  configuration of a "fresh" Connection. Thus, it is inadvisable to use this method to call
79       *  nonstandard mutators. 
80       */
81      public Object   rawConnectionOperation(Method   m, Object   target, Object  [] args)
82      throws IllegalAccessException  , IllegalArgumentException  , InvocationTargetException  , SQLException  ;
83  }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags