[INLONG-11049][SDK] Standardize existing functions (apache#11339)

Co-authored-by: ZKpLo <[email protected]>

inlong-sdk/transform-sdk/src/main/java/org/apache/inlong/sdk/transform/process/function/FunctionTools.java

@@ -19,7 +19,9 @@
 
 import org.apache.inlong.sdk.transform.process.parser.ColumnParser;
 import org.apache.inlong.sdk.transform.process.parser.ValueParser;
+import org.apache.inlong.sdk.transform.process.pojo.FunctionInfo;
 
+import com.google.common.collect.Lists;
 import com.google.common.collect.Maps;
 import lombok.extern.slf4j.Slf4j;
 import net.sf.jsqlparser.expression.Function;
@@ -29,6 +31,8 @@
 import org.reflections.scanners.Scanners;
 
 import java.lang.reflect.Constructor;
+import java.util.Collection;
+import java.util.List;
 import java.util.Map;
 import java.util.Set;
 
@@ -65,10 +69,45 @@ private static void init() {
                     return clazz;
                 });
             }
+        }
+    }
+
+    private static class FunctionDocHolder {
+
+        final static List<FunctionInfo> functionDocList = Lists.newCopyOnWriteArrayList();
 
+        static {
+            initFunctionDoc();
+        }
+
+        private static void initFunctionDoc() {
+            Collection<Class<?>> clazzList = functionMap.values();
+            for (Class<?> clazz : clazzList) {
+                TransformFunction annotation = clazz.getAnnotation(TransformFunction.class);
+                if (annotation == null || ArrayUtils.isEmpty(annotation.names())) {
+                    continue;
+                }
+                StringBuilder name = new StringBuilder();
+                StringBuilder explanation = new StringBuilder();
+                StringBuilder example = new StringBuilder();
+                for (String functionName : annotation.names()) {
+                    name.append(functionName.concat(annotation.parameter() + "\r\n"));
+                }
+                for (String functionExplanation : annotation.descriptions()) {
+                    explanation.append(functionExplanation.concat("\r\n"));
+                }
+                for (String functionExample : annotation.examples()) {
+                    example.append(functionExample.concat("\r\n"));
+                }
+                functionDocList.add(new FunctionInfo(name.toString(), explanation.toString(), example.toString()));
+            }
         }
     }
 
