Author: xuefu
Date: Tue Mar 25 20:37:33 2014
New Revision: 1581502
URL: http://svn.apache.org/r1581502
Log:
HIVE-5652: Improve JavaDoc of UDF class (Lars via Xuefu)
Modified:
hive/trunk/ql/src/java/org/apache/hadoop/hive/ql/exec/UDF.java
Modified: hive/trunk/ql/src/java/org/apache/hadoop/hive/ql/exec/UDF.java
URL:
http://svn.apache.org/viewvc/hive/trunk/ql/src/java/org/apache/hadoop/hive/ql/exec/UDF.java?rev=1581502&r1=1581501&r2=1581502&view=diff
==============================================================================
--- hive/trunk/ql/src/java/org/apache/hadoop/hive/ql/exec/UDF.java (original)
+++ hive/trunk/ql/src/java/org/apache/hadoop/hive/ql/exec/UDF.java Tue Mar 25
20:37:33 2014
@@ -21,17 +21,37 @@ package org.apache.hadoop.hive.ql.exec;
import org.apache.hadoop.hive.ql.udf.UDFType;
/**
- * A User-defined function (UDF) for the use with Hive.
- *
- * New UDF classes need to inherit from this UDF class.
- *
- * Required for all UDF classes: 1. Implement one or more methods named
- * "evaluate" which will be called by Hive. The following are some examples:
- * public int evaluate(); public int evaluate(int a); public double
evaluate(int
- * a, double b); public String evaluate(String a, int b, String c);
- *
- * "evaluate" should never be a void method. However it can return "null" if
+ * A User-defined function (UDF) for use with Hive.
+ * <p>
+ * New UDF classes need to inherit from this UDF class (or from {@link
+ * org.apache.hadoop.hive.ql.udf.generic.GenericUDF GenericUDF} which provides
more flexibility at
+ * the cost of more complexity).
+ * <p>
+ * Requirements for all classes extending this UDF are:
+ * <ul>
+ * <li>Implement one or more methods named {@code evaluate} which will be
called by Hive (the exact
+ * way in which Hive resolves the method to call can be configured by setting
a custom {@link
+ * UDFMethodResolver}). The following are some examples:
+ * <ul>
+ * <li>{@code public int evaluate();}</li>
+ * <li>{@code public int evaluate(int a);}</li>
+ * <li>{@code public double evaluate(int a, double b);}</li>
+ * <li>{@code public String evaluate(String a, int b, Text c);}</li>
+ * <li>{@code public Text evaluate(String a);}</li>
+ * <li>{@code public String evaluate(List<Integer> a);} (Note that Hive Arrays
are represented as
+ * {@link java.util.List Lists} in Hive.
+ * So an {@code ARRAY<int>} column would be passed in as a {@code
List<Integer>}.)</li>
+ * </ul>
+ * </li>
+ * <li>{@code evaluate} should never be a void method. However it can return
{@code null} if
* needed.
+ * <li>Return types as well as method arguments can be either Java primitives
or the corresponding
+ * {@link org.apache.hadoop.io.Writable Writable} class.</li>
+ * </ul>
+ * One instance of this class will be instantiated per JVM and it will not be
called concurrently.
+ *
+ * @see Description
+ * @see UDFType
*/
@UDFType(deterministic = true)
public class UDF {
@@ -49,7 +69,7 @@ public class UDF {
}
/**
- * The constructor with user-provided UDFMethodResolver.
+ * The constructor with user-provided {@link UDFMethodResolver}.
*/
protected UDF(UDFMethodResolver rslv) {
this.rslv = rslv;
@@ -58,8 +78,7 @@ public class UDF {
/**
* Sets the resolver.
*
- * @param rslv
- * The method resolver to use for method resolution.
+ * @param rslv The method resolver to use for method resolution.
*/
public void setResolver(UDFMethodResolver rslv) {
this.rslv = rslv;
@@ -73,13 +92,25 @@ public class UDF {
}
/**
- * These can be overriden to provide the same functionality as the
- * correspondingly named methods in GenericUDF.
+ * This can be overridden to include JARs required by this UDF.
+ *
+ * @see org.apache.hadoop.hive.ql.udf.generic.GenericUDF#getRequiredJars()
+ * GenericUDF.getRequiredJars()
+ *
+ * @return an array of paths to files to include, {@code null} by default.
*/
public String[] getRequiredJars() {
return null;
}
+ /**
+ * This can be overridden to include files required by this UDF.
+ *
+ * @see org.apache.hadoop.hive.ql.udf.generic.GenericUDF#getRequiredFiles()
+ * GenericUDF.getRequiredFiles()
+ *
+ * @return an array of paths to files to include, {@code null} by default.
+ */
public String[] getRequiredFiles() {
return null;
}
