001    /*
002    // $Id: OlapWrapper.java 482 2012-01-05 23:27:27Z jhyde $
003    //
004    // Licensed to Julian Hyde under one or more contributor license
005    // agreements. See the NOTICE file distributed with this work for
006    // additional information regarding copyright ownership.
007    //
008    // Julian Hyde licenses this file to you under the Apache License,
009    // Version 2.0 (the "License"); you may not use this file except in
010    // compliance with the License. You may obtain a copy of the License at:
011    //
012    // http://www.apache.org/licenses/LICENSE-2.0
013    //
014    // Unless required by applicable law or agreed to in writing, software
015    // distributed under the License is distributed on an "AS IS" BASIS,
016    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017    // See the License for the specific language governing permissions and
018    // limitations under the License.
019    */
020    package org.olap4j;
021    
022    import java.sql.SQLException;
023    
024    /**
025     * Interface for olap4j classes which provide the ability to retrieve the
026     * delegate instance when the instance in question is in fact a proxy class.
027     *
028     * <p><code>OlapWrapper</code> duplicates the functionality of the
029     * <code>java.sql.Wrapper</code> interface (introduced in JDBC 4.0), making
030     * this functionality available to olap4j clients running in a JDBC 3.0
031     * environment. For code which will run only on JDBC 4.0 and later, Wrapper can
032     * be used, and OlapWrapper can be ignored.</p>
033     *
034     * <p>In JDBC 3.0 (JDK 1.5) and earlier, the <code>OlapWrapper</code> interface
035     * is used to convert a JDBC class to the corresponding olap4j class. For
036     * instance, write
037     *
038     * <blockquote>
039     * <pre>
040     * import java.sql.Connection;
041     * import java.sql.DriverManager;
042     * import org.olap4j.OlapConnection;
043     * import org.olap4j.OlapWrapper;
044     *
045     * Connection connection = DriverManager.getConnection("jdbc: ...");
046     * OlapWrapper wrapper = (OlapWrapper) connection;
047     * OlapConnection olapConnection = wrapper.unwrap(OlapConnection.class);
048     * </pre>
049     * </blockquote>
050     *
051     * to create a JDBC 3.0 connection and convert it to an olap4j connection.
052     *
053     * <p>In JDBC 4.0 (JDK 1.6) and later, you don't need to use this class. All of
054     * the key JDBC classes implement <code>java.sql.Wrapper</code> interface, so
055     * you can use its <code>isWrapper</code> and <code>unwrap</code> methods
056     * without casting. For instance, write
057     *
058     * <blockquote>
059     * <pre>
060     * import java.sql.Connection;
061     * import java.sql.DriverManager;
062     * import org.olap4j.OlapConnection;
063     *
064     * Connection connection = DriverManager.getConnection("jdbc: ...");
065     * OlapConnection olapConnection = connection.unwrap(OlapConnection.class);
066     * </pre>
067     * </blockquote>
068     *
069     * to create a JDBC 4.0 connection and convert it to an olap4j connection.
070     *
071     * @author jhyde
072     * @version $Id: OlapWrapper.java 482 2012-01-05 23:27:27Z jhyde $
073     * @since Jun 14, 2007
074     */
075    public interface OlapWrapper {
076        // duplicate method from java.sql.Wrapper (JDBC 4.0), so method is available
077        // in JDBC 3.0
078        <T> T unwrap(Class<T> iface) throws SQLException;
079    
080        // duplicate method from java.sql.Wrapper (JDBC 4.0), so method is available
081        // in JDBC 3.0
082        boolean isWrapperFor(Class<?> iface) throws SQLException;
083    }
084    
085    // End OlapWrapper.java