Update specification and java code, especially metadata (org.olap4j.m…

…etadata) and type (org.olap4j.type) sections, and description of how to interoperate with connection pools.

git-svn-id: https://olap4j.svn.sourceforge.net/svnroot/olap4j/trunk@10 c6a108a4-781c-0410-a6c6-c2d559e19af0

build.xml

@@ -14,7 +14,7 @@
  <property file="${project.location}/build.properties"/>
  <property name="project.build.debug" value="on"/>
  <property name="name" value="olap4j"/>
- <property name="version" value="0.5"/>
+ <property name="version" value="0.6"/>
  <property name="dist.name" value="${name}-${version}" />
 
  <!-- properties related to paths -->
@@ -183,7 +183,7 @@ ${doc.dir}/api/src-html/**/*"/>
  </target>
 
  <target name="doczip"
- depends="version,javadoc"
+ depends="version,javadoc,javadoc-pdf"
  description="Builds a zipfile of the documentation, which can then be
  deployed to sf.net. See also doc/deployDoc.sh.">
  <mkdir dir="${dist.dir}" />
@@ -197,7 +197,8 @@ doc/api/**/*,
 doc/**/*.html,
 doc/**/*.pdf,
 doc/**/*.css,
-doc/**/*.xml"
+doc/**/*.xml,
+doc/olap4j_api.pdf"
  excludes="
 **/*~,
 **/_vti*/*,

src/org/olap4j/Olap4j.java

@@ -0,0 +1,237 @@
+/*
+// $Id: $
+// This software is subject to the terms of the Common Public License
+// Agreement, available at the following URL:
+// http://www.opensource.org/licenses/cpl.html.
+// Copyright (C) 2006-2006 Julian Hyde
+// All Rights Reserved.
+// You must accept the terms of that agreement to use this software.
+*/
+package org.olap4j;
+
+import org.olap4j.mdx.parser.MdxParserFactory;
+
+import java.sql.*;
+
+/**
+ * Miscellaneous utility functions, in particular dealing with the wrapped
+ * objects created by connection pools.
+ *
+ * <p>Connection pools typically work by creating wrapped versions of
+ * connection, statement, prepared statement, result set, and metadata objects.
+ * These are problematic for olap4j, because olap4j extends the JDBC interfaces,
+ * and the wrapped objects will not implement those interfaces. The following
+ * table lists the interfaces extended by olap4j:</p>
+ *
+ * <table border="1">
+ * <tr>
+ * <th>olap4j class</th>
+ * <th>extends JDBC class</th>
+ * <th>created by</th>
+ * </tr>
+ * <tr>
+ * <td>{@link OlapConnection}</td>
+ * <td><code>{@link Connection}</code></td>
+ * <td>
+ * <ul>
+ * <li><code>{@link DriverManager#getConnection(String) Connection DriverManager.getConnection(String)}</code></li>
+ * <li><code>{@link javax.sql.DataSource#getConnection() Connection DataSource.getConnection()}</code></li>
+ * </ul>
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>{@link OlapStatement}</td>
+ * <td><code>{@link Statement}</code></td>
+ * <td>
+ * <ul>
+ * <li><code>{@link java.sql.Connection#createStatement() Statement Connection.createStatement()}</code></li>
+ * </ul>
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>{@link PreparedOlapStatement}</td>
+ * <td><code>{@link PreparedStatement}</code></td>
+ * <td>
+ * <ul>
+ * <li><code>{@link Connection#prepareStatement(String) PreparedStatement Connection.prepareStatement(String)}</code></li>
+ * </ul>
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>{@link OlapResultSet}</td>
+ * <td><code>{@link ResultSet}</code></td>
+ * <td>
+ * <ul>
+ * <li><code>{@link Statement#execute(String) ResultSet Statement.executeQuery(String)}</code></li>
+ * <li><code>{@link PreparedStatement#execute(String) ResultSet PreparedStatement.executeQuery()}</code></li>
+ * </ul>
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * <p>If you are using a connection pool, you cannot safely cast a
+ * {@link Connection} to an {@link OlapConnection}, or a {@link Statement} to
+ * a {@link OlapStatement}. Use the appropriate
+ * {@link #convert(java.sql.Connection)} method, and the resulting object will
+ * implement the necessary interface and also implement the behavior required
+ * by the connection pool in order to manage sub-objects safely.
+ *
+ * <p>We plan to support common connection-pooling libraries:
+ * <ul>
+ * <li><a href="http://jakarta.apache.org/commons/dbcp/">Jakarta Commons DBCP</a>;</li>
+ * <li><a href="http://sourceforge.net/projects/c3p0">C3P0</a>.</li>
+ * </ul>
+ *
+ * @author jhyde
+ * @version $Id: $
+ * @since Oct 13, 2006
+ */
+public class Olap4j {
+ /**
+ * Converts a JDBC connection ({@link java.sql.Connection})
+ * to an olap4j connection ({@link OlapConnection}).
+ *
+ * <p>The connection produced by an olap4j driver will already implement the
+ * <code>OlapConnection</code> interface, but certain connection pools
+ * add wrappers. This method removes those wrappers.
+ */
+ public static OlapConnection convert(Connection connection) {
+ return adapterFor(connection).convert(connection);
+ }
+
+ /**
+ * Converts a JDBC statement ({@link java.sql.Statement})
+ * to an olap4j statement ({@link OlapStatement}).
+ *
+ * <p>The statement produced by an olap4j driver will already implement the
+ * <code>OlapStatement</code> interface, but certain connection pools
+ * add wrappers. This method removes those wrappers.
+ */
+ public static OlapStatement convert(Statement stmt) {
+ return adapterFor(stmt).convert(stmt);
+ }
+
+ /**
+ * Converts a JDBC prepared statement ({@link java.sql.Connection})
+ * to an olap4j prepared statement ({@link PreparedOlapStatement}).
+ *
+ * <p>The prepared statement produced by an olap4j driver will already
+ * implement the <code>PreparedOlapStatement</code> interface, but certain
+ * connection pools add wrappers. This method removes those wrappers.
+ */
+ public static PreparedOlapStatement convert(PreparedStatement pstmt) {
+ return adapterFor(pstmt).convert(pstmt);
+ }
+
+ /**
+ * Converts a JDBC result set ({@link java.sql.ResultSet})
+ * to an olap4j result set ({@link OlapResultSet}).
+ *
+ * <p>The result set eproduced by an olap4j driver will already
+ * implement the <code>OlapResultSet</code> interface, but certain
+ * connection pools add wrappers. This method removes those wrappers.
+ */
+ public static OlapResultSet convert(ResultSet resultSet) {
+ return adapterFor(resultSet).convert(resultSet);
+ }
+
+ /**
+ * Converts a JDBC result set ({@link java.sql.DatabaseMetaData})
+ * to an olap4j result set ({@link OlapDatabaseMetaData}).
+ *
+ * <p>The <code>DatabaseMetaData</code> eproduced by an olap4j driver will
+ * already implement the <code>OlapDatabaseMetaData</code> interface, but
+ * certain connection pools add wrappers. This method removes those
+ * wrappers.
+ */
+ public static OlapDatabaseMetaData convert(DatabaseMetaData metadata) {
+ return adapterFor(metadata).convert(metadata);
+ }
+
+ /**
+ * Helper method to automatically create the right adapter to unpack a
+ * connection.
+ */
+ private static Adapter adapterFor(Connection connection) {
+ return CastingAdapter.INSTANCE;
+ }
+
+ /**
+ * Helper method to automatically create the right adapter to unpack a
+ * statement.
+ */
+ private static Adapter adapterFor(Statement stmt) {
+ return CastingAdapter.INSTANCE;
+ }
+
+ /**
+ * Helper method to automatically create the right adapter to unpack a
+ * prepared statement.
+ */
+ private static Adapter adapterFor(PreparedStatement pstmt) {
+ return CastingAdapter.INSTANCE;
+ }
+
+ /**
+ * Helper method to automatically create the right adapter to unpack a
+ * database metadata.
+ */
+ private static Adapter adapterFor(DatabaseMetaData metadata) {
+ return CastingAdapter.INSTANCE;
+ }
+
+ /**
+ * Helper method to automatically create the right adapter to unpack a
+ * result set.
+ */
+ private static Adapter adapterFor(ResultSet resultSet) {
+ return CastingAdapter.INSTANCE;
+ }
+
+ public static MdxParserFactory getParserFactory(Connection connection) {
+ return convert(connection).getParserFactory();
+ }
+
+ /**
+ * Specification for a helper which can remove the wrappers added by
+ * certain connection pools.
+ */
+ private static interface Adapter {
+ OlapConnection convert(Connection connection);
+ OlapStatement convert(Statement stmt);
+ PreparedOlapStatement convert(PreparedStatement pstmt);
+ OlapDatabaseMetaData convert(DatabaseMetaData metadata);
+ OlapResultSet convert(ResultSet resultSet);
+ }
+
+
+ /**
+ * Implementation of {@link Adapter} which simply casts objects to the
+ * desired type.
+ */
+ private static class CastingAdapter implements Adapter {
+ private static final Adapter INSTANCE = new CastingAdapter();
+
+ public OlapConnection convert(Connection connection) {
+ return (OlapConnection) connection;
+ }
+
+ public OlapStatement convert(Statement stmt) {
+ return (OlapStatement) stmt;
+ }
+
+ public PreparedOlapStatement convert(PreparedStatement pstmt) {
+ return (PreparedOlapStatement) pstmt;
+ }
+
+ public OlapDatabaseMetaData convert(DatabaseMetaData metadata) {
+ return (OlapDatabaseMetaData) metadata;
+ }
+
+ public OlapResultSet convert(ResultSet resultSet) {
+ return (OlapResultSet) resultSet;
+ }
+ }
+}
+
+// End Olap4j.java

src/org/olap4j/OlapConnection.java

@@ -13,6 +13,7 @@
 
 import java.sql.Connection;
 import java.sql.SQLException;
+import java.sql.Statement;
 
 /**
  * Connection to an OLAP server.
@@ -32,6 +33,12 @@ public interface OlapConnection extends Connection {
  * Returns the factory used to create MDX parsers in this connection.
  */
  MdxParserFactory getParserFactory();
+
+ /**
+ * Override {@link java.sql.Connection#createStatement()} with refined
+ * result type.
+ */
+ OlapStatement createStatement() throws SQLException;
 }
 
 // End OlapConnection.java