From a3d548027c78571e918adc9a7c909d8ffd9139a3 Mon Sep 17 00:00:00 2001 From: Julian Hyde Date: Thu, 20 Sep 2007 10:46:43 +0000 Subject: [PATCH] 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/olap4j_fs.html | 320 ++++++++++++------ doc/tasks.txt | 24 +- src/mondrian/olap4j/EmptyResultSet.java | 12 +- .../olap4j/MondrianOlap4jConnection.java | 48 ++- src/mondrian/olap4j/MondrianOlap4jLevel.java | 24 -- src/org/olap4j/CellSetAxis.java | 27 +- src/org/olap4j/OlapConnection.java | 3 + src/org/olap4j/OlapWrapper.java | 9 +- .../olap4j/driver/xmla/EmptyResultSet.java | 12 +- src/org/olap4j/mdx/ParseRegion.java | 23 ++ src/org/olap4j/mdx/ParseTreeNode.java | 15 +- src/org/olap4j/mdx/ParseTreeWriter.java | 30 +- src/org/olap4j/metadata/Catalog.java | 18 +- src/org/olap4j/metadata/Cube.java | 20 +- src/org/olap4j/metadata/Dimension.java | 30 +- src/org/olap4j/metadata/Hierarchy.java | 26 +- src/org/olap4j/metadata/Level.java | 15 + src/org/olap4j/metadata/Measure.java | 5 +- src/org/olap4j/metadata/Member.java | 8 + src/org/olap4j/metadata/MetadataElement.java | 12 +- src/org/olap4j/metadata/NamedSet.java | 5 +- src/org/olap4j/metadata/Property.java | 7 + src/org/olap4j/metadata/Schema.java | 22 +- 23 files changed, 528 insertions(+), 187 deletions(-) diff --git a/doc/olap4j_fs.html b/doc/olap4j_fs.html index 29487c8..ed8fb68 100644 --- a/doc/olap4j_fs.html +++ b/doc/olap4j_fs.html @@ -79,7 +79,7 @@

olap4j Functional Specification

Author(s): Julian Hyde, Barry Klawans
-Version: 0.6-dev (draft)
+Version: 0.89.1-dev (draft)
Revision: $Id$ (log)
Last modified: June 10th, 2007.

@@ -113,8 +113,9 @@

