Skip to content

Commit 5e3c581

Browse files
committed
docs: update javadoc comments and add timeout example.
1 parent 5ccacf9 commit 5e3c581

File tree

3 files changed

+109
-13
lines changed

3 files changed

+109
-13
lines changed
Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
/*
2+
* The MIT License
3+
*
4+
* Permission is hereby granted, free of charge, to any person obtaining a copy
5+
* of this software and associated documentation files (the "Software"), to deal
6+
* in the Software without restriction, including without limitation the rights
7+
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8+
* copies of the Software, and to permit persons to whom the Software is
9+
* furnished to do so, subject to the following conditions:
10+
*
11+
* The above copyright notice and this permission notice shall be included in
12+
* all copies or substantial portions of the Software.
13+
*
14+
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15+
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16+
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17+
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18+
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19+
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
20+
* THE SOFTWARE.
21+
*/
22+
package com.influxdb.v3;
23+
24+
import java.time.Duration;
25+
import java.util.concurrent.TimeUnit;
26+
import java.util.stream.Stream;
27+
28+
import com.influxdb.v3.client.InfluxDBClient;
29+
import com.influxdb.v3.client.PointValues;
30+
import com.influxdb.v3.client.config.ClientConfig;
31+
32+
/**
33+
* This example shows how to set universal timeouts for writes and queries.
34+
* <p>
35+
* The example depends on the "influxdb3-java" module and this module should be built first
36+
* by running "mvn install" in the root directory.
37+
*/
38+
public final class TimeoutsExample {
39+
40+
public static String resolveProperty(final String property, final String fallback) {
41+
return System.getProperty(property, System.getenv(property)) == null
42+
? fallback : System.getProperty(property, System.getenv(property));
43+
}
44+
45+
private TimeoutsExample() { }
46+
47+
public static void main(final String[] args) {
48+
// timeout to use for writes. Experiment with lower values to see timeout exceptions.
49+
Duration writeTimeout = Duration.ofMillis(5000L);
50+
// timeout to use for queries. Experiment with lower values to see timeout exceptions.
51+
Duration queryTimeout = Duration.ofMillis(5000L);
52+
53+
String host = resolveProperty("INFLUX_HOST", "http://localhost:8181");
54+
String token = resolveProperty("INFLUX_TOKEN", "my-token");
55+
String database = resolveProperty("INFLUX_DATABASE", "my-database");
56+
57+
String measurement = "timeout_example";
58+
59+
ClientConfig config = new ClientConfig.Builder()
60+
.host(host)
61+
.token(token.toCharArray())
62+
.database(database)
63+
.writeTimeout(writeTimeout) // set timeout to be used with the Write API
64+
.queryTimeout(queryTimeout) // set timeout to be used with the Query API
65+
.build();
66+
67+
try (InfluxDBClient client = InfluxDBClient.getInstance(config)) {
68+
client.writeRecord(String.format("%s,id=0001 temp=30.14,ticks=42i", measurement));
69+
70+
TimeUnit.SECONDS.sleep(1);
71+
String sql = String.format("SELECT * FROM %s ORDER BY time DESC", measurement);
72+
try (Stream<PointValues> values = client.queryPoints(sql)) {
73+
values.forEach(pv -> {
74+
String sv = measurement + ","
75+
+ " id: " + pv.getTag("id") + ","
76+
+ " fVal: " + pv.getFloatField("temp") + ","
77+
+ " iVal: " + pv.getIntegerField("ticks") + ","
78+
+ " " + pv.getTimestamp();
79+
System.out.println(sv);
80+
});
81+
}
82+
} catch (Exception e) {
83+
throw new RuntimeException(e);
84+
}
85+
}
86+
}

src/main/java/com/influxdb/v3/client/config/ClientConfig.java

Lines changed: 20 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -39,8 +39,6 @@
3939
import com.influxdb.v3.client.write.WriteOptions;
4040
import com.influxdb.v3.client.write.WritePrecision;
4141

