From 6308b288845e0d64f76ed90f6eed4b2f84035799 Mon Sep 17 00:00:00 2001 From: Julian Hyde Date: Sun, 10 Apr 2011 00:57:09 +0000 Subject: [PATCH] Revise functional specification (including PDF version) for release 1.0. Add spacer image (website was broken without it). Minor javadoc tweaks, and remove an obsolete method. git-svn-id: https://olap4j.svn.sourceforge.net/svnroot/olap4j/trunk@439 c6a108a4-781c-0410-a6c6-c2d559e19af0 --- doc/images/spacer.png | Bin 0 -> 188 bytes doc/olap4j_fs.html | 5702 +++++++++-------- doc/olap4j_fs.pdf | Bin 482505 -> 654846 bytes .../xmla/XmlaOlap4jDatabaseMetaData.java | 4 - src/org/olap4j/metadata/Database.java | 19 +- 5 files changed, 3032 insertions(+), 2693 deletions(-) create mode 100644 doc/images/spacer.png diff --git a/doc/images/spacer.png b/doc/images/spacer.png new file mode 100644 index 0000000000000000000000000000000000000000..55e77fcf6624f7e037428eef1e687ba22c2b17ce GIT binary patch literal 188 zcmeAS@N?(olHy`uVBq!ia0vp^5oPhp7+$ literal 0 HcmV?d00001 diff --git a/doc/olap4j_fs.html b/doc/olap4j_fs.html index bdaad23..c410279 100644 --- a/doc/olap4j_fs.html +++ b/doc/olap4j_fs.html @@ -1,8 +1,9 @@ + - -olap4j Specification + +olap4j Specification - - +

olap4j Specification

-

Authors: Julian Hyde, Barry Klawans
-Version: 0.9.7 (beta)
+

Authors: Julian Hyde, Barry Klawans
+Version: 1.0
Revision: $Id$ -(log)
-Last modified: June 25th, 2009.

-
+(log)
+Last modified: April 9th, 2011.

+

