MONDRIAN: Add javadoc on encoded function signatures.

  Add Util.isEmpty(String) and Util.hash() functions.

[git-p4: depot-paths = "//open/mondrian/": change = 3059]

src/main/mondrian/olap/Util.java

@@ -373,7 +373,7 @@ public static int getMemberOrdinalInParent(SchemaReader reader, Member member) {
 		throw Util.newInternal(
 				"could not find member " + member + " amongst its siblings");
 	}
-	
+
 	/**
 	 * returns the first descendant on the level underneath parent.
 	 * If parent = [Time].[1997] and level = [Time].[Month], then
@@ -388,8 +388,15 @@ public static Member getFirstDescendantOnLevel(SchemaReader reader, Member paren
 		return m;
 	}
 
+    /**
+     * Returns whether a string is null or empty.
+     */
+    public static boolean isEmpty(String s) {
+        return s == null || s.length() == 0;
+    }
 
-	/**
+
+    /**
 	 * A <code>NullCellValue</code> is a placeholder value used when cells have
 	 * a null value. It is a singleton.
 	 */
@@ -822,6 +829,50 @@ public static List makeMutable(List list) {
 		}
 	}
 
+    /**
+     * Combines two integers into a hash code.
+     */
+    public static int hash(
+        int i,
+        int j)
+    {
+        return (i << 4) ^ j;
+    }
+
+    /**
+     * Computes a hash code from an existing hash code and an object (which
+     * may be null).
+     */
+    public static int hash(
+        int h,
+        Object o)
+    {
+        int k = (o == null) ? 0 : o.hashCode();
+        return ((h << 4) | h) ^ k;
+    }
+
+    /**
+     * Computes a hash code from an existing hash code and an array of objects
+     * (which may be null).
+     */
+    public static int hashArray(
+        int h,
+        Object [] a)
+    {
+        // The hashcode for a null array and an empty array should be different
+        // than h, so use magic numbers.
+        if (a == null) {
+            return hash(h, 19690429);
+        }
+        if (a.length == 0) {
+            return hash(h, 19690721);
+        }
+        for (int i = 0; i < a.length; i++) {
+            h = hash(h, a[i]);
+        }
+        return h;
+    }
+
     /**
      * Creates a very simple implementation of {@link Exp.Resolver}. (Only
      * useful for resolving trivial expressions.)

src/main/mondrian/olap/fun/BuiltinFunTable.java

@@ -93,73 +93,7 @@ protected void define(Resolver resolver) {
         }
     }
 
-	static Syntax decodeSyntacticType(String flags) {
-		char c = flags.charAt(0);
-		switch (c) {
-		case 'p':
-			return Syntax.Property;
-		case 'f':
-			return Syntax.Function;
-		case 'm':
-			return Syntax.Method;
-		case 'i':
-			return Syntax.Infix;
-		case 'P':
-			return Syntax.Prefix;
-		case 'I':
-			return Syntax.Internal;
-		default:
-			throw Util.newInternal(
-					"unknown syntax code '" + c + "' in string '" + flags + "'");
-		}
-	}
-
-	static int decodeReturnType(String flags) {
-		final int returnType = decodeType(flags, 1);
-		if ((returnType & Category.Mask) != returnType) {
-			throw Util.newInternal("bad return code flag in flags '" + flags + "'");
-		}
-		return returnType;
-	}
-
-	static int decodeType(String flags, int offset) {
-		char c = flags.charAt(offset);
-		switch (c) {
-		case 'a':
-			return Category.Array;
-		case 'd':
-			return Category.Dimension;
-		case 'h':
-			return Category.Hierarchy;
-		case 'l':
-			return Category.Level;
-		case 'b':
-			return Category.Logical;
-		case 'm':
-			return Category.Member;
-		case 'N':
-			return Category.Numeric | Category.Constant;
-		case 'n':
-			return Category.Numeric;
-		case 'x':
-			return Category.Set;
-		case '#':
-			return Category.String | Category.Constant;
-		case 'S':
-			return Category.String;
-		case 't':
-			return Category.Tuple;
-		case 'v':
-			return Category.Value;
-		case 'y':
-			return Category.Symbol;
-		default:
-			throw Util.newInternal(
-					"unknown type code '" + c + "' in string '" + flags + "'");
-		}
-	}
-
-	/**
+    /**
 	 * Converts an argument to a parameter type.
 	 */
 	public Exp convert(Exp fromExp, int to, Exp.Resolver resolver) {
@@ -394,15 +328,7 @@ static boolean canConvert(Exp fromExp, int to, int[] conversionCount) {
 		}
 	}
 
-	static int[] decodeParameterTypes(String flags) {
-		int[] parameterTypes = new int[flags.length() - 2];
-		for (int i = 0; i < parameterTypes.length; i++) {
-			parameterTypes[i] = decodeType(flags, i + 2);
-		}
-		return parameterTypes;
-	}
-
-	public FunDef getDef(FunCall call, Exp.Resolver resolver) {
+    public FunDef getDef(FunCall call, Exp.Resolver resolver) {
         String key = makeResolverKey(call.getFunName(), call.getSyntax());
 
 		// Resolve function by its upper-case name first.  If there is only one
@@ -1866,8 +1792,7 @@ public Object evaluate(Evaluator evaluator, Exp[] args) {
 								getMemberArg(evaluator, args, 0, false));
 					}
 				}));
