Package com.faunadb.client

Class FaunaClient

java.lang.Object

com.faunadb.client.FaunaClient

public class FaunaClient
extends Object

The Java native client for FaunaDB.

The client is asynchronous. All methods that performs latent operations return an instance of CompletableFuture.

Queries are constructed by using the static methods in the Language class.

Example:

 import static com.faunadb.client.query.Language.*;

 FaunaClient client = FaunaClient.builder()
   .withSecret("someAuthToken")
   .build();

 client.query(
   Get(
     Ref(Collection("some_collection"), "123")
   )
 );
 
 

See Also:

Language

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	FaunaClient.Builder	A builder for creating an instance of FaunaClient

Method Summary

Modifier and Type	Method	Description
static FaunaClient.Builder	builder()	Creates a new FaunaClient.Builder
long	getLastTxnTime()	Get the freshest timestamp reported to this client.
FaunaClient	newSessionClient(String secret)	Creates a session client with the user secret provided.
CompletableFuture<Value>	query(Expr expr)	Issues a Query to FaunaDB.
CompletableFuture<List<Value>>	query(Expr... exprs)	Issues multiple queries to FaunaDB.
CompletableFuture<Value>	query(Expr expr, Duration timeout)	Issues a Query to FaunaDB.
CompletableFuture<Value>	query(Expr expr, Optional<Duration> timeout)	Issues a Query to FaunaDB.
CompletableFuture<List<Value>>	query(List<? extends Expr> exprs)	Issues multiple queries to FaunaDB.
CompletableFuture<List<Value>>	query(List<? extends Expr> exprs, Duration timeout)	Issues multiple queries to FaunaDB.
CompletableFuture<List<Value>>	query(List<? extends Expr> exprs, Optional<Duration> timeout)	Issues multiple queries to FaunaDB.
CompletableFuture<MetricsResponse>	queryWithMetrics(Expr expr, Optional<Duration> timeout)	Issues a Query to FaunaDB with extra information
CompletableFuture<Flow.Publisher<Value>>	stream(Expr expr)	Creates a subscription to the result of the given read-only expression.
CompletableFuture<Flow.Publisher<Value>>	stream(Expr expr, List<EventField> fields, boolean snapshot)	Creates a subscription to the result of the given read-only expression.
void	syncLastTxnTime(long timestamp)	Sync the freshest timestamp seen by this client.

Methods inherited from class java.lang.Object

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

Method Detail

builder

public static FaunaClient.Builder builder()

Creates a new FaunaClient.Builder

Returns:

FaunaClient.Builder

newSessionClient

public FaunaClient newSessionClient(String secret)

Creates a session client with the user secret provided. Queries submitted to a session client will be authenticated with the secret provided. A session client shares its parent's Connection instance.

Parameters:

secret - user secret for the session client

Returns:

a new FaunaClient

query

public CompletableFuture<Value> query(Expr expr)

Issues a Query to FaunaDB.

Queries are constructed by the helper methods in the Language class.

Responses are represented as structured tree where each node is a Value instance. Value instances can be converted to native types. See Value class for details.

Parameters:

expr - the query to be executed.

Returns:

a CompletableFuture containing the root node of the response tree.

See Also:

Value, Language

query

public CompletableFuture<Value> query(Expr expr,
                                      Duration timeout)

Issues a Query to FaunaDB.

Queries are constructed by the helper methods in the Language class.

Responses are represented as structured tree where each node is a Value instance. Value instances can be converted to native types. See Value class for details.

Parameters:

expr - the query to be executed.

timeout - the timeout for the current query. It replaces the timeout value set for this FaunaClient (if any), for the scope of this query. The timeout value has milliseconds precision.

Returns:

a CompletableFuture containing the root node of the response tree.

See Also:

Value, Language

query

public CompletableFuture<Value> query(Expr expr,
                                      Optional<Duration> timeout)

Issues a Query to FaunaDB.

Queries are constructed by the helper methods in the Language class.

Responses are represented as structured tree where each node is a Value instance. Value instances can be converted to native types. See Value class for details.

Parameters:

expr - the query to be executed.

timeout - the timeout for the current query. It replaces the timeout value set for this FaunaClient (if any), for the scope of this query. The timeout value has milliseconds precision.

