InfluxDB.java

package org.influxdb;

import org.influxdb.dto.BatchPoints;
import org.influxdb.dto.Point;
import org.influxdb.dto.Pong;
import org.influxdb.dto.Query;
import org.influxdb.dto.QueryResult;

import java.util.List;
import java.util.concurrent.ThreadFactory;
import java.util.concurrent.TimeUnit;
import java.util.function.BiConsumer;
import java.util.function.Consumer;

/**
 * Interface with all available methods to access a InfluxDB database.
 *
 * A full list of currently available interfaces is implemented in:
 *
 * <a
 * href="https://github.com/influxdb/influxdb/blob/master/src/api/http/api.go">https://github.com/
 * influxdb/influxdb/blob/master/src/api/http/api.go</a>
 *
 * @author stefan.majer [at] gmail.com
 *
 */
public interface InfluxDB {

  /** Controls the level of logging of the REST layer. */
  public enum LogLevel {
    /** No logging. */
    NONE,
    /** Log only the request method and URL and the response status code and execution time. */
    BASIC,
    /** Log the basic information along with request and response headers. */
    HEADERS,
    /**
     * Log the headers, body, and metadata for both requests and responses.
     * <p>
     * Note: This requires that the entire request and response body be buffered in memory!
     */
    FULL;
  }

  /**
   * ConsistencyLevel for write Operations.
   */
  public enum ConsistencyLevel {
    /** Write succeeds only if write reached all cluster members. */
    ALL("all"),
    /** Write succeeds if write reached any cluster members. */
    ANY("any"),
    /** Write succeeds if write reached at least one cluster members. */
    ONE("one"),
    /** Write succeeds only if write reached a quorum of cluster members. */
    QUORUM("quorum");
    private final String value;

    private ConsistencyLevel(final String value) {
      this.value = value;
    }

    /**
     * Get the String value of the ConsistencyLevel.
     *
     * @return the lowercase String.
     */
    public String value() {
      return this.value;
    }
  }

  /**
   * Set the loglevel which is used for REST related actions.
   *
   * @param logLevel
   *            the loglevel to set.
   * @return the InfluxDB instance to be able to use it in a fluent manner.
   */
  public InfluxDB setLogLevel(final LogLevel logLevel);

  /**
   * Enable Gzip compress for http request body.
   * @return the InfluxDB instance to be able to use it in a fluent manner.
   */
  public InfluxDB enableGzip();

  /**
   * Disable Gzip compress for http request body.
   * @return the InfluxDB instance to be able to use it in a fluent manner.
   */
  public InfluxDB disableGzip();

  /**
   * Returns whether Gzip compress for http request body is enabled.
   * @return true if gzip is enabled.
   */
  public boolean isGzipEnabled();

  /**
   * Enable batching of single Point writes as {@link #enableBatch(int, int, TimeUnit, ThreadFactory)}}
   * using {@linkplain java.util.concurrent.Executors#defaultThreadFactory() default thread factory}.
   *
   * @param actions
   *            the number of actions to collect
   * @param flushDuration
   *            the time to wait at most.
   * @param flushDurationTimeUnit
   *            the TimeUnit for the given flushDuration.
   *
   * @see #enableBatch(int, int, TimeUnit, ThreadFactory)
   *
   * @return the InfluxDB instance to be able to use it in a fluent manner.
   */
  public InfluxDB enableBatch(final int actions, final int flushDuration, final TimeUnit flushDurationTimeUnit);

  /**
   * Enable batching of single Point writes as
   * {@link #enableBatch(int, int, TimeUnit, ThreadFactory, BiConsumer)}
   * using with a exceptionHandler that does nothing.
   *
   * @param actions
   *            the number of actions to collect
   * @param flushDuration
   *            the time to wait at most.
   * @param flushDurationTimeUnit
   *            the TimeUnit for the given flushDuration.
   * @param threadFactory
   *            a ThreadFactory instance to be used.
   *
   * @see #enableBatch(int, int, TimeUnit, ThreadFactory, BiConsumer)
   *
   * @return the InfluxDB instance to be able to use it in a fluent manner.
   */
  public InfluxDB enableBatch(final int actions, final int flushDuration, final TimeUnit flushDurationTimeUnit,
                              final ThreadFactory threadFactory);

