From c4940c5310e503ee3016f49998a30678a2d49c6a Mon Sep 17 00:00:00 2001 From: Julian Hyde Date: Tue, 30 Jun 2009 17:58:43 +0000 Subject: [PATCH] Javadoc. git-svn-id: https://olap4j.svn.sourceforge.net/svnroot/olap4j/trunk@255 c6a108a4-781c-0410-a6c6-c2d559e19af0 --- src/org/olap4j/OlapDatabaseMetaData.java | 6 +++ src/org/olap4j/query/QueryEvent.java | 48 ++++++++++++++----- src/org/olap4j/query/QueryNodeImpl.java | 44 ++++++++++------- .../driver/xmla/cache/XmlaShaEncoderTest.java | 2 +- 4 files changed, 70 insertions(+), 30 deletions(-) diff --git a/src/org/olap4j/OlapDatabaseMetaData.java b/src/org/olap4j/OlapDatabaseMetaData.java index df9ff62..38b8f07 100644 --- a/src/org/olap4j/OlapDatabaseMetaData.java +++ b/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; diff --git a/src/org/olap4j/query/QueryEvent.java b/src/org/olap4j/query/QueryEvent.java index 178650d..b61d9d8 100644 --- a/src/org/olap4j/query/QueryEvent.java +++ b/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 children = - new HashMap(); + private final Map 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 children) { - this.children.putAll(children); + // copy the map, and make immutable + this.children = + Collections.unmodifiableMap( + new HashMap(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,6 +104,8 @@ public QueryNode getSource() { /** * Returns the event type. */ + // REVIEW: consider renaming to 'getEventType', or rename enum Type to + // Operation. public QueryEvent.Type getOperation() { return operation; } @@ -92,10 +113,13 @@ public QueryEvent.Type getOperation() { /** * 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, + * + *

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 getChildrens() { return children; } diff --git a/src/org/olap4j/query/QueryNodeImpl.java b/src/org/olap4j/query/QueryNodeImpl.java index 6dacff9..79bff49 100644 --- a/src/org/olap4j/query/QueryNodeImpl.java +++ b/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 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 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 children) { + assert children != null; QueryEvent event = new QueryEvent( QueryEvent.Type.SELECTION_CHANGED, this, diff --git a/testsrc/org/olap4j/driver/xmla/cache/XmlaShaEncoderTest.java b/testsrc/org/olap4j/driver/xmla/cache/XmlaShaEncoderTest.java index 0f828a6..c39d252 100644 --- a/testsrc/org/olap4j/driver/xmla/cache/XmlaShaEncoderTest.java +++ b/testsrc/org/olap4j/driver/xmla/cache/XmlaShaEncoderTest.java @@ -14,7 +14,7 @@ import org.olap4j.driver.xmla.cache.XmlaOlap4jShaEncoder; /** - *

Test for {@ink org.olap4j.driver.xmla.cache.XmlaOlap4jShaEncoder}. + *

Test for {@link org.olap4j.driver.xmla.cache.XmlaOlap4jShaEncoder}. * * @author Luc Boudreau * @version $Id$