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*/
020package org.olap4j;
021
022import 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 */
075public 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