com.github.nickrm.jflux

Class JFluxClient

java.lang.Object

com.github.nickrm.jflux.JFluxClient

All Implemented Interfaces:

AutoCloseable

public final class JFluxClient
extends Object
implements AutoCloseable

Client for InfluxDB.

Provides convenient abstractions over JFluxHttpClient.

Since:

1.0.0

See Also:

JFluxHttpClient

Nested Class Summary

Nested Classes

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

Method Summary

Modifier and Type	Method and Description
void	alterRetentionPolicy(String retentionPolicyName, RetentionPolicy newDefinition) Alters the specified retention policy.
void	alterRetentionPolicy(String retentionPolicyName, String databaseName, RetentionPolicy newDefinition) Alters the specified retention policy.
void	close()
void	createDatabase(String databaseName) Creates a new database with the specified name.
void	createRetentionPolicy(RetentionPolicy retentionPolicy) Creates a new retention policy on the selected database.
void	createRetentionPolicy(RetentionPolicy retentionPolicy, String databaseName) Creates a new retention policy on the specified database.
boolean	databaseExists(String databaseName) Gets a value indicating whether the specified database exists.
void	dropDatabase(String databaseName) Drops the specified database.
void	dropRetentionPolicy(String retentionPolicyName) Drops the specified retention policy on the selected database.
void	dropRetentionPolicy(String retentionPolicyName, String databaseName) Drops the specified retention policy.
<T> List<T>	getAllPoints(Class<T> targetType) Alias for getAllPoints(String, Class) using a preselected database.
List<Point>	getAllPoints(String measurementName) Alias for getAllPoints(String, String) using a preselected database.
<T> List<T>	getAllPoints(String databaseName, Class<T> targetType) Retrieves all points for the specified class.
List<Point>	getAllPoints(String databaseName, String measurementName) Retrieves all points for the specified measurement.
List<String>	getDatabases() Gets the existing databases.
List<RetentionPolicy>	getRetentionPolicies() Gets all the retention policies defined on the currently selected database.
List<RetentionPolicy>	getRetentionPolicies(String databaseName) Gets all the retention policies defined on the specified database.
RetentionPolicy	getRetentionPolicy(String retentionPolicyName) Gets the definition of the specified retention policy.
RetentionPolicy	getRetentionPolicy(String retentionPolicyName, String databaseName) Gets the definition of the specified retention policy.
boolean	retentionPolicyExists(String retentionPolicyName) Returns a value indicating whether the specified retention policy exists on the selected database.
boolean	retentionPolicyExists(String retentionPolicyName, String databaseName) Returns a value indicating whether the specified retention policy exists on the specified database.
void	useDatabase(String databaseName) Selects a database to use implicitly with methods in this class.
void	write(Collection<?> data) Writes the specified data using the specified retention policy.
void	write(Collection<?> data, String retentionPolicyName) Writes the specified data using the specified retention policy.
void	write(Object data) Alias for write(Collection) for a single object.
void	write(Object data, String retentionPolicyName) Alias for write(Collection, String) for a single point.
void	write(String databaseName, Collection<?> data) Writes the specified data to the specified database, using the default retention policy.
void	write(String databaseName, Collection<?> data, String retentionPolicyName) Writes the specified data to the specified database, using the specified retention policy.
void	write(String databaseName, Object data) Alias for write(String, Collection) for a single point.
void	write(String databaseName, Object data, String retentionPolicyName) Alias for write(String, Collection, String) for a single point.
void	writePoint(String measurementName, Point point) Alias for writePoints(String, Collection) for a single point.
void	writePoint(String measurementName, Point point, String retentionPolicyName) Alias for writePoints(String, Collection, String) for a single point.
void	writePoint(String databaseName, String measurementName, Point point) Alias for writePoints(String, String, Collection) for a single point.
void	writePoint(String databaseName, String measurementName, Point point, String retentionPolicyName) Alias for writePoints(String, String, Collection, String) for a single point.
void	writePoints(String measurementName, Collection<Point> points) Writes the specified points to InfluxDB, using the default retention policy.
void	writePoints(String measurementName, Collection<Point> points, String retentionPolicyName) Writes the specified points to InfluxDB.
void	writePoints(String databaseName, String measurementName, Collection<Point> points) Writes the specified points to InfluxDB, using the default retention policy.
void	writePoints(String databaseName, String measurementName, Collection<Point> points, String retentionPolicyName) Writes the specified points to InfluxDB.

