Javadoc.

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

src/org/olap4j/OlapDatabaseMetaData.java

@@ -482,8 +482,14 @@ ResultSet getDimensions(
  * function description
  *
  * @exception OlapException if a database access error occurs
+ *
+ * @see #getFunctions(String, String, String)
  * @see #getSearchStringEscape
  */
+ // NOTE: '#getFunctions(String, String, String)' above generates a javadoc
+ // error on JDK 1.5, because it is new in JDBC 4.0/JDK 1.6. But please leave
+ // it in. Most olap4j users run on JDK 1.6 or later, and the javadoc is
+ // intended for them.
  ResultSet getOlapFunctions(
  String functionNamePattern) throws OlapException;
 

src/org/olap4j/query/QueryEvent.java

@@ -9,8 +9,7 @@
 */
 package org.olap4j.query;
 
-import java.util.HashMap;
-import java.util.Map;
+import java.util.*;
 
 /**
  * Describes which changes were performed to the query model.
@@ -25,47 +24,67 @@ public final class QueryEvent {
  */
  public static enum Type {
  /**
- * Some choldren of a QueryNode were removed from
- * it's list.
+ * Event where one or more children of a QueryNode were removed.
  */
  CHILDREN_REMOVED,
  /**
- * Some children of a QueryNode were added to
- * it's list.
+ * Event where one or more nodes were added as children of a QueryNode.
  */
  CHILDREN_ADDED,
  /**
- * A Selection object operator was changed.
+ * Event where a Selection object operator was changed.
  */
  SELECTION_CHANGED
  }
 
  private final QueryNode source;
  private final QueryEvent.Type operation;
- private Map<Integer, QueryNode> children =
- new HashMap<Integer, QueryNode>();
+ private final Map<Integer, QueryNode> children;
 
+ /**
+ * Creates a QueryEvent with a single child.
+ *
+ * @param operation Even type
+ * @param source Query node that generated this event
+ * @param child Child node
+ */
  QueryEvent(
  QueryEvent.Type operation,
  QueryNode source,
  QueryNode child,
  int index)
  {
- this.children.put(Integer.valueOf(index), child);
+ this.children = Collections.singletonMap(index, child);
  this.source = source;
  this.operation = operation;
  }
 
+ /**
+ * Creates a QueryEvent with multiple children.
+ *
+ * @param operation Even type
+ * @param source Query node that generated this event
+ * @param children Child nodes and their indexes within the parent
+ */
  QueryEvent(
  QueryEvent.Type operation,
  QueryNode source,
  Map<Integer, QueryNode> children)
  {
- this.children.putAll(children);
+ // copy the map, and make immutable
+ this.children =
+ Collections.unmodifiableMap(
+ new HashMap<Integer, QueryNode>(children));
  this.source = source;
  this.operation = operation;
  }
 
+ /**
+ * Creates a QueryEvent with no children.
+ *
+ * @param operation Even type
+ * @param source Query node that generated this event
+ */
  QueryEvent(
  QueryEvent.Type operation,
  QueryNode source)
@@ -85,17 +104,22 @@ public QueryNode getSource() {
  /**
  * Returns the event type.
  */
+ // REVIEW: consider renaming to 'getEventType', or rename enum Type to
+ // Operation.
  public QueryEvent.Type getOperation() {
  return operation;
  }
 
  /**
  * Returns a map of objects affected by the event and
  * their index in the list of the source children.
- * If the event is of type QueryEvent.Type.SELECTION_CHANGED,
+ *
+ * <p>If the event is of type {@link QueryEvent.Type#SELECTION_CHANGED},
  * this method will return null because the source object was affected
  * and not the children.
  */
+ // REVIEW: 'children' is already plural. Consider renaming to 'getChildren'
+ // or 'getChildNodes'.
  public Map<Integer, QueryNode> getChildrens() {
  return children;
  }

src/org/olap4j/query/QueryNodeImpl.java

@@ -35,12 +35,14 @@ public void removeQueryNodeListener(QueryNodeListener l) {
 
  /**
  * Subclasses should call this helper method to
- * notify it's listeners that a child was added.
- * @param child A reference to the child that was added.
- * @param index The index at which it was added.
+ * notify its listeners that a child was added.
+ *
+ * @param child Child that was added
+ * @param index The index at which it was added
  */
  protected void notifyAdd(QueryNode child, int index)
  {
+ assert child != null;
  QueryEvent event = new QueryEvent(
  QueryEvent.Type.CHILDREN_ADDED,
  this,
@@ -52,11 +54,13 @@ protected void notifyAdd(QueryNode child, int index)
  /**
  * Subclasses should call this helper method to
  * notify it's listeners that children were added.
+ *
  * @param children A map of indexes and children QueryNode
- * objects that were just added.
+ *  objects that were added
  */
  protected void notifyAdd(Map<Integer, QueryNode> children)
  {
+ assert children != null;
  QueryEvent event = new QueryEvent(
  QueryEvent.Type.CHILDREN_ADDED,
  this,
@@ -75,12 +79,14 @@ private void notifyAddInternal(QueryEvent event) {
 
  /**
  * Subclasses should call this helper method to
- * notify it's listeners that a child was removed.
- * @param child A reference to the child that was removed.
- * @param index The index at which it was removed.
+ * notify its listeners that a child was removed.
+ *
+ * @param child Child that was removed
+ * @param index Index of child
  */
  protected void notifyRemove(QueryNode child, int index)
  {
+ assert child != null;
  QueryEvent event = new QueryEvent(
  QueryEvent.Type.CHILDREN_REMOVED,
  this,
@@ -91,12 +97,14 @@ protected void notifyRemove(QueryNode child, int index)
 
  /**
  * Subclasses should call this helper method to
- * notify it's listeners that children were added.
+ * notify its listeners that children were added.
+ *
  * @param children A map of indexes and children QueryNode
- * objects that were just added.
+ *  objects that were removed
  */
  protected void notifyRemove(Map<Integer, QueryNode> children)
  {
+ assert children != null;
  QueryEvent event = new QueryEvent(
  QueryEvent.Type.CHILDREN_REMOVED,
  this,
@@ -115,14 +123,15 @@ private void notifyRemoveInternal(QueryEvent event) {
 
  /**
  * Subclasses should call this helper method to
- * notify it's listeners that a child selection
+ * notify its listeners that a child selection
  * object has a new operator value.
- * @param child A reference to the child that was updated.
- * @param index The index of the updated object in its
- * parent's list.
+ *
+ * @param child Child that was updated
+ * @param index The index of the child among its siblings
  */
  protected void notifyChange(QueryNode child, int index)
  {
+ assert child != null;
  QueryEvent event = new QueryEvent(
  QueryEvent.Type.SELECTION_CHANGED,
  this,
@@ -133,14 +142,15 @@ protected void notifyChange(QueryNode child, int index)
 
  /**
  * Subclasses should call this helper method to
- * notify it's listeners that children selections
+ * notify its listeners that children selections
  * object has a new operator value.
- * @param child A reference to the child that was updated.
- * @param index The index of the updated object in its
- * parent's list.
+ *
+ * @param children A map of indexes and children QueryNode
+ *  objects that were updated
  */
  protected void notifyChange(Map<Integer, QueryNode> children)
  {
+ assert children != null;
  QueryEvent event = new QueryEvent(
  QueryEvent.Type.SELECTION_CHANGED,
  this,

testsrc/org/olap4j/driver/xmla/cache/XmlaShaEncoderTest.java

@@ -14,7 +14,7 @@
 import org.olap4j.driver.xmla.cache.XmlaOlap4jShaEncoder;
 
 /**
- * <p>Test for {@ink org.olap4j.driver.xmla.cache.XmlaOlap4jShaEncoder}.
+ * <p>Test for {@link org.olap4j.driver.xmla.cache.XmlaOlap4jShaEncoder}.
  *
  * @author Luc Boudreau
  * @version $Id$