More API changes before 1.0...

Remove 'locale' parameter from MetadataElement methods getCaption and
getDescription; locale is inherited from connection.

Add method OlapStatement.getConnection that overrides the method on Statement
and refines the return type to OlapConnection.

Add method CellSet.getStatement that overrides the method on ResultSet and
refines the return type to OlapStatement.


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

src/org/olap4j/CellSet.java

@@ -9,6 +9,7 @@
 */
 package org.olap4j;
 
+import java.sql.SQLException;
 import java.util.List;
 import java.sql.ResultSet;
 
@@ -54,6 +55,23 @@
  * @since Aug 22, 2006
  */
 public interface CellSet extends ResultSet, OlapWrapper {
+
+ /**
+ * Retrieves the <code>OlapStatement</code> object that produced this
+ * <code>CellSet</code> object.
+ * If the result set was generated some other way, such as by a
+ * {@link org.olap4j.OlapDatabaseMetaData} method, this method may return
+ * <code>null</code>.
+ *
+ * @return the <code>OlapStatment</code> object that produced
+ * this <code>CellSet</code> object or <code>null</code>
+ * if the cell set was produced some other way
+ *
+ * @exception SQLException if a database access error occurs
+ * or this method is called on a closed cell set
+ */
+ OlapStatement getStatement() throws SQLException;
+
  /**
  * Retrieves the description of this <code>CellSet</code>'s axes
  * and cells.

src/org/olap4j/OlapConnection.java

@@ -88,13 +88,19 @@ public interface OlapConnection extends Connection, OlapWrapper {
  * <p>Most drivers support a <code>Locale</code> connect-string property.
  *
  * @param locale Locale
+ *
+ * @see #getLocale()
  */
  void setLocale(Locale locale);
 
  /**
  * Returns this connection's locale. The value is never null.
  *
  * @return locale of this connection
+ *
+ * @see #setLocale(java.util.Locale)
+ * @see org.olap4j.metadata.MetadataElement#getCaption()
+ * @see org.olap4j.metadata.MetadataElement#getDescription()
  */
  Locale getLocale();
 

src/org/olap4j/OlapStatement.java

@@ -9,6 +9,7 @@
 */
 package org.olap4j;
 
+import java.sql.SQLException;
 import java.sql.Statement;
 
 import org.olap4j.mdx.SelectNode;
@@ -28,6 +29,12 @@
  */
 public interface OlapStatement extends Statement, OlapWrapper {
 
+ /**
+ * Retrieves the <code>OlapConnection</code> object
+ * that produced this <code>OlapStatement</code> object.
+ */
+ OlapConnection getConnection() throws SQLException;
+
  /**
  * Executes an OLAP statement.
  *

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

@@ -12,7 +12,6 @@
 import org.olap4j.metadata.Datatype;
 import org.olap4j.metadata.Property;
 
-import java.util.Locale;
 import java.util.Set;
 
 /**
@@ -51,11 +50,11 @@ public String getUniqueName() {
  return propertyName;
  }
 
- public String getCaption(Locale locale) {
+ public String getCaption() {
  return propertyName;
  }
 
- public String getDescription(Locale locale) {
+ public String getDescription() {
  return "";
  }
 

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

@@ -1194,8 +1194,8 @@ public void moveToCurrentRow() throws SQLException {
  throw new UnsupportedOperationException();
  }
 
- public Statement getStatement() throws SQLException {
- throw new UnsupportedOperationException();
+ public OlapStatement getStatement() {
+ return olap4jStatement;
  }
 
  public Object getObject(
@@ -1475,11 +1475,11 @@ public String getUniqueName() {
  return uname;
  }
 
- public String getCaption(Locale locale) {
+ public String getCaption() {
  return caption;
  }
 
- public String getDescription(Locale locale) {
+ public String getDescription() {
  return null;
  }
  }

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

@@ -11,7 +11,6 @@
 import org.olap4j.impl.Named;
 import org.olap4j.metadata.*;
 
-import java.util.Locale;
 import java.util.Set;
 
 /**
@@ -54,11 +53,11 @@ public String getUniqueName() {
  return propertyUniqueName;
  }
 
- public String getCaption(Locale locale) {
+ public String getCaption() {
  return propertyUniqueName;
  }
 
- public String getDescription(Locale locale) {
+ public String getDescription() {
  return "";
  }
 

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

@@ -117,11 +117,11 @@ public String getUniqueName() {
  return "[" + name + "]";
  }
 
- public String getCaption(Locale locale) {
+ public String getCaption() {
  return name;
  }
 
- public String getDescription(Locale locale) {
+ public String getDescription() {
  return description;
  }
 

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

@@ -11,8 +11,6 @@
 import org.olap4j.impl.Named;
 import org.olap4j.metadata.MetadataElement;
 
-import java.util.Locale;
-
 /**
  * Abstract implementation of {@link MetadataElement}
  * for XML/A providers.
@@ -52,11 +50,11 @@ public String getUniqueName() {
  return uniqueName;
  }
 
- public String getCaption(Locale locale) {
+ public String getCaption() {
  return caption;
  }
 
- public String getDescription(Locale locale) {
+ public String getDescription() {
  return description;
  }
 

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

@@ -206,7 +206,7 @@ static Object getPropertyValue(
  (Property.StandardMemberProperty) property;
  switch (o) {
  case MEMBER_CAPTION:
- return member.getCaption(member.getConnection().getLocale());
+ return member.getCaption();
  case MEMBER_NAME:
  return member.getName();
  case MEMBER_UNIQUE_NAME:
@@ -220,8 +220,7 @@ static Object getPropertyValue(
  case DEPTH:
  return member.getDepth();
  case DESCRIPTION:
- return member.getDescription(
- member.getConnection().getLocale());
+ return member.getDescription();
  case DIMENSION_UNIQUE_NAME:
  return member.getDimension().getUniqueName();
  case DISPLAY_INFO:

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

@@ -13,8 +13,6 @@
 import org.olap4j.metadata.Cube;
 import org.olap4j.metadata.NamedSet;
 
-import java.util.Locale;
-
 /**
  * Implementation of {@link org.olap4j.metadata.NamedSet}
  * for XML/A providers.
@@ -53,11 +51,11 @@ public String getUniqueName() {
  return name;
  }
 
- public String getCaption(Locale locale) {
+ public String getCaption() {
  return name;
  }
 
- public String getDescription(Locale locale) {
+ public String getDescription() {
  return "";
  }
 }

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

@@ -22,7 +22,8 @@
  *
  * <p>This class is necessary because a member can have different properties
  * when it is retrieved as part of a cell set than if it is retrieved by
- * querying schema metadata (e.g. using {@link Cube#lookupMember(String[])}.
+ * querying schema metadata (e.g. using
+ * {@link Cube#lookupMember(java.util.List)}.
  * XmlaOlap4jPositionMember wraps the schema member (which might potentially
  * be cached between queries - even though today it is not) and adds extra
  * properties. All other methods are delegated to the underlying member.</p>
@@ -201,12 +202,12 @@ public String getUniqueName() {
  return member.getUniqueName();
  }
 
- public String getCaption(Locale locale) {
- return member.getCaption(locale);
+ public String getCaption() {
+ return member.getCaption();
  }
 
- public String getDescription(Locale locale) {
- return member.getDescription(locale);
+ public String getDescription() {
+ return member.getDescription();
  }
 
  /**

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

@@ -57,7 +57,7 @@ class XmlaOlap4jStatement implements OlapStatement {
  *
  * @return Error handler
  */
- private final XmlaHelper getHelper() {
+ private XmlaHelper getHelper() {
  return olap4jConnection.helper;
  }
 
@@ -193,8 +193,8 @@ public int[] executeBatch() throws SQLException {
  throw new UnsupportedOperationException();
  }
 
- public Connection getConnection() throws SQLException {
- throw new UnsupportedOperationException();
+ public OlapConnection getConnection() {
+ return olap4jConnection;
  }
 
  public boolean getMoreResults(int current) throws SQLException {

src/org/olap4j/layout/RectangularCellSetFormatter.java

@@ -360,7 +360,7 @@ private void populateAxis(
  String value =
  member == null
  ? ""
- : member.getCaption(null);
+ : member.getCaption();
  if (isColumns) {
  matrix.set(x, y, value, false, same);
  } else {

src/org/olap4j/metadata/MetadataElement.java

@@ -9,8 +9,6 @@
 */
 package org.olap4j.metadata;
 
-import java.util.Locale;
-
 /**
  * An element which describes the structure of an OLAP schema.
  *
@@ -22,45 +20,61 @@ public interface MetadataElement {
  /**
  * Returns the name of this element.
  *
- * @return name
+ * <p>Name is never null. Unlike {@link #getCaption() caption} and
+ * {@link #getDescription() description}, an element's name is the same in
+ * all locales.
+ *
+ * @return name of this element
  */
  String getName();
 
  /**
  * Returns the unique name of this element within its schema.
  *
+ * <p>The unique name is never null, and is unique among all elements in
+ * this {@link Schema}.
+ *
+ * <p>Unlike {@link #getCaption() caption} and
+ * {@link #getDescription() description}, an element's unique name is the
+ * same in all locales.
+ *
+ * <p>The structure of the unique name is provider-specific and subject to
+ * change between provider versions. Applications should not attempt to
+ * reverse-engineer the structure of the name.
+ *
  * @return unique name of this element
  */
  String getUniqueName();
 
  /**
- * Returns the caption of this element in the given locale.
+ * Returns the caption of this element in the current connection's locale.
  *
- * <p>If <code>locale</code> is null or if no caption has been defined for
- * the element in that locale, returns the caption in base locale.</p>
+ * <p>This method may return the empty string, but never returns null.
+ * The rules for deriving an element's caption are provider-specific,
+ * but generally if no caption is defined for the element in a given locale,
+ * returns the name of the element.</p>
  *
- * <p>This method may return the empty string, but never returns null.</p>
+ * @return caption of this element in the current locale; never null.
  *
- * @param locale Locale
- * @return Caption of this element in the given locale, or the base locale;
- * never null.
+ * @see org.olap4j.OlapConnection#getLocale()
  */
- String getCaption(Locale locale);
+ String getCaption();
 
  /**
- * Returns the description of this element in the given locale.
+ * Returns the description of this element in the current connection's
+ * {@link java.util.Locale}.
  *
- * <p>If <code>locale</code> is null or if no description has been defined
- * for the element in that locale, returns the description in base
+ * <p>This method may return the empty string, but never returns null.
+ * The rules for deriving an element's description are provider-specific,
+ * but generally if no description is defined
+ * for the element in a given locale, returns the description in base
  * locale.</p>
  *
- * <p>This method may return the empty string, but never returns null.</p>
+ * @return description of this element in the current locale; never null.
  *
- * @param locale Locale
- * @return description of this element in the given locale, or the base
- * locale; never null.
+ * @see org.olap4j.OlapConnection#getLocale()
  */
- String getDescription(Locale locale);
+ String getDescription();
 }
 
 // End MetadataElement.java