Methods inherited from class java.lang.Object

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

Method Detail

getDatabases

public List<String> getDatabases()

Gets the existing databases.

Returns:

the existing databases, should always contain at least the internal one

databaseExists

public boolean databaseExists(String databaseName)

Gets a value indicating whether the specified database exists.

Parameters:

databaseName - the database name to check, not null

Returns:

true if the database exists, false otherwise

Throws:

IllegalArgumentException - if databaseName is null

createDatabase

public void createDatabase(String databaseName)

Creates a new database with the specified name.

Parameters:

databaseName - the database to create, not null

Throws:

IllegalArgumentException - if databaseName is null

DatabaseAlreadyExistsException - if the database already exists

dropDatabase

public void dropDatabase(String databaseName)

Drops the specified database.

Parameters:

databaseName - the database to drop, not null

Throws:

IllegalArgumentException - if trying to drop the internal InfluxDB database

IllegalArgumentException - if databaseName is null

UnknownDatabaseException - if the database does not exist

useDatabase

public void useDatabase(String databaseName)

Selects a database to use implicitly with methods in this class.

This is convenience method to avoid having to specify the database to perform operations on in every method call, similar to InfluxDB's own USE DATABASE statement.

Parameters:

databaseName - the database to use, not null

Throws:

IllegalArgumentException - if databaseName is null

UnknownDatabaseException - if the specified database does not exist

getRetentionPolicies

public List<RetentionPolicy> getRetentionPolicies()

Gets all the retention policies defined on the currently selected database.

Note that a database must have been already selected with useDatabase(String) before calling this method.

Returns:

the selected database's retention policies

Throws:

NoDatabaseSelectedException - if no database has been selected

getRetentionPolicies

public List<RetentionPolicy> getRetentionPolicies(String databaseName)

Gets all the retention policies defined on the specified database.

Parameters:

databaseName - name of the database to check, not null

Returns:

the database's retention policies

Throws:

UnknownDatabaseException - if the database does not exist

getRetentionPolicy

public RetentionPolicy getRetentionPolicy(String retentionPolicyName)

Gets the definition of the specified retention policy.

Note that a database must have been already selected with useDatabase(String) before calling this method.

Parameters:

retentionPolicyName - the retention policy to get

Returns:

the retention policy definition, or null if not found

Throws:

IllegalArgumentException - if retentionPolicyName is null

NoDatabaseSelectedException - if no database has been selected

getRetentionPolicy

public RetentionPolicy getRetentionPolicy(String retentionPolicyName,
                                          String databaseName)

Gets the definition of the specified retention policy.

Parameters:

retentionPolicyName - the retention policy to get

databaseName - the database the retention policy is defined on

Returns:

the retention policy definition, or null if not found

Throws:

IllegalArgumentException - if retentionPolicyName or databaseName are null

UnknownDatabaseException - if the database does not exist

retentionPolicyExists

public boolean retentionPolicyExists(String retentionPolicyName)

Returns a value indicating whether the specified retention policy exists on the selected database.

Note that a database must have been already selected with useDatabase(String) before calling this method.

Parameters:

retentionPolicyName - the retention policy to check

Returns:

true if the retention policy exists, false otherwise

Throws:

NoDatabaseSelectedException - if no database has been selected

retentionPolicyExists

public boolean retentionPolicyExists(String retentionPolicyName,
                                     String databaseName)

Returns a value indicating whether the specified retention policy exists on the specified database.

Parameters:

retentionPolicyName - the retention policy to check

databaseName - the database to check

Returns:

true if the retention policy exists, false otherwise

Throws:

IllegalArgumentException - if the retention policy or database names are null

UnknownDatabaseException - if the database does not exist

createRetentionPolicy

public void createRetentionPolicy(RetentionPolicy retentionPolicy)

Creates a new retention policy on the selected database.

Note that a database must have been already selected with useDatabase(String) before calling this method.

Parameters:

retentionPolicy - the retention policy to create

Throws:

NoDatabaseSelectedException - if no database has been selected

IllegalArgumentException - if retentionPolicy is null

RetentionPolicyAlreadyExistsException - if the retention policy already exists

createRetentionPolicy

public void createRetentionPolicy(RetentionPolicy retentionPolicy,
                                  String databaseName)

Creates a new retention policy on the specified database.

Parameters:

retentionPolicy - the retention policy to create

databaseName - the database to create the retention policy on

Throws:

IllegalArgumentException - if retentionPolicy or databaseName is null

UnknownDatabaseException - if the database does not exist

RetentionPolicyAlreadyExistsException - if the retention policy already exists

alterRetentionPolicy

public void alterRetentionPolicy(String retentionPolicyName,
                                 RetentionPolicy newDefinition)

Alters the specified retention policy.

Note that the name of the retention policy cannot be altered and thus the original name will always be kept, even if the new definition specifies a different one.

Note also that a database must have been already selected with useDatabase(String) before calling this method.

Parameters:

retentionPolicyName - the retention policy to alter

newDefinition - the new definition for the retention policy

Throws:

NoDatabaseSelectedException - if no database has been selected

IllegalArgumentException - if any of the arguments are null

UnknownRetentionPolicyException - if the retention policy does not exist

alterRetentionPolicy

public void alterRetentionPolicy(String retentionPolicyName,
                                 String databaseName,
                                 RetentionPolicy newDefinition)

Alters the specified retention policy.

Note that the name of the retention policy cannot be altered and thus the original name will always be kept, even if the new definition specifies a different one.

Parameters:

retentionPolicyName - the retention policy to alter

databaseName - the database the retention policy is defined on

newDefinition - the new definition for the retention policy

Throws:

IllegalArgumentException - if any of the arguments are null

UnknownDatabaseException - if the database does not exist

UnknownRetentionPolicyException - if the retention policy does not exist

dropRetentionPolicy

public void dropRetentionPolicy(String retentionPolicyName)

Drops the specified retention policy on the selected database.

Note that a database must have been already selected with useDatabase(String) before calling this method.

Parameters:

retentionPolicyName - the retention policy to drop

Throws:

NoDatabaseSelectedException - if no database has been selected

IllegalArgumentException - if retentionPolicy is null

UnknownRetentionPolicyException - if the retention policy does not exist

dropRetentionPolicy

public void dropRetentionPolicy(String retentionPolicyName,
                                String databaseName)

Drops the specified retention policy.

Parameters:

retentionPolicyName - the retention policy to drop

databaseName - the database the retention policy is defined on

Throws:

IllegalArgumentException - if retentionPolicy or databaseName are null

UnknownDatabaseException - if the database does not exist

UnknownRetentionPolicyException - if the retention policy does not exist

write

public void write(Object data)

Alias for write(Collection) for a single object.

Parameters:

data - the data to write, not null

Throws:

NoDatabaseSelectedException - if no database has been selected

IllegalArgumentException - if data is null

AnnotationProcessingException - if the data object is not correctly annotated

write

public void write(String databaseName,
                  Object data)

Alias for write(String, Collection) for a single point.

Parameters:

databaseName - the database to write to, not null

data - the data to write, not null

Throws:

AnnotationProcessingException - if the data object is not correctly annotated

IllegalArgumentException - if the input data is null

UnknownDatabaseException - if the database does not exist

See Also:

writePoint(String, String, Point)

write

public void write(Collection<?> data)

Writes the specified data using the specified retention policy.

Note that a database must have been already selected with useDatabase(String) before calling this method.

Parameters:

data - the data to write

