Add task list, and minor spec/javadoc edits

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

doc/olap4j_fs.html

@@ -192,7 +192,7 @@ <h2><a name="Contents">Contents</a></h2>
 	<li><a href="#Non-functionality">Non-functionality</a></li>
 	<li><a href="#Related_projects">Related projects</a><ol>
 		<li><a href="#Mondrian_provider">Mondrian provider</a></li>
-		<li><a href="#JPivot">JPivot</a></li>
+		<li><a href="#XMLA_provider">XML for Analysis provider</a></li>
 		<li><a href="#Other_data_sources">Other data sources</a></li>
 	</ol>
 	</li>
@@ -208,7 +208,7 @@ <h2>1. <a name="Introduction">Introduction</a></h2>
 
 <p>olap4j is an open Java API for building OLAP applications.</p>
 
-<p>In essence, olap4j is to multidimensional data JDBC is for relational data.
+<p>In essence, olap4j is to multidimensional data what JDBC is for relational data.
 olap4j has a similar programming model to JDBC, shares some of its core classes,
 and has many of the same advantages. You can write an OLAP application in Java
 for one
@@ -390,7 +390,7 @@ <h2>
 <p>We now describe the olap4j API in more detail, by breaking it down into a set
 of functional areas.</p>
 
-<img class="std" alt="olap4j components" src="open/olap4j/doc/olap4j-comp.png" width="740" height="692">
+<img class="std" alt="olap4j components" src="olap4j-comp.png" width="740" height="692">
 
 <h3>2.1. <a name="Driver_management">Driver management</a></h3>
 
@@ -3259,12 +3259,12 @@ <h3>3.2. <a name="XML/A_provider">XML/A provider</a></h3>
 <h2>4. <a name="Non-functionality">Non-functionality</a></h2>
 
 <p>Here are some of the areas of functionality which will <i>not</i> be part of
-the olap4j project:</p>
+olap4j:</p>
 <ul>
   <li>Schema reader parses an XML file to create a schema</li>
   <li>Cache management functions </li>
   <li>Ability to create/modify schema dynamically</li>
-  <li>Definitions of MDX functions</li>
+  <li>Definitions of MDX functions (such as the number and types of parameters)</li>
   <li>SPI to extend the system by creating user-defined functions and so forth</li>
   <li>XML/A bridge (to make an olap4j data source appear as an XML/A server)</li>
   <li>SchemaReader</li>
@@ -3275,16 +3275,19 @@ <h2>5. <a name="Related_projects">Related projects</a></h2>
 <h3>5.1. <a name="Mondrian_provider">Mondrian provider</a></h3>
 
 <p>The Mondrian project will contain an implementation of the olap4j API based on
-the Mondrian OLAP server.</p>
-
-<h3>5.2. <a name="JPivot">JPivot</a></h3>
-
-<p>JPivot currently based on two data sources: the Mondrian server, and a
-generic XML/A data source.</p>
-
-<p>We intend to convert JPivot to run solely on the olap4j API. Connectivity to
-Mondrian and XML/A sources will be achieved by choosing the appropriate olap4j
-provider. </p>
+the Mondrian OLAP engine.</p>
+<p>This code is currently being developed the same source-code repository as 
+olap4j, and is the reference implementation of olap4j. The code will be 
+contributed to the mondrian project in the mondrian-3.0 release, when olap4j 
+will become mondrian's primary API, and the mondrian team will take over its 
+development.</p>
+
+<h3>5.2. <a name="XMLA_provider">XML for Analysis provider</a></h3>
+<p>We intend to create an a driver which implements the olap4j API on top of any 
+XML/A data source.</p>
+<p>This code is currently being developed in the same source-code repository as 
+olap4j, but will never be part of any olap4j release, and will be spun off as a 
+separate project before olap4j 1.0.</p>
 
 <h3>5.3. <a name="Other_data_sources">Other data sources</a></h3>
 

doc/tasks.txt