Contents

    -
  1. Introduction
      -
    1. A brief history of OLAP - standards
      2. -
    2. Overview of olap4j
      3. -
    3. Relationship to other standards
        -
      1. olap4j and XML/A
        2. -
      2. olap4j is built on - other standards
        3. -
      -
      4. -
    4. Benefits of a - standard Java API for OLAP
      5. -
    5. Architecture of olap4j
      6. -
    6. Compatibility
      7. -
    7. Compliance levels
      8. -
    -
    2. -
  2. Components of the API
      -
    1. Driver management
        -
      1. The Driver class
        2. -
      2. The DriverManager class
        3. -
      3. The DataSource interface
        4. -
      4. The OlapDataSource interface
        5. -
      5. The OlapException class
        6. -
      -
      2. -
    2. Connections
        -
      1. Connection pooling
        2. -
      2. The OlapConnection interface
        3. -
      3. The OlapWrapper interface
        4. -
      4. The OlapDatabaseMetaData interface
        5. -
      3. -
    3. Statements
        -
      1. The OlapStatement interface
        2. -
      2. The PreparedOlapStatement interface
        3. -
      3. The OlapParameterMetaData interface
        4. -
      4. The CellSet interface
        5. -
      5. The CellSetAxis interface
        6. -
      6. The Axis enum
        7. -
      7. The CellSetAxisMetaData interface
        8. -
      8. The Position interface
        9. -
      9. The Cell interface
        10. -
      10. The CellSetMetaData interface
        11. -
      4. -
    4. MDX parse tree model
        -
      1. The ParseTreeWriter class
        2. -
      5. -
    5. MDX parser
      6. -
    6. MDX type model
      7. -
    7. Metadata
        -
      1. Access control
        2. -
      2. Metadata objects
          -
        1. The MetadataElement interface
          2. -
        2. The Catalog interface
          3. -
        3. The Schema interface
          4. -
        4. The Cube interface
          5. -
        5. The Dimension interface
          6. -
        6. The Hierarchy interface
          7. -
        7. The Level interface
          8. -
        8. The Member interface
          9. -
        9. The Measure interface
          10. -
        10. The Property interface
          11. -
        11. The NamedSet interface
          12. -
        12. The Datatype enum
          13. -
        3. -
      3. - The OlapDatabaseMetaData interface, and schema result sets
          -
        1. The getDatasources method
          2. -
        2. The getDatabaseProperties method
          3. -
        3. The getLiterals method
          4. -
        4. The getCubes method
          5. -
        5. The getDimensions method
          6. -
        6. The getFunctions method
          7. -
        7. The getHierarchies method
          8. -
        8. The getLevels method
          9. -
        9. The getMeasures method
          10. -
        10. The getMembers method
          11. -
        11. The getProperties method
          12. -
        12. The getSets method
          13. -
        4. -
      4. Other methods
        5. -
      8. -
    8. Transform
      9. -
        -
      1. Query model details
        2. -
      2. Navigation actions
        3. -
          -
        1. Slicing navigations
          2. -
        2. Restructuring navigations
          3. -
        3. Drilling navigations
          4. -
        4. Scoping navigations
          5. -
        -
      3. Open issues
        4. -
      -
    9. Layout
      10. -
    -
    3. -
  3. Other topics
      -
    1. Internationalization
      2. -
    2. Concurrency and thread-safety
      3. -
    3. Canceling statements
      4. -
    -
    4. -
  4. Other components
      -
    1. Test suite
      2. -
    2. XML/A provider
      3. -
    -
    5. -
  5. Non-functionality
    6. -
  6. Related projects
      -
    1. Mondrian provider
      2. -
    2. XML for Analysis provider
      3. -
    3. Other data sources
      4. -
    -
    7. -
  7. Appendix A. Opportunities for - specification
    8. -
  8. Appendix B. Feedback
    9. -
  9. Appendix C. Open issues
    10. -
  10. Appendix D. Miscellaneous
    11. -
  11. Appendix E. References
    12. -
  12. Appendix F. Change log
    13. + +
  13. Introduction +
      +
    1. A brief history +of OLAP standards
      2. +
    2. Overview of olap4j
      3. +
    3. Relationship to +other standards +
        +
      1. olap4j and XML/A
        2. +
      2. olap4j is +built on other standards
        3. +
      +
      4. +
    4. Benefits +of a standard Java API for OLAP
      5. +
    5. Architecture of olap4j
      6. +
    6. Compatibility
      7. +
    7. Compliance levels
      8. +
    +
    14. +
  14. Components of the API +
      +
    1. Driver management +
        +
      1. The Driver class
        2. +
      2. The DriverManager class
        3. +
      3. The DataSource +interface
        4. +
      4. The +OlapDataSource interface
        5. +
      5. The OlapException class
        6. +
      +
      2. +
    2. Connections +
        +
      1. Connection pooling
        2. +
      2. The OlapConnection interface
        3. +
      3. The OlapWrapper +interface
        4. +
      4. The +OlapDatabaseMetaData interface
        5. +
      +
      3. +
    3. Statements +
        +
      1. The OlapStatement interface
        2. +
      2. The +PreparedOlapStatement interface
        3. +
      3. The +OlapParameterMetaData interface
        4. +
      4. The CellSet interface
        5. +
      5. The CellSetAxis interface
        6. +
      6. The Axis enum
        7. +
      7. The +CellSetAxisMetaData interface
        8. +
      8. The Position interface
        9. +
      9. The Cell interface
        10. +
      10. The +CellSetMetaData interface
        11. +
      +
      4. +
    4. MDX parse tree model +
        +
      1. The ParseTreeWriter +class
        2. +
      +
      5. +
    5. MDX parser
      6. +
    6. MDX type model
      7. +
    7. Metadata +
        +
      1. Access control
        2. +
      2. Metadata objects +
          +
        1. The MetadataElement +interface
          2. +
        2. The Database interface
          3. +
        3. The Catalog interface
          4. +
        4. The Schema interface
          5. +
        5. The Cube interface
          6. +
        6. The Dimension interface
          7. +
        7. The Hierarchy interface
          8. +
        8. The Level interface
          9. +
        9. The Member interface
          10. +
        10. The Measure interface
          11. +
        11. The Property interface
          12. +
        12. The NamedSet interface
          13. +
        13. The Datatype enum
          14. +
        +
        3. +
      3. The +OlapDatabaseMetaData interface, and schema result sets +
          +
        1. The getDatabases method
          2. +
        2. The +getDatabaseProperties method
          3. +
        3. The getLiterals method
          4. +
        4. The getCubes method
          5. +
        5. The getDimensions method
          6. +
        6. The getFunctions method
          7. +
        7. The getHierarchies method
          8. +
        8. The getLevels method
          9. +
        9. The getMeasures method
          10. +
        10. The getMembers method
          11. +
        11. The getProperties method
          12. +
        12. The getSets method
          13. +
        +
        4. +
      4. Other methods
        5. +
      +
      8. +
    8. Transform +
        +
      1. Query model details
        2. +
      2. Navigation actions +
          +
        1. Slicing navigations
          2. +
        2. Restructuring +navigations
          3. +
        3. Drilling navigations
          4. +
        4. Scoping navigations
          5. +
        +
        3. +
      3. Open issues
        4. +
      +
      9. +
    9. Layout
      10. +
    10. Scenarios
      11. +
    11. Notifications
      12. +
    12. Drill through
      13. +
    +
    15. +
  15. Other topics +
      +
    1. Internationalization
      2. +
    2. Concurrency and +thread-safety
      3. +
    3. Canceling statements
      4. +
    +
    16. +
  16. Other components +
      +
    1. Test suite
      2. +
    2. XML/A provider
      3. +
    +
    17. +
  17. Non-functionality
    18. +
  18. Related projects +
      +
    1. Mondrian provider
      2. +
    2. XML for Analysis provider
      3. +
    3. Other data sources
      4. +
    +
    19. +
  19. Appendix A. +Opportunities for specification
    20. +
  20. Appendix B. Feedback
    21. +
  21. Appendix C. Open issues
    22. +
  22. Appendix D. Miscellaneous
    23. +
  23. Appendix E. References
    24. +
  24. Appendix F. Change log
