Add table of contents functional spec, and some content regarding dri…

…vers, connections and statements; Add ant target to generate javadoc in PDF format; Rename OlapResult to OlapResultSet.

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

build.xml

@@ -36,6 +36,9 @@
  <property name="dist.src.file" value="${dist.dir}/${dist.name}-src.zip" />
  <property name="dist.doc.file" value="${dist.dir}/doc.tar.gz" />
 
+ <property name="generated.java.files" value=""/>
+ <property name="generated.lib.files" value=""/>
+
  <path id="project.classpath">
  <pathelement location="${classes.dir}"/>
  <!-- <pathelement location="${lib.dir}/retroweaver-1.2.4.jar"/> -->
@@ -44,7 +47,7 @@
  <pathelement location="${ant.home}/lib/optional.jar"/>
  <!-- We depend on mondrian right now. Ugh. -->
  <pathelement location="${lib.dir}/mondrian-2.1.1.jar"/>
- 
+
  </path>
 
  <path id="project.test.classpath">
@@ -147,11 +150,8 @@ ${generated.java.files}" />
 
  <target name="release" depends="binzip"/>
 
- <!-- These targets need to be added in: 
- retroweave,jar-jdk14,javadoc -->
-
  <target name="binzip"
- depends="clean,jar,version,srczip">
+ depends="clean,jar,version,srczip,retroweave,jar-jdk14,javadoc">
  <mkdir dir="${dist.dir}" />
  <delete file="${dist.bin.file}"/>
  <zip zipfile="${dist.bin.file}">
@@ -164,8 +164,8 @@ ${doc.dir}/**/*.html,
 ${doc.dir}/**/*.pdf,
 ${doc.dir}/**/*.png,
 ${doc.dir}/api/**/*.xml,
-${war.file},
 ${jar.file},