-		define(new FunDefBase(
-				":", "<Member>:<Member>", "Infix colon operator returns the set of members between a given pair of members.", "ixmm") {
+		define(new FunDefBase(":", "<Member>:<Member>", "Infix colon operator returns the set of members between a given pair of members.", "ixmm") {
 			// implement FunDef
 			public Object evaluate(Evaluator evaluator, Exp[] args) {
 				final Member member0 = getMemberArg(evaluator, args, 0, true);

src/main/mondrian/olap/fun/FunDefBase.java

@@ -17,6 +17,60 @@
 /**
  * <code>FunDefBase</code> is the default implementation of {@link FunDef}.
  *
+ * <h3>Signatures</h3>
+ *
+ * A function is defined by the following:<ul>
+ *
+ * <table border="1">
+ *
+ * <tr><th>Parameter</th><th>Meaning</th><th>Example</th></tr>
+ *
+ * <tr>
+ * <td>name</td><td>Name of the function</td><td>"Members"</td>
+ * </tr>
+ *
+ * <tr>
+ * <td>signature</td>
+ * <td>Signature of the function</td>
+ * <td>"&lt;Dimension&gt;.Members"</td>
+ * </tr>
+ *
+ * <tr>
+ * <td>description</td>
+ * <td>Description of the function</td>
+ * <td>"Returns the set of all members in a dimension."</td>
+ * </tr>
+ *
+ * <tr>
+ * <td>flags</td>
+ * <td>Encoding of the syntactic type, return type, and parameter
+ *    types of this operator. The encoding is described below.</td>
+ * <td>"pxd"</tr>
+ * </table>
+ *
+ * <p>The <code>flags</code> field is an string which encodes
+ * the syntactic type, return type, and parameter types of this operator.
+ * <ul>
+ * <li>The first character determines the syntactic type, as described by
+ *     {@link FunUtil#decodeSyntacticType(String)}.
+ * <li>The second character determines the return type, as described by
+ *     {@link FunUtil#decodeReturnType(String)}.
+ * <li>The third and subsequence characters determine the types of the
+ *     arguments arguments, as described by
+ *     {@link FunUtil#decodeParameterTypes(String)}.
+ * </ul>
+ *
+ * <p>For example,  <code>"pxd"</code> means "an operator with
+ * {@link Syntax#Property property} syntax (p) which returns a set
+ * (x) and takes a dimension (d) as its argument".</p>
+ *
+ * <p>The arguments are always read from left to right, regardless of the
+ * syntactic type of the operator. For example, the
+ * <code>"&lt;Set&gt;.Item(&lt;Index&gt;)"</code> operator
+ * (signature <code>"mmxn"</code>) has the
+ * syntax of a method-call, and takes two parameters:
+ * a set (x) and a numeric (n).</p>
+ *
  * @author jhyde
  * @since 26 February, 2002
  * @version $Id$
@@ -29,6 +83,26 @@ public class FunDefBase extends FunUtil implements FunDef {
 	protected int[] parameterTypes;
 	boolean isAbstract = false;
 
+    /**
+     * Creates an operator.
+     *
+     * @param name Name of the function, for example "Members".
+     *
+     * @param signature Signature of the function, for example
+     *     "&lt;Dimension&gt;.Members".
+     *
+     * @param description Description of the function, for example
+     *    "Returns the set of all members in a dimension."
+     *
+     * @param syntax Syntactic type of the operator (for example, function,
+     *   method, infix operator)
+     *
+     * @param returnType The {@link Category} of the value returned by this
+     *   operator.
+     *
+     * @param parameterTypes An array of {@link Category} codes, one for
+     *   each parameter.
+     */
 	FunDefBase(
 			String name, String signature, String description,
 			Syntax syntax, int returnType, int[] parameterTypes) {
@@ -39,14 +113,32 @@ public class FunDefBase extends FunUtil implements FunDef {
 		this.returnType = returnType;
 		this.parameterTypes = parameterTypes;
 	}
+
+    /**
+     * Creates an operator.
+     *
+     * @param name Name of the function, for example "Members".
+     *
+     * @param signature Signature of the function, for example
+     *     "&lt;Dimension&gt;.Members".
+     *
+     * @param description Description of the function, for example
+     *    "Returns the set of all members in a dimension."
+     *
+     * @param flags Encoding of the syntactic type, return type, and parameter
+     *    types of this operator. The "Members" operator has a syntactic
+     *    type "pxd" which means "an operator with
+     *    {@link Syntax#Property property} syntax (p) which returns a set
+     *    (x) and takes a dimension (d) as its argument".
+     */
 	protected FunDefBase(
 			String name, String signature, String description, String flags) {
 		this(name,
 			signature,
 			description,
-			BuiltinFunTable.decodeSyntacticType(flags),
-			BuiltinFunTable.decodeReturnType(flags),
-			BuiltinFunTable.decodeParameterTypes(flags));
+			decodeSyntacticType(flags),
+			decodeReturnType(flags),
+			decodeParameterTypes(flags));
 	}
 	/**
 	 * Convenience constructor when we are created by a {@link Resolver}.