+

1. Introduction

olap4j is an open Java API for building OLAP applications.

@@ -291,9 +331,15 @@

1.2. Overview of olap4j

higher-level query model, which includes operations to transform queries (also called 'navigations'), and facilities to layout multidimensional results as HTML tables.

-

1.3. Relationship to other standards

+

There are experimental modules in olap4j for scenarios (also +called 'what-if' analysis, or 'writeback') and notifications, +pushed from the server to the client when the data set on the server +changes.

+ +

1.3. Relationship to +other standards

-

1.3.1. olap4j and XML/A

+

1.3.1. olap4j and XML/A

At this point, you may be saying: what about XML/A? XML/A was here first, is an open standard, and is supported by a number of servers. Is olap4j an attempt to @@ -320,7 +366,16 @@

1.3.1. olap4j and XML/A

XML/A provider to connect to the underlying data source, execute queries, and browse metadata, but can still use olap4j's features for MDX parsing, query models and layout.

-

1.3.2. olap4j is built on other + +

The metamodels of olap4j and XML/A are similar. Both contain +schemas, cubes, dimensions, et cetera. Where possible, olap4j uses the +same terminology for entity and attribute names. This simplifies the +job of creating an XML/A driver for olap4j, and also makes possible an +XML/A -to-olap4j bridge (a server that answers XML/A requests by +querying an underlying olap4j data source).

+ +

1.3.2. olap4j is +built on other standards

Where possible, olap4j leverages existing standards. This has several advantages. First, an end-user familiar with the existing standards can come up @@ -375,13 +430,14 @@

1.6. Compatibility

olap4j requires JDK 1.5 or higher, in particular because it uses the generics and enum features introduced in JDK 1.5.0.

+

olap4j works best against JDK 1.6 or higher, because it makes use of the - -java.sql.Wrapper interface. In earlier Java versions, the same functionality +java.sql.Wrapper +interface. In earlier Java versions, the same functionality is available by casting objects to the built-in OlapWrapper interface.

-

JDK 1.4 compatibility will be available on demand, using the +

JDK 1.4 compatibility will be available on demand, using the Retroweaver utility. This will consist of a retrowoven JAR file, olap4j-jdk1.4.jar and retroweaver's runtime library retroweaver-rt-1.2.4.jar. (See @@ -389,54 +445,61 @@

1.6. Compatibility

olap4j's JDBC support is consistent with JDBC version 3.0 (which was introduced in JDK 1.4 and is also in JDK 1.5) and also with JDBC version 4.0 (introduced in JDK 1.6).

+

1.7. Compliance levels

-

There are two compliance levels to which a driver can support olap4j. olap4j -is a rich specification, and it takes a considerable effort to implement it -fully, but applications can still be built on a driver which only implements the -core parts of the specification. The lower level allows a vendor to a subset of -the specification without the significant investment of a fully-compliant + +

There are two compliance levels to which a driver can support olap4j. olap4j +is a rich specification, and it takes a considerable effort to implement it +fully, but applications can still be built on a driver which only implements the +core parts of the specification. The lower level allows a vendor to a subset of +the specification without the significant investment of a fully-compliant driver.

+

The compliance levels are as follows:

+
    -
  • olap4j Core Compliance. To comply with the olap4j core - specification, it must implement all classes in the org.olap4j - package, with the exception of the getXxxxs() methods in - - OlapDatabaseMetaData that return result sets, and all classes in the - org.olap4j.metadata package. The OLAP server must also - implement the fundamental features of the MDX language (see below).
    • -
  • olap4j Full Compliance. To fully comply with the olap4j - specification, a driver must comply with the core requirements, plus - implement the - - OlapDatabaseMetaData.getXxxxs() methods, plus - implements an MDX parser and validator (org.olap4j.mdx.parser - package).
    • +
  • olap4j Core Compliance. To comply with the olap4j core + specification, it must implement all classes in the org.olap4j + package, with the exception of the getXxxxs() methods in + + OlapDatabaseMetaData that return result sets, and all classes in the + org.olap4j.metadata package. The OLAP server must also + implement the fundamental features of the MDX language (see below).
    • +
  • olap4j Full Compliance. To fully comply with the olap4j + specification, a driver must comply with the core requirements, plus + implement the + + OlapDatabaseMetaData.getXxxxs() methods, plus + implements an MDX parser and validator (org.olap4j.mdx.parser + package).
