Added pre tag to keep formatting for incorrectly formatted java docs.

Author: MitchellGale

core/src/main/java/org/opensearch/sql/executor/pagination/CanPaginateVisitor.java

@@ -41,16 +41,21 @@
 import org.opensearch.sql.expression.function.BuiltinFunctionName;
 
 /**
- * Use this unresolved plan visitor to check if a plan can be serialized by PaginatedPlanCache. If
- *
- * <pre>plan.accept(new CanPaginateVisitor(...))</pre>
- *
- * returns <em>true</em>, then PaginatedPlanCache.convertToCursor will succeed. Otherwise, it will
- * fail. The purpose of this visitor is to activate legacy engine fallback mechanism. Currently, V2
- * engine does not support queries with: - aggregation (GROUP BY clause or aggregation functions
- * like min/max) - in memory aggregation (window function) - LIMIT/OFFSET clause(s) - without FROM
- * clause - JOIN - a subquery V2 also requires that the table being queried should be an OpenSearch
- * index. See PaginatedPlanCache.canConvertToCursor for usage.
+ * <pre>
+ * Use this unresolved plan visitor to check if a plan can be serialized by PaginatedPlanCache.
+ * If <pre>plan.accept(new CanPaginateVisitor(...))</pre> returns <em>true</em>,
+ * then PaginatedPlanCache.convertToCursor will succeed. Otherwise, it will fail.
+ * The purpose of this visitor is to activate legacy engine fallback mechanism.
+ * Currently, V2 engine does not support queries with:
+ * - aggregation (GROUP BY clause or aggregation functions like min/max)
+ * - in memory aggregation (window function)
+ * - LIMIT/OFFSET clause(s)
+ * - without FROM clause
+ * - JOIN
+ * - a subquery
+ * V2 also requires that the table being queried should be an OpenSearch index.
+ * See PaginatedPlanCache.canConvertToCursor for usage.
+ * </pre>
  */
 public class CanPaginateVisitor extends AbstractNodeVisitor<Boolean, Object> {
 

core/src/main/java/org/opensearch/sql/expression/ExpressionNodeVisitor.java

@@ -82,9 +82,12 @@ public T visitNamedAggregator(NamedAggregator node, C context) {
   }
 
   /**
-   * Call visitFunction() by default rather than visitChildren(). This makes CASE/WHEN able to be
-   * handled: 1) by visitFunction() if not overwritten: ex. FilterQueryBuilder 2) by
-   * visitCase/When() otherwise if any special logic: ex. ExprReferenceOptimizer
+   * <pre>
+   * Call visitFunction() by default rather than visitChildren().
+   * This makes CASE/WHEN able to be handled:
+   *  1) by visitFunction() if not overwritten: ex. FilterQueryBuilder
+   *  2) by visitCase/When() otherwise if any special logic: ex. ExprReferenceOptimizer
+   * </pre>
    */
   public T visitCase(CaseClause node, C context) {
     return visitFunction(node, context);

core/src/main/java/org/opensearch/sql/expression/ReferenceExpression.java

@@ -61,21 +61,39 @@ public String toString() {
   }
 
   /**
-   * Resolve the ExprValue from {@link ExprTupleValue} using paths. Considering the following sample
-   * data. { "name": "bob smith" "project.year": 1990, "project": { "year": "2020" } "address": {
-   * "state": "WA", "city": "seattle", "project.year": 1990 } "address.local": { "state": "WA", } }
-   * The paths could be 1. top level, e.g. "name", which will be resolved as "bob smith" 2. multiple
-   * paths, e.g. "name.address.state", which will be resolved as "WA" 3. special case, the "." is
-   * the path separator, but it is possible that the path include ".", for handling this use case,
-   * we define the resolve rule as bellow, e.g. "project.year" is resolved as 1990 instead of 2020.
-   * Note. This logic only applied top level none object field. e.g. "address.local.state" been
-   * resolved to Missing. but "address.project.year" could been resolved as 1990.
+   * <pre>
+   * Resolve the ExprValue from {@link ExprTupleValue} using paths.
+   * Considering the following sample data.
+   * {
+   *   "name": "bob smith"
+   *   "project.year": 1990,
+   *   "project": {
+   *     "year": "2020"
+   *   }
+   *   "address": {
+   *     "state": "WA",
+   *     "city": "seattle",
+   *     "project.year": 1990
+   *   }
+   *   "address.local": {
+   *     "state": "WA",
+   *   }
+   * }
+   * The paths could be
+   * 1. top level, e.g. "name", which will be resolved as "bob smith"
+   * 2. multiple paths, e.g. "name.address.state", which will be resolved as "WA"
+   * 3. special case, the "." is the path separator, but it is possible that the path include
+   * ".", for handling this use case, we define the resolve rule as bellow, e.g. "project.year" is
+   * resolved as 1990 instead of 2020. Note. This logic only applied top level none object field.
+   * e.g. "address.local.state" been resolved to Missing. but "address.project.year" could been
+   * resolved as 1990.
    *
    * <p>Resolve Rule 1. Resolve the full name by combine the paths("x"."y"."z") as whole ("x.y.z").
    * 2. Resolve the path recursively through ExprValue.
    *
    * @param value {@link ExprTupleValue}.
    * @return {@link ExprTupleValue}.
+   * <pre>
    */
   public ExprValue resolve(ExprTupleValue value) {
     return resolve(value, paths);

core/src/main/java/org/opensearch/sql/expression/aggregation/AggregatorFunction.java

@@ -34,9 +34,14 @@
 import org.opensearch.sql.expression.function.FunctionSignature;
 
 /**
- * The definition of aggregator function avg, Accepts two numbers and produces a number. sum,
- * Accepts two numbers and produces a number. max, Accepts two numbers and produces a number. min,
- * Accepts two numbers and produces a number. count, Accepts two numbers and produces a number.
+ * <pre>
+ * The definition of aggregator function
+ * avg, Accepts two numbers and produces a number.
+ * sum, Accepts two numbers and produces a number.
+ * max, Accepts two numbers and produces a number.
+ * min, Accepts two numbers and produces a number.
+ * count, Accepts two numbers and produces a number.
+ * </pre>
  */
 @UtilityClass
 public class AggregatorFunction {

core/src/main/java/org/opensearch/sql/expression/datetime/DateTimeFunction.java

@@ -847,11 +847,15 @@ private DefaultFunctionResolver subdate() {
   }
 
   /**
-   * Subtracts expr2 from expr1 and returns the result. (TIME, TIME/DATE/DATETIME/TIMESTAMP) -> TIME
-   * (DATE/DATETIME/TIMESTAMP, TIME/DATE/DATETIME/TIMESTAMP) -> DATETIME TODO: MySQL has these
-   * signatures too (STRING, STRING/TIME) -> STRING // second arg - string with time only (x,
-   * STRING) -> NULL // second arg - string with timestamp (x, STRING/DATE) -> x // second arg -
-   * string with date only
+   * <pre>
+   * Subtracts expr2 from expr1 and returns the result.
+   * (TIME, TIME/DATE/DATETIME/TIMESTAMP) -> TIME
+   * (DATE/DATETIME/TIMESTAMP, TIME/DATE/DATETIME/TIMESTAMP) -> DATETIME
+   * TODO: MySQL has these signatures too
+   * (STRING, STRING/TIME) -> STRING               // second arg - string with time only
+   * (x, STRING) -> NULL                           // second arg - string with timestamp
+   * (x, STRING/DATE) -> x                         // second arg - string with date only
+   * </pre>
    */
   private DefaultFunctionResolver subtime() {
     return define(
@@ -954,11 +958,17 @@ private DefaultFunctionResolver time() {
   }
 
   /**
-   * Returns different between two times as a time. (TIME, TIME) -> TIME MySQL has these signatures
-   * too (DATE, DATE) -> TIME // result is > 24 hours (DATETIME, DATETIME) -> TIME // result is > 24
-   * hours (TIMESTAMP, TIMESTAMP) -> TIME // result is > 24 hours (x, x) -> NULL // when args have
-   * different types (STRING, STRING) -> TIME // argument strings contain same types only (STRING,
-   * STRING) -> NULL // argument strings are different types
+   * <pre>
+   * Returns different between two times as a time.
+   * (TIME, TIME) -> TIME
+   * MySQL has these signatures too
+   * (DATE, DATE) -> TIME                      // result is > 24 hours
+   * (DATETIME, DATETIME) -> TIME              // result is > 24 hours
+   * (TIMESTAMP, TIMESTAMP) -> TIME            // result is > 24 hours
+   * (x, x) -> NULL                            // when args have different types
+   * (STRING, STRING) -> TIME                  // argument strings contain same types only
+   * (STRING, STRING) -> NULL                  // argument strings are different types
+   * </pre>
    */
   private DefaultFunctionResolver timediff() {
     return define(
@@ -979,11 +989,14 @@ private DefaultFunctionResolver time_to_sec() {
   }
 
   /**
-   * Extracts the timestamp of a date and time value. Input strings may contain a timestamp only in
-   * format 'yyyy-MM-dd HH:mm:ss[.SSSSSSSSS]' STRING/DATE/TIME/DATETIME/TIMESTAMP -> TIMESTAMP
-   * STRING/DATE/TIME/DATETIME/TIMESTAMP, STRING/DATE/TIME/DATETIME/TIMESTAMP -> TIMESTAMP All types
-   * are converted to TIMESTAMP actually before the function call - it is responsibility of the
-   * automatic cast mechanism defined in `ExprCoreType` and performed by `TypeCastOperator`.
+   * <pre>
+   * Extracts the timestamp of a date and time value.
+   * Input strings may contain a timestamp only in format 'yyyy-MM-dd HH:mm:ss[.SSSSSSSSS]'
+   * STRING/DATE/TIME/DATETIME/TIMESTAMP -> TIMESTAMP
+   * STRING/DATE/TIME/DATETIME/TIMESTAMP, STRING/DATE/TIME/DATETIME/TIMESTAMP -> TIMESTAMP
+   * All types are converted to TIMESTAMP actually before the function call - it is responsibility
+   * of the automatic cast mechanism defined in `ExprCoreType` and performed by `TypeCastOperator`.
+   * </pre>
    */
   private DefaultFunctionResolver timestamp() {
     return define(
@@ -1221,9 +1234,15 @@ private DefaultFunctionResolver yearweek() {
   }
 
   /**
-   * Formats date according to format specifier. First argument is date, second is format. Detailed
-   * supported signatures: (STRING, STRING) -> STRING (DATE, STRING) -> STRING (DATETIME, STRING) ->
-   * STRING (TIME, STRING) -> STRING (TIMESTAMP, STRING) -> STRING
+   * <pre>
+   * Formats date according to format specifier. First argument is date, second is format.
+   * Detailed supported signatures:
+   * (STRING, STRING) -> STRING
+   * (DATE, STRING) -> STRING
+   * (DATETIME, STRING) -> STRING
+   * (TIME, STRING) -> STRING
+   * (TIMESTAMP, STRING) -> STRING
+   * </pre>
    */
   private DefaultFunctionResolver date_format() {
     return define(
@@ -1302,9 +1321,15 @@ private ExprValue exprDateApplyInterval(
   }
 
   /**
-   * Formats date according to format specifier. First argument is time, second is format. Detailed
-   * supported signatures: (STRING, STRING) -> STRING (DATE, STRING) -> STRING (DATETIME, STRING) ->
-   * STRING (TIME, STRING) -> STRING (TIMESTAMP, STRING) -> STRING
+   * <pre>
+   * Formats date according to format specifier. First argument is time, second is format.
+   * Detailed supported signatures:
+   * (STRING, STRING) -> STRING
+   * (DATE, STRING) -> STRING
+   * (DATETIME, STRING) -> STRING
+   * (TIME, STRING) -> STRING
+   * (TIMESTAMP, STRING) -> STRING
+   * </pre>
    */
   private DefaultFunctionResolver time_format() {
     return define(
@@ -1683,14 +1708,18 @@ private ExprValue exprLastDayToday(Clock clock) {
   }
 
   /**
+   * <pre>
    * Following MySQL, function receives arguments of type double and rounds them before use.
-   * Furthermore: - zero year interpreted as 2000 - negative year is not accepted - @dayOfYear
-   * should be greater than 1 - if @dayOfYear is greater than 365/366, calculation goes to the next
-   * year(s)
+   * Furthermore:
+   *  - zero year interpreted as 2000
+   *  - negative year is not accepted
+   *  - @dayOfYear should be greater than 1
+   *  - if @dayOfYear is greater than 365/366, calculation goes to the next year(s)
    *
    * @param yearExpr year
    * @param dayOfYearExp day of the @year, starting from 1
    * @return Date - ExprDateValue object with LocalDate
+   * </pre>
    */
   private ExprValue exprMakeDate(ExprValue yearExpr, ExprValue dayOfYearExp) {
     var year = Math.round(yearExpr.doubleValue());

core/src/main/java/org/opensearch/sql/expression/function/FunctionSignature.java

@@ -27,10 +27,13 @@ public class FunctionSignature {
   private final List<ExprType> paramTypeList;
 
   /**
+   * <pre>
    * calculate the function signature match degree.
    *
-   * @return EXACTLY_MATCH: exactly match NOT_MATCH: not match By widening rule, the small number
-   *     means better match
+   * @return  EXACTLY_MATCH: exactly match
+   *          NOT_MATCH: not match
+   *          By widening rule, the small number means better match
+   * </pre>
    */
   public int match(FunctionSignature functionSignature) {
     List<ExprType> functionTypeList = functionSignature.getParamTypeList();

core/src/main/java/org/opensearch/sql/expression/operator/arthmetic/ArithmeticFunction.java

@@ -29,10 +29,14 @@
 import org.opensearch.sql.expression.function.FunctionName;
 
 /**
- * The definition of arithmetic function add, Accepts two numbers and produces a number. subtract,
- * Accepts two numbers and produces a number. multiply, Accepts two numbers and produces a number.
- * divide, Accepts two numbers and produces a number. module, Accepts two numbers and produces a
- * number.
+ * <pre>
+ * The definition of arithmetic function
+ * add, Accepts two numbers and produces a number.
+ * subtract, Accepts two numbers and produces a number.
+ * multiply, Accepts two numbers and produces a number.
+ * divide, Accepts two numbers and produces a number.
+ * module, Accepts two numbers and produces a number.
+ * </pre>
  */
 @UtilityClass
 public class ArithmeticFunction {
@@ -108,9 +112,11 @@ private static DefaultFunctionResolver addFunction() {
   }
 
   /**
-   * Definition of divide(x, y) function. Returns the number x divided by number y The supported
-   * signature of divide function is (x: BYTE/SHORT/INTEGER/LONG/FLOAT/DOUBLE, y:
-   * BYTE/SHORT/INTEGER/LONG/FLOAT/DOUBLE) -> wider type between types of x and y
+   * Definition of divide(x, y) function.
+   * Returns the number x divided by number y
+   * The supported signature of divide function is
+   * (x: BYTE/SHORT/INTEGER/LONG/FLOAT/DOUBLE, y: BYTE/SHORT/INTEGER/LONG/FLOAT/DOUBLE)
+   * -> wider type between types of x and y
    */
   private static DefaultFunctionResolver divideBase(FunctionName functionName) {
     return define(
@@ -256,9 +262,15 @@ private static DefaultFunctionResolver modulusFunction() {
   }
 
   /**
-   * Definition of multiply(x, y) function. Returns the number x multiplied by number y The
-   * supported signature of multiply function is (x: BYTE/SHORT/INTEGER/LONG/FLOAT/DOUBLE, y:
-   * BYTE/SHORT/INTEGER/LONG/FLOAT/DOUBLE) -> wider type between types of x and y
+   * <pre>
+   * Definition of multiply(x, y) function.
+   * Returns the number x multiplied by number y
+   * The supported signature of multiply function is
+   * (x: BYTE/SHORT/INTEGER/LONG/FLOAT/DOUBLE, y: BYTE/SHORT/INTEGER/LONG/FLOAT/DOUBLE)
+   * -> wider type between types of x and y
+   * (x: BYTE/SHORT/INTEGER/LONG/FLOAT/DOUBLE, y: BYTE/SHORT/INTEGER/LONG/FLOAT/DOUBLE)
+   * -> wider type between types of x and y
+   * </pre>
    */
   private static DefaultFunctionResolver multiplyBase(FunctionName functionName) {
     return define(
@@ -308,9 +320,13 @@ private static DefaultFunctionResolver multiplyFunction() {
   }
 
   /**
-   * Definition of subtract(x, y) function. Returns the number x minus number y The supported
-   * signature of subtract function is (x: BYTE/SHORT/INTEGER/LONG/FLOAT/DOUBLE, y:
-   * BYTE/SHORT/INTEGER/LONG/FLOAT/DOUBLE) -> wider type between types of x and y
+   * <pre>
+   * Definition of subtract(x, y) function.
+   * Returns the number x minus number y
+   * The supported signature of subtract function is
+   * (x: BYTE/SHORT/INTEGER/LONG/FLOAT/DOUBLE, y: BYTE/SHORT/INTEGER/LONG/FLOAT/DOUBLE)
+   * -> wider type between types of x and y
+   * </pre>
    */
   private static DefaultFunctionResolver subtractBase(FunctionName functionName) {
     return define(

core/src/main/java/org/opensearch/sql/expression/operator/arthmetic/MathematicalFunction.java

@@ -151,9 +151,13 @@ private static DefaultFunctionResolver ceiling() {
   }
 
   /**
-   * Definition of conv(x, a, b) function. Convert number x from base a to base b The supported
-   * signature of floor function is (STRING, INTEGER, INTEGER) -> STRING (INTEGER, INTEGER, INTEGER)
-   * -> STRING
+   * <pre>
+   * Definition of conv(x, a, b) function.
+   * Convert number x from base a to base b
+   * The supported signature of floor function is
+   * (STRING, INTEGER, INTEGER) -> STRING
+   * (INTEGER, INTEGER, INTEGER) -> STRING
+   * </pre>
    */
   private static DefaultFunctionResolver conv() {
     return define(
@@ -396,9 +400,15 @@ private static DefaultFunctionResolver pi() {
   }
 
   /**
-   * Definition of pow(x, y)/power(x, y) function. Calculate the value of x raised to the power of y
-   * The supported signature of pow/power function is (INTEGER, INTEGER) -> DOUBLE (LONG, LONG) ->
-   * DOUBLE (FLOAT, FLOAT) -> DOUBLE (DOUBLE, DOUBLE) -> DOUBLE
+   * <pre>
+   * Definition of pow(x, y)/power(x, y) function.
+   * Calculate the value of x raised to the power of y
+   * The supported signature of pow/power function is
+   * (INTEGER, INTEGER) -> DOUBLE
+   * (LONG, LONG) -> DOUBLE
+   * (FLOAT, FLOAT) -> DOUBLE
+   * (DOUBLE, DOUBLE) -> DOUBLE
+   * </pre>
    */
   private static DefaultFunctionResolver pow() {
     return define(BuiltinFunctionName.POW.getName(), powerFunctionImpl());
@@ -478,10 +488,15 @@ private static DefaultFunctionResolver rint() {
   }
 
   /**
-   * Definition of round(x)/round(x, d) function. Rounds the argument x to d decimal places, d
-   * defaults to 0 if not specified. The supported signature of round function is (x: INTEGER [, y:
-   * INTEGER]) -> INTEGER (x: LONG [, y: INTEGER]) -> LONG (x: FLOAT [, y: INTEGER]) -> FLOAT (x:
-   * DOUBLE [, y: INTEGER]) -> DOUBLE
+   * <pre>
+   * Definition of round(x)/round(x, d) function.
+   * Rounds the argument x to d decimal places, d defaults to 0 if not specified.
+   * The supported signature of round function is
+   * (x: INTEGER [, y: INTEGER]) -> INTEGER
+   * (x: LONG [, y: INTEGER]) -> LONG
+   * (x: FLOAT [, y: INTEGER]) -> FLOAT
+   * (x: DOUBLE [, y: INTEGER]) -> DOUBLE
+   * </pre>
    */
   private static DefaultFunctionResolver round() {
     return define(
@@ -613,9 +628,15 @@ private static DefaultFunctionResolver cbrt() {
   }
 
   /**
-   * Definition of truncate(x, d) function. Returns the number x, truncated to d decimal places The
-   * supported signature of round function is (x: INTEGER, y: INTEGER) -> LONG (x: LONG, y: INTEGER)
-   * -> LONG (x: FLOAT, y: INTEGER) -> DOUBLE (x: DOUBLE, y: INTEGER) -> DOUBLE
+   * <pre>
+   * Definition of truncate(x, d) function.
+   * Returns the number x, truncated to d decimal places
+   * The supported signature of round function is
+   * (x: INTEGER, y: INTEGER) -> LONG
+   * (x: LONG, y: INTEGER) -> LONG
+   * (x: FLOAT, y: INTEGER) -> DOUBLE
+   * (x: DOUBLE, y: INTEGER) -> DOUBLE
+   * </pre>
    */
   private static DefaultFunctionResolver truncate() {
     return define(