1 package org.influxdb;
2
3 import org.influxdb.dto.BatchPoints;
4 import org.influxdb.dto.Point;
5 import org.influxdb.dto.Pong;
6 import org.influxdb.dto.Query;
7 import org.influxdb.dto.QueryResult;
8 import retrofit2.Call;
9
10 import java.util.List;
11 import java.util.concurrent.ThreadFactory;
12 import java.util.concurrent.TimeUnit;
13 import java.util.function.BiConsumer;
14 import java.util.function.Consumer;
15
16 /**
17 * Interface with all available methods to access a InfluxDB database.
18 *
19 * A full list of currently available interfaces is implemented in:
20 *
21 * <a
22 * href="https://github.com/influxdb/influxdb/blob/master/src/api/http/api.go">https://github.com/
23 * influxdb/influxdb/blob/master/src/api/http/api.go</a>
24 *
25 * @author stefan.majer [at] gmail.com
26 *
27 */
28 public interface InfluxDB extends AutoCloseable {
29
30 /**
31 * The system property key to set the http logging level across the JVM.
32 * @see LogLevel for available values
33 */
34 public static final String LOG_LEVEL_PROPERTY = "org.influxdb.InfluxDB.logLevel";
35
36 /** Controls the level of logging of the REST layer. */
37 public enum LogLevel {
38 /** No logging. */
39 NONE,
40 /** Log only the request method and URL and the response status code and execution time. */
41 BASIC,
42 /** Log the basic information along with request and response headers. */
43 HEADERS,
44 /**
45 * Log the headers, body, and metadata for both requests and responses.
46 * <p>
47 * Note: This requires that the entire request and response body be buffered in memory!
48 */
49 FULL;
50 /**
51 * Parses the string argument as a LogLevel constant.
52 * @param value a {@code String} containing the {@code LogLevel constant}
53 * representation to be parsed
54 * @return the LogLevel constant representation of the param
55 * or {@code NONE} for null or any invalid String representation.
56 */
57 public static LogLevel parseLogLevel(final String value) {
58 LogLevel logLevel = NONE;
59 if (value != null) {
60 try {
61 logLevel = valueOf(value.toUpperCase());
62 } catch (IllegalArgumentException e) {
63 }
64 }
65
66 return logLevel;
67 }
68 }
69
70 /**
71 * ConsistencyLevel for write Operations.
72 */
73 public enum ConsistencyLevel {
74 /** Write succeeds only if write reached all cluster members. */
75 ALL("all"),
76 /** Write succeeds if write reached any cluster members. */
77 ANY("any"),
78 /** Write succeeds if write reached at least one cluster members. */
79 ONE("one"),
80 /** Write succeeds only if write reached a quorum of cluster members. */
81 QUORUM("quorum");
82 private final String value;
83
84 private ConsistencyLevel(final String value) {
85 this.value = value;
86 }
87
88 /**
89 * Get the String value of the ConsistencyLevel.
90 *
91 * @return the lowercase String.
92 */
93 public String value() {
94 return this.value;
95 }
96 }
97
98 /**
99 * Format of HTTP Response body from InfluxDB server.
100 */
101 public enum ResponseFormat {
102 /** application/json format. */
103 JSON,
104 /** application/x-msgpack format. */
105 MSGPACK
106 }
107
108 /**
109 * A cancelable allows to discontinue a streaming query.
110 */
111 public interface Cancellable {
112
113 /**
114 * Cancel the streaming query call.
115 *
116 * @see Call#cancel()
117 */
118 void cancel();
119
120 /**
121 * Return {@code true} if the {@link Cancellable#cancel()} was called.
122 *
123 * @return {@code true} if the {@link Cancellable#cancel()} was called
124 * @see Call#isCanceled()
125 */
126 boolean isCanceled();
127 }
128
129 /**
130 * Set the loglevel which is used for REST related actions.
131 *
132 * @param logLevel
133 * the loglevel to set.
134 * @return the InfluxDB instance to be able to use it in a fluent manner.
135 */
136 public InfluxDB setLogLevel(final LogLevel logLevel);
137
138 /**
139 * Enable Gzip compress for http request body.
140 * @return the InfluxDB instance to be able to use it in a fluent manner.
141 */
142 public InfluxDB enableGzip();
143
144 /**
145 * Disable Gzip compress for http request body.
146 * @return the InfluxDB instance to be able to use it in a fluent manner.
147 */
148 public InfluxDB disableGzip();
149
150 /**
151 * Returns whether Gzip compress for http request body is enabled.
152 * @return true if gzip is enabled.
153 */
154 public boolean isGzipEnabled();
155
156 /**
157 * Enable batching of single Point writes to speed up writes significantly. This is the same as calling
158 * InfluxDB.enableBatch(BatchOptions.DEFAULTS)
159 * @return the InfluxDB instance to be able to use it in a fluent manner.
160 */
161 public InfluxDB enableBatch();
162
163 /**
164 * Enable batching of single Point writes to speed up writes significantly. If either number of points written or
165 * flushDuration time limit is reached, a batch write is issued.
166 * Note that batch processing needs to be explicitly stopped before the application is shutdown.
167 * To do so call disableBatch().
168 *
169 * @param batchOptions
170 * the options to set for batching the writes.
171 * @return the InfluxDB instance to be able to use it in a fluent manner.
172 */
173 public InfluxDB enableBatch(final BatchOptions batchOptions);
174
175 /**
176 * Enable batching of single Point writes as {@link #enableBatch(int, int, TimeUnit, ThreadFactory)}}
177 * using {@linkplain java.util.concurrent.Executors#defaultThreadFactory() default thread factory}.
178 *
179 * @param actions
180 * the number of actions to collect
181 * @param flushDuration
182 * the time to wait at most.
183 * @param flushDurationTimeUnit
184 * the TimeUnit for the given flushDuration.
185 *
186 * @see #enableBatch(int, int, TimeUnit, ThreadFactory)
187 *
188 * @return the InfluxDB instance to be able to use it in a fluent manner.
189 */
190 public InfluxDB enableBatch(final int actions, final int flushDuration, final TimeUnit flushDurationTimeUnit);
191
192 /**
193 * Enable batching of single Point writes as
194 * {@link #enableBatch(int, int, TimeUnit, ThreadFactory, BiConsumer)}
195 * using with a exceptionHandler that does nothing.
196 *
197 * @param actions
198 * the number of actions to collect
199 * @param flushDuration
200 * the time to wait at most.
201 * @param flushDurationTimeUnit
202 * the TimeUnit for the given flushDuration.
203 * @param threadFactory
204 * a ThreadFactory instance to be used.
205 *
206 * @see #enableBatch(int, int, TimeUnit, ThreadFactory, BiConsumer)
207 *
208 * @return the InfluxDB instance to be able to use it in a fluent manner.
209 */
210 public InfluxDB enableBatch(final int actions, final int flushDuration, final TimeUnit flushDurationTimeUnit,
211 final ThreadFactory threadFactory);
212 /**
213 * Enable batching of single Point writes with consistency set for an entire batch
214 * flushDurations is reached first, a batch write is issued.
215 * Note that batch processing needs to be explicitly stopped before the application is shutdown.
216 * To do so call disableBatch(). Default consistency is ONE.
217 *
218 * @param actions
219 * the number of actions to collect
220 * @param flushDuration
221 * the time to wait at most.
222 * @param flushDurationTimeUnit
223 * the TimeUnit for the given flushDuration.
224 * @param threadFactory
225 * a ThreadFactory instance to be used.
226 * @param exceptionHandler
227 * a consumer function to handle asynchronous errors
228 * @param consistency
229 * a consistency setting for batch writes.
230 * @return the InfluxDB instance to be able to use it in a fluent manner.
231 */
232
233 InfluxDB enableBatch(int actions, int flushDuration, TimeUnit flushDurationTimeUnit,
234 ThreadFactory threadFactory, BiConsumer<Iterable<Point>, Throwable> exceptionHandler,
235 ConsistencyLevel consistency);
236
237 /**
238 * Enable batching of single Point writes to speed up writes significant. If either actions or
239 * flushDurations is reached first, a batch write is issued.
240 * Note that batch processing needs to be explicitly stopped before the application is shutdown.
241 * To do so call disableBatch().
242 *
243 * @param actions
244 * the number of actions to collect
245 * @param flushDuration
246 * the time to wait at most.
247 * @param flushDurationTimeUnit
248 * the TimeUnit for the given flushDuration.
249 * @param threadFactory
250 * a ThreadFactory instance to be used.
251 * @param exceptionHandler
252 * a consumer function to handle asynchronous errors
253 * @return the InfluxDB instance to be able to use it in a fluent manner.
254 */
255 public InfluxDB enableBatch(final int actions, final int flushDuration, final TimeUnit flushDurationTimeUnit,
256 final ThreadFactory threadFactory,
257 final BiConsumer<Iterable<Point>, Throwable> exceptionHandler);
258
259 /**
260 * Disable Batching.
261 */
262 public void disableBatch();
263
264 /**
265 * Returns whether Batching is enabled.
266 * @return true if batch is enabled.
267 */
268 public boolean isBatchEnabled();
269
270 /**
271 * Ping this influxDB.
272 *
273 * @return the response of the ping execution.
274 */
275 public Pong ping();
276
277 /**
278 * Return the version of the connected influxDB Server.
279 *
280 * @return the version String, otherwise unknown.
281 */
282 public String version();
283
284 /**
285 * Write a single Point to the default database.
286 *
287 * @param point
288 * The point to write
289 */
290 public void write(final Point point);
291
292 /**
293 * Write a set of Points to the default database with the string records.
294 *
295 * @param records
296 * the points in the correct lineprotocol.
297 */
298 public void write(final String records);
299
300 /**
301 * Write a set of Points to the default database with the list of string records.
302 *
303 * @param records
304 * the List of points in the correct lineprotocol.
305 */
306 public void write(final List<String> records);
307
308 /**
309 * Write a single Point to the database.
310 *
311 * @param database
312 * the database to write to.
313 * @param retentionPolicy
314 * the retentionPolicy to use.
315 * @param point
316 * The point to write
317 */
318 public void write(final String database, final String retentionPolicy, final Point point);
319
320 /**
321 * Write a single Point to the database through UDP.
322 *
323 * @param udpPort
324 * the udpPort to write to.
325 * @param point
326 * The point to write.
327 */
328 public void write(final int udpPort, final Point point);
329
330 /**
331 * Write a set of Points to the influxdb database with the new (>= 0.9.0rc32) lineprotocol.
332 *
333 * @see <a href="https://github.com/influxdb/influxdb/pull/2696">2696</a>
334 *
335 * @param batchPoints
336 * the points to write in BatchPoints.
337 */
338 public void write(final BatchPoints batchPoints);
339
340 /**
341 * Write a set of Points to the influxdb database with the new (>= 0.9.0rc32) lineprotocol.
342 *
343 * If batching is enabled with appropriate {@code BatchOptions} settings
344 * ({@code BatchOptions.bufferLimit} greater than {@code BatchOptions.actions})
345 * This method will try to retry in case of some recoverable errors.
346 * Otherwise it just works as {@link #write(BatchPoints)}
347 *
348 * @see <a href="https://github.com/influxdb/influxdb/pull/2696">2696</a>
349 * @see <a href="https://github.com/influxdata/influxdb-java/wiki/Handling-errors-of-InfluxDB-under-high-load">
350 * Retry worth errors</a>
351 *
352 * @param batchPoints
353 * the points to write in BatchPoints.
354 */
355 public void writeWithRetry(final BatchPoints batchPoints);
356
357 /**
358 * Write a set of Points to the influxdb database with the string records.
359 *
360 * @see <a href="https://github.com/influxdb/influxdb/pull/2696">2696</a>
361 *
362 * @param database
363 * the name of the database to write
364 * @param retentionPolicy
365 * the retentionPolicy to use
366 * @param consistency
367 * the ConsistencyLevel to use
368 * @param records
369 * the points in the correct lineprotocol.
370 */
371 public void write(final String database, final String retentionPolicy,
372 final ConsistencyLevel consistency, final String records);
373
374 /**
375 * Write a set of Points to the influxdb database with the string records.
376 *
377 * @see <a href="https://github.com/influxdb/influxdb/pull/2696">2696</a>
378 *
379 * @param database
380 * the name of the database to write
381 * @param retentionPolicy
382 * the retentionPolicy to use
383 * @param consistency
384 * the ConsistencyLevel to use
385 * @param precision
386 * the time precision to use
387 * @param records
388 * the points in the correct lineprotocol.
389 */
390 public void write(final String database, final String retentionPolicy,
391 final ConsistencyLevel consistency, final TimeUnit precision, final String records);
392
393 /**
394 * Write a set of Points to the influxdb database with the list of string records.
395 *
396 * @see <a href="https://github.com/influxdb/influxdb/pull/2696">2696</a>
397 *
398 * @param database
399 * the name of the database to write
400 * @param retentionPolicy
401 * the retentionPolicy to use
402 * @param consistency
403 * the ConsistencyLevel to use
404 * @param records
405 * the List of points in the correct lineprotocol.
406 */
407 public void write(final String database, final String retentionPolicy,
408 final ConsistencyLevel consistency, final List<String> records);
409
410 /**
411 * Write a set of Points to the influxdb database with the list of string records.
412 *
413 * @see <a href="https://github.com/influxdb/influxdb/pull/2696">2696</a>
414 *
415 * @param database
416 * the name of the database to write
417 * @param retentionPolicy
418 * the retentionPolicy to use
419 * @param consistency
420 * the ConsistencyLevel to use
421 * @param precision
422 * the time precision to use
423 * @param records
424 * the List of points in the correct lineprotocol.
425 */
426 public void write(final String database, final String retentionPolicy,
427 final ConsistencyLevel consistency, final TimeUnit precision, final List<String> records);
428
429 /**
430 * Write a set of Points to the influxdb database with the string records through UDP.
431 *
432 * @param udpPort
433 * the udpPort where influxdb is listening
434 * @param records
435 * the content will be encoded by UTF-8 before sent.
436 */
437 public void write(final int udpPort, final String records);
438
439 /**
440 * Write a set of Points to the influxdb database with the list of string records through UDP.
441 *
442 * @param udpPort
443 * the udpPort where influxdb is listening
444 * @param records
445 * list of record, the content will be encoded by UTF-8 before sent.
446 */
447 public void write(final int udpPort, final List<String> records);
448
449 /**
450 * Execute a query against a database.
451 *
452 * @param query
453 * the query to execute.
454 * @return a List of Series which matched the query.
455 */
456 public QueryResult query(final Query query);
457
458 /**
459 * Execute a query against a database.
460 *
461 * One of the consumers will be executed.
462 *
463 * @param query
464 * the query to execute.
465 * @param onSuccess
466 * the consumer to invoke when result is received
467 * @param onFailure
468 * the consumer to invoke when error is thrown
469 */
470 public void query(final Query query, final Consumer<QueryResult> onSuccess, final Consumer<Throwable> onFailure);
471
472 /**
473 * Execute a streaming query against a database.
474 *
475 * @param query
476 * the query to execute.
477 * @param chunkSize
478 * the number of QueryResults to process in one chunk.
479 * @param onNext
480 * the consumer to invoke for each received QueryResult
481 */
482 public void query(Query query, int chunkSize, Consumer<QueryResult> onNext);
483
484 /**
485 * Execute a streaming query against a database.
486 *
487 * @param query
488 * the query to execute.
489 * @param chunkSize
490 * the number of QueryResults to process in one chunk.
491 * @param onNext
492 * the consumer to invoke for each received QueryResult; with capability to discontinue a streaming query
493 */
494 public void query(Query query, int chunkSize, BiConsumer<Cancellable, QueryResult> onNext);
495
496 /**
497 * Execute a streaming query against a database.
498 *
499 * @param query
500 * the query to execute.
501 * @param chunkSize
502 * the number of QueryResults to process in one chunk.
503 * @param onNext
504 * the consumer to invoke for each received QueryResult
505 * @param onComplete
506 * the onComplete to invoke for successfully end of stream
507 */
508 public void query(Query query, int chunkSize, Consumer<QueryResult> onNext, Runnable onComplete);
509
510 /**
511 * Execute a streaming query against a database.
512 *
513 * @param query
514 * the query to execute.
515 * @param chunkSize
516 * the number of QueryResults to process in one chunk.
517 * @param onNext
518 * the consumer to invoke for each received QueryResult; with capability to discontinue a streaming query
519 * @param onComplete
520 * the onComplete to invoke for successfully end of stream
521 */
522 public void query(Query query, int chunkSize, BiConsumer<Cancellable, QueryResult> onNext, Runnable onComplete);
523
524 /**
525 * Execute a streaming query against a database.
526 *
527 * @param query
528 * the query to execute.
529 * @param chunkSize
530 * the number of QueryResults to process in one chunk.
531 * @param onNext
532 * the consumer to invoke for each received QueryResult; with capability to discontinue a streaming query
533 * @param onComplete
534 * the onComplete to invoke for successfully end of stream
535 * @param onFailure
536 * the consumer for error handling
537 */
538 public void query(Query query, int chunkSize, BiConsumer<Cancellable, QueryResult> onNext, Runnable onComplete,
539 Consumer<Throwable> onFailure);
540
541 /**
542 * Execute a query against a database.
543 *
544 * @param query
545 * the query to execute.
546 * @param timeUnit the time unit of the results.
547 * @return a List of Series which matched the query.
548 */
549 public QueryResult query(final Query query, TimeUnit timeUnit);
550
551 /**
552 * Create a new Database.
553 *
554 * @param name
555 * the name of the new database.
556 * @deprecated (since 2.9, removed in 3.0) Use <code>org.influxdb.InfluxDB.query(Query)</code>
557 * to execute a parameterized <strong>CREATE DATABASE</strong> query.
558 */
559 @Deprecated
560 public void createDatabase(final String name);
561
562 /**
563 * Delete a database.
564 *
565 * @param name
566 * the name of the database to delete.
567 * @deprecated (since 2.9, removed in 3.0) Use <code>org.influxdb.InfluxDB.query(Query)</code>
568 * to execute a <strong>DROP DATABASE</strong> query.
569 */
570 @Deprecated
571 public void deleteDatabase(final String name);
572
573 /**
574 * Describe all available databases.
575 *
576 * @return a List of all Database names.
577 * @deprecated (since 2.9, removed in 3.0) Use <code>org.influxdb.InfluxDB.query(Query)</code>
578 * to execute a <strong>SHOW DATABASES</strong> query.
579 */
580 @Deprecated
581 public List<String> describeDatabases();
582
583 /**
584 * Check if a database exists.
585 *
586 * @param name
587 * the name of the database to search.
588 *
589 * @return true if the database exists or false if it doesn't exist
590 * @deprecated (since 2.9, removed in 3.0) Use <code>org.influxdb.InfluxDB.query(Query)</code>
591 * to execute a <strong>SHOW DATABASES</strong> query and inspect the result.
592 */
593 @Deprecated
594 public boolean databaseExists(final String name);
595
596 /**
597 * Send any buffered points to InfluxDB. This method is synchronous and will block while all pending points are
598 * written.
599 *
600 * @throws IllegalStateException if batching is not enabled.
601 */
602 public void flush();
603
604 /**
605 * close thread for asynchronous batch write and UDP socket to release resources if need.
606 */
607 public void close();
608
609 /**
610 * Set the consistency level which is used for writing points.
611 *
612 * @param consistency
613 * the consistency level to set.
614 * @return the InfluxDB instance to be able to use it in a fluent manner.
615 */
616 public InfluxDB setConsistency(final ConsistencyLevel consistency);
617
618 /**
619 * Set the database which is used for writing points.
620 *
621 * @param database
622 * the database to set.
623 * @return the InfluxDB instance to be able to use it in a fluent manner.
624 */
625 public InfluxDB setDatabase(final String database);
626
627 /**
628 * Set the retention policy which is used for writing points.
629 *
630 * @param retentionPolicy
631 * the retention policy to set.
632 * @return the InfluxDB instance to be able to use it in a fluent manner.
633 */
634 public InfluxDB setRetentionPolicy(final String retentionPolicy);
635
636 /**
637 * Creates a retentionPolicy.
638 * @param rpName the name of the retentionPolicy(rp)
639 * @param database the name of the database
640 * @param duration the duration of the rp
641 * @param shardDuration the shardDuration
642 * @param replicationFactor the replicationFactor of the rp
643 * @param isDefault if the rp is the default rp for the database or not
644 * @deprecated (since 2.9, removed in 3.0) Use <code>org.influxdb.InfluxDB.query(Query)</code>
645 * to execute a parameterized <strong>CREATE RETENTION POLICY</strong> query.
646 */
647 @Deprecated
648 public void createRetentionPolicy(final String rpName, final String database, final String duration,
649 final String shardDuration, final int replicationFactor, final boolean isDefault);
650
651 /**
652 * Creates a retentionPolicy. (optional shardDuration)
653 * @param rpName the name of the retentionPolicy(rp)
654 * @param database the name of the database
655 * @param duration the duration of the rp
656 * @param replicationFactor the replicationFactor of the rp
657 * @param isDefault if the rp is the default rp for the database or not
658 * @deprecated (since 2.9, removed in 3.0) Use <code>org.influxdb.InfluxDB.query(Query)</code>
659 * to execute a parameterized <strong>CREATE RETENTION POLICY</strong> query.
660 */
661 @Deprecated
662 public void createRetentionPolicy(final String rpName, final String database, final String duration,
663 final int replicationFactor, final boolean isDefault);
664
665 /**
666 * Creates a retentionPolicy. (optional shardDuration and isDefault)
667 * @param rpName the name of the retentionPolicy(rp)
668 * @param database the name of the database
669 * @param duration the duration of the rp
670 * @param shardDuration the shardDuration
671 * @param replicationFactor the replicationFactor of the rp
672 * @deprecated (since 2.9, removed in 3.0) Use <code>org.influxdb.InfluxDB.query(Query)</code>
673 * to execute a parameterized <strong>CREATE RETENTION POLICY</strong> query.
674 */
675 @Deprecated
676 public void createRetentionPolicy(final String rpName, final String database, final String duration,
677 final String shardDuration, final int replicationFactor);
678
679 /**
680 * Drops a retentionPolicy in a database.
681 * @param rpName the name of the retentionPolicy
682 * @param database the name of the database
683 * @deprecated (since 2.9, removed in 3.0) Use <code>org.influxdb.InfluxDB.query(Query)</code>
684 * to execute a <strong>DROP RETENTION POLICY</strong> query.
685 */
686 @Deprecated
687 public void dropRetentionPolicy(final String rpName, final String database);
688 }
689