Fix javadoc on Level.getMembers (for MONDRIAN-1063);

add 3 more constructors for OlapException, to match SQLException;
add an enum to XmlaConstants;
correct values for ActionType constants.


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

src/org/olap4j/OlapException.java

@@ -19,7 +19,7 @@
 */
 package org.olap4j;
 
-import java.sql.SQLException;
+import java.sql.*;
 
 /**
  * <p>An exception describing an error accessing an OLAP database.</p>
@@ -41,7 +41,9 @@ public class OlapException extends SQLException {
  private Object context;
 
  /**
- * Constructs a fully-specified <code>SQLException</code> object.
+ * Constructs an <code>OlapException</code> object with a given
+ * <code>reason</code>, <code>SQLState</code> and
+ * <code>vendorCode</code>.
  *
  * @param reason a description of the exception
  * @param sqlState an XOPEN or SQL 99 code identifying the exception
@@ -52,7 +54,7 @@ public OlapException(String reason, String sqlState, int vendorCode) {
  }
 
  /**
- * Constructs an <code>SQLException</code> object with the given reason and
+ * Constructs an <code>OlapException</code> object with the given reason and
  * SQLState; the <code>vendorCode</code> field defaults to 0.
  *
  * @param reason a description of the exception
@@ -63,7 +65,7 @@ public OlapException(String reason, String sqlState) {
  }
 
  /**
- * Constructs an <code>SQLException</code> object with a reason;
+ * Constructs an <code>OlapException</code> object with a reason;
  * the <code>sqlState</code> field defaults to <code>null</code>, and
  * the <code>vendorCode</code> field defaults to 0.
  *
@@ -74,7 +76,7 @@ public OlapException(String reason) {
  }
 
  /**
- * Constructs an <code>SQLException</code> object;
+ * Constructs an <code>OlapException</code> object;
  * the <code>reason</code> field defaults to null,
  * the <code>sqlState</code> field defaults to <code>null</code>, and
  * the <code>vendorCode</code> field defaults to 0.
@@ -83,6 +85,24 @@ public OlapException() {
  super();
  }
 
+ /**
+ * Constructs an <code>OlapException</code> object with a given
+ * <code>cause</code>.
+ * The <code>SQLState</code> is initialized
+ * to <code>null</code> and the vendor code is initialized to 0.
+ * The <code>reason</code> is initialized to <code>null</code> if
+ * <code>cause==null</code> or to <code>cause.toString()</code> if
+ * <code>cause!=null</code>.
+ * <p>
+ * @param cause the underlying reason for this <code>OlapException</code>
+ * (which is saved for later retrieval by the <code>getCause()</code>
+ * method); may be null indicating the cause is non-existent or unknown.
+ */
+ public OlapException(Throwable cause) {
+ super();
+ initCause(cause);
+ }
+
  /**
  * Constructs an <code>OlapException</code> object with a given
  * <code>reason</code> and <code>cause</code>.
@@ -101,6 +121,50 @@ public OlapException(String reason, Throwable cause) {
  initCause(cause);
  }
 
+ /**
+ * Constructs an <code>OlapException</code> object with a given
+ * <code>reason</code>, <code>SQLState</code> and <code>cause</code>.
+ * The vendor code is initialized to 0.
+ *
+ * @param reason a description of the exception.
+ * @param sqlState an XOPEN or SQL:2003 code identifying the exception
+ * @param cause the underlying reason for this <code>OlapException</code>
+ * (which is saved for later retrieval by the
+ * <code>getCause()</code> method); may be null indicating
+ * the cause is non-existent or unknown.
+ */
+ public OlapException(String reason, String sqlState, Throwable cause) {
+ // Cannot call SQLException(String, String, Throwable); it only
+ // exists from JDK 1.6
+ super(reason, sqlState);
+ initCause(cause);
+ }
+
+ /**
+ * Constructs an <code>OlapException</code> object with a given
+ * <code>reason</code>, <code>SQLState</code>, <code>vendorCode</code>
+ * and <code>cause</code>.
+ *
+ * @param reason a description of the exception
+ * @param sqlState an XOPEN or SQL:2003 code identifying the exception
+ * @param vendorCode a database vendor-specific exception code
+ * @param cause the underlying reason for this <code>OlapException</code>
+ * (which is saved for later retrieval by the <code>getCause()</code>
+ * method);
+ * may be null indicating the cause is non-existent or unknown.
+ */
+ public OlapException(
+ String reason,
+ String sqlState,
+ int vendorCode,
+ Throwable cause)
+ {
+ // Cannot call SQLException(String, String, int, Throwable); it only
+ // exists from JDK 1.6
+ super(reason, sqlState, vendorCode);
+ initCause(cause);
+ }
+
  /**
  * Sets the textual region where the exception occurred.
  *

src/org/olap4j/metadata/Level.java

@@ -88,10 +88,27 @@ public interface Level extends MetadataElement {
  NamedList<Property> getProperties();
 
  /**
- * Returns a list of Member objects which belong to this Level.
+ * Returns a list of {@link Member} objects that belong to this Level.
+ *
+ * <p>The list does not include calculated members.</p>
  *
  * <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.
+ * method may be expensive in space and/or time and is not recommended.</p>
+ *
+ * <p>If you need to include calculated members, or if you need to query
+ * specific members or subsets of members in a level, consider instead
+ * generating and executing an MDX query with a single axis. MDX functions
+ * {@code AddCalculatedMembers}, {@code Filter} and {@code Order} are
+ * especially useful. For example,
+ *
+ * <pre>with member [Measures].[Zero] as 0
+ * select AddCalculatedMembers([Time].[Month].Members) on 0
+ * from [Sales]
+ * where [Measures].[Zero]</pre>
+ *
+ * returns the {@code [Month]} level including calculated members. The
+ * {@code [Measures].[Zero]} calculated member saves the OLAP server the
+ * effort of retrieving cell values.</p>
  *
  * <p>The members of a level do not have unique names, so unlike
  * {@link Hierarchy#getRootMembers()} and

src/org/olap4j/metadata/Property.java

@@ -704,10 +704,10 @@ enum StandardCellProperty implements Property {
  + "usually used for currency conversion."),
 
  ACTION_TYPE(
- Datatype.UNSIGNED_INTEGER,
+ Datatype.INT4,
  0,
  false,
- null,
+ XmlaConstants.ActionType.class,
  "A bitmask that indicates which types of actions exist on the "
  + "cell."),
 

src/org/olap4j/metadata/XmlaConstants.java

@@ -358,16 +358,29 @@ public int xmlaOrdinal() {
  }
  }
 
+ /**
+ * Action type.
+ *
+ * <p>Fields correspond to XMLA constants MDACTION_TYPE_URL (0x01),
+ * MDACTION_TYPE_HTML (0x02),
+ * MDACTION_TYPE_STATEMENT (0x04),
+ * MDACTION_TYPE_DATASET (0x08),
+ * MDACTION_TYPE_ROWSET (0x10),
+ * MDACTION_TYPE_COMMANDLINE (0x20),
+ * MDACTION_TYPE_PROPRIETARY (0x40),
+ * MDACTION_TYPE_REPORT (0x80),
+ * MDACTION_TYPE_DRILLTHROUGH (0x100)</p>
+ */
  public static enum ActionType implements XmlaConstant {
- URL(-1),
- HTML(-1),
- STATEMENT(-1),
- DATASET(-1),
- ROWSET(-1),
- COMMANDLINE(-1),
- PROPRIETARY(-1),
- REPORT(-1),
- DRILLTHROUGH(-1);
+ URL(0x01),
+ HTML(0x02),
+ STATEMENT(0x04),
+ DATASET(0x08),
+ ROWSET(0x10),
+ COMMANDLINE(0x20),
+ PROPRIETARY(0x40),
+ REPORT(0x80),
+ DRILLTHROUGH(0x100);
 
  private final int xmlaOrdinal;
 
@@ -401,6 +414,57 @@ public int xmlaOrdinal() {
  }
  }
 