Returns:

a CompletableFuture containing the root node of the response tree.

See Also:

Value, Language

queryWithMetrics

public CompletableFuture<MetricsResponse> queryWithMetrics(Expr expr,
                                                           Optional<Duration> timeout)

Issues a Query to FaunaDB with extra information

Queries are constructed by the helper methods in the Language class.

Responses are represented as structured tree where each node is a Value instance. Value instances can be converted to native types. See Value class for details.

Parameters:

expr - the query to be executed.

timeout - the timeout for the current query. It replaces the timeout value set for this FaunaClient (if any), for the scope of this query. The timeout value has milliseconds precision.

Returns:

a CompletableFuture containing the root node of the response tree.

See Also:

MetricsResponse, Language

query

public CompletableFuture<List<Value>> query(Expr... exprs)

Issues multiple queries to FaunaDB.

These queries are sent to FaunaDB in a single request. A list containing all responses is returned in the same order as the issued queries.

Parameters:

exprs - the list of queries to be sent to FaunaDB.

Returns:

a CompletableFuture containing an ordered list of the query's responses.

query

public CompletableFuture<List<Value>> query(List<? extends Expr> exprs)

Issues multiple queries to FaunaDB.

These queries are sent to FaunaDB in a single request. A list containing all responses is returned in the same order as the issued queries.

Parameters:

exprs - the list of queries to be sent to FaunaDB.

Returns:

a CompletableFuture containing an ordered list of the query's responses.

query

public CompletableFuture<List<Value>> query(List<? extends Expr> exprs,
                                            Duration timeout)

Issues multiple queries to FaunaDB.

These queries are sent to FaunaDB in a single request. A list containing all responses is returned in the same order as the issued queries.

Parameters:

exprs - the list of queries to be sent to FaunaDB.

timeout - the timeout for the current query. It replaces the timeout value set for this FaunaClient (if any), for the scope of this query. The timeout value has milliseconds precision.

Returns:

a CompletableFuture containing an ordered list of the query's responses.

query

public CompletableFuture<List<Value>> query(List<? extends Expr> exprs,
                                            Optional<Duration> timeout)

Issues multiple queries to FaunaDB.

These queries are sent to FaunaDB in a single request. A list containing all responses is returned in the same order as the issued queries.

Parameters:

exprs - the list of queries to be sent to FaunaDB.

timeout - the timeout for the current query. It replaces the timeout value set for this FaunaClient (if any), for the scope of this query. The timeout value has milliseconds precision.

Returns:

a CompletableFuture containing an ordered list of the query's responses.

syncLastTxnTime

public void syncLastTxnTime(long timestamp)

Sync the freshest timestamp seen by this client.

This has no effect if staler than currently stored timestamp.

WARNING: This should be used only when coordinating timestamps across multiple clients. Moving the timestamp arbitrarily forward into the future will cause transactions to stall.

getLastTxnTime

public long getLastTxnTime()

Get the freshest timestamp reported to this client.

stream

public CompletableFuture<Flow.Publisher<Value>> stream(Expr expr)

Creates a subscription to the result of the given read-only expression. When executed, the expression must only perform reads and produce a single streamable type, such as a reference or a version. Expressions that attempt to perform writes or produce non-streamable types will result in an error. Otherwise, any expression can be used to initiate a stream, including user-defined function calls.

Parameters:

expr - the query to subscribe to.

Returns:

a CompletableFuture containing a Flow.Publisher of Value.

See Also:

Value, Language

stream

public CompletableFuture<Flow.Publisher<Value>> stream(Expr expr,
                                                       List<EventField> fields,
                                                       boolean snapshot)

Creates a subscription to the result of the given read-only expression. When executed, the expression must only perform reads and produce a single streamable type, such as a reference or a version. Expressions that attempt to perform writes or produce non-streamable types will result in an error. Otherwise, any expression can be used to initiate a stream, including user-defined function calls.

Parameters:

expr - the query to subscribe to.

fields - fields to opt-in on the events.

snapshot - if true the second event will be a snapshot event of the target

Returns:

a CompletableFuture containing a Flow.Publisher of Value.

See Also:

Value, Language