42-
// TODO ensure that if writeTimeout is not defined but timeout is that writeTimeout is initialized to timeout
43-
4442
/**
4543
* The <code>ClientConfig</code> holds the configurations for the
4644
* {@link com.influxdb.v3.client.InfluxDBClient} client.
@@ -59,7 +57,7 @@
5957
* <li><code>timeout</code> - <i>deprecated in 1.4.0</i> timeout when connecting to InfluxDB,
6058
* please use more informative properties <code>writeTimeout</code> and <code>queryTimeout</code></li>
6159
* <li><code>writeTimeout</code> - timeout when writing data to InfluxDB</li>
62-
* <li><code>queryTimeout</code> - timeout used to calculate a default GRPC deadline when querying InfluxDB.
60+
* <li><code>queryTimeout</code> - timeout used to calculate a default gRPC deadline when querying InfluxDB.
6361
* Can be <code>null</code>, in which case queries can potentially run forever.</li>
6462
* <li><code>allowHttpRedirects</code> - allow redirects for InfluxDB connections</li>
6563
* <li><code>disableServerCertificateValidation</code> -
@@ -212,18 +210,23 @@ public Map<String, String> getDefaultTags() {
212210
}
213211

214212
/**
215-
* Gets the default timeout to use for the API calls. Default to '10 seconds'.
213+
* Gets the default timeout to use for write API calls.
214+
* Defaults to '{@value com.influxdb.v3.client.write.WriteOptions#DEFAULT_WRITE_TIMEOUT} seconds'.
215+
* <p>
216+
* Deprecated in v1.4.0. Please use more informative <code>getWriteTimeout()</code>.
216217
*
217-
* @return the default timeout to use for the API calls
218+
* @return the default timeout to use for write API calls
219+
* @see #getWriteTimeout()
218220
*/
219221
@Nonnull
222+
@Deprecated
220223
public Duration getTimeout() {
221224
return timeout;
222225
}
223226

224227
/**
225228
* Gets the default timeout to use for REST Write API calls. Default is
226-
* {@value com.influxdb.v3.client.write.WriteOptions#DEFAULT_WRITE_TIMEOUT}
229+
* {@value com.influxdb.v3.client.write.WriteOptions#DEFAULT_WRITE_TIMEOUT} seconds.
227230
*
228231
* @return the default timeout to use for REST Write API calls.
229232
*/
@@ -233,10 +236,10 @@ public Duration getWriteTimeout() {
233236
}
234237

235238
/**
236-
* Gets the default timeout in seconds to use for calculating a GRPC Deadline when making Query API calls.
239+
* Gets the default timeout Duration to use for calculating a gRPC Deadline when making Query API calls.
237240
* Can be null, in which case queries can potentially wait or run forever.
238241
*
239-
* @return the default timeout in seconds to use for Query API calls.
242+
* @return the default timeout Duration to use for Query API calls.
240243
*/
241244
@Nullable
242245
public Duration getQueryTimeout() {
@@ -401,6 +404,7 @@ public static final class Builder {
401404
private Integer gzipThreshold;
402405
private Boolean writeNoSync;
403406
private Map<String, String> defaultTags;
407+
@Deprecated
404408
private Duration timeout;
405409
private Duration writeTimeout;
406410
private Duration queryTimeout;
@@ -533,12 +537,16 @@ public Builder defaultTags(@Nullable final Map<String, String> defaultTags) {
533537
}
534538

535539
/**
536-
* Sets the default timeout to use for the API calls. Default to '10 seconds'.
540+
* Sets the default timeout to use for Write API calls. Defaults to
541+
* '{@value com.influxdb.v3.client.write.WriteOptions#DEFAULT_WRITE_TIMEOUT} seconds'.
537542
* <p>
538-
* Note that this parameter is being superseded by clearer writeTimeout.
543+
* Deprecated in v1.4.0. This setter is superseded by the clearer <code>writeTimeout()</code>.
539544
*
540-
* @param timeout default timeout to use for the API calls. Default to '10 seconds'.
545+
* @param timeout default timeout to use for Write API calls. Default to
546+
* ''{@value com.influxdb.v3.client.write.WriteOptions#DEFAULT_WRITE_TIMEOUT} seconds'.
541547
* @return this
548+
*
549+
* @see #writeTimeout(Duration writeTimeout)
542550
*/
543551
@Deprecated
544552
@Nonnull
@@ -564,7 +572,7 @@ public Builder writeTimeout(@Nullable final Duration writeTimeout) {
564572
}
565573

566574
/**
567-
* Sets standard query timeout used to calculate a GRPC deadline when making Query API calls.
575+
* Sets standard query timeout used to calculate a gRPC deadline when making Query API calls.
568576
* If <code>null</code>, queries can potentially wait or run forever.
569577
*
570578
* @param queryTimeout default timeout used to calculate deadline for Query API calls.

src/main/java/com/influxdb/v3/client/internal/GrpcCallOptions.java

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -289,7 +289,7 @@ public Builder withMaxInboundMessageSize(@Nonnull final Integer maxInboundMessag
289289
}
290290

291291
/**
292-
* Helper method to clone already existing options.
292+
* Helper method to clone already existing gRPC options.
293293
*
294294
* @param grpcCallOptions = options to copy
295295
* @return this
@@ -326,6 +326,8 @@ public Builder fromGrpcCallOptions(@Nonnull final GrpcCallOptions grpcCallOption
326326
* @return this
327327
*/
328328
public Builder withMaxOutboundMessageSize(@Nonnull final Integer maxOutboundMessageSize) {
329+
// TODO remove warning about issue 12109 in javadoc above,
330+
// once 12109 is resolved and dependencies are updated.
329331
this.maxOutboundMessageSize = maxOutboundMessageSize;
330332
return this;
331333
}

0 commit comments

Comments
 (0)