1 /* 2 * @(#)Wrapper.java 1.6 06/05/28 3 * 4 * Copyright 2006 Sun Microsystems, Inc. All rights reserved. 5 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. 6 */ 7 8 package java.sql; 9 10 /** 11 * Interface for JDBC classes which provide the ability to retrieve the delegate instance when the instance 12 * in question is in fact a proxy class. 13 * <p> 14 * The wrapper pattern is employed by many JDBC driver implementations to provide extensions beyond 15 * the traditional JDBC API that are specific to a data source. Developers may wish to gain access to 16 * these resources that are wrapped (the delegates) as proxy class instances representing the 17 * the actual resources. This interface describes a standard mechanism to access 18 * these wrapped resources 19 * represented by their proxy, to permit direct access to the resource delegates. 20 * 21 * @since 1.6 22 */ 23 24 public interface Wrapper { 25 26 /** 27 * Returns an object that implements the given interface to allow access to 28 * non-standard methods, or standard methods not exposed by the proxy. 29 * 30 * If the receiver implements the interface then the result is the receiver 31 * or a proxy for the receiver. If the receiver is a wrapper 32 * and the wrapped object implements the interface then the result is the 33 * wrapped object or a proxy for the wrapped object. Otherwise return the 34 * the result of calling <code>unwrap</code> recursively on the wrapped object 35 * or a proxy for that result. If the receiver is not a 36 * wrapper and does not implement the interface, then an <code>SQLException</code> is thrown. 37 * 38 * @param iface A Class defining an interface that the result must implement. 39 * @return an object that implements the interface. May be a proxy for the actual implementing object. 40 * @throws java.sql.SQLException If no object found that implements the interface 41 * @since 1.6 42 */ 43 <T> T unwrap(java.lang.Class<T> iface) throws java.sql.SQLException; 44 45 /** 46 * Returns true if this either implements the interface argument or is directly or indirectly a wrapper 47 * for an object that does. Returns false otherwise. If this implements the interface then return true, 48 * else if this is a wrapper then return the result of recursively calling <code>isWrapperFor</code> on the wrapped 49 * object. If this does not implement the interface and is not a wrapper, return false. 50 * This method should be implemented as a low-cost operation compared to <code>unwrap</code> so that 51 * callers can use this method to avoid expensive <code>unwrap</code> calls that may fail. If this method 52 * returns true then calling <code>unwrap</code> with the same argument should succeed. 53 * 54 * @param iface a Class defining an interface. 55 * @return true if this implements the interface or directly or indirectly wraps an object that does. 56 * @throws java.sql.SQLException if an error occurs while determining whether this is a wrapper 57 * for an object with the given interface. 58 * @since 1.6 59 */ 60 boolean isWrapperFor(java.lang.Class<?> iface) throws java.sql.SQLException; 61 62 } 63 64 65