Javadoc and spec tasks, mostly adding descriptions of metadata elements.

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

doc/tasks.txt

@@ -22,7 +22,6 @@ Specification
 * 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: 
@@ -32,28 +31,13 @@ Specification
 * 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 
+* add mdx parser and mdx parse tree 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 
+
+* 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 

src/mondrian/olap4j/EmptyResultSet.java

@@ -20,7 +20,11 @@
 import java.net.URL;
 
 /**
- * <code>EmptyResultSet</code> ...
+ * Implementation of {@link ResultSet} which returns 0 rows.
+ *
+ * <p>This class is used to implement {@link java.sql.DatabaseMetaData}
+ * methods for querying object types where those object types never have
+ * any instances for this particular driver.</p>
  *
  * @author jhyde
  * @version $Id$
@@ -82,9 +86,6 @@ public BigDecimal getBigDecimal(
  }
 
  public byte[] getBytes(int columnIndex) throws SQLException {
- if (false) {
- return new byte[0];
- }
  throw new UnsupportedOperationException();
  }
 
@@ -150,9 +151,6 @@ public BigDecimal getBigDecimal(
  }
 
  public byte[] getBytes(String columnLabel) throws SQLException {
- if (false) {
- return new byte[0];
- }
  throw new UnsupportedOperationException();
  }
 

src/mondrian/olap4j/MondrianOlap4jConnection.java

@@ -84,6 +84,7 @@ abstract class MondrianOlap4jConnection implements OlapConnection {
  *
  * @pre acceptsURL(url)
  *
+ * @param factory Factory
  * @param url Connect-string URL
  * @param info Additional properties
  * @throws SQLException if there is an error
@@ -440,13 +441,16 @@ Type[] toOlap4j(mondrian.olap.type.Type[] mondrianTypes) {
  return types;
  }
 
- public Axis toOlap4j(mondrian.olap.AxisOrdinal axisOrdinal) {
- if (false) {
- return null;
- }
+ Axis toOlap4j(mondrian.olap.AxisOrdinal axisOrdinal) {
  throw new UnsupportedOperationException();
  }
 
+ /**
+ * Converts a Properties object to a Map with String keys and values.
+ *
+ * @param properties Properties
+ * @return Map backed by the given Properties object
+ */
  public static Map<String, String> toMap(final Properties properties) {
  return new AbstractMap<String, String>() {
  public Set<Entry<String, String>> entrySet() {
@@ -457,23 +461,57 @@ public Set<Entry<String, String>> entrySet() {
 
  // inner classes
 
+ /**
+ * Package-private helper class which encapsulates policies which are
+ * common throughout the driver. These policies include exception handling
+ * and factory methods.
+ */
  static class Helper {
  SQLException createException(String msg) {
  return new SQLException(msg);
  }
 
+ /**
+ * Creates an exception in the context of a particular Cell.
+ *
+ * @param context Cell context for exception
+ * @param msg Message
+ * @return New exception
+ */
  OlapException createException(Cell context, String msg) {
  OlapException exception = new OlapException(msg);
  exception.setContext(context);
  return exception;
  }
 
- OlapException createException(Cell context, String msg, Throwable cause) {
+ /**
+ * Creates an exception in the context of a particular Cell and with
+ * a given cause.
+ *
+ * @param context Cell context for exception
+ * @param msg Message
+ * @param cause Causing exception
+ * @return New exception
+ */
+ OlapException createException(
+ Cell context, String msg, Throwable cause)
+ {
  OlapException exception = new OlapException(msg, cause);
  exception.setContext(context);
  return exception;
  }
 
+ /**
+ * Converts a SQLException to an OlapException. Casts the exception
+ * if it is already an OlapException, wraps otherwise.
+ *
+ * <p>This method is typically used as an adapter for SQLException
+ * instances coming from a base class, where derived interface declares
+ * that it throws the more specific OlapException.
+ *
+ * @param e Exception
+ * @return Exception as an OlapException
+ */
  public OlapException toOlapException(SQLException e) {
  if (e instanceof OlapException) {
  return (OlapException) e;

src/mondrian/olap4j/MondrianOlap4jLevel.java

@@ -56,58 +56,34 @@ public Dimension getDimension() {
  }
 
  public Type getLevelType() {
- if (false) {
- return null;
- }
  throw new UnsupportedOperationException();
  }
 
  public NamedList<Property> getProperties() {
- if (false) {
- return null;
- }
  throw new UnsupportedOperationException();
  }
 
  public Member findMember(String memberName) {
- if (false) {
- return null;
- }
  throw new UnsupportedOperationException();
  }
 
  public List<Member> getMembers() {
- if (false) {
- return null;
- }
  throw new UnsupportedOperationException();
  }
 
  public String getName() {
- if (false) {
- return null;
- }
  throw new UnsupportedOperationException();
  }
 
  public String getUniqueName() {
- if (false) {
- return null;
- }
  throw new UnsupportedOperationException();
  }
 
  public String getCaption(Locale locale) {
- if (false) {
- return null;
- }
  throw new UnsupportedOperationException();
  }
 
  public String getDescription(Locale locale) {
- if (false) {
- return null;
- }
  throw new UnsupportedOperationException();
  }
 }

src/org/olap4j/CellSetAxis.java

@@ -13,7 +13,20 @@
 import java.util.ListIterator;
 
 /**
- * <code>CellSetAxis</code> ...
+ * Axis of a CellSet.
+ *
+ * <p>A cell set has the same number of axes as the MDX statement which was
+ * executed to produce it. For example, a typical cell set, resulting from an
+ * MDX query with COLUMNS and ROWS expressions is two-dimensional, and
+ * therefore has two axes.</p>
+ *
+ * <p>Each axis is an ordered collection of members or tuples. Each member or
+ * tuple on an axis is called a {@link Position}.</p>
+ *
+ * <p>The positions on the cell set axis can be accessed sequentially or
+ * random-access. Use the {@link #getPositions()} method to return a list for
+ * random access, or the {@link #iterate()} method to obtain an iterator for
+ * sequential access.
  *
  * @author jhyde
  * @version $Id$
@@ -25,12 +38,16 @@ public interface CellSetAxis {
  *
  * <p>0 = ROWS, 1 = COLUMNS, and so forth, as described by the
  * {@link Axis#axisOrdinal()} method of the {@link Axis} enumeration.</p>
+ *
+ * @return the ordinal of this axis
  */
  int getOrdinal();
 
  /**
  * Returns the {@link CellSet} which this <code>CellSetAxis</code>
  * belongs to.
+ *
+ * @return the CellSet
  */
  CellSet getCellSet();
 
@@ -44,6 +61,8 @@ public interface CellSetAxis {
  * getCellSet().getMetaData().getAxesMetaData(getOrdinal())
  * </code>
  * </blockquote>
+ *
+ * @return metadata describing this CellSetAxis
  */
  CellSetAxisMetaData getAxisMetaData();
 
@@ -63,11 +82,15 @@ public interface CellSetAxis {
  *
  * <p>The number of positions on an axis is important when computing the
  * ordinal of a cell.</p>
+ *
+ * @return the number of positions
  */
  int getPositionCount();
 
  /**
- * Opens an iterator on
+ * Opens an iterator over the positions on this CellSetAxis.
+ *
+ * @return iterator over the collection of positions
  */
  ListIterator<Position> iterate();
 

src/org/olap4j/OlapConnection.java

@@ -51,6 +51,9 @@ public interface OlapConnection extends Connection, OlapWrapper {
  * Returns a list of {@link org.olap4j.metadata.Catalog} objects which
  * belong to this connection's OLAP server.
  *
+ * <p>The caller should assume that the list is immutable;
+ * if the caller modifies the list, behavior is undefined.</p>
+ *
  * @see OlapDatabaseMetaData#getCatalogs()
  * @return List of Catalogs in this connection's OLAP server
  */

src/org/olap4j/OlapWrapper.java

@@ -12,7 +12,14 @@
 import java.sql.SQLException;
 
 /**
- * <code>OlapWrapper</code> ...
+ * Interface for olap4j classes which provide the ability to retrieve the
+ * delegate instance when the instance in question is in fact a proxy class.
+ *
+ * <p><code>OlapWrapper</code> duplicates the functionality of the
+ * <code>java.sql.Wrapper</code> interface (introduced in JDBC 4.0), making
+ * this functionality available to olap4j clients running in a JDBC 3.0
+ * environment. For code which will run only on JDBC 4.0 and later, Wrapper can
+ * be used, and OlapWrapper can be ignored.</p>
  *
  * <p>In JDBC 3.0 (JDK 1.5) and earlier, the <code>OlapWrapper</code> interface
  * is used to convert a JDBC class to the corresponding olap4j class. For

src/org/olap4j/driver/xmla/EmptyResultSet.java

@@ -19,7 +19,11 @@
 import java.net.URL;
 
 /**
- * <code>EmptyResultSet</code> ...
+ * Implementation of {@link ResultSet} which returns 0 rows.
+ *
+ * <p>This class is used to implement {@link java.sql.DatabaseMetaData}
+ * methods for querying object types where those object types never have
+ * any instances for this particular driver.</p>
  *
  * @author jhyde
  * @version $Id: EmptyResultSet.java 22 2007-06-15 02:23:07Z jhyde $
@@ -81,9 +85,6 @@ public BigDecimal getBigDecimal(
  }
 
  public byte[] getBytes(int columnIndex) throws SQLException {
- if (false) {
- return new byte[0];
- }
  throw new UnsupportedOperationException();
  }
 
@@ -149,9 +150,6 @@ public BigDecimal getBigDecimal(
  }
 
  public byte[] getBytes(String columnLabel) throws SQLException {
- if (false) {
- return new byte[0];
- }
  throw new UnsupportedOperationException();
  }
 

src/org/olap4j/mdx/ParseRegion.java

@@ -364,10 +364,33 @@ private static String addCarets(
  return sqlWithCarets;
  }
 
+ /**
+ * Combination of a region within an MDX statement with the source text
+ * of the whole MDX statement.
+ *
+ * <p>Useful for reporting errors. For example, the error in the statement
+ *
+ * <blockquote>
+ * <pre>
+ * SELECT {<b><i>[Measures].[Units In Stock]</i></b>} ON COLUMNS
+ * FROM [Sales]
+ * </pre>
+ * </blockquote>
+ *
+ * has source
+ * "SELECT {[Measures].[Units In Stock]} ON COLUMNS\nFROM [Sales]" and
+ * region [1:9, 1:34].
+ */
  public static class RegionAndSource {
  public final String source;
  public final ParseRegion region;
 
+ /**
+ * Creates a RegionAndSource.
+ *
+ * @param source Source MDX code
+ * @param region Coordinates of region within MDX code
+ */
  public RegionAndSource(String source, ParseRegion region) {
  this.source = source;
  this.region = region;