+    public static List<FunctionInfo> getFunctionDoc() {
+        return FunctionDocHolder.functionDocList;
+    }
+
     public static ValueParser getTransformFunction(Function func) {
         if (func == null) {
             return null;

inlong-sdk/transform-sdk/src/main/java/org/apache/inlong/sdk/transform/process/function/TransformFunction.java

@@ -28,4 +28,11 @@
 public @interface TransformFunction {
 
     String[] names();
+
+    String parameter() default "";
+
+    String[] descriptions() default {};
+
+    String[] examples() default {};
+
 }

inlong-sdk/transform-sdk/src/main/java/org/apache/inlong/sdk/transform/process/function/arithmetic/AbsFunction.java

@@ -28,31 +28,32 @@
 import java.math.BigDecimal;
 
 /**
- * AbsFunction
- * description: abs(numeric)--returns the absolute value of numeric
+ * AbsFunction  ->  abs(numeric)
+ * description:
+ * - Return NULL if 'numeric' is NULL;
+ * - Return the absolute value of 'numeric'.
  */
-@TransformFunction(names = {"abs"})
+@TransformFunction(names = {"abs"}, parameter = "(Numeric numeric)", descriptions = {
+        "- Return \"\" if 'numeric' is NULL;",
+        "- Return the absolute value of 'numeric'."
+}, examples = {
+        "abs(2) = 2",
+        "abs(-4.25) = 4.25"
+})
 public class AbsFunction implements ValueParser {
 
     private ValueParser numberParser;
 
-    /**
-     * Constructor
-     * @param expr
-     */
     public AbsFunction(Function expr) {
         numberParser = OperatorTools.buildParser(expr.getParameters().getExpressions().get(0));
     }
 
-    /**
-     * parse
-     * @param sourceData
-     * @param rowIndex
-     * @return
-     */
     @Override
     public Object parse(SourceData sourceData, int rowIndex, Context context) {
         Object numberObj = numberParser.parse(sourceData, rowIndex, context);
+        if (numberObj == null) {
+            return null;
+        }
         BigDecimal numberValue = OperatorTools.parseBigDecimal(numberObj);
         return numberValue.abs();
     }

inlong-sdk/transform-sdk/src/main/java/org/apache/inlong/sdk/transform/process/function/arithmetic/AcosFunction.java

@@ -28,31 +28,33 @@
 import java.math.BigDecimal;
 
 /**
- * AcosFunction
- * description: acos(numeric)--returns the arc cosine of numeric
+ * AcosFunction  ->  acos(numeric)
+ * description:
+ * - Return NULL if 'numeric' is NULL;
+ * - Return the arc cosine of 'numeric'.
  */
-@TransformFunction(names = {"acos"})
+@TransformFunction(names = {"acos"}, parameter = "(Numeric numeric)", descriptions = {
+        "- Return \"\" if 'numeric' is NULL;",
+        "- Return the arc cosine of 'numeric'."
+}, examples = {
+        "acos(1) = 0.0",
+        "acos(0) = 1.5707963267948966",
+        "acos(-1) = 3.141592653589793"
+})
 public class AcosFunction implements ValueParser {
 
     private ValueParser numberParser;
 
-    /**
-     * Constructor
-     * @param expr
-     */
     public AcosFunction(Function expr) {
         numberParser = OperatorTools.buildParser(expr.getParameters().getExpressions().get(0));
     }
 
-    /**
-     * parse
-     * @param sourceData
-     * @param rowIndex
-     * @return
-     */
     @Override
     public Object parse(SourceData sourceData, int rowIndex, Context context) {
         Object numberObj = numberParser.parse(sourceData, rowIndex, context);
+        if (numberObj == null) {
+            return null;
+        }
         BigDecimal numberValue = OperatorTools.parseBigDecimal(numberObj);
         return Math.acos(numberValue.doubleValue());
     }

inlong-sdk/transform-sdk/src/main/java/org/apache/inlong/sdk/transform/process/function/arithmetic/AcosdFunction.java

@@ -28,10 +28,19 @@
 import java.math.BigDecimal;
 
 /**
- * AcosdFunction
- * description: acosd(numeric)--returns the arc cosine of numeric in units of degrees
+ * AcosdFunction   ->   acosd(numeric)
+ * description:
+ * - Return NULL if 'numeric' is NULL;
+ * - Return the arc cosine of 'numeric' in units of degrees.
  */
-@TransformFunction(names = {"acosd"})
+@TransformFunction(names = {"acosd"}, parameter = "(Numeric numeric)", descriptions = {
+        "- Return \"\" if 'numeric' is NULL;",
+        "- Return the arc cosine of 'numeric' in units of degrees."
+}, examples = {
+        "acosd(1) = 0.0",
+        "acosd(0) = 90.0",
+        "acosd(-1) = 180.0"
+})
 public class AcosdFunction implements ValueParser {
 
     private ValueParser numberParser;
@@ -43,6 +52,9 @@ public AcosdFunction(Function expr) {
     @Override
     public Object parse(SourceData sourceData, int rowIndex, Context context) {
         Object numberObj = numberParser.parse(sourceData, rowIndex, context);
+        if (numberObj == null) {
+            return null;
+        }
         BigDecimal numberValue = OperatorTools.parseBigDecimal(numberObj);
         return Math.toDegrees(Math.acos(numberValue.doubleValue()));
     }

inlong-sdk/transform-sdk/src/main/java/org/apache/inlong/sdk/transform/process/function/arithmetic/AsinFunction.java

@@ -28,10 +28,19 @@
 import java.math.BigDecimal;
 
 /**
- * AsinFunction
- * description: asin(numeric)--returns the arc sine of numeric
+ * AsinFunction  ->  asin(numeric)
+ * description:
+ * - Return NULL if 'numeric' is NULL;
+ * - Return the arc sine of 'numeric'.
  */
-@TransformFunction(names = {"asin"})
+@TransformFunction(names = {"asin"}, parameter = "(Numeric numeric)", descriptions = {
+        "- Return \"\" if 'numeric' is NULL;",
+        "- Return the arc sine of 'numeric' in units of degrees."
+}, examples = {
+        "asin(0.5) = 0.5235987755982989",
+        "asin(0) = 0.0",
+        "asin(-0.5) = -0.5235987755982989"
+})
 public class AsinFunction implements ValueParser {
 
     private ValueParser numberParser;
@@ -44,7 +53,7 @@ public AsinFunction(Function expr) {
     public Object parse(SourceData sourceData, int rowIndex, Context context) {
         Object numberObj = numberParser.parse(sourceData, rowIndex, context);
         if (numberObj == null) {
-            throw new NullPointerException("Parsed number object is null");
+            return null;
         }
         BigDecimal numberValue = OperatorTools.parseBigDecimal(numberObj);
         return Math.asin(numberValue.doubleValue());

inlong-sdk/transform-sdk/src/main/java/org/apache/inlong/sdk/transform/process/function/arithmetic/AsindFunction.java

@@ -28,10 +28,19 @@
 import java.math.BigDecimal;
 
 /**
- * AsindFunction
- * description: asind(numeric)--returns the arc sine of numeric in units of degrees
+ * AsindFunction  ->  asind(numeric)
+ * description:
+ * - Return NULL if 'numeric' is NULL;
+ * - Return the arc sine of 'numeric' in units of degrees.
  */
-@TransformFunction(names = {"asind"})
+@TransformFunction(names = {"asind"}, parameter = "(Numeric numeric)", descriptions = {
+        "- Return \"\" if 'numeric' is NULL;",
+        "- Return the arc sine of 'numeric' in units of degrees."
+}, examples = {
+        "asind(0.5) = 30.000000000000004",
+        "asind(0) = 0.0",
+        "asind(-0.5) = -30.000000000000004"
+})
 public class AsindFunction implements ValueParser {
 
     private ValueParser numberParser;
@@ -43,6 +52,9 @@ public AsindFunction(Function expr) {
     @Override
     public Object parse(SourceData sourceData, int rowIndex, Context context) {
         Object numberObj = numberParser.parse(sourceData, rowIndex, context);
+        if (numberObj == null) {
+            return null;
+        }
         BigDecimal numberValue = OperatorTools.parseBigDecimal(numberObj);
         return Math.toDegrees(Math.asin(numberValue.doubleValue()));
     }

inlong-sdk/transform-sdk/src/main/java/org/apache/inlong/sdk/transform/process/function/arithmetic/Atan2Function.java

@@ -28,10 +28,19 @@
 import java.math.BigDecimal;
 
 /**
- * Atan2Function
- * description: atan2(numeric)--returns the arc tangent of a coordinate (numeric1, numeric2).
+ * Atan2Function  ->  atan2(numericx,numericy)
+ * description:
+ * - Return NULL if 'numericx' or 'numericy' is NULL;
+ * - Return the arc tangent of a coordinate ('numericx', 'numericy').
  */
-@TransformFunction(names = {"atan2"})
+@TransformFunction(names = {"atan2"}, parameter = "(Numeric numeric)", descriptions = {
+        "Return \"\" if 'numericx' or 'numericy' is NULL;",
+        "Return the arc tangent of a coordinate ('numericx', 'numericy')."
+}, examples = {
+        "atan2(1, 1) = 0.7853981633974483",
+        "atan2(1, 0) = 1.5707963267948966",
+        "atan2(0, -1) = 3.141592653589793"
+})
 public class Atan2Function implements ValueParser {
 
     private ValueParser xParser;
@@ -47,8 +56,8 @@ public Object parse(SourceData sourceData, int rowIndex, Context context) {
         Object xObj = xParser.parse(sourceData, rowIndex, context);
         Object yObj = yParser.parse(sourceData, rowIndex, context);
 
-        if (xObj == null) {
-            throw new NullPointerException("Parsed number object on the x-axis is null");
+        if (xObj == null || yObj == null) {
+            return null;
         }
 
         BigDecimal xValue = OperatorTools.parseBigDecimal(xObj);

inlong-sdk/transform-sdk/src/main/java/org/apache/inlong/sdk/transform/process/function/arithmetic/Atan2dFunction.java

@@ -28,10 +28,19 @@
 import java.math.BigDecimal;
 
 /**
- * Atan2dFunction
- * description: asind(numeric)--returns the arc sine of numeric in units of degrees
+ * Atan2dFunction  ->  atan2d(numericx,numericy)
+ * description:
+ * - Return NULL if 'numericx' or 'numericy' is NULL;
+ * - Return inverse tangent of 'numericy'/'numericx', result in degrees.
  */
-@TransformFunction(names = {"atan2d"})
+@TransformFunction(names = {"atan2d"}, parameter = "(Numeric numericx, Numeric numericy)", descriptions = {
+        "- Return \"\" if 'numericx' or 'numericy' is NULL;",
+        "- Return inverse tangent of 'numericy'/'numericx', result in degrees."
+}, examples = {
+        "atan2d(1, 1) = 45.0",
+        "atan2d(1, 0) = 90.0",
+        "atan2d(0, -1) = 180.0"
+})
 public class Atan2dFunction implements ValueParser {
 
     private ValueParser xParser;
@@ -47,8 +56,8 @@ public Object parse(SourceData sourceData, int rowIndex, Context context) {
         Object xObj = xParser.parse(sourceData, rowIndex, context);
         Object yObj = yParser.parse(sourceData, rowIndex, context);
 
-        if (xObj == null) {
-            throw new NullPointerException("Parsed number object on the x-axis is null");
+        if (xObj == null || yObj == null) {
+            return null;
         }
 
         BigDecimal xValue = OperatorTools.parseBigDecimal(xObj);

inlong-sdk/transform-sdk/src/main/java/org/apache/inlong/sdk/transform/process/function/arithmetic/AtanFunction.java

@@ -28,10 +28,19 @@
 import java.math.BigDecimal;
 
 /**
- * AtanFunction
- * description: atan(numeric)--returns the arc tangent of numeric
+ * AtanFunction  ->  atan(numeric)
+ * description:
+ * - Return NULL if 'numeric' is NULL;
+ * - Return the arc tangent of 'numeric'.
  */
-@TransformFunction(names = {"atan"})
+@TransformFunction(names = {"atan"}, parameter = "(Numeric numeric)", descriptions = {
+        "- Return \"\" if 'numeric' is NULL;",
+        "- Return the arc tangent of 'numeric'."
+}, examples = {
+        "atan(1) = 0.7853981633974483",
+        "atan(0) = 0.0",
+        "atan(-1) = -0.7853981633974483"
+})
 public class AtanFunction implements ValueParser {
 
     private ValueParser numberParser;
@@ -43,6 +52,9 @@ public AtanFunction(Function expr) {
     @Override
     public Object parse(SourceData sourceData, int rowIndex, Context context) {
         Object numberObj = numberParser.parse(sourceData, rowIndex, context);
+        if (numberObj == null) {
+            return null;
+        }
         BigDecimal numberValue = OperatorTools.parseBigDecimal(numberObj);
         return Math.atan(numberValue.doubleValue());
     }