+ /**
+ * How the COORDINATE restriction column is interpreted.
+ *
+ * <p>Fields correspond to the XMLA values
+ * MDACTION_COORDINATE_CUBE (1),
+ * MDACTION_COORDINATE_DIMENSION (2)
+ * MDACTION_COORDINATE_LEVEL (3),
+ * MDACTION_COORDINATE_MEMBER (4),
+ * MDACTION_COORDINATE_SET (5),
+ * MDACTION_COORDINATE_CELL (6)</p>
+ */
+ public static enum CoordinateType implements XmlaConstant {
+ CUBE(1),
+ DIMENSION(2),
+ LEVEL(3),
+ MEMBER(4),
+ SET(5),
+ CELL(6);
+
+ private final int xmlaOrdinal;
+
+ private static final Dictionary<ActionType> DICTIONARY =
+ DictionaryImpl.forClass(ActionType.class);
+
+ /**
+ * Per {@link XmlaConstant}, returns a dictionary
+ * of all values of this enumeration.
+ *
+ * @return Dictionary of all values
+ */
+ public static Dictionary<ActionType> getDictionary() {
+ return DICTIONARY;
+ }
+
+ CoordinateType(int xmlaOrdinal) {
+ this.xmlaOrdinal = xmlaOrdinal;
+ }
+
+ public String xmlaName() {
+ return "MDACTION_COORDINATE_" + name();
+ }
+
+ public String getDescription() {
+ return name();
+ }
+
+ public int xmlaOrdinal() {
+ return xmlaOrdinal;
+ }
+ }
+
  /**
  * The only OLE DB Types Indicators returned by SQL Server are thoses coded
  * below.