Throws:

NoDatabaseSelectedException - if no database has been selected

AnnotationProcessingException - if the data objects are not correctly annotated.

write

public void write(String databaseName,
                  Collection<?> data)

Writes the specified data to the specified database, using the default retention policy.

The data object must be annotated in order to be converted to points and written to InfluxDB.

Parameters:

databaseName - the database to write to, not null

data - the data to write

Throws:

AnnotationProcessingException - if the data objects are not correctly annotated

UnknownDatabaseException - if the database does not exist

See Also:

writePoints(String, String, Collection)

write

public void write(Object data,
                  String retentionPolicyName)

Alias for write(Collection, String) for a single point.

Parameters:

data - the data to write, not null

retentionPolicyName - the retention policy to write to, not null

Throws:

NoDatabaseSelectedException - if no database has been selected

IllegalArgumentException - if any of the arguments is null

AnnotationProcessingException - if the data objects are not correctly annotated

UnknownRetentionPolicyException - if the retenion policy does not exist

write

public void write(String databaseName,
                  Object data,
                  String retentionPolicyName)

Alias for write(String, Collection, String) for a single point.

Parameters:

databaseName - the database to write to, not null

data - the data to write, not null

retentionPolicyName - the retention policy to write to, not null

Throws:

AnnotationProcessingException - if the data object is not correctly annotated

UnknownDatabaseException - if the database does not exist

IllegalArgumentException - if the retention policy does not exist

See Also:

writePoint(String, String, Point, String)

write

public void write(Collection<?> data,
                  String retentionPolicyName)

Writes the specified data using the specified retention policy.

Note that a database must have been already selected with useDatabase(String) before calling this method.

Parameters:

data - the data to write

retentionPolicyName - the retention policy to write to, not null

Throws:

NoDatabaseSelectedException - if no database has been selected

IllegalArgumentException - if retentionPolicyName is null

AnnotationProcessingException - if the data objects are not correctly annotated

UnknownRetentionPolicyException - if the retention policy does not exist

write

public void write(String databaseName,
                  Collection<?> data,
                  String retentionPolicyName)

Writes the specified data to the specified database, using the specified retention policy.

The data object must be annotated in order to be converted to points and written to InfluxDB.

Parameters:

databaseName - the database to write to, not null

data - the data to write

retentionPolicyName - the retention policy to write to, not null

Throws:

AnnotationProcessingException - if the data objects are not correctly annotated

UnknownDatabaseException - if the database does not exist

IllegalArgumentException - if the retention policy does not exist

See Also:

writePoints(String, String, Collection, String)

writePoint

public void writePoint(String measurementName,
                       Point point)

Alias for writePoints(String, Collection) for a single point.

Parameters:

measurementName - the measurement to write to, not null

point - the point to write, not null

Throws:

NoDatabaseSelectedException - if no database has been selected

IllegalArgumentException - if any of the arguments is null

writePoint

public void writePoint(String databaseName,
                       String measurementName,
                       Point point)

Alias for writePoints(String, String, Collection) for a single point.

Parameters:

databaseName - the database to write to, not null

measurementName - the measurement to write to, not null

point - the point to write

Throws:

IllegalArgumentException - if the database or measurement name is null

UnknownDatabaseException - if the database does not exist

writePoint

public void writePoint(String measurementName,
                       Point point,
                       String retentionPolicyName)

Alias for writePoints(String, Collection, String) for a single point.

Parameters:

measurementName - the measurement to write to, not null

point - the point to write, not null

retentionPolicyName - the retention policy to write to, not null

Throws:

NoDatabaseSelectedException - if no database has been selected

IllegalArgumentException - if any of the arguments is null

UnknownRetentionPolicyException - if the retention policy does not exist

writePoint

public void writePoint(String databaseName,
                       String measurementName,
                       Point point,
                       String retentionPolicyName)

Alias for writePoints(String, String, Collection, String) for a single point.

Parameters:

databaseName - the database to write to, not null

measurementName - the measurement to write to, not null