  /**
   * Enable batching of single Point writes to speed up writes significant. If either actions or
   * flushDurations is reached first, a batch write is issued.
   * Note that batch processing needs to be explicitly stopped before the application is shutdown.
   * To do so call disableBatch().
   *
   * @param actions
   *            the number of actions to collect
   * @param flushDuration
   *            the time to wait at most.
   * @param flushDurationTimeUnit
   *            the TimeUnit for the given flushDuration.
   * @param threadFactory
   *            a ThreadFactory instance to be used.
   * @param exceptionHandler
   *            a consumer function to handle asynchronous errors
   * @return the InfluxDB instance to be able to use it in a fluent manner.
   */
  public InfluxDB enableBatch(final int actions, final int flushDuration, final TimeUnit flushDurationTimeUnit,
                              final ThreadFactory threadFactory,
                              final BiConsumer<Iterable<Point>, Throwable> exceptionHandler);

  /**
   * Disable Batching.
   */
  public void disableBatch();

  /**
   * Returns whether Batching is enabled.
   * @return true if batch is enabled.
   */
  public boolean isBatchEnabled();

  /**
   * Ping this influxDB.
   *
   * @return the response of the ping execution.
   */
  public Pong ping();

  /**
   * Return the version of the connected influxDB Server.
   *
   * @return the version String, otherwise unknown.
   */
  public String version();

  /**
   * Write a single Point to the default database.
   *
   * @param point
   *            The point to write
   */
  public void write(final Point point);

  /**
   * Write a set of Points to the default database with the string records.
   *
   * @param records
   *            the points in the correct lineprotocol.
   */
  public void write(final String records);

  /**
   * Write a set of Points to the default database with the list of string records.
   *
   * @param records
   *            the List of points in the correct lineprotocol.
   */
  public void write(final List<String> records);

  /**
   * Write a single Point to the database.
   *
   * @param database
   *            the database to write to.
   * @param retentionPolicy
   *            the retentionPolicy to use.
   * @param point
   *            The point to write
   */
  public void write(final String database, final String retentionPolicy, final Point point);

  /**
   * Write a single Point to the database through UDP.
   *
   * @param udpPort
   *            the udpPort to write to.
   * @param point
   *            The point to write.
   */
  public void write(final int udpPort, final Point point);

  /**
   * Write a set of Points to the influxdb database with the new (&gt;= 0.9.0rc32) lineprotocol.
   *
   * @see <a href="https://github.com/influxdb/influxdb/pull/2696">2696</a>
   *
   * @param batchPoints
   *            the points to write in BatchPoints.
   */
  public void write(final BatchPoints batchPoints);

  /**
   * Write a set of Points to the influxdb database with the string records.
   *
   * @see <a href="https://github.com/influxdb/influxdb/pull/2696">2696</a>
   *
   * @param database
   *          the name of the database to write
   * @param retentionPolicy
   *          the retentionPolicy to use
   * @param consistency
   *          the ConsistencyLevel to use
   * @param records
   *            the points in the correct lineprotocol.
   */
  public void write(final String database, final String retentionPolicy,
                    final ConsistencyLevel consistency, final String records);

  /**
   * Write a set of Points to the influxdb database with the list of string records.
   *
   * @see <a href="https://github.com/influxdb/influxdb/pull/2696">2696</a>
   *
   * @param database
   *          the name of the database to write
   * @param retentionPolicy
   *          the retentionPolicy to use
   * @param consistency
   *          the ConsistencyLevel to use
   * @param records
   *          the List of points in the correct lineprotocol.
   */
  public void write(final String database, final String retentionPolicy,
                    final ConsistencyLevel consistency, final List<String> records);

  /**
   * Write a set of Points to the influxdb database with the string records through UDP.
   *
   * @param udpPort
  *           the udpPort where influxdb is listening
   * @param records
   *          the content will be encoded by UTF-8 before sent.
   */
  public void write(final int udpPort, final String records);

