feat: extend flux-dsl (#373)

CHANGELOG.md

@@ -1,5 +1,16 @@
 ## 6.4.0 [unreleased]
 
+### Features
+1. [#373](https://github.com/influxdata/influxdb-client-java/pull/373):
+   * Add ability to define imports for each flux function [FluxDSL]
+   * Add ability use multiple flux expressions [FluxDSL]
+   * Add ability to define custom functions [FluxDSL]
+   * Improve join flux, so it can be nested [FluxDSL]
+   * Add missing parameter variants for RangeFlux amd AggregateWindow [FluxDSL]
+   * Add TruncateTimeColumnFlux [FluxDSL]
+   * Add ArrayFromFlux [FluxDSL]
+   * Add UnionFlux [FluxDSL]
+
 ## 6.3.0 [2022-06-30]
 
 ### Features

flux-dsl/README.md

@@ -4,7 +4,9 @@
 
 - [Function properties](#function-properties)
 - [Supported functions](#supported-functions)
-- [Custom function](#custom-function)
+- [Using Imports](#using-imports)
+- [Add missing functions](#add-missing-functions)
+- [Custom functions](#custom-functions)
 - [Time zones](#time-zones)
 
 ## Function properties
@@ -67,6 +69,19 @@ Flux flux = Flux
     .last();
 ```
 
+### arrayFrom
+
+Constructs a table from an array of records.
+- `rows` - Array of records to construct a table with. [array of records]
+
+```java
+Map<String, Object> record1 = new HashMap<>();
+record1.put("foo",  "bar");
+record1.put("baz",  21.2);
+
+Flux flux = Flux.arrayFrom(record1, record1);
+```
+
 ### custom expressions
 ```java
 Flux flux = Flux.from("telegraf")
@@ -336,6 +351,15 @@ Flux flux = Flux
     .integral(1L, ChronoUnit.MINUTES);
 ```
 
+### interpolateLinear
+the `interpolate.linear` function inserts rows at regular intervals using linear interpolation to determine values for inserted rows.
+- `duration` - Time duration to use when computing the interpolation. [duration]
+```java
+Flux flux = Flux
+    .from("telegraf")
+    .interpolateLinear(1L, ChronoUnit.MINUTES);
+```
+
 ### join
 Join two time series together on time and the list of `on` keys [[doc](http://bit.ly/flux-spec#join)].
 - `tables` - Map of tables to join. Currently only two tables are allowed. [map of tables]
@@ -631,6 +655,16 @@ Flux flux = Flux
     .timeShift(10L, ChronoUnit.HOURS, new String[]{"_time", "custom"});
 ```
 
+### truncateTimeColumn
+Truncates all input time values in the _time to a specified unit. [[doc](http://bit.ly/flux-spec#truncateTimeColumn)].
+- `unit` - Unit of time to truncate to. Has to be defined. [duration]
+```java
+Flux flux = Flux
+    .from("telegraf")
+    .truncateTimeColumn(ChronoUnit.SECONDS);
+```
+
+
 ### skew
 Skew of the results [[doc](http://bit.ly/flux-spec#skew)].
 - `column` - The column on which to operate. Defaults to `_value`. [string]
@@ -783,6 +817,24 @@ Flux flux = Flux
     .toUInt();
 ```
 
+### union
+
+Merges two or more input streams into a single output stream [[doc](http://bit.ly/flux-spec#union)]. 
+- `tables` - the tables to union. [array of flux]
+
+```java
+Flux flux = Flux.union(
+    Flux.from("telegraf1"),
+    Flux.from("telegraf2")
+);
+```
+
+```java
+Flux v1 = Flux.from("telegraf1").asVariable("v1");
+Flux v2 = Flux.from("telegraf1").asVariable("v2");
+Flux flux = Flux.union(v1, v2);
+```
+
 ### window
 Groups the results by a given time range [[doc](http://bit.ly/flux-spec#window)].
 - `every` - Duration of time between windows. Defaults to `period's` value. [duration] 
@@ -817,7 +869,13 @@ Flux flux = Flux
     .yield("0");
 ```
 
-## Custom function
+## Using Imports
+
+Each Flux-Class can add required imports via the `addImport` method.
+For an example take a look at the [custom functions section](#custom-functions) below.
+
+## Add missing functions
+
 We assume that exist custom function measurement that filter measurement by their name. The `Flux` implementation looks like this: 
 
 ```flux
@@ -873,6 +931,109 @@ from(bucket:"telegraf")
     |> sum()
 ```
 
+## Custom functions
+
+### Custom function with a flux implementation
+
+```java
+public static class MyCustomFunction extends AbstractFunctionFlux<MyCustomFunction.MyCustomFunctionCall> {
+
+    public MyCustomFunction() {
+        super("from2",
+                new FromFlux()
+                        .withPropertyValue("bucket", "n"),
+                MyCustomFunctionCall::new,
+                new Parameter("n"));
+        addImport("foo");
+    }
+
+    public static class MyCustomFunctionCall extends AbstractFunctionCallFlux {
+
+        public MyCustomFunctionCall(@Nonnull String name) {
+            super(name);
+        }
+
+        public MyCustomFunctionCall withN(final String n) {
+            this.withPropertyValueEscaped("n", n);
+            return this;
+        }
+    }
+}
+```
+
+usage:
+
+```java
+MyCustomFunction fun = new MyCustomFunction();
+
+Expressions flux = new Expressions(
+    fun,
+    fun.invoke().withN(0)
+);
+flux.toString()
+```
+
+result:
+
+```javascript
+import "foo"
+from2 = (n) => from(bucket: n)
+from2(n:"telegraf")
+```
+
+### Defining a custom function with a freestyle expression
+
+```java
+public static class MultByXFunction extends AbstractFunctionFlux<MultByXFunction.MultByXFunctionCall> {
+
+  public MultByXFunction() {
+    super("multByX",
+            new FreestyleExpression("tables")
+                    .map("(r) => ({r with _value: r._value * x})"),
+            MultByXFunctionCall::new,
+            new Parameter("tables").withPipeForward(true),
+            new Parameter("x"));
+  }
+
+  public static class MultByXFunctionCall extends AbstractFunctionCallFlux {
+
+    public MultByXFunctionCall(@Nonnull String name) {
+      super(name);
+    }
+
+    @Nonnull
+    public MultByXFunctionCall withX(final Number x) {
+      this.withPropertyValue("x", x);
+      return this;
+    }
+  }
+}
+```
+
+usage:
+
+```java
+MultByXFunction multByX = new MultByXFunction();
+Expressions flux = new Expressions(
+    multByX,
+    Flux.from("telegraph")
+        .withPipedFunction(multByX)
+        .withX(42.)
+        .count()
+);
+flux.toString()
+```
+
+result:
+
+```javascript
+multByX = (tables=<-, x) => ()
+	|> map(fn: (r) => (r) => ({r with _value: r._value * x}))
+from(bucket:"telegraph")
+	|> multByX(x:42.0)
+	|> count()
+```
+
 ## Time zones
 
 The Flux option sets the default time zone of all times in the script. The default value is `timezone.utc`.
@@ -955,4 +1116,4 @@ The snapshots are deployed into [OSS Snapshot repository](https://oss.sonatype.o
 repositories {
     maven { url "https://oss.sonatype.org/content/repositories/snapshots" }
 }
-```
+```

flux-dsl/src/main/java/com/influxdb/query/dsl/Expression.java

@@ -0,0 +1,43 @@
+/*
+ * The MIT License
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package com.influxdb.query.dsl;
+
+import java.util.Map;
+import javax.annotation.Nonnull;
+
+import com.influxdb.query.dsl.functions.FreestyleExpression;
+
+/**
+ * Marker interface for Expressions.
+ *
+ * @see com.influxdb.query.dsl.Flux
+ * @see FreestyleExpression
+ */
+public interface Expression extends HasImports {
+
+    /**
+     * @param parameters     parameters to resolve
+     * @param prependImports true, if the imports should be prepended
+     * @return the string representation of the expression
+     */
+    String toString(@Nonnull final Map<String, Object> parameters, final boolean prependImports);
+}