# The QueryDimension.SortOrder and QueryAxis.SortOrder will both be f…

…actored out and a single enumeration org.olap4j.query.SortOrder will remain. All relevant method setters and getters will be changed accordingly. We can't use Java's regular deprecation mechanism because of Java's no support for enumeration class heritage.

# QueryDimension.setSortOrder() will be renamed QueryDimension.sort() in order to preserve method names homogeneity.

# Including selections by name parts will now throw OlapException when no member corresponding to the supplied name parts can be found. It used to fail silently, but no more.

# SelectionFactory scope will be limited to package level because all necessary methods to create inclusions/exclusions are now encapsulated in QueryDimension.

# CellSetFormatter, TraditionalCellSetFormatter and RectangularCellSetFormatter were moved in the long overdue org.olap4j.layout package. 

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

src/org/olap4j/Axis.java

@@ -29,6 +29,8 @@ public interface Axis {
  /**
  * @deprecated Will be removed before olap4j 1.0.
  */
+ // REVIEW: Is it wise to remove this axis enum value?
+ // It's existence IS relevant.
  Standard UNUSED = null;
 
  /**

src/org/olap4j/impl/Olap4jUtil.java

@@ -364,6 +364,22 @@ public static String[] uniqueNameToStringArray(String uniqueName) {
  return trail.toArray(new String[trail.size()]);
  }
 
+ /**
+ * Converts the contents of an array of strings to
+ * a proper String representation.
+ */
+ public static String stringArrayToString(String[] array) {
+ StringBuilder sb = new StringBuilder("[");
+ for (int i = 0; i < array.length; i++) {
+ sb.append(array[i]);
+ if (i < (array.length - 1)) {
+ sb.append(",");
+ }
+ }
+ sb.append("]");
+ return sb.toString();
+ }
+
  @SuppressWarnings({"unchecked"})
  public static <T> NamedList<T> emptyNamedList() {
  return (NamedList<T>) EMPTY_NAMED_LIST;

src/org/olap4j/query/CellSetFormatter.java → src/org/olap4j/layout/CellSetFormatter.java

@@ -1,13 +1,13 @@
 /*
-// $Id$
+// $Id:$
 // This software is subject to the terms of the Eclipse Public License v1.0
 // Agreement, available at the following URL:
 // http://www.eclipse.org/legal/epl-v10.html.
 // Copyright (C) 2009-2009 Julian Hyde
 // All Rights Reserved.
 // You must accept the terms of that agreement to use this software.
 */
-package org.olap4j.query;
+package org.olap4j.layout;
 
 import org.olap4j.CellSet;
 import java.io.PrintWriter;
@@ -19,7 +19,7 @@
  * specification and is subject to change without notice.</b></p>
  *
  * @author jhyde
- * @version $Id$
+ * @version $Id:$
  * @since Apr 15, 2009
  */
 public interface CellSetFormatter {

src/org/olap4j/query/RectangularCellSetFormatter.java → src/org/olap4j/layout/RectangularCellSetFormatter.java

@@ -1,13 +1,13 @@
 /*
-// $Id$
+// $Id:$
 // This software is subject to the terms of the Eclipse Public License v1.0
 // Agreement, available at the following URL:
 // http://www.eclipse.org/legal/epl-v10.html.
 // Copyright (C) 2009-2009 Julian Hyde
 // All Rights Reserved.
 // You must accept the terms of that agreement to use this software.
 */
-package org.olap4j.query;
+package org.olap4j.layout;
 
 import org.olap4j.*;
 import org.olap4j.metadata.Member;
@@ -51,7 +51,7 @@
  * specification and is subject to change without notice.</b></p>
  *
  * @author jhyde
- * @version $Id$
+ * @version $Id:$
  * @since Apr 15, 2009
 */
 public class RectangularCellSetFormatter implements CellSetFormatter {

src/org/olap4j/query/TraditionalCellSetFormatter.java → src/org/olap4j/layout/TraditionalCellSetFormatter.java

@@ -1,13 +1,13 @@
 /*
-// $Id$
+// $Id:$
 // This software is subject to the terms of the Eclipse Public License v1.0
 // Agreement, available at the following URL:
 // http://www.eclipse.org/legal/epl-v10.html.
 // Copyright (C) 2009-2009 Julian Hyde
 // All Rights Reserved.
 // You must accept the terms of that agreement to use this software.
 */
-package org.olap4j.query;
+package org.olap4j.layout;
 
 import org.olap4j.*;
 import org.olap4j.metadata.Member;
@@ -24,7 +24,7 @@
  * specification and is subject to change without notice.</b></p>
  *
  * @author jhyde
- * @version $Id$
+ * @version $Id:$
  * @since Apr 15, 2009
  */
 public class TraditionalCellSetFormatter implements CellSetFormatter {

src/org/olap4j/layout/package.html

@@ -0,0 +1,8 @@
+<html>
+<body>
+Provides utility classes to display and render olap4j specific data structures.
+
+<p><b>NOTE</b>: This package is experimental. Classes may be renamed or removed in a future release of olap4j.
+
+</body>
+</html>

src/org/olap4j/query/Query.java

@@ -22,7 +22,7 @@
 /**
  * Base query model object.
  *
- * @author jhyde, jdixon
+ * @author jhyde, jdixon, Luc Boudreau
  * @version $Id$
  * @since May 29, 2007
  */
@@ -45,6 +45,13 @@ public class Query extends QueryNodeImpl {
  private final OlapConnection connection;
  private final SelectionFactory selectionFactory = new SelectionFactory();
 
+ /**
+ * Constructs a Query object.
+ * @param name Any arbitrary name to give to this query.
+ * @param cube A Cube object against which to build a query.
+ * @throws SQLException If an error occurs while accessing the
+ * cube's underlying connection.
+ */
  public Query(String name, Cube cube) throws SQLException {
  super();
  this.name = name;
@@ -160,6 +167,13 @@ public QueryAxis getUnusedAxis() {
  return unused;
  }
 
+ /**
+ * Safely disposes of all underlying objects of this
+ * query.
+ * @param closeConnection Whether or not to call the
+ * {@link OlapConnection#close()} method of the underlying
+ * connection.
+ */
  public void tearDown(boolean closeConnection) {
  for (Entry<Axis, QueryAxis> entry : this.axes.entrySet()) {
  entry.getValue().tearDown();
@@ -175,6 +189,11 @@ public void tearDown(boolean closeConnection) {
  }
  }
 
+ /**
+ * Safely disposes of all underlying objects of this
+ * query and closes the underlying {@link OlapConnection}.
+ * <p>Equivalent of calling Query.tearDown(true).
+ */
  public void tearDown() {
  this.tearDown(true);
  }

src/org/olap4j/query/QueryAxis.java

@@ -27,7 +27,7 @@
  * <p>An axis has a location (columns, rows, etc) and has zero or more
  * dimensions that are placed on it.
  *
- * @author jdixon
+ * @author jdixon, Luc Boudreau
  * @version $Id$
  * @since May 29, 2007
  */
@@ -245,36 +245,6 @@ void tearDown() {
  this.getDimensions().clear();
  }
 
- /**
- * Defines in what order to perform the sort.
- */
- public static enum SortOrder {
- /**
- * Ascending sort order. Members of
- * the same hierarchy are still kept together.
- */
- ASC,
- /**
- * Descending sort order. Members of
- * the same hierarchy are still kept together.
- */
- DESC,
- /**
- * Sorts in ascending order, but does not
- * maintain members of a same hierarchy
- * together. This is known as a "break
- * hierarchy ascending sort".
- */
- BASC,
- /**
- * Sorts in descending order, but does not
- * maintain members of a same hierarchy
- * together. This is known as a "break
- * hierarchy descending sort".
- */
- BDESC
- }
-
  /**
  * <p>Sorts the axis according to the supplied order. The sort evaluation
  * expression will be the default member of the default hierarchy of
@@ -297,7 +267,7 @@ public void sort(SortOrder order) throws OlapException {
  * parts from the underlying cube and find the corresponding
  * member. This member will then be passed as a sort evaluation
  * expression.
- * @param order The {@link QueryAxis.SortOrder} in which to
+ * @param order The {@link SortOrder} in which to
  * sort the axis.
  * @param nameParts The unique name parts of the sort
  * evaluation expression.
@@ -322,7 +292,7 @@ public void sort(SortOrder order, String... nameParts)
  * and member.
  * <p>This method is most commonly called by passing
  * it a {@link Measure}.
- * @param order The {@link QueryAxis.SortOrder} in which to
+ * @param order The {@link SortOrder} in which to
  * sort the axis.
  * @param member The member that will be used as a sort
  * evaluation expression.
@@ -338,7 +308,7 @@ public void sort(SortOrder order, Member member) {
  * and evaluation expression.
  * <p>The string value passed as the sortIdentifierNodeName
  * parameter willb e used literally as a sort evaluator.
- * @param order The {@link QueryAxis.SortOrder} in which to
+ * @param order The {@link SortOrder} in which to
  * sort the axis.
  * @param sortEvaluationLiteral The literal expression that
  * will be used to sort against.