@@ -0,0 +1,105 @@
+# Tasks for olap4j 0.9 
+# Author: Julian Hyde
+# $Id: $
+
+Introduction: How to use this document
+--------------------------------------
+
+This document is a list of tasks to be accomplished before olap4j-0.9 is released.
+
+The tasks are grouped by category, but sometimes different aspects of the same task appear in multiple categories, so be smart when selecting which tasks to work on. For example, writing a description of the Cube class appears as a specification task and a javadoc task.
+
+Pick some tasks to work on - most of them are quite short - make the changes to the specification, delete the completed tasks from this list, and check in your changes along with the new version of this file.
+
+Remember that other people may be editing this file, so avoid non-mergeable edits.
+
+Specification
+-------------
+
+* D.1 add discussion of thread-safety 
+* D.1 add discussion of api for cancelling statements 
+* D.1 add discussion of compliance levels 
+* D.1 describe how members of axis can be accessed via iterator or list, with code examples 
+* 2.1.5 internationalization: move section elsewhere; what is the behavior of locale? does it belong to connection? fix and test Query.getLocale(). document that all methods which return localized strings take a locale parameter; that parameter may be null, in which case the connection's locale is used 
+* 2.3.2 how to find out what cube a prepared statement relates to 
+* 2.3.10 remove section CellSetAxis - duplicates 2.3.5 
+* 2.7.2 diagram of object model 
+* 2.7.2.x define Schema, Cube, Dimension, Hierarchy, Level, Member, Measure, Property, NamedSet. 
+* 2.7.3 The OlapDatabaseMetaData interface: 
+** clean up data types (should be JDBC types)  
+** clean up column names (should be UPPER_CASE) 
+** define enum types 
+* 2.7.3.2 is VALUE a SQL reserved word? if so, rename the property 
+* 2.8 query model - barry and/or james complete? 
+* 2.9 layout - remove from spec? 
+* add parse and parser model to specification 
+* discuss access-control (each provider can have their own rules. can set access-control on the connection. metadata methods should be consistent with that.) 
+
+Javadoc
+-------
+
+* class doc for org.olap4j.cellsetaxis 
+* class doc for org.olap4j.olapwrapper 
+* class doc for mondrian.olap4j.emptyresultset 
+* class doc for mondrianolap4jconnection.helper 
+* class doc for olap4j.mdx.parsetreewriter 
+* class doc for olap4j.mdx.parseregion.regionandsource 
+* class doc for org.olap4j.metadata.Catalog 
+* class doc for org.olap4j.metadata.Cube 
+* class doc for org.olap4j.metadata.Dimension 
+* class doc for org.olap4j.metadata.Hierarchy 
+* class doc for org.olap4j.metadata.Measure 
+* class doc for org.olap4j.metadata.MetadataElement 
+* class doc for org.olap4j.metadata.Schema 
+* class doc for org.olap4j.metadata.Property.Datatype 
+* class doc for org.olap4j.metadata.Property.Scope 
+* change ant task so it doesn't generate mondrian.olap4j.* or olap4j.test.* or org.olap4j.mdx.parser.impl or package-protected classes (E.g. org.olap4j.mdx.MdxValidator) in public api; remove class OlapTest, class Todo 
+* package mdx.parser.impl - comment that this package is not part of the spec, and implementation may change at any time 
+* ensure that every public method has a javadoc description, including @param, @return and @throws declarations 
+* document OlapDatabaseMetadata.getXxx methods 
+* Review olap4j.type package. Document all public methods. Make non-essential methods (E.g. MemberType.forType) package-private. If in doubt, leave it out 
+
+Code
+----
+
+* Write javadoc for, implement and test Level.findMember 
+* in QueryAxis, make dimension list mutable; remove methods QueryAxis.clearDimensions, appendDimensions, appendDimension, insertDimension, removeDimension; and add tests for the functionality of these methods; remove methods from spec. 
+* in QueryDimension, make selection list mutable; remove methods addSelection, addMemberSelection, addSelections, clearSelections; add tests; remove from spec. 
+* fix 4 TODOs in ParserTest 
+
+Testing
+-------
+
+* Ensure that there is a unit test for every method in every public class or interface. 
+* Write unit test for metadata classes. 
+* Write unit test for OlapDatabaseMetadata.getXxx methods 
+* Internationalization test, including Connection.getLocale(), Query.getLocale(), and all methods with Locale methods or results 
+* Test access control. The metadata (e.g. members & hierarchies) should reflect what the current user/role can see. For example, USA.CA.SF has no children. This test should test every method which returns a metadata element or collection of metadata elements. 
+* ConnectionTest (301, 12) // todo: call getCubes with a pattern for cube name and schema name  
+* ConnectionTest (303, 12) // todo: call getCubes with a different schema  
+* ConnectionTest (367, 12) // todo: More tests required for other methods on DatabaseMetaData  
+* ConnectionTest (428, 8) // todo: test statement with no slicer  
+* ConnectionTest (596, 12) // todo: test all of the PreparedOlapStatement.setXxx methods 
+* Test methods in class Cell. (see ConnectionTest.testCell) 
+* Test methods in class CellSetAxis. (see ConnectionTest.testCellSetAxis) 
+* Test methods in OlapResultAxisMetaData (see ConnectionTest.testOlapResultAxisMetaData) 
+* Test cell and dimension properties (in ConnectionTest, see "todo: submit a query with cell and dimension properties, and make sure the properties appear in the result set") 
+* Test scrolling (in ConnectionTest, see "todo: submit a query where you ask for different scrolling") 
+* Test building parse tree (in ConnectionTest see "build parse tree (todo) ") 
+* Test axis name uniqueness (in ConnectionTest, see "test that get error if axes do not have unique names (todo)") 
+
+Not in scope for olap4j 0.9
+---------------------------
+
+* convert parser to javacc 
+* XMLA driver 
+
+General guidelines
+------------------
+
+* Coding standards are as for mondrian: 80 characters, indent 4, no tabs 
+* Javadoc: all public classes and members have javadoc, including @param, @return, @throws 
+* Do not write javadoc for overriding/implementing methods 
+* Must be javadoc clean on checkin 
+
+# Ends

src/org/olap4j/Cell.java