+${jar-jdk14.file},
 lib/*.dtd,
 LICENSE.html,
 README.txt,
@@ -281,6 +281,22 @@ META-INF/**"/>
  </javadoc>
  </target>
 
+ <target name="javadoc-pdf">
+ <javadoc sourcepath="${src.dir}:${testsrc.dir}"
+ classpathref="project.test.classpath"
+ packagenames="org.olap4j.*"
+ excludepackagenames="org.olap4j.sample.*"
+ overview="${src.dir}/overview.html"
+ author="true"
+ source="1.5"
+ access="package"
+ doclet="com.tarsec.javadoc.pdfdoclet.PDFDoclet"
+ docletpath="lib/pdfdoclet-1.0.2-all.jar"
+ additionalparam="-pdf doc/olap4j_api.pdf -config doc/pdfdoclet.properties"
+ >
+ </javadoc>
+ </target>
+
  <target name="test" />
 
  <taskdef name="retroweaver"

doc/pdfdoclet.properties

@@ -0,0 +1,139 @@
+# $Id: $
+# Configuration file for PDFDoclet.
+
+############################################################
+# Boolean properties
+############################################################
+
+# Lets the doclet print additional output in the console and to a logfile.
+#debug
+
+# Print "Author" tags
+#author
+
+# Print "Version" tags
+#version
+
+# Print "since" tags
+#tag.since
+
+# Create summary tables
+#summary.table
+
+# Create hyperlinks
+#create.links
+
+# Encrypt the PDF file
+#encrypted
+
+# Allow printing of the PDF file
+#allow.printing
+
+# Create a bookmark frame
+#create.frame
+
+# Print a title page
+api.title.page=true
+
+# Enables the tag-based filter
+#filter
+
+############################################################
+# Properties with a value
+############################################################
+
+# The path of the created PDF file.
+#pdf <file>
+
+# The base directory for image file path specifications (default is the current directory).
+#workdir <dir>
+
+# Optional comma-separated list of package names to define the ordering of the packages in the bookmarks frame.
+#sort <list>
+
+# Optional comma-separated list of package names to define packages whose classes should not be printed fully qualified (just "String" instead of "java.lang.String").
+#dontspec <list>
+
+# Specifies a custom doc tag with a certain label.
+#label.tag.<name> <label>
+
+# Overrides the text label to be printed for the title of the bookmarks.
+#label.bookmarks.title
+
+# Overrides the text label to be printed for the index entry in the bookmarks.
+#label.bookmarks.index
+
+# Overrides the text label to be printed for the overview entry in the bookmarks.
+#label.bookmarks.overview
+
+# Overrides the text label to be printed for the packages entry in the bookmarks.
+#label.bookmarks.packages
+
+# Only used with the -group parameter. Overrides the text label to be printed for the "Other Packages" entry in the bookmarks.
+#label.bookmarks.otherPackages
+
+# Overrides the text label to be printed for the fields entry in the bookmarks.
+#label.fields
+
+# Overrides the text label to be printed for the constructors entry in the bookmarks.
+#label.constructors
+
+# Overrides the text label to be printed for the methods entry in the bookmarks.
+#label.methods
+
+# Defines the text label for a tag. Can either override the label of a default tag such as "author", or define the label for a custom tag (custom tags are not printed as long as no label is defined for them).
+#label.tag.<tagname>
+
+# Create summary tables for inherited fields/methods. If the values is set to internal, summary tables are printed only for elements inherited by classes and interfaces within the scope of the API. Elements inherited from other classes such as java.lang.Object are ignored.
+#inherited.summary.table=[yes|internal]
+
+# Defines the name / number of the appendix.
+#appendix.<number>.name
+
+# Defines the title label of the appendix.
+#appendix.<number>.title
+
+# Path of the HTML or PDF file that should be included. If a PDF file is specified, the filename may be followed by a comma-separated list of single page numbers or page ranges, to define which pages to import from the PDF document.
+#appendix.<number>.file=<file path>[,page,from-to,..,..]
+
+# Prefix-text for page numbers.
+#page.numbers.prefix <text>
+
+# "full" or "simple"
+#page.numbers.type <type>
+
+# "left", "center", "right" or "switch". Defines the alignment of page numbers. "switch" means that they will switch from left to right and back, as needed for printing.
+#page.numbers.alignment <type>
+
+# The path of a HTML file used for the title page of the PDF.
+#api.title.file <file>
+
+# Title for the title page if no external HTML title page is used.
+api.title=olap4j, version 0.6
+
+# Copyright remark for the title page if no external HTML title page is used.
+api.copyright=Copyright (C) 2006-2006 Julian Hyde and others
+
+# Author's name for the title page if no external HTML title page is used.
+api.author=Julian Hyde
+
+# Font to be used for all regular text. Default is TIMES-ROMAN (path of TrueType-font, like ./fonts/garait.ttf).
+#font.text.name <ttf-file>
+
+# Optional encoding for the text font.
+#font.text.enc
+
+# Font to be used for all fixed-width code parts. Default is COURIER.
+#font.code.name <ttf-file>
+
+# Optional encoding for the code font.
+#font.code.enc
+
+# Comma-separated list of filter tags.
+#filter.tags <taglist>
+
+# Filter tag with certain name and value.
+#filter.tag.<name> <label>
+
+# End pdfdoclet.properties
+

src/org/olap4j/OlapConnection.java

@@ -22,10 +22,6 @@
  * @since Aug 22, 2006
  */
 public interface OlapConnection extends Connection {
- /**
- * Creates an OLAP Statement.
- */
- OlapStatement createOlapStatement() throws SQLException;
 
  /**
  * Creates a prepared OLAP Statement.

src/org/olap4j/OlapParameterMetaData.java

@@ -0,0 +1,52 @@
+/*
+// $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.type.Type;
+
+import java.sql.ParameterMetaData;
+import java.sql.SQLException;
+
+/**
+ * Extension to {@link ParameterMetaData} for parameters of OLAP statements.
+ *
+ * <p>Chief differences:
+ * <ul>
+ * <li>An OLAP statement parameter has a name.
+ * <li>An OLAP statement parameter may be a member. If this is the case,
+ * the {@link #getParameterType(int)} method returns
+ * {@link java.sql.Types#OTHER}.
+ * <li>An additional method {@link #getOlapType(int)} provides extra type
+ * information; in particular, the hierarchy that a member parameter
+ * belongs to.
+ * </ul>
+ * <p>an
+ *
+ * @author jhyde
+ * @version $Id: $
+ * @since Oct 12, 2006
+ */
+public interface OlapParameterMetaData extends ParameterMetaData {
+ /**
+ * Returns the name of this parameter.
+ */
+ String getName();
+
+ /**
+ * Retrieves the designated parameter's OLAP type.
+ *
+ * @param param the first parameter is 1, the second is 2, ...
+ * @return OLAP type
+ * @exception SQLException if a database access error occurs
+ */
+ Type getOlapType(int param) throws SQLException;
+}
+
+// End OlapParameterMetaData.java

src/org/olap4j/OlapResult.java → src/org/olap4j/OlapResultSet.java

@@ -10,6 +10,7 @@
 package org.olap4j;
 
 import java.util.List;
+import java.sql.ResultSet;
 
 /**
  * Result of executing an OLAP Statement.
@@ -22,10 +23,22 @@
  * @version $Id$
  * @since Aug 22, 2006
  */
-public interface OlapResult {
+public interface OlapResultSet extends ResultSet {
+ /**
+ * Retrieves a list of axes containing the result.
+ *
+ * <p>The list contains axes according to their ordinal: 0 is the columns
+ * axis, 1 the rows axis, and so forth.
+ */
  List<ResultAxis> getAxes();
 
+ /**
+ * Returns the cell at a given set of coordinates.
+ *
+ * @param coordinates 0-based coordinates of the cell
+ * @return Cell
+ */
  ResultCell getCell(int[] coordinates);
 }
 
-// End OlapResult.java
+// End OlapResultSet.java

src/org/olap4j/OlapStatement.java

@@ -18,7 +18,7 @@
 
 /**
  * Object used for statically executing an MDX statement and returning an
- * {@link OlapResult}.
+ * {@link OlapResultSet}.
  *
  * @see PreparedOlapStatement
  *
@@ -27,10 +27,11 @@
  * @since Aug 22, 2006
  */
 public interface OlapStatement extends Statement {
+
  /**
  * Executes an OLAP statement.
  */
- OlapResult executeOlapQuery(String mdx) throws SQLException;
+ OlapResultSet executeOlapQuery(String mdx) throws SQLException;
 
  /**
  * Executes an OLAP statement expressed as a parse tree.
@@ -39,12 +40,7 @@ public interface OlapStatement extends Statement {
  * @param query Parse tree of MDX SELECT statement
  * @return Result
  */
- OlapResult executeOlapQuery(Query query);
-
- /**
- * Returns the cube (or virtual cube) which this statement is based upon.
- */
- Cube getCube();
+ OlapResultSet executeOlapQuery(Query query);
 
 }