  /**
   * Write a set of Points to the influxdb database with the list of string records through UDP.
   *
   * @param udpPort
   *           the udpPort where influxdb is listening
   * @param records
   *           list of record, the content will be encoded by UTF-8 before sent.
   */
  public void write(final int udpPort, final List<String> records);

  /**
   * Execute a query against a database.
   *
   * @param query
   *            the query to execute.
   * @return a List of Series which matched the query.
   */
  public QueryResult query(final Query query);

  /**
   * Execute a streaming query against a database.
   *
   * @param query
   *            the query to execute.
   * @param chunkSize
   *            the number of QueryResults to process in one chunk.
   * @param consumer
   *            the consumer to invoke for each received QueryResult
   */
    public void query(Query query, int chunkSize, Consumer<QueryResult> consumer);

  /**
   * Execute a query against a database.
   *
   * @param query
   *            the query to execute.
   * @param timeUnit the time unit of the results.
   * @return a List of Series which matched the query.
   */
  public QueryResult query(final Query query, TimeUnit timeUnit);

  /**
   * Create a new Database.
   *
   * @param name
   *            the name of the new database.
   */
  public void createDatabase(final String name);

  /**
   * Delete a database.
   *
   * @param name
   *            the name of the database to delete.
   */
  public void deleteDatabase(final String name);

  /**
   * Describe all available databases.
   *
   * @return a List of all Database names.
   */
  public List<String> describeDatabases();

  /**
   * Check if a database exists.
   *
   * @param name
   *            the name of the database to search.
   *
   * @return true if the database exists or false if it doesn't exist
   */
  public boolean databaseExists(final String name);

  /**
   * Send any buffered points to InfluxDB. This method is synchronous and will block while all pending points are
   * written.
   *
   * @throws IllegalStateException if batching is not enabled.
   */
  public void flush();

  /**
   * close thread for asynchronous batch write and UDP socket to release resources if need.
   */
  public void close();

  /**
   * Set the consistency level which is used for writing points.
   *
   * @param consistency
   *            the consistency level to set.
   * @return the InfluxDB instance to be able to use it in a fluent manner.
   */
  public InfluxDB setConsistency(final ConsistencyLevel consistency);

  /**
   * Set the database which is used for writing points.
   *
   * @param database
   *            the database to set.
   * @return the InfluxDB instance to be able to use it in a fluent manner.
   */
  public InfluxDB setDatabase(final String database);

  /**
   * Set the retention policy which is used for writing points.
   *
   * @param retentionPolicy
   *            the retention policy to set.
   * @return the InfluxDB instance to be able to use it in a fluent manner.
   */
  public InfluxDB setRetentionPolicy(final String retentionPolicy);

  /**
   * Creates a retentionPolicy.
   * @param rpName the name of the retentionPolicy(rp)
   * @param database the name of the database
   * @param duration the duration of the rp
   * @param shardDuration the shardDuration
   * @param replicationFactor the replicationFactor of the rp
   * @param isDefault if the rp is the default rp for the database or not
   */
  public void createRetentionPolicy(final String rpName, final String database, final String duration,
                                    final String shardDuration, final int replicationFactor, final boolean isDefault);

  /**
   * Creates a retentionPolicy. (optional shardDuration)
   * @param rpName the name of the retentionPolicy(rp)
   * @param database the name of the database
   * @param duration the duration of the rp
   * @param replicationFactor the replicationFactor of the rp
   * @param isDefault if the rp is the default rp for the database or not
   */
  public void createRetentionPolicy(final String rpName, final String database, final String duration,
                                    final int replicationFactor, final boolean isDefault);

  /**
   * Creates a retentionPolicy. (optional shardDuration and isDefault)
   * @param rpName the name of the retentionPolicy(rp)
   * @param database the name of the database
   * @param duration the duration of the rp
   * @param replicationFactor the replicationFactor of the rp
   */
  public void createRetentionPolicy(final String rpName, final String database, final String duration,
                                    final String shardDuration, final int replicationFactor);

  /**
   * Drops a retentionPolicy in a database.
   * @param rpName the name of the retentionPolicy
   * @param database the name of the database
   */
  public void dropRetentionPolicy(final String rpName, final String database);
}