@@ -43,6 +43,8 @@ public interface Cell {
      * <li>(row 1, column 0) has ordinal 10,</li>
      * <li>(row 19, column 9) has ordinal 199.</li>
      * </ul>
+     *
+     * @return Ordinal of this Cell
      */
     int getOrdinal();
 
@@ -56,14 +58,22 @@ public interface Cell {
      *    getResult().ordinalToCoordinateList(getOrdinal())
      * </code>
      * </blockquote>
+     *
+     * @return Coordinates of this Cell
      */
     List<Integer> getCoordinateList();
 
     /**
      * Returns the value of a given property for this Cell.
      *
-     * @see org.olap4j.CellSet#getMetaData()
-     * @see Todo
+     * <p>The list of allowable properties may be obtained by calling
+     * {@link org.olap4j.CellSet#getMetaData()} followed by
+     * {@link CellSetMetaData#getCellProperties()}.</p>
+     *
+     * @param property Property whose value to retrieve
+     *
+     * @return Value of the given property for this Cell; if the property is
+     * not set, returns null
      */
     Object getPropertyValue(Property property);
 
@@ -91,20 +101,40 @@ public interface Cell {
     /**
      * Returns the value of this cell as a <code>double</code> value.
      *
+     * <p>Not all values can be represented as using the Java
+     * <code>double</code>, therefore for some providers, {@link #getValue()}
+     * may return a more accurate result.
+     *
+     * @return The value of this cell; if the cell is null, the
+     * returns <code>0</code>
+     *
      * @throws OlapException if this cell does not have a numeric value
      */
     double getDoubleValue() throws OlapException;
 
     /**
-     * @see Todo
+     * Returns the error message of this Cell, or null if the cell is not
+     * in error.
+     *
+     * <p>If the cell is an error, the value will be an {@link OlapException}.
+     * (This value is returned, not thrown.)
+     *
+     * @return value of this Cell
      */
     String getErrorText();
 
     /**
-     * @see Todo
+     * Returns the value of this Cell.
+     *
+     * <p>If the cell is an error, the value will be an {@link OlapException}.
+     * (This value is returned, not thrown.)
      *
-     * Returns (does not throw) an {@link OlapException} if the cell is an
-     * error.
+     * <p>If the cell has a numeric value, returns an object which implements
+     * the {@link Number} interface.
+     *
+     * @see #getDoubleValue()
+     *
+     * @return value of this Cell
      */
     Object getValue();
 
@@ -120,6 +150,8 @@ public interface Cell {
     /**
      * Drills through from this cell to the underlying fact table data,
      * and returns a {@link java.sql.ResultSet} of the results.
+     *
+     * @return result set of the fact rows underlying this Cell
      */
     ResultSet drillThrough();
 }

src/org/olap4j/metadata/Level.java

@@ -58,8 +58,14 @@ public interface Level extends MetadataElement {
     // todo: needs specification
     Member findMember(String memberName);
 
-    // todo: better query interface? (level can have a lot of members)
-    // todo: return NamedList?
+    /**
+     * Returns a list of Member objects which belong to this Level.
+     *
+     * <p>Some levels have a very many members. In this case, calling this
+     * method may be expensive in space and/or time and is not recommended.
+     *
+     * @return List of members in this level
+     */
     List<Member> getMembers();
 
     /**

src/org/olap4j/metadata/Member.java

@@ -139,9 +139,8 @@ private Type(int ordinal) {
      *
      * <p>Every member has certain system properties such as "name" and
      * "caption" (the full list is described in the {@link Property}
-     * ({@link org.olap4j.Todo todo: move Property})
      * enumeration), as well as extra properties defined for its Level
-     * (see {@link Level#getProperties()}
+     * (see {@link Level#getProperties()}).</p>
      *
      * @see #getPropertyValue(String)
      */

src/org/olap4j/query/QueryDimension.java

@@ -85,8 +85,13 @@ public void clearSelections() {
         selections.clear();
     }
 
-    public Selection createSelection(String hierarchyName, String levelName, String memberName) {
-        return createSelection(hierarchyName, levelName, memberName, Selection.Operator.MEMBER);
+    public Selection createSelection(
+        String hierarchyName,
+        String levelName,
+        String memberName)
+    {
+        return createSelection(
+            hierarchyName, levelName, memberName, Selection.Operator.MEMBER);
     }
 
     public Selection createSelection(
@@ -102,7 +107,9 @@ public Selection createSelection(
             if (level != null) {
                 Member member = level.findMember(memberName);
                 if (member != null) {
-                    selection = query.getSelectionFactory().createMemberSelection(member);
+                    selection =
+                        query.getSelectionFactory()
+                            .createMemberSelection(member);
                 }
             }
         }

testsrc/org/olap4j/ConnectionTest.java

@@ -808,10 +808,6 @@ public void testUnparsing() {
 
     }
 
-    /**
-     * Tests access control. The metadata (e.g. members & hierarchies) should
-     * reflect what the current user/role can see. For example, USA.CA.SF has no children.
-     */
     /**
      * Abstracts the information about specific drivers and database instances
      * needed by this test. This allows the same test suite to be used for