docs: Clarify how to use a client with InfluxDB 1.8 (#103)

Author: bednar

CHANGELOG.md

@@ -4,7 +4,10 @@
 1. [#93](https://github.com/influxdata/influxdb-client-java/issues/93): Add addTags and addFields helper functions to Point
 1. [#97](https://github.com/influxdata/influxdb-client-java/pull/97): Add the ability to specify the org and the bucket when creating the client
 
-### Bugs
+### Documentation
+1. [#103](https://github.com/influxdata/influxdb-client-java/pull/103): Clarify how to use a client with InfluxDB 1.8
+
+### Bug Fixes
 1. [#98](https://github.com/influxdata/influxdb-client-java/issues/98): @Column supports super class inheritance for write measurements
 
 ## 1.6.0 [2020-03-13]
@@ -14,7 +17,7 @@
 1. [#83](https://github.com/influxdata/influxdb-client-java/issues/83): Add reduce operator to FluxDSL
 1. [#91](https://github.com/influxdata/influxdb-client-java/pull/91): Set User-Agent to influxdb-client-java/VERSION for all requests
 
-### Bugs
+### Bug Fixes
 1. [#90](https://github.com/influxdata/influxdb-client-java/pull/90): Correctly parse CSV where multiple results include multiple tables
 1. [#89](https://github.com/influxdata/influxdb-client-java/issues/89): @Column supports super class inheritance
 
@@ -25,7 +28,7 @@
 1. [#33](https://github.com/influxdata/influxdb-client-java/issues/33): InfluxDBClient.close also dispose a created writeApi
 1. [#80](https://github.com/influxdata/influxdb-client-java/issues/80): FluxRecord, FluxColumn, FluxTable are serializable
 
-### Bugs
+### Bug Fixes
 1. [#82](https://github.com/influxdata/influxdb-client-java/pull/82): Apply backpressure strategy when a buffer overflow
 
 ## 1.4.0 [2020-01-17]
@@ -41,7 +44,7 @@
 ### API
 1. [#68](https://github.com/influxdata/influxdb-client-java/pull/68): Updated swagger to latest version
 
-### Bugs
+### Bug Fixes
 1. [#69](https://github.com/influxdata/influxdb-client-java/issues/69): Fixed android compatibility
 
 ## 1.2.0 [2019-11-08]
@@ -64,15 +67,15 @@
 ### API
 1. [#58](https://github.com/influxdata/influxdb-client-java/pull/58): Updated swagger to latest version
 
-### Bugs
+### Bug Fixes
 1. [#57](https://github.com/influxdata/influxdb-client-java/pull/57): LabelsApi: orgID parameter has to be pass as second argument
 
 ## 1.0.0 [2019-08-30]
 
 ### Features
 1. [#50](https://github.com/influxdata/influxdb-client-java/issues/50): Added support for gzip compression of query response
 
-### Bugs
+### Bug Fixes
 1. [#48](https://github.com/influxdata/influxdb-client-java/issues/48): The org parameter takes either the ID or Name interchangeably
 1. [#53](https://github.com/influxdata/influxdb-client-java/issues/53): Drop NaN and infinity values from fields when writing to InfluxDB
 
@@ -92,7 +95,7 @@
 1. [#35](https://github.com/influxdata/influxdb-client-java/issues/35): Possibility to specify default tags
 1. [#41](https://github.com/influxdata/influxdb-client-java/issues/41): Synchronous blocking API to Write time-series data into InfluxDB 2.0
 
-### Bugs
+### Bug Fixes
 1. [#43](https://github.com/influxdata/influxdb-client-java/issues/43): The data point without field should be ignored
 
 ### CI

README.md

@@ -11,7 +11,7 @@
 
 This repository contains the reference JVM clients for the InfluxDB 2.0. Currently, Java, Reactive, Kotlin and Scala clients are implemented.
 
-#### Note: Use this client library with InfluxDB 2.x and InfluxDB 1.8+. For connecting to InfluxDB 1.7 or earlier instances, use the [influxdb-java](https://github.com/influxdata/influxdb-java) client library.
+#### Note: Use this client library with InfluxDB 2.x and InfluxDB 1.8+ ([see details](#influxdb-18-api-compatibility)). For connecting to InfluxDB 1.7 or earlier instances, use the [influxdb-java](https://github.com/influxdata/influxdb-java) client library.
 
 - [Features](#features)
 - [Documentation](#documentation)
@@ -281,6 +281,20 @@ public class InfluxDB2ManagementExample {
 }
 ``` 
 
+### InfluxDB 1.8 API compatibility
+
+[InfluxDB 1.8.0 introduced forward compatibility APIs](https://docs.influxdata.com/influxdb/latest/tools/api/#influxdb-2-0-api-compatibility-endpoints) for InfluxDB 2.0. This allow you to easily move from InfluxDB 1.x to InfluxDB 2.0 Cloud or open source.
+
+The following forward compatible APIs are available:
+
+| API | Endpoint | Description |
+|:----------|:----------|:----------|
+| [QueryApi.java](client/src/main/java/com/influxdb/client/QueryApi.java) | [/api/v2/query](https://docs.influxdata.com/influxdb/latest/tools/api/#api-v2-query-http-endpoint) | Query data in InfluxDB 1.8.0+ using the InfluxDB 2.0 API and [Flux](https://docs.influxdata.com/flux/latest/) _(endpoint should be enabled by [`flux-enabled` option](https://docs.influxdata.com/influxdb/latest/administration/config/#flux-enabled-false))_  |
+| [WriteApi.java](client/src/main/java/com/influxdb/client/WriteApi.java) | [/api/v2/write](https://docs.influxdata.com/influxdb/latest/tools/api/#api-v2-write-http-endpoint) | Write data to InfluxDB 1.8.0+ using the InfluxDB 2.0 API |
+| [health()](client/src/main/java/com/influxdb/client/InfluxDBClient.java#L236) | [/health](https://docs.influxdata.com/influxdb/latest/tools/api/#health-http-endpoint) | Check the health of your InfluxDB instance |    
+
+For detail info see [InfluxDB 1.8 example](examples/src/main/java/example/InfluxDB18Example.java).
+
 ### Flux queries in InfluxDB 1.7+
 
 The following example demonstrates querying using the Flux language.

client/src/main/java/com/influxdb/client/InfluxDBClientFactory.java

@@ -152,6 +152,37 @@ public static InfluxDBClient create(@Nonnull final String url,
         return create(options);
     }
 
+    /**
+     * Create a instance of the InfluxDB 2.0 client to connect into InfluxDB 1.8.
+     *
+     * @param url             the url to connect to the InfluxDB 1.8
+     * @param username        authorization username
+     * @param password        authorization password
+     * @param database        database name
+     * @param retentionPolicy retention policy
+     * @return client
+     */
+    @Nonnull
+    public static InfluxDBClient createV1(@Nonnull final String url,
+                                          @Nullable final String username,
+                                          final char[] password,
+                                          @Nonnull final String database,
+                                          @Nullable final String retentionPolicy) {
+
+        Arguments.checkNonEmpty(database, "database");
+
+        InfluxDBClientOptions options = InfluxDBClientOptions.builder()
+                .url(url)
+                .org("-")
+                .authenticateToken(String.format("%s:%s",
+                        username == null ? "" : username,
+                        password == null ? "" : String.valueOf(password)).toCharArray())
+                .bucket(String.format("%s/%s", database, retentionPolicy == null ? "" : retentionPolicy))
+                .build();
+
+        return create(options);
+    }
+
     /**
      * Create an instance of the InfluxDB 2.0 client.
      *

client/src/test/java/com/influxdb/client/InfluxDBClientFactoryTest.java

@@ -159,4 +159,24 @@ void loadFromProperties() throws NoSuchFieldException, IllegalAccessException {
                 .hasEntrySatisfying("version", value -> Assertions.assertThat(value).isEqualTo("${version}"))
                 .hasEntrySatisfying("hostname", value -> Assertions.assertThat(value).isEqualTo("${env.hostname}"));
     }
+
+    @Test
+    void v1Configuration() throws NoSuchFieldException, IllegalAccessException {
+        InfluxDBClient client = InfluxDBClientFactory.createV1("http://localhost:8086", "my-username", "my-password".toCharArray(), "database", "week");
+
+        InfluxDBClientOptions options = getDeclaredField(client, "options", AbstractInfluxDBClient.class);
+
+        Assertions.assertThat(options.getUrl()).isEqualTo("http://localhost:8086");
+        Assertions.assertThat(options.getOrg()).isEqualTo("-");
+        Assertions.assertThat(options.getBucket()).isEqualTo("database/week");
+        Assertions.assertThat(options.getToken()).isEqualTo("my-username:my-password".toCharArray());
+
+        client = InfluxDBClientFactory.createV1("http://localhost:8086", null, null, "database", null);
+
+        options = getDeclaredField(client, "options", AbstractInfluxDBClient.class);
+        Assertions.assertThat(options.getUrl()).isEqualTo("http://localhost:8086");
+        Assertions.assertThat(options.getOrg()).isEqualTo("-");
+        Assertions.assertThat(options.getBucket()).isEqualTo("database/");
+        Assertions.assertThat(options.getToken()).isEqualTo(":".toCharArray());
+    }
 }

examples/src/main/java/example/InfluxDB18Example.java

@@ -0,0 +1,71 @@
+/*
+ * 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 example;
+
+import java.util.List;
+
+import com.influxdb.client.InfluxDBClient;
+import com.influxdb.client.InfluxDBClientFactory;
+import com.influxdb.client.WriteApi;
+import com.influxdb.client.write.Point;
+import com.influxdb.query.FluxTable;
+
+/**
+ * @author Jakub Bednar (16/04/2020 11:00)
+ */
+public class InfluxDB18Example {
+
+    public static void main(final String[] args) {
+
+        String database = "telegraf";
+        String retentionPolicy = "autogen";
+
+        InfluxDBClient client = InfluxDBClientFactory.createV1("http://localhost:8086",
+                "username",
+                "password".toCharArray(),
+                database,
+                retentionPolicy);
+
+        System.out.println("*** Write Points ***");
+
+        try (WriteApi writeApi = client.getWriteApi()) {
+
+            Point point = Point.measurement("mem")
+                    .addTag("host", "host1")
+                    .addField("used_percent", 29.43234543);
+
+            System.out.println(point.toLineProtocol());
+
+            writeApi.writePoint(point);
+        }
+
+        System.out.println("*** Query Points ***");
+        String query = String.format("from(bucket: \"%s/%s\") |> range(start: -1h)", database, retentionPolicy);
+
+        List<FluxTable> tables = client.getQueryApi().query(query);
+        tables.get(0).getRecords()
+                .forEach(record -> System.out.println(String.format("%s %s: %s %s",
+                        record.getTime(), record.getMeasurement(), record.getField(), record.getValue())));
+
+        client.close();
+    }
+}