+

MDX language compliance

-

All olap4j drivers must implement the fundamental features of the MDX -language, but olap4j compliance levels do not imply a particular degree of -support for the MDX language.

+ +

All olap4j drivers must implement the fundamental features of the +MDX language, but olap4j compliance levels do not imply a particular +degree of support for the MDX language.

+

The fundamental features of MDX are:

+
    -
  • Queries of the form "SELECT ... FROM ... WHERE".
    • -
  • The set constructor operator { ... }.
    • -
  • Set functions CrossJoin(<Set>, <Set>), Filter(<Set>, <Condition>), - Order(<Set>, <Expression>), Hierarchize(<Set>).
    • -
  • Navigation operators <Member>.Children, <Level>.Members - <Hierarchy>.Members, <Member>.Parent, Level, Hierarchy, Dimension
    • -
  • Aggregation functions Aggregate
    • -
  • Basic arithmetic and logical operators
    • +
  • Queries of the form "SELECT ... FROM ... WHERE".
    • +
  • The set constructor operator { ... }.
    • +
  • Set functions CrossJoin(<Set>, <Set>), Filter(<Set>, <Condition>), + Order(<Set>, <Expression>), Hierarchize(<Set>).
    • +
  • Navigation operators <Member>.Children, <Level>.Members + <Hierarchy>.Members, <Member>.Parent, Level, Hierarchy, Dimension
    • +
  • Aggregation functions Aggregate
    • +
  • Basic arithmetic and logical operators
-

Of course, a provider may implement a larger subset of MDX, and -most do. A provider can describe its MDX compliance level by describing the -additional features it supports (e.g. WITH MEMBER, WITH SET, NON EMPTY, and -HAVING clauses in queries; virtual cubes; and calculated members and sets + +

Of course, a provider may implement a larger subset of MDX, and +most do. A provider can describe its MDX compliance level by describing the +additional features it supports (e.g. WITH MEMBER, WITH SET, NON EMPTY, and +HAVING clauses in queries; virtual cubes; and calculated members and sets defined against cubes) and additional functions and operators implemented.

-

-2. -Components of the API

+

2. Components of the API

We now describe the olap4j API in more detail, by breaking it down into a set of functional areas.

@@ -450,47 +513,65 @@

2.1. Driver management

connection pooling, driver registration.

Classes:

+

2.1.1. The Driver class

Same functionality as JDBC.

+

Here is an example of registering an olap4j driver:

Class.forName("mondrian.olap4j.MondrianOlap4jDriver");
+

Note that this is the same as you would write for any JDBC driver. +From JDBC 4.0 (JDK 1.6) onwards, compliant JDBC drivers register +themselves +automatically by creating an entry in their JAR file's +META-INF/services/java.sql.Driver file. +Compliant olap4j drivers register themselves in the same way.

+

2.1.2. The DriverManager class

Same functionality as JDBC.

+

2.1.3. The DataSource interface

+

Same functionality as JDBC.

-

2.1.4. The OlapDataSource interface

-

Extension to DataSource that returns OlapConnection + +

See also: Database.

+ +

2.1.4. The OlapDataSource +interface

+ +

Extension to DataSource that returns OlapConnection objects rather than mere java.sql.Connection objects.

+

2.1.5. The OlapException class

-

OlapException + +

OlapException (extends - -java.sql.SQLException) describes an error which occurred while accessing an -OLAP server.

-

Since olap4j extends JDBC, it is natural that OlapException should extend -JDBC's - -SQLException. The implementation by an olap4j
-driver of a JDBC method which is declared to throw a SQLException may, if the -driver chooses, throw instead an OlapException.
-
-OlapException provides some additional information to help an OLAP client -identify the location of the error. The context is the Cell -or Position object where the error occurred. The region is an -object representing the textual region in the MDX statement.

+java.sql.SQLException) +describes an error which occurred while accessing an OLAP server.

+ +

Since olap4j extends JDBC, it is natural that OlapException should +extend JDBC's +SQLException. +The implementation by an olap4j driver of a JDBC method which is declared to throw a SQLException may, +if the driver chooses, throw instead an OlapException.

+ +

OlapException provides some additional information to help an OLAP +client identify the location of the error. The context is +the Cell or Position object where the error occurred. The region +is an object representing the textual region in the MDX statement.

+

Methods:

+