Contents

  • Connections
      -
    1. The OlapConnection interface
    2. Connection pooling
      3. +
    3. The OlapConnection interface
      4. +
    4. The OlapWrapper interface
  • Statements
      @@ -123,18 +124,17 @@

      Contents

    1. The OlapParameterMetaData interface
    2. The CellSet interface
    3. The CellSetAxis interface
      4. +
    4. The CellSetAxisMetaData interface
    5. The Position interface
    6. The Cell interface
      7. -
    7. The CellSetMetaData - interface
      8. -
    8. The - OlapDatabaseMetaData interface
      9. -
    9. The CellSetAxis interface
      10. -
    10. The CellSetAxisMetaData - interface
      11. +
    11. The CellSetMetaData interface
      12. +
    12. The OlapDatabaseMetaData interface
      13. +
    +
    • +
  • MDX parse tree model
      +
    1. The ParseTreeWriter class
    • -
  • MDX parse tree model
  • MDX parser
  • MDX type model
  • Metadata
      @@ -465,14 +465,16 @@

      2.2. Connections

      import org.olap4j.*;

      Class.forName("mondrian.olap4j.Driver");
      - OlapConnection connection = (OlapConnection)
      + OlapConnection connection =
          DriverManager.createConnection(
              "jdbc:mondrian:local:Jdbc=jdbc:odbc:MondrianFoodMart;" +
              "Catalog=/WEB-INF/queries/FoodMart.xml;" +
              "Role='California manager'");
      - OlapStatement statement = connection.createOlapStatement();
      + OlapWrapper wrapper = (OlapWrapper) connection;
      + OlapConnection olapConnection = wrapper.unwrap(OlapConnection.class);
      + OlapStatement statement = olapConnection.createOlapStatement();

      OlapResult result =
          statement.execute(
      @@ -487,31 +489,27 @@

      2.2. Connections

      string, the code is identical.

      - import org.olap4j.*;

      Class.forName("olap4j.impl.xmla.Driver");
      OlapConnection connection = (OlapConnection)
          DriverManager.createConnection(
              "jdbc:olap4jxmla:Server=http://localhost/xmla/msxisapi.dll;" - +
              "Catalog=FoodMart");
      OlapStatement statement = connection.createOlapStatement();
      -
      CellSet result =
          statement.execute(
              "SELECT {[Measures].[Unit Sales]} ON + import org.olap4j.*;
      +
      + Class.forName("olap4j.impl.xmla.Driver");
      + OlapConnection connection =
      +     DriverManager.createConnection(
      +         "jdbc:olap4jxmla:Server=http://localhost/xmla/msxisapi.dll;" + +
              "Catalog=FoodMart");
      + OlapWrapper wrapper = (OlapWrapper) connection;
      + OlapConnection olapConnection = wrapper.unwrap(OlapConnection.class);
      + OlapStatement statement = connection.createOlapStatement();
      +
      + CellSet result =
      +     statement.execute(
      +         "SELECT {[Measures].[Unit Sales]} ON COLUMNS,\n" +
              "  {[Product].Members} ON ROWS\n" +
              "FROM [Sales]");

      In the above examples, a statement was created from a string. As we shall see, a statement can also be created from an MDX parse tree.

      -

      Package name: org.olap4j

      - -

      2.2.1. The OlapConnection interface

      - -

      -OlapConnection  (extends - -java.sql.Connection) is a -connection to an OLAP data source.

      -

      -Methods:

      -
        -
      • NamedList<Catalog> getCatalogs()
        • -
      - -

      2.2.2. Connection pooling

      +

      2.2.1. Connection pooling

      Look again at the code samples in the previous section. One would expect that it would be safe to downcast the result of a factory @@ -528,9 +526,44 @@

      2.2.2. Connection pooling

      OlapConnection. To access methods of the OlapConnection, the client application must first strip away the wrapper object.

      -

      If you are using a connection-pooling library, olap4j provides a helper -method unwrap(Class) to access the object underneath a wrapped -connection, statement, prepared statement or result set. For instance,

      +

      If you are using a connection-pooling library, olap4j provides the +OlapWrapper +interface with the method method unwrap(Class) to access the object underneath +the wrapped +connection. For instance,

      + +
      DataSource dataSource; // a data source using a connection + pool
      + Connection connection =
      +    DriverManager.createConnection(
      +        "jdbc:mondrian:local:Jdbc=jdbc:odbc:MondrianFoodMart;" + +
      +        "Catalog=/WEB-INF/queries/FoodMart.xml;" + +
      +        "Role='California manager'");
      + OlapWrapper wrapper = (OlapWrapper) connection;
      + OlapConnection olapConnection = wrapper.unwrap(OlapConnection.class);
      + OlapStatement statement = olapConnection.createOlapStatement();
      + +

      The OlapStatement, +OlapPreparedStatement, +and OlapResult +interfaces also extend OlapWrapper, and can be accessed similarly.

      + +

      If connection pooling is not being used, then the object returned by the +driver will be an OlapConnection and will therefore trivially +implement OlapWrapper (because the OlapConnection +interface extends OlapWrapper). If connection pooling is being +used, the code will work provided that the implementor of the connection pool +has ensured that the pooled connection object implements the OlapWrapper +interface. This is a minor change to the connection pool, and we hope that +popular connection pools will utilize this method in the near future.

      + +

      If you are using JDBC 4.0 (which is part of JDK 1.6 and later), the +java.sql.Connection +class implements the +java.sql.Wrapper interface introduced in JDBC 4.0, +so the code can be simplified:

      DataSource dataSource; // a data source using a connection pool
      @@ -544,10 +577,44 @@

      2.2.2. Connection pooling

      OlapConnection olapConnection = connection.unwrap(OlapConnection.class);
      OlapStatement statement = olapConnection.createOlapStatement();
      -

      The unwrap method is part of the -java.sql.Wrapper interface introduced in JDBC 4.0, but -will also work when olap4j is used with JDBC 3.0. We hope that popular -connection pools will utilize this method in the near future.

      +

      Note that the OlapWrapper interface is not needed. This code +will work with any JDBC 4.0-compliant connection pool.

      + +

      Package name: org.olap4j

      + +

      2.2.2. The OlapConnection interface

      + +

      +OlapConnection (extends + +java.sql.Connection) is a +connection to an OLAP data source.

      +

      +Methods:

      +
        +
      • NamedList<Catalog> getCatalogs()
        • +
      + +

      2.2.3. The OlapWrapper interface

      + +

      +OlapWrapper +provides the ability to retrieve a delegate instance when the instance in +question is in fact a proxy class.

      +

      +OlapWrapper duplicates the functionality of the +java.sql.Wrapper +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.

      +

      +Methods:

      +
        +
      • boolean isWrapper()
        • +
      • T unwrap(Class<T>)
        • +
      +

      2.3. Statements

      2.3.1. The OlapStatement interface

      @@ -616,24 +683,60 @@

      2.3.4. The CellSet interface

      previous CellSet.

      2.3.5. The CellSetAxis interface

      -

      A CellSetAxis is -a ...

      -

      [tbd]

      -

      [access positions by index (i.e. a list) and by scrolling (i.e. an iterator)]

      -

      2.3.6. The Position interface

      -

      Position + +

      A CellSetAxis is +an axis belonging to a CellSet.

      + +

      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.

      + +

      Each axis is an ordered collection of members or tuples. Each member or tuple +on an axis is called a Position.

      + +

      The positions on the cell set axis can be accessed sequentially or +random-access. Use the List<Position> getPositions() method to +return a list for random access, or the Iterator<Position> iterate() +method to obtain an iterator for sequential access.

      + +

      Methods:

      +
        +
      • int getOrdinal()
        • +
      • CellSet getCellSet()
        • +
      • CellSetAxisMetaData getAxisMetaData()
        • +
      • List<Position> getPositions()
        • +
      • int getPositionCount()
        • +
      • ListIterator<Position> iterate()
        • +
      + +

      2.3.6. The CellSetAxisMetaData interface

      + +

      Methods:

      +
        +
      • Axis getAxis()
        • +
      • List<Hierarchy> getHierarchies()
        • +
      • List<Property> getProperties()
        • +
      + +

      2.3.7. The Position interface

      + +

      Position is a position on a CellSetAxis.

      +

      Methods:

      • List<Member> getMembers()
      • int getOrdinal()
      -

      2.3.7. The Cell interface

      -

      A Cell is +

      2.3.8. The Cell interface

      + +

      A Cell is a cell returned from an CellSet.

      +

      Methods:

      -

      2.3.8. The CellSetMetaData interface

      +

      2.3.9. The CellSetMetaData interface

      Extends @@ -661,36 +764,15 @@

      2.3.8. The CellSetMetaData interface
    1. List<CellSetAxisMetaData> getAxesMetaData()
      2. -

      2.3.9. The OlapDatabaseMetaData -interface

      +

      2.3.10. The OlapDatabaseMetaData interface

      Extends java.sql.DatabaseMetaData.

      -

      2.3.10. The CellSetAxis interface

      -

      Methods:

      -
        -
      • int getOrdinal()
        • -
      • CellSet getCellSet()
        • -
      • CellSetAxisMetaData getAxisMetaData()
        • -
      • List<Position> getPositions()
        • -
      • int getPositionCount()
        • -
      • ListIterator<Position> iterate()
        • -
      - -

      2.3.11. The CellSetAxisMetaData -interface

      -

      Methods:

      -
        -
      • Axis getAxis()
        • -
      • List<Hierarchy> getHierarchies()
        • -
      • List<Property> getProperties()
        • -
      -

      2.4. MDX query model

      -

      The MDX query model represents a parsed MDX statement.

      +

      The MDX query model represents a parsed MDX statement.

      An MDX query model can be created in three ways:

      +

      2.4.1 The ParseTreeWriter class

      +

      +ParseTreeWriter is used in conjunction with the + +ParseTreeNode.unparse(ParseTreeWriter) method to convert a parse tree into +MDX code.

      +

      2.5. MDX parser

      Package name: org.olap4j.mdx.parser

      @@ -946,8 +1035,11 @@

      2.7.2. Metadata objects

      IdentityHashMap.

      2.7.2.1. The MetadataElement interface
      -

      -MetadataElement is the base class for Cube, Dimension, Hierarchy, Level, Member, Property; provides +

      A +MetadataElement is an element which describes the structure of an OLAP +schema.

      +

      Subtypes are Cube, Dimension, Hierarchy, Level, Member, Property. +MetadataElement provides name and unique-name properties (not localized), and localized caption and description.

      2.7.2.2. The Catalog interface
      -

      Catalog -is the highest level element in the hierarchy of metadata objects.

      -

      Some OLAP servers may only have one catalog. Mondrian is one such OLAP +

      A Catalog +is the highest level element in the hierarchy of metadata objects. A catalog +contains one or more schemas.

      + +

      Some OLAP servers may only have one catalog. Mondrian is one such OLAP server; its sole catalog is always called "LOCALDB".

      +

      To obtain the collection of catalogs in the current server, call the OlapConnection.getCatalogs() method.

      +

      Methods:

      • String getName()
      • NamedList<Schema> getSchemas()
        • +
      • OlapDatabaseMetaData getMetaData()
      +
      2.7.2.3. The Schema interface
      -

      Schema ...

      + +

      A Schema is +a collection of database objects that contain structural information, or +metadata, about a database.

      + +

      It belongs to a catalog and contains a number of cubes and shared dimensions.

      +
      2.7.2.4. The Cube interface
      -

      Cube ...

      + +

      A Cube is the +central metadata object for representing multidimensional data.

      + +

      It belongs to a schema, and is described by a list of dimensions and a list +of measures. It may also have a collection of named sets, each defined by a +formula.

      +
      • List<Dimension> getDimensions()
        • +
      • List<Measure> getMeasures()
        • +
      • NamedList<NamedSet> getSets();
      • Schema getSchema()
      • String getName()
      • getSupportedLocales() (see Internationalization)
      +
      2.7.2.5. The Dimension interface
      -

      Dimension + +

      A Dimension (extends -MetadataElement)

      +MetadataElement) is an organized hierarchy of categories, known as levels, +that describes data in a cube.

      +

      Dimensions typically describe a similar set of members upon which the user +wants to base an analysis.

      +

      A dimension must have at least one hierarchy, and may have more than once, +but most have exactly one hierarchy.

      +
      • String getName()
      • List<Hierarchy> getHierarchies()
        • @@ -997,10 +1118,12 @@
        2.7.2.5. The Dimension interface
      • Dimension.Type getDimensionType()
      2.7.2.6. The Hierarchy interface
      -

      Hierarchy  +

      A Hierarchy  (extends -MetadataElement) -...

      +MetadataElement) is an organization of the set of members in a dimension and +their positions relative to one another.

      +

      A hierarchy is a collection of levels, each of which is a category of similar +members.

      • Dimension getDimension()
      • String getName()
        • @@ -1009,19 +1132,22 @@
        2.7.2.6. The Hierarchy interface
      • Member getDefaultMember()
      2.7.2.7. The Level interface
      -

      Level  +

      A Level  (extends -MetadataElement) ...

      +MetadataElement) is a group of members in a hierarchy, all with the same +attributes and at the same depth in the hierarchy.

      • int getDepth()
      • Hierarchy getHierarchy()
      • Level.Type getLevelType()
      • List<Property> getProperties()
        • +
      • List<Member> getMembers()
        • +
      • Member findMember(String name)
      2.7.2.8. The Member interface
      -

      Member  +

      A Member  (extends -MetadataElement) ...

      +MetadataElement) is a data value in an OLAP dimension.

      • String getName()
      • List<Member> getChildMembers()
        • @@ -1042,17 +1168,17 @@
        2.7.2.8. The Member interface
      • Member getDataMember()
      2.7.2.9. The Measure interface
      -

      Measure  -(extends -MetadataElement) ...

      -
        -
      • extends Member
        • -
      + +

      A Measure (extends +Member) is a +data value of primary interest to the user browsing the cube. It provides the +value of each cell, and is usually numeric.

      + +

      Every measure is a member of a special dimension called "Measures".

      2.7.2.10. The Property interface

      Property  (extends -MetadataElement) -...

      +MetadataElement) is the definition of a property of a member or a cell.

      • Datatype getType()
      • Scope getScope()
        • @@ -1065,10 +1191,10 @@
        2.7.2.10. The Property interface
      • enum StandardCellProperty { BACK_COLOR, CELL_EVALUATION_LIST, ... }
      2.7.2.11. The NamedSet interface
      -

      NamedSet +

      A NamedSet (extends -MetadataElement) -...

      +MetadataElement) describes a set whose value is determined by an MDX +expression. It belongs to a cube.

      • Cube getCube()
      diff --git a/doc/tasks.txt b/doc/tasks.txt index 342c7a2..1044f99 100644 --- a/doc/tasks.txt +++ b/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 diff --git a/src/mondrian/olap4j/EmptyResultSet.java b/src/mondrian/olap4j/EmptyResultSet.java index ffc0e38..1db9c77 100644 --- a/src/mondrian/olap4j/EmptyResultSet.java +++ b/src/mondrian/olap4j/EmptyResultSet.java @@ -20,7 +20,11 @@ import java.net.URL; /** - * EmptyResultSet ... + * Implementation of {@link ResultSet} which returns 0 rows. + * + *

      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.

      * * @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(); } diff --git a/src/mondrian/olap4j/MondrianOlap4jConnection.java b/src/mondrian/olap4j/MondrianOlap4jConnection.java index 521e471..8e87d5e 100644 --- a/src/mondrian/olap4j/MondrianOlap4jConnection.java +++ b/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 toMap(final Properties properties) { return new AbstractMap() { public Set> entrySet() { @@ -457,23 +461,57 @@ public Set> 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. + * + *

      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; diff --git a/src/mondrian/olap4j/MondrianOlap4jLevel.java b/src/mondrian/olap4j/MondrianOlap4jLevel.java index 225c922..8e39c2d 100644 --- a/src/mondrian/olap4j/MondrianOlap4jLevel.java +++ b/src/mondrian/olap4j/MondrianOlap4jLevel.java @@ -56,58 +56,34 @@ public Dimension getDimension() { } public Type getLevelType() { - if (false) { - return null; - } throw new UnsupportedOperationException(); } public NamedList getProperties() { - if (false) { - return null; - } throw new UnsupportedOperationException(); } public Member findMember(String memberName) { - if (false) { - return null; - } throw new UnsupportedOperationException(); } public List 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(); } } diff --git a/src/org/olap4j/CellSetAxis.java b/src/org/olap4j/CellSetAxis.java index a7dc348..d67f25d 100755 --- a/src/org/olap4j/CellSetAxis.java +++ b/src/org/olap4j/CellSetAxis.java @@ -13,7 +13,20 @@ import java.util.ListIterator; /** - * CellSetAxis ... + * Axis of a CellSet. + * + *

      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.

      + * + *

      Each axis is an ordered collection of members or tuples. Each member or + * tuple on an axis is called a {@link Position}.

      + * + *

      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 { * *

      0 = ROWS, 1 = COLUMNS, and so forth, as described by the * {@link Axis#axisOrdinal()} method of the {@link Axis} enumeration.

      + * + * @return the ordinal of this axis */ int getOrdinal(); /** * Returns the {@link CellSet} which this CellSetAxis * belongs to. + * + * @return the CellSet */ CellSet getCellSet(); @@ -44,6 +61,8 @@ public interface CellSetAxis { * getCellSet().getMetaData().getAxesMetaData(getOrdinal()) * * + * + * @return metadata describing this CellSetAxis */ CellSetAxisMetaData getAxisMetaData(); @@ -63,11 +82,15 @@ public interface CellSetAxis { * *

      The number of positions on an axis is important when computing the * ordinal of a cell.

      + * + * @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 iterate(); diff --git a/src/org/olap4j/OlapConnection.java b/src/org/olap4j/OlapConnection.java index ebc1d0c..faf89c4 100644 --- a/src/org/olap4j/OlapConnection.java +++ b/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. * + *

      The caller should assume that the list is immutable; + * if the caller modifies the list, behavior is undefined.

      + * * @see OlapDatabaseMetaData#getCatalogs() * @return List of Catalogs in this connection's OLAP server */ diff --git a/src/org/olap4j/OlapWrapper.java b/src/org/olap4j/OlapWrapper.java index caecccc..b5703ad 100644 --- a/src/org/olap4j/OlapWrapper.java +++ b/src/org/olap4j/OlapWrapper.java @@ -12,7 +12,14 @@ import java.sql.SQLException; /** - * OlapWrapper ... + * Interface for olap4j classes which provide the ability to retrieve the + * delegate instance when the instance in question is in fact a proxy class. + * + *

      OlapWrapper duplicates the functionality of the + * java.sql.Wrapper 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.

      * *

      In JDBC 3.0 (JDK 1.5) and earlier, the OlapWrapper interface * is used to convert a JDBC class to the corresponding olap4j class. For diff --git a/src/org/olap4j/driver/xmla/EmptyResultSet.java b/src/org/olap4j/driver/xmla/EmptyResultSet.java index 2ae704a..124d355 100644 --- a/src/org/olap4j/driver/xmla/EmptyResultSet.java +++ b/src/org/olap4j/driver/xmla/EmptyResultSet.java @@ -19,7 +19,11 @@ import java.net.URL; /** - * EmptyResultSet ... + * Implementation of {@link ResultSet} which returns 0 rows. + * + *

      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.

      * * @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(); } diff --git a/src/org/olap4j/mdx/ParseRegion.java b/src/org/olap4j/mdx/ParseRegion.java index 51c8de3..3c5d960 100644 --- a/src/org/olap4j/mdx/ParseRegion.java +++ b/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. + * + *

      Useful for reporting errors. For example, the error in the statement + * + *

      + * 
      +     * SELECT {[Measures].[Units In Stock]} ON COLUMNS
+     * FROM [Sales]
+     *
      + *
      + * + * 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; diff --git a/src/org/olap4j/mdx/ParseTreeNode.java b/src/org/olap4j/mdx/ParseTreeNode.java index 2ae2986..a272473 100644 --- a/src/org/olap4j/mdx/ParseTreeNode.java +++ b/src/org/olap4j/mdx/ParseTreeNode.java @@ -14,19 +14,8 @@ /** * Node in a parse tree representing a parsed MDX statement. * - *

      To convert a parse tree to an MDX string, use a {@link ParseTreeWriter} as - * follows: - *

      - * 
      - * ParseTreeNode node;
- * StringWriter sw = new StringWriter();
- * PrintWriter pw = new PrintWriter(sw);
- * ParseTreeWriter mdxWriter = new ParseTreeWriter(pw);
- * node.unparse(mdxWriter);
- * pw.flush();
- * String mdx = sw.toString();
- *
      - *
      + *

      To convert a parse tree to an MDX string, use a {@link ParseTreeWriter} + * and the {@link #unparse(ParseTreeWriter)} method. * * @author jhyde * @version $Id$ diff --git a/src/org/olap4j/mdx/ParseTreeWriter.java b/src/org/olap4j/mdx/ParseTreeWriter.java index b982a55..f4ea2d5 100644 --- a/src/org/olap4j/mdx/ParseTreeWriter.java +++ b/src/org/olap4j/mdx/ParseTreeWriter.java @@ -12,7 +12,25 @@ import java.io.PrintWriter; /** - * ParseTreeWriter ... + * Writer for MDX parse tree. + * + *

      Typical use is with the {@link ParseTreeNode#unparse(ParseTreeWriter)} + * method as follows: + * + *

      + * 
      + * ParseTreeNode node;
+ * StringWriter sw = new StringWriter();
+ * PrintWriter pw = new PrintWriter(sw);
+ * ParseTreeWriter mdxWriter = new ParseTreeWriter(pw);
+ * node.unparse(mdxWriter);
+ * pw.flush();
+ * String mdx = sw.toString();
+ *
      + *
      + * + * + * @see org.olap4j.mdx.ParseTreeNode#unparse(ParseTreeWriter) * * @author jhyde * @version $Id$ @@ -21,10 +39,20 @@ public class ParseTreeWriter { private final PrintWriter pw; + /** + * Creates a ParseTreeWriter. + * + * @param pw Underlying writer + */ public ParseTreeWriter(PrintWriter pw) { this.pw = pw; } + /** + * Returns the underlying writer. + * + * @return underlying writer + */ public PrintWriter getPrintWriter() { return pw; } diff --git a/src/org/olap4j/metadata/Catalog.java b/src/org/olap4j/metadata/Catalog.java index 4c6b097..62313e4 100644 --- a/src/org/olap4j/metadata/Catalog.java +++ b/src/org/olap4j/metadata/Catalog.java @@ -13,10 +13,18 @@ import org.olap4j.OlapDatabaseMetaData; /** - * Catalog ... + * Highest level element in the hierarchy of metadata objects. * - * A Catalog is the root object in the hierarchy of metadata - * objects: + *

      A Catalog contains one or more {@link Schema}s.

      + * + *

      Some OLAP servers may only have one Catalog. Mondrian is one such + * OLAP server; its sole catalog is called "LOCALDB". + * + *

      To obtain the collection of catalogs in the current server, call the + * {@link org.olap4j.OlapConnection#getCatalogs()} method. + * + *

      The hierarchy of metadata objects, rooted at the connection from which + * they are accessed, is as follows: *

      *
        *
      • {@link org.olap4j.OlapConnection}
          @@ -38,6 +46,7 @@ *
        • *
      *
      + *

      * * @author jhyde * @version $Id$ @@ -48,6 +57,9 @@ public interface Catalog { * Returns a list of {@link Schema} objects which belong to * this Catalog. * + *

      The caller should assume that the list is immutable; + * if the caller modifies the list, behavior is undefined.

      + * * @see org.olap4j.OlapDatabaseMetaData#getSchemas * @return List of Schema in this Catalog * @throws OlapException if error occurs diff --git a/src/org/olap4j/metadata/Cube.java b/src/org/olap4j/metadata/Cube.java index 5259580..92483a0 100644 --- a/src/org/olap4j/metadata/Cube.java +++ b/src/org/olap4j/metadata/Cube.java @@ -14,7 +14,11 @@ import java.util.Collection; /** - * Cube ... + * Central metadata object for representation of multidimensional data. + * + *

      A Cube belongs to a {@link Schema}, and is described by a list of + * {@link Dimension}s and a list of {@link Measure}s. It may also have one or + * more {@link NamedSet}s. * * @author jhyde * @version $Id$ @@ -23,13 +27,20 @@ public interface Cube extends MetadataElement { /** * Returns the {@link Schema} this Cube belongs to. + * + * @return Schema this Cube belongs to */ Schema getSchema(); /** * Returns a list of {@link Dimension} objects in this Cube. * + *

      The caller should assume that the list is immutable; + * if the caller modifies the list, behavior is undefined.

      + * * @see org.olap4j.OlapDatabaseMetaData#getDimensions() + * + * @return list of Dimensions */ NamedList getDimensions(); @@ -37,13 +48,20 @@ public interface Cube extends MetadataElement { * Returns a list of {@link Measure} objects in this Cube. * * @see org.olap4j.OlapDatabaseMetaData#getMeasures() + * + * @return list of Measures */ List getMeasures(); /** * Returns a list of {@link NamedSet} objects in this Cube. * + *

      The caller should assume that the list is immutable; + * if the caller modifies the list, behavior is undefined.

      + * * @see org.olap4j.OlapDatabaseMetaData#getSets() + * + * @return list of NamedSets */ NamedList getSets(); diff --git a/src/org/olap4j/metadata/Dimension.java b/src/org/olap4j/metadata/Dimension.java index 4c76dff..57d8bb0 100644 --- a/src/org/olap4j/metadata/Dimension.java +++ b/src/org/olap4j/metadata/Dimension.java @@ -12,7 +12,14 @@ import org.olap4j.OlapException; /** - * Dimension ... + * An organized hierarchy of categories, known as levels, that describes data + * in a cube. + * + *

      A Dimension typically describes a similar set of members upon which the + * user wants to base an analysis. + * + *

      A Dimension must have at least one Hierarchy, and may have more than one, + * but most have exactly one Hierarchy.

      * * @author jhyde * @version $Id$ @@ -26,7 +33,12 @@ public interface Dimension extends MetadataElement { *

      Many dimensions have only one Hierarchy, whose name is the same as the * Dimension. * + *

      The caller should assume that the list is immutable; + * if the caller modifies the list, behavior is undefined.

      + * * @see org.olap4j.OlapDatabaseMetaData#getHierarchies + * + * @return hierarchies in this dimension */ NamedList getHierarchies(); @@ -35,14 +47,30 @@ public interface Dimension extends MetadataElement { * *

      If the dimension has an 'all' member, then this will be the sole * root member. + * + *

      The caller should assume that the list is immutable; + * if the caller modifies the list, behavior is undefined.

      + * + * @return root members of this hierarchy + * + * @throws OlapException if database error occurs */ NamedList getRootMembers() throws OlapException; /** * Returns the type of this Dimension. + * + * @return dimension type + * + * @throws OlapException if database error occurs */ Dimension.Type getDimensionType() throws OlapException; + /** + * Returns the default Hierarchy of this Dimension. + * + * @return default hierarchy + */ Hierarchy getDefaultHierarchy(); /** diff --git a/src/org/olap4j/metadata/Hierarchy.java b/src/org/olap4j/metadata/Hierarchy.java index 5054586..1c9c55d 100644 --- a/src/org/olap4j/metadata/Hierarchy.java +++ b/src/org/olap4j/metadata/Hierarchy.java @@ -10,7 +10,14 @@ package org.olap4j.metadata; /** - * Hierarchy ... + * An organization of the set of {@link Member}s in a {@link Dimension} and + * their positions relative to one another. + * + *

      A Hierarchy is a collection of {@link Level}s, each of which is a + * category of similar {@link Member}s.

      + * + *

      A Dimension must have at least one Hierarchy, and may have more than one, + * but most have exactly one Hierarchy.

      * * @author jhyde * @version $Id$ @@ -19,6 +26,8 @@ public interface Hierarchy extends MetadataElement { /** * Returns the {@link Dimension} this Hierarchy belongs to. + * + * @return dimension this hierarchy belongs to */ Dimension getDimension(); @@ -26,15 +35,30 @@ public interface Hierarchy extends MetadataElement { * Returns a list of the {@link Level} objects in this * Hierarchy. * + *

      The caller should assume that the list is immutable; + * if the caller modifies the list, behavior is undefined.

      + * * @see org.olap4j.OlapDatabaseMetaData#getLevels + * + * @return list of levels */ NamedList getLevels(); /** * Returns whether this Hierarchy has an 'all' member. + * + * @return whether this hierarchy has an 'all' member */ boolean hasAll(); + /** + * Returns the default {@link Member} of this Hierarchy. + * + *

      If the hierarchy has an 'all' member, this member is often the + * default. + * + * @return the default member of this hierarchy + */ Member getDefaultMember(); } diff --git a/src/org/olap4j/metadata/Level.java b/src/org/olap4j/metadata/Level.java index 0f40169..7c57dab 100644 --- a/src/org/olap4j/metadata/Level.java +++ b/src/org/olap4j/metadata/Level.java @@ -28,22 +28,30 @@ public interface Level extends MetadataElement { * *

      Note #2: In a parent-child hierarchy, the depth of a member (as * returned by may not be the same as the depth of its level. + * + * @return depth of this level */ int getDepth(); /** * Returns the {@link Hierarchy} this Level belongs to. + * + * @return hierarchy this level belongs to */ Hierarchy getHierarchy(); /** * Returns the Dimension this Level belongs to. * (Always equivalent to getHierarchy().getDimension().) + * + * @return dimension this level belongs to */ Dimension getDimension(); /** * Returns the type of this Level. + * + * @return level type */ Level.Type getLevelType(); @@ -51,7 +59,12 @@ public interface Level extends MetadataElement { * Returns a list of definitions for the properties available to members * of this Level. * + *

      The caller should assume that the list is immutable; + * if the caller modifies the list, behavior is undefined.

      + * * @see org.olap4j.OlapDatabaseMetaData#getProperties() + * + * @return properties of this level */ NamedList getProperties(); @@ -130,6 +143,8 @@ private Type(boolean time) { * Returns whether this is a time-related level * ({@link #TimeYears}, {@link #TimeQuarters}, {@link #TimeMonths}, * {@link #TimeWeeks}, {@link #TimeDays}). + * + * @return whether this is a time-related level */ public boolean isTime() { return time; diff --git a/src/org/olap4j/metadata/Measure.java b/src/org/olap4j/metadata/Measure.java index 73eec5b..48d797d 100644 --- a/src/org/olap4j/metadata/Measure.java +++ b/src/org/olap4j/metadata/Measure.java @@ -10,7 +10,10 @@ package org.olap4j.metadata; /** - * Measure ... + * Data value of primary interest to the user browsing the cube. + * + *

      A Measure provides the value of each cell, and is usually + * numeric. Every measure is a member of a special dimension called "Measures". * * @author jhyde * @version $Id$ diff --git a/src/org/olap4j/metadata/Member.java b/src/org/olap4j/metadata/Member.java index ea14fdf..c2131ca 100644 --- a/src/org/olap4j/metadata/Member.java +++ b/src/org/olap4j/metadata/Member.java @@ -28,7 +28,15 @@ public interface Member extends MetadataElement { *

      If access-control is in place, the list does not contain inaccessible * children. * + *

      If the member has no children, returns an empty list: the result is + * never null. + * + *

      The caller should assume that the list is immutable; + * if the caller modifies the list, behavior is undefined.

      + * * @see org.olap4j.OlapDatabaseMetaData#getMembers() + * + * @return children of this member */ NamedList getChildMembers(); diff --git a/src/org/olap4j/metadata/MetadataElement.java b/src/org/olap4j/metadata/MetadataElement.java index 2f9523e..3b9f240 100644 --- a/src/org/olap4j/metadata/MetadataElement.java +++ b/src/org/olap4j/metadata/MetadataElement.java @@ -12,15 +12,25 @@ import java.util.Locale; /** - * Common interface for + * An element which describes the structure of an OLAP schema. * * @author jhyde * @version $Id$ * @since Oct 13, 2006 */ public interface MetadataElement { + /** + * Returns the name of this element. + * + * @return name + */ String getName(); + /** + * Returns the unique name of this element within its schema. + * + * @return unique name of this element + */ String getUniqueName(); /** diff --git a/src/org/olap4j/metadata/NamedSet.java b/src/org/olap4j/metadata/NamedSet.java index 5f21298..176a272 100644 --- a/src/org/olap4j/metadata/NamedSet.java +++ b/src/org/olap4j/metadata/NamedSet.java @@ -18,7 +18,10 @@ */ public interface NamedSet extends MetadataElement { /** - * Returns the Cube that this NamedSet belongs to. + * Returns the Cube that this NamedSet belongs + * to. + * + * @return cube this named set belongs to */ Cube getCube(); } diff --git a/src/org/olap4j/metadata/Property.java b/src/org/olap4j/metadata/Property.java index d4f7ccb..939fbad 100644 --- a/src/org/olap4j/metadata/Property.java +++ b/src/org/olap4j/metadata/Property.java @@ -36,11 +36,18 @@ public interface Property extends MetadataElement { boolean isInternal(); + /** + * Enumeration of the scope of a Property: whether it belongs to a member + * or a cell. + */ enum Scope { MEMBER, CELL } + /** + * Enumeration of the allowable data types of a Property. + */ enum Datatype { TYPE_STRING, TYPE_OTHER, diff --git a/src/org/olap4j/metadata/Schema.java b/src/org/olap4j/metadata/Schema.java index ea9b5a4..aa106b8 100644 --- a/src/org/olap4j/metadata/Schema.java +++ b/src/org/olap4j/metadata/Schema.java @@ -15,7 +15,11 @@ import org.olap4j.OlapException; /** - * Schema ... + * A collection of database objects that contain structural information, or + * metadata, about a database. + * + *

      A Schema belongs to a {@link Catalog} and contains a number of + * {@link Cube}s and shared {@link Dimension}s. * * @author jhyde * @version $Id$ @@ -24,6 +28,8 @@ public interface Schema { /** * Returns the {@link Catalog} this Schema belongs to. + * + * @return catalog this schema belongs to */ Catalog getCatalog(); @@ -37,8 +43,13 @@ public interface Schema { /** * Returns a list of cubes in this Schema. * + *

      The caller should assume that the list is immutable; + * if the caller modifies the list, behavior is undefined.

      + * * @see org.olap4j.OlapDatabaseMetaData#getCubes * @return List of cubes in this Schema + * + * @throws OlapException if database error occurs */ NamedList getCubes() throws OlapException; @@ -46,7 +57,14 @@ public interface Schema { * Returns a list of shared {@link Dimension} objects in this * Schema. * + *

      The caller should assume that the list is immutable; + * if the caller modifies the list, behavior is undefined.

      + * * @see org.olap4j.OlapDatabaseMetaData#getDimensions() + * + * @return list of shared dimensions + * + * @throws OlapException if database error occurs */ NamedList getSharedDimensions() throws OlapException; @@ -69,6 +87,8 @@ public interface Schema { * * @return List of locales for which this Schema has been * localized + * + * @throws OlapException if database error occurs */ Collection getSupportedLocales() throws OlapException; }