com.github.nickrm.jflux.api

Class JFluxHttpClient

java.lang.Object

com.github.nickrm.jflux.api.JFluxHttpClient

All Implemented Interfaces:

AutoCloseable

public final class JFluxHttpClient
extends Object
implements AutoCloseable

Makes calls to the InfluxDB HTTP API.

Since:

1.0.0

See Also:

JFluxHttpClient.Builder

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	JFluxHttpClient.Builder Used to construct JFluxHttpClient instances.

Method Summary

Modifier and Type	Method and Description
ApiResponse	batchQuery(String query) Executes a query and returns the result.
void	close()
void	execute(String statement) Executes DDL statements, such as CREATE or ALTER.
String	getHostUrl() Gets the URL of the InfluxDB instance this client is pointed to.
ResponseMetadata	ping() Tests the connection to the InfluxDB API and returns the result.
Measurement	query(String query) Executes a query and returns the result.
QueryResult	queryMultipleSeries(String query) Executes a query and returns the result.
ApiResponse	write(String database, String lineProtocol) Writes points into the default retention policy.
ApiResponse	write(String database, String retentionPolicy, String lineProtocol) Writes points into the specified retention policy.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getHostUrl

public String getHostUrl()

Gets the URL of the InfluxDB instance this client is pointed to.

Returns:

the InfluxDB host URL

ping

public ResponseMetadata ping()
                      throws IOException

Tests the connection to the InfluxDB API and returns the result.

Returns:

metadata about the InfluxDB instance

Throws:

IOException - if the instance is not reachable

query

public Measurement query(String query)
                  throws IOException

Executes a query and returns the result.

This method expects that the query will produce a single result, i.e. is a single statement, querying a single measurement. The following example query can be executed with this method:

 SELECT * FROM measurement_1
 

The following queries will result in an exception:

 SELECT * FROM measurement_1, measurement_2
 SELECT * FROM measurement_1; SELECT * FROM measurement_2
 

For multi-series or batch queries, see queryMultipleSeries(String) and batchQuery(String) respectively instead.

Parameters:

query - the query to execute

Returns:

the query result, or null if no results

Throws:

IllegalStatementException - if the query format is invalid

IOException - if query execution fails

See Also:

queryMultipleSeries(String), batchQuery(String)

queryMultipleSeries

public QueryResult queryMultipleSeries(String query)
                                throws IOException

Executes a query and returns the result.

This method can be used to query across multiple series. Queries such as the following can be used:

 SELECT * FROM measurement_1, measurement_2
 

Note that while single series queries are possible with this method, the responsibility of unwrapping the result falls then on the caller. For a more convenient way of executing single series queries see query(String).

Parameters:

query - the query to execute

Returns:

the query result

Throws:

IllegalStatementException - if the query format is invalid

IOException - if query execution fails

See Also:

query(String), batchQuery(String)

batchQuery

public ApiResponse batchQuery(String query)
                       throws IOException

Executes a query and returns the result.

This method can be used to execute multiple queries at once, spanning one or more measurements. Queries such as the following can be executed:

 SELECT * FROM measurement_1; SELECT * FROM measurement_2, measurement_3;
 

Note that while single statement and/or single series queries are also possible with this method, the responsibility of unwrapping the result falls then on the caller. For more convenient ways of executing single statement and single series queries see query(String) and queryMultipleSeries(String).

Parameters:

query - the query to execute

Returns:

the query result

Throws:

IllegalStatementException - if the query format is invalid

IOException - if query execution fails

See Also:

query(String), queryMultipleSeries(String)

execute

public void execute(String statement)
             throws IOException

Executes DDL statements, such as CREATE or ALTER.

Parameters:

statement - the statement to execute

Throws:

IOException - if execution fails

write

public ApiResponse write(String database,
                         String lineProtocol)
                  throws IOException

Writes points into the default retention policy.

Points to be written are specified using InfluxDB's line protocol format. Multiple points can be written by separating them with a \n character.

Parameters:

database - the database to write to

lineProtocol - the point(s) to write

Returns:

the API's response

Throws:

IOException - if InfluxDB cannot be reached

InfluxClientException - if the points are not in the correct format

write

public ApiResponse write(String database,
                         String retentionPolicy,
                         String lineProtocol)
                  throws IOException

Writes points into the specified retention policy.

Points to be written are specified using InfluxDB's line protocol format. Multiple points can be written by separating them with a \n character.

Parameters:

database - the database to write to

retentionPolicy - the retention policy to use

lineProtocol - the point(s) to write

Returns:

the API's response

Throws:

IOException - if InfluxDB cannot be reached

InfluxClientException - if the points are not in the correct format

close

public void close()

Specified by:

close in interface AutoCloseable