point - the point to write

retentionPolicyName - the retention policy to write to, not null

Throws:

UnknownDatabaseException - if the database does not exist

IllegalArgumentException - if the retention policy does not exist

writePoints

public void writePoints(String measurementName,
                        Collection<Point> points)

Writes the specified points to InfluxDB, using the default retention policy.

Note that a database must have been already selected with useDatabase(String) before calling this method.

Parameters:

measurementName - the measurement to write to, not null

points - the points to write

Throws:

NoDatabaseSelectedException - if no database has been selected

IllegalArgumentException - if measurementName is null

writePoints

public void writePoints(String databaseName,
                        String measurementName,
                        Collection<Point> points)

Writes the specified points to InfluxDB, using the default retention policy.

Parameters:

databaseName - the database to write to, not null

measurementName - the measurement to write to, not null

points - the points to write

Throws:

IllegalArgumentException - if the database or measurement name is null

UnknownDatabaseException - if the database does not exist

writePoints

public void writePoints(String measurementName,
                        Collection<Point> points,
                        String retentionPolicyName)

Writes the specified points to InfluxDB.

Note that a database must have been already selected with useDatabase(String) before calling this method.

Parameters:

measurementName - the measurement to write to, not null

points - the points to write

retentionPolicyName - the retention policy to write to, not null

Throws:

NoDatabaseSelectedException - if no database has been selected

IllegalArgumentException - if any of the arguments is null

UnknownRetentionPolicyException - if the retention policy does not exist

writePoints

public void writePoints(String databaseName,
                        String measurementName,
                        Collection<Point> points,
                        String retentionPolicyName)

Writes the specified points to InfluxDB.

Parameters:

databaseName - the database to write to, not null

measurementName - the measurement to write to, not null

points - the points to write

retentionPolicyName - the retention policy to write to, not null

Throws:

UnknownDatabaseException - if the database does not exist

UnknownRetentionPolicyException - if the retention policy does not exist

getAllPoints

public <T> List<T> getAllPoints(Class<T> targetType)

Alias for getAllPoints(String, Class) using a preselected database.

Note that a database must have been already selected with useDatabase(String) before calling this method.

Type Parameters:

T - type of the results

Parameters:

targetType - the class to convert to, not null

Returns:

the points converted to instances of targetType, or an empty list if no results

Throws:

NoDatabaseSelectedException - if no database selected

getAllPoints

public <T> List<T> getAllPoints(String databaseName,
                                Class<T> targetType)

Retrieves all points for the specified class.

The measurement name is read from the class name, or the Measurement annotation if present. The resulting points are converted to instances of the class, setting the values of fields annotated with Timestamp, Field, and Tag.

Type Parameters:

T - type of the results

Parameters:

databaseName - the database where the measurement is found, not null

targetType - the class to convert the results to, not null

Returns:

the points converted to instance of targetType, or an empty list if no results

Throws:

IllegalArgumentException - if databaseName or targetType is null

UnknownDatabaseException - if the database cannot be found

See Also:

AnnotationBasedPointConverter

getAllPoints

public List<Point> getAllPoints(String measurementName)

Alias for getAllPoints(String, String) using a preselected database.

Note that a database must have been already selected with useDatabase(String) before calling this method.

Parameters:

measurementName - the measurement to query, not null

Returns:

the retrieved points, or an empty list if no result or measurement does not exist

Throws:

NoDatabaseSelectedException - if no database has been selected

IllegalArgumentException - if the measurement name is null

getAllPoints

public List<Point> getAllPoints(String databaseName,
                                String measurementName)

Retrieves all points for the specified measurement.

Parameters:

databaseName - the database where the measurement is found, not null

measurementName - the measurement to query, not null

Returns:

the retrieved points, or an empty list if no results or measurement does not exist

Throws:

IllegalArgumentException - if the database or measurement name is null

UnknownDatabaseException - if the database does not exist

close

public void close()
           throws Exception

Specified by:

close in interface AutoCloseable

Throws:

Exception