001    /*
002    // $Id: OlapWrapper.java 229 2009-05-08 19:11:29Z jhyde $
003    // This software is subject to the terms of the Eclipse Public License v1.0
004    // Agreement, available at the following URL:
005    // http://www.eclipse.org/legal/epl-v10.html.
006    // Copyright (C) 2007-2008 Julian Hyde
007    // All Rights Reserved.
008    // You must accept the terms of that agreement to use this software.
009    */
010    package org.olap4j;
011    
012    import java.sql.SQLException;
013    
014    /**
015     * Interface for olap4j classes which provide the ability to retrieve the
016     * delegate instance when the instance in question is in fact a proxy class.
017     *
018     * <p><code>OlapWrapper</code> duplicates the functionality of the
019     * <code>java.sql.Wrapper</code> interface (introduced in JDBC 4.0), making
020     * this functionality available to olap4j clients running in a JDBC 3.0
021     * environment. For code which will run only on JDBC 4.0 and later, Wrapper can
022     * be used, and OlapWrapper can be ignored.</p>
023     *
024     * <p>In JDBC 3.0 (JDK 1.5) and earlier, the <code>OlapWrapper</code> interface
025     * is used to convert a JDBC class to the corresponding olap4j class. For
026     * instance, write
027     *
028     * <blockquote>
029     * <pre>
030     * import java.sql.Connection;
031     * import java.sql.DriverManager;
032     * import org.olap4j.OlapConnection;
033     * import org.olap4j.OlapWrapper;
034     *
035     * Connection connection = DriverManager.getConnection("jdbc: ...");
036     * OlapWrapper wrapper = (OlapWrapper) connection;
037     * OlapConnection olapConnection = wrapper.unwrap(OlapConnection.class);
038     * </pre>
039     * </blockquote>
040     *
041     * to create a JDBC 3.0 connection and convert it to an olap4j connection.
042     *
043     * <p>In JDBC 4.0 (JDK 1.6) and later, you don't need to use this class. All of
044     * the key JDBC classes implement <code>java.sql.Wrapper</code> interface, so
045     * you can use its <code>isWrapper</code> and <code>unwrap</code> methods
046     * without casting. For instance, write
047     *
048     * <blockquote>
049     * <pre>
050     * import java.sql.Connection;
051     * import java.sql.DriverManager;
052     * import org.olap4j.OlapConnection;
053     *
054     * Connection connection = DriverManager.getConnection("jdbc: ...");
055     * OlapConnection olapConnection = connection.unwrap(OlapConnection.class);
056     * </pre>
057     * </blockquote>
058     *
059     * to create a JDBC 4.0 connection and convert it to an olap4j connection.
060     *
061     * @author jhyde
062     * @version $Id: OlapWrapper.java 229 2009-05-08 19:11:29Z jhyde $
063     * @since Jun 14, 2007
064     */
065    public interface OlapWrapper {
066        // duplicate method from java.sql.Wrapper (JDBC 4.0), so method is available
067        // in JDBC 3.0
068        <T> T unwrap(Class<T> iface) throws SQLException;
069    
070        // duplicate method from java.sql.Wrapper (JDBC 4.0), so method is available
071        // in JDBC 3.0
072        boolean isWrapperFor(Class<?> iface) throws SQLException;
073    }
074    
075    // End OlapWrapper.java