Package com.fauna.client

Class FaunaClient

java.lang.Object

com.fauna.client.FaunaClient

Direct Known Subclasses:

BaseFaunaClient, ScopedFaunaClient

public abstract class FaunaClient
extends java.lang.Object

A client to interact with the Fauna service, providing asynchronous and synchronous query execution, pagination, and streaming features.

Field Summary

Fields

Modifier and Type	Field	Description
static RetryStrategy	DEFAULT_RETRY_STRATEGY
static RetryStrategy	NO_RETRY_STRATEGY

Constructor Summary

Constructors

Constructor	Description
FaunaClient(java.lang.String secret, java.util.logging.Handler logHandler, StatsCollector statsCollector)	Constructs a FaunaClient with the provided secret and log handler.
FaunaClient(java.lang.String secret, java.util.logging.Logger logger, StatsCollector statsCollector)	Constructs a FaunaClient with the provided secret and logger.

Method Summary

Modifier and Type	Method	Description
<E> java.util.concurrent.CompletableFuture<FeedIterator<E>>	asyncFeed(Query fql, FeedOptions feedOptions, java.lang.Class<E> elementClass)	Return a CompletableFuture that completes with a FeedIterator based on an FQL query.
java.util.concurrent.CompletableFuture<QuerySuccess<java.lang.Object>>	asyncQuery(Query fql)	Sends an asynchronous Fauna Query Language (FQL) query to Fauna.
<E> java.util.concurrent.CompletableFuture<QuerySuccess<E>>	asyncQuery(Query fql, ParameterizedOf<E> parameterizedType)	Sends an asynchronous Fauna Query Language (FQL) query to Fauna.
<E> java.util.concurrent.CompletableFuture<QuerySuccess<E>>	asyncQuery(Query fql, ParameterizedOf<E> parameterizedType, QueryOptions options)	Sends an asynchronous Fauna Query Language (FQL) query to Fauna.
<T> java.util.concurrent.CompletableFuture<QuerySuccess<T>>	asyncQuery(Query fql, java.lang.Class<T> resultClass)	Sends an asynchronous Fauna Query Language (FQL) query to Fauna.
<T> java.util.concurrent.CompletableFuture<QuerySuccess<T>>	asyncQuery(Query fql, java.lang.Class<T> resultClass, QueryOptions options)	Sends an asynchronous Fauna Query Language (FQL) query to Fauna.
<E> java.util.concurrent.CompletableFuture<QuerySuccess<Page<E>>>	asyncQueryPage(AfterToken after, java.lang.Class<E> elementClass, QueryOptions options)	Sends a query to Fauna that retrieves the Page for the given page token.
<E> java.util.concurrent.CompletableFuture<FaunaStream<E>>	asyncStream(EventSource eventSource, StreamOptions streamOptions, java.lang.Class<E> elementClass)	Send a request to the Fauna stream endpoint, and return a CompletableFuture that completes with the FaunaStream publisher.
<E> java.util.concurrent.CompletableFuture<FaunaStream<E>>	asyncStream(Query fql, java.lang.Class<E> elementClass)	Start a Fauna stream based on an FQL query, and return a CompletableFuture of the resulting FaunaStream publisher.
<E> FeedIterator<E>	feed(EventSource eventSource, FeedOptions feedOptions, java.lang.Class<E> elementClass)	Send a request to the Feed endpoint and return a FeedIterator.
<E> FeedIterator<E>	feed(Query fql, FeedOptions feedOptions, java.lang.Class<E> elementClass)	Return a FeedIterator based on an FQL query.
protected java.lang.String	getFaunaSecret()	Retrieves the Fauna secret used for authentication.
java.util.Optional<java.lang.Long>	getLastTransactionTs()	Retrieves the last known transaction timestamp.
java.util.logging.Logger	getLogger()	Retrieves the logger used for logging Fauna client activity.
StatsCollector	getStatsCollector()	Retrieves the stats collector instance.
PageIterator<java.lang.Object>	paginate(Query fql)	Send a Fauna Query Language (FQL) query to Fauna and return a paginated result.
PageIterator<java.lang.Object>	paginate(Query fql, QueryOptions options)	Send a Fauna Query Language (FQL) query to Fauna and return a paginated result.
<E> PageIterator<E>	paginate(Query fql, java.lang.Class<E> elementClass)	Send a Fauna Query Language (FQL) query to Fauna and return a paginated result.
<E> PageIterator<E>	paginate(Query fql, java.lang.Class<E> elementClass, QueryOptions options)	Send a Fauna Query Language (FQL) query to Fauna and return a paginated result.
<E> java.util.concurrent.CompletableFuture<FeedPage<E>>	poll(EventSource eventSource, FeedOptions feedOptions, java.lang.Class<E> elementClass)	Send a request to the Fauna feed endpoint, and return a CompletableFuture that completes with the feed page.
QuerySuccess<java.lang.Object>	query(Query fql)	Sends a Fauna Query Language (FQL) query to Fauna and returns the result.
<E> QuerySuccess<E>	query(Query fql, ParameterizedOf<E> parameterizedType)	Sends a Fauna Query Language (FQL) query to Fauna and returns the result.
<E> QuerySuccess<E>	query(Query fql, ParameterizedOf<E> parameterizedType, QueryOptions options)	Sends a Fauna Query Language (FQL) query to Fauna and returns the result.
<T> QuerySuccess<T>	query(Query fql, java.lang.Class<T> resultClass)	Sends a Fauna Query Language (FQL) query to Fauna and returns the result.
<T> QuerySuccess<T>	query(Query fql, java.lang.Class<T> resultClass, QueryOptions options)	Sends a Fauna Query Language (FQL) query to Fauna and returns the result.
<E> QuerySuccess<Page<E>>	queryPage(AfterToken after, java.lang.Class<E> elementClass, QueryOptions options)	Sends a query to Fauna that retrieves the Page for the given page token.
<E> FaunaStream<E>	stream(EventSource eventSource, StreamOptions streamOptions, java.lang.Class<E> elementClass)	Send a request to the Fauna stream endpoint to start a stream, and return a FaunaStream publisher.
<E> FaunaStream<E>	stream(Query fql, java.lang.Class<E> elementClass)	Start a Fauna stream based on an FQL query.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_RETRY_STRATEGY

public static final RetryStrategy DEFAULT_RETRY_STRATEGY

NO_RETRY_STRATEGY

public static final RetryStrategy NO_RETRY_STRATEGY

Constructor Detail

FaunaClient

public FaunaClient(java.lang.String secret,
                   java.util.logging.Logger logger,
                   StatsCollector statsCollector)

Constructs a FaunaClient with the provided secret and logger.

Parameters:

secret - The Fauna secret used for authentication.

logger - The logger instance.

statsCollector - A collector for tracking statistics.

FaunaClient

public FaunaClient(java.lang.String secret,
                   java.util.logging.Handler logHandler,
                   StatsCollector statsCollector)

Constructs a FaunaClient with the provided secret and log handler.

Parameters:

secret - The Fauna secret used for authentication.

logHandler - The handler to manage log outputs.

statsCollector - A collector for tracking statistics.

Method Detail

getFaunaSecret

protected java.lang.String getFaunaSecret()

Retrieves the Fauna secret used for authentication.

Returns:

The Fauna secret.

getLogger

public java.util.logging.Logger getLogger()

Retrieves the logger used for logging Fauna client activity.

Returns:

The logger instance.

getStatsCollector

public StatsCollector getStatsCollector()

Retrieves the stats collector instance.

Returns:

The stats collector instance.

getLastTransactionTs

public java.util.Optional<java.lang.Long> getLastTransactionTs()

Retrieves the last known transaction timestamp.

Returns:

An Optional containing the last transaction timestamp, if available.

asyncQuery

public java.util.concurrent.CompletableFuture<QuerySuccess<java.lang.Object>> asyncQuery(Query fql)

Sends an asynchronous Fauna Query Language (FQL) query to Fauna.

var future = client.asyncQuery(fql); ... do some other stuff ... var result = future.get().getData();

Parameters:

fql - The FQL query to be executed.

Returns:

QuerySuccess The successful query result.

Throws:

FaunaException - If the query does not succeed, an exception will be thrown.

asyncQuery

public <T> java.util.concurrent.CompletableFuture<QuerySuccess<T>> asyncQuery(Query fql,
                                                                              java.lang.Class<T> resultClass,
                                                                              QueryOptions options)

Sends an asynchronous Fauna Query Language (FQL) query to Fauna.

CompletableFuture<QuerySuccess<Document>> future = client.asyncQuery(fql, Document.class, null); ... do some other stuff ... Document doc = future.get().getData();

Type Parameters:

T - The return type of the query.

Parameters:

fql - The FQL query to be executed.

resultClass - The expected class of the query result.

options - A (nullable) set of options to pass to the query.

Returns:

QuerySuccess The successful query result.

Throws:

FaunaException - If the query does not succeed, an exception will be thrown.

asyncQuery

public <E> java.util.concurrent.CompletableFuture<QuerySuccess<E>> asyncQuery(Query fql,
                                                                              ParameterizedOf<E> parameterizedType,
                                                                              QueryOptions options)

Sends an asynchronous Fauna Query Language (FQL) query to Fauna.

CompletableFuture<QuerySuccess<List<int>>> future = client.asyncQuery(fql, Parameterized.listOf(int.class), null); ... do some other stuff ... List<int>> data = future.get().getData();

Type Parameters:

E - The inner type for the parameterized wrapper.

Parameters:

fql - The FQL query to be executed.

parameterizedType - The expected class of the query result.

options - A (nullable) set of options to pass to the query.

Returns:

QuerySuccess The successful query result.

Throws:

FaunaException - If the query does not succeed, an exception will be thrown.

asyncQuery

public <T> java.util.concurrent.CompletableFuture<QuerySuccess<T>> asyncQuery(Query fql,
                                                                              java.lang.Class<T> resultClass)

Sends an asynchronous Fauna Query Language (FQL) query to Fauna.

CompletableFuture<QuerySuccess<Document>> future = client.asyncQuery(fql, Document.class); ... do some other stuff ... Document doc = future.get().getData();

Type Parameters:

T - The return type of the query.

Parameters:

fql - The FQL query to be executed.

resultClass - The expected class of the query result.

Returns:

QuerySuccess A CompletableFuture that completes with the successful query result.

Throws:

FaunaException - If the query does not succeed, an exception will be thrown.

asyncQuery

public <E> java.util.concurrent.CompletableFuture<QuerySuccess<E>> asyncQuery(Query fql,
                                                                              ParameterizedOf<E> parameterizedType)

Sends an asynchronous Fauna Query Language (FQL) query to Fauna.

CompletableFuture<QuerySuccess<List<int>>> future = client.asyncQuery(fql, Parameterized.listOf(int.class)); ... do some other stuff ... List<int>> data = future.get().getData();

Type Parameters:

E - The inner type for the parameterized wrapper.

Parameters:

fql - The FQL query to be executed.

parameterizedType - The expected class of the query result.

Returns:

QuerySuccess The successful query result.

Throws:

FaunaException - If the query does not succeed, an exception will be thrown.

query

public QuerySuccess<java.lang.Object> query(Query fql)
                                     throws FaunaException

Sends a Fauna Query Language (FQL) query to Fauna and returns the result.

var result = client.query(fql); var data = result.getData();

Parameters:

fql - The FQL query to be executed.

Returns:

QuerySuccess The successful query result.

Throws:

FaunaException - If the query does not succeed, an exception will be thrown.

query

public <T> QuerySuccess<T> query(Query fql,
                                 java.lang.Class<T> resultClass)
                          throws FaunaException

Sends a Fauna Query Language (FQL) query to Fauna and returns the result.

QuerySuccess<Document> result = client.query(fql, Document.class); Document doc = result.getData();

Type Parameters:

T - The return type of the query.

Parameters:

fql - The FQL query to be executed.

resultClass - The expected class of the query result.

Returns:

QuerySuccess The successful query result.

Throws:

FaunaException - If the query does not succeed, an exception will be thrown.

query

public <E> QuerySuccess<E> query(Query fql,
                                 ParameterizedOf<E> parameterizedType)
                          throws FaunaException

Sends a Fauna Query Language (FQL) query to Fauna and returns the result.

QuerySuccess<List<int>>> result = client.query(fql, Parameterized.listOf(int.class)); List<int>> data = result.getData();

Type Parameters:

E - The inner type for the parameterized wrapper.

Parameters:

fql - The FQL query to be executed.

parameterizedType - The expected class of the query result.

Returns:

QuerySuccess The successful query result.

Throws:

FaunaException - If the query does not succeed, an exception will be thrown.

query

public <T> QuerySuccess<T> query(Query fql,
                                 java.lang.Class<T> resultClass,
                                 QueryOptions options)
                          throws FaunaException

Sends a Fauna Query Language (FQL) query to Fauna and returns the result.

QuerySuccess result = client.query(fql, Document.class, null); Document doc = result.getData();

Type Parameters:

T - The return type of the query.

Parameters:

fql - The FQL query to be executed.

resultClass - The expected class of the query result.

options - A (nullable) set of options to pass to the query.

Returns:

QuerySuccess The successful query result.

Throws:

FaunaException - If the query does not succeed, an exception will be thrown.

query

public <E> QuerySuccess<E> query(Query fql,
                                 ParameterizedOf<E> parameterizedType,
                                 QueryOptions options)
                          throws FaunaException

Sends a Fauna Query Language (FQL) query to Fauna and returns the result.

QuerySuccess<List<int>>> result = client.query(fql, Parameterized.listOf(int.class), null); List<int>> data = result.getData();

Type Parameters:

E - The inner type for the parameterized wrapper.

Parameters:

fql - The FQL query to be executed.

parameterizedType - The expected class of the query result.

options - A (nullable) set of options to pass to the query.

Returns:

QuerySuccess The successful query result.

Throws:

FaunaException - If the query does not succeed, an exception will be thrown.

asyncQueryPage

public <E> java.util.concurrent.CompletableFuture<QuerySuccess<Page<E>>> asyncQueryPage(AfterToken after,
                                                                                        java.lang.Class<E> elementClass,
                                                                                        QueryOptions options)

Sends a query to Fauna that retrieves the Page for the given page token.

Type Parameters:

E - The type of the elements of the page.

Parameters:

after - The page token (result of a previous paginated request).

elementClass - The expected class of the query result.

options - A (nullable) set of options to pass to the query.

Returns:

A CompletableFuture that returns a QuerySuccess with data of type Page.

Throws:

FaunaException - If the query does not succeed, an exception will be thrown.

queryPage

public <E> QuerySuccess<Page<E>> queryPage(AfterToken after,
                                           java.lang.Class<E> elementClass,
                                           QueryOptions options)

Sends a query to Fauna that retrieves the Page for the given page token.

Type Parameters:

E - The type of the elements of the page.

Parameters:

after - The page token (result of a previous paginated request).

elementClass - The expected class of the query result.

options - A (nullable) set of options to pass to the query.

Returns:

A QuerySuccess with data of type Page.

Throws:

FaunaException - If the query does not succeed, an exception will be thrown.

paginate

public <E> PageIterator<E> paginate(Query fql,
                                    java.lang.Class<E> elementClass,
                                    QueryOptions options)

Send a Fauna Query Language (FQL) query to Fauna and return a paginated result.

Type Parameters:

E - The type of the elements of the page.

Parameters:

fql - The FQL query to be executed.

elementClass - The expected class of the query result.

options - A (nullable) set of options to pass to the query.

Returns:

QuerySuccess The successful query result.

Throws:

FaunaException - If the query does not succeed, an exception will be thrown.

paginate

public PageIterator<java.lang.Object> paginate(Query fql)

Send a Fauna Query Language (FQL) query to Fauna and return a paginated result.

Parameters:

fql - The FQL query to be executed.

Returns:

The successful query result.

Throws:

FaunaException - If the query does not succeed, an exception will be thrown.

paginate

public PageIterator<java.lang.Object> paginate(Query fql,
                                               QueryOptions options)

Send a Fauna Query Language (FQL) query to Fauna and return a paginated result.

Parameters:

fql - The FQL query to be executed.

options - A (nullable) set of options to pass to the query.

Returns:

The successful query result.

Throws:

FaunaException - If the query does not succeed, an exception will be thrown.

paginate

public <E> PageIterator<E> paginate(Query fql,
                                    java.lang.Class<E> elementClass)

Send a Fauna Query Language (FQL) query to Fauna and return a paginated result.

Type Parameters:

E - The type for each element in a page.

Parameters:

fql - The FQL query to be executed.

elementClass - The expected class of the query result.

Returns:

QuerySuccess The successful query result.

Throws:

FaunaException - If the query does not succeed, an exception will be thrown.

asyncStream

public <E> java.util.concurrent.CompletableFuture<FaunaStream<E>> asyncStream(EventSource eventSource,
                                                                              StreamOptions streamOptions,
                                                                              java.lang.Class<E> elementClass)

Send a request to the Fauna stream endpoint, and return a CompletableFuture that completes with the FaunaStream publisher.

Type Parameters:

E - The type for data in an event.

Parameters:

eventSource - The Event Source (e.g. token from `.eventSource()`).

streamOptions - The Stream Options (including start timestamp, retry strategy).

elementClass - The target type into which event data will be deserialized.

Returns:

CompletableFuture A CompletableFuture of FaunaStream.

Throws:

FaunaException - If the query does not succeed, an exception will be thrown.

stream

public <E> FaunaStream<E> stream(EventSource eventSource,
                                 StreamOptions streamOptions,
                                 java.lang.Class<E> elementClass)

Send a request to the Fauna stream endpoint to start a stream, and return a FaunaStream publisher.

Type Parameters:

E - The type for data in an event.

Parameters:

eventSource - The request object including a stream token, and optionally a cursor, or timestamp.

streamOptions - The stream options.

elementClass - The expected class <E> of the stream events.

Returns:

FaunaStream A publisher, implementing Flow.Publisher<StreamEvent<E>> from the Java Flow API.

Throws:

FaunaException - If the query does not succeed, an exception will be thrown.

asyncStream

public <E> java.util.concurrent.CompletableFuture<FaunaStream<E>> asyncStream(Query fql,
                                                                              java.lang.Class<E> elementClass)

Start a Fauna stream based on an FQL query, and return a CompletableFuture of the resulting FaunaStream publisher. This method sends two requests, one to the query endpoint to get the stream token, and then another to the stream endpoint. This method is equivalent to calling the query, then the stream methods on FaunaClient.

This method does not take QueryOptions, or StreamOptions as parameters. If you need specify either query, or stream options; you can use the asyncQuery/asyncStream methods.

Type Parameters:

E - The type for data in an event.

Parameters:

fql - The FQL query to be executed. It must return an event source, e.g. ends in `.eventSource()`.

elementClass - The expected class <E> of the stream events.

Returns:

FaunaStream A publisher, implementing Flow.Publisher<StreamEvent<E>> from the Java Flow API.

Throws:

FaunaException - If the query does not succeed, an exception will be thrown.

stream

public <E> FaunaStream<E> stream(Query fql,
                                 java.lang.Class<E> elementClass)

Start a Fauna stream based on an FQL query. This method sends two requests, one to the query endpoint to get the stream token, and then another request to the stream endpoint which return the FaunaStream publisher.

Query = fql("Product.all().eventSource()"); QuerySuccess<EventSource> querySuccess = client.query(fql, EventSource.class); EventSource source = querySuccess.getData(); FaunaStream<Product> faunaStream = client.stream(source, StreamOptions.DEFAULT, Product.class)

Type Parameters:

E - The type for data in an event.

Parameters:

fql - The FQL query to be executed. It must return a stream, e.g. ends in `.toStream()`.

elementClass - The expected class <E> of the stream events.

Returns:

FaunaStream A publisher, implementing Flow.Publisher<StreamEvent<E>> from the Java Flow API.

Throws:

FaunaException - If the query does not succeed, an exception will be thrown.

poll

public <E> java.util.concurrent.CompletableFuture<FeedPage<E>> poll(EventSource eventSource,
                                                                    FeedOptions feedOptions,
                                                                    java.lang.Class<E> elementClass)

Send a request to the Fauna feed endpoint, and return a CompletableFuture that completes with the feed page.

Type Parameters:

E - The type for data in an event.

Parameters:

eventSource - An EventSource object (e.g. token from `.eventSource()`)

feedOptions - The FeedOptions object (default options will be used if null).

elementClass - The expected class <E> of the feed events.

Returns:

CompletableFuture A CompletableFuture that completes with a FeedPage<E>.

asyncFeed

public <E> java.util.concurrent.CompletableFuture<FeedIterator<E>> asyncFeed(Query fql,
                                                                             FeedOptions feedOptions,
                                                                             java.lang.Class<E> elementClass)

Return a CompletableFuture that completes with a FeedIterator based on an FQL query. This method sends two requests, one to the query endpoint to get the event source token, and then another request to the feed endpoint to get the first page of results.

Type Parameters:

E - The type for data in an event.

Parameters:

fql - The FQL query to be executed. It must return a token, e.g. ends in `.changesOn()`.

feedOptions - The FeedOptions object (must not be null).

elementClass - The expected class <E> of the feed events.

Returns:

FeedIterator A CompletableFuture that completes with a feed iterator that returns pages of Feed events.

feed

public <E> FeedIterator<E> feed(Query fql,
                                FeedOptions feedOptions,
                                java.lang.Class<E> elementClass)

Return a FeedIterator based on an FQL query. This method sends two requests, one to the query endpoint to get the stream/feed token, and then another request to the feed endpoint to get the first page of results.

Type Parameters:

E - The type for data in an event.

Parameters:

fql - The FQL query to be executed. It must return a token, e.g. ends in `.changesOn()`.

feedOptions - The Feed Op

elementClass - The expected class <E> of the feed events.

Returns:

FeedIterator An iterator that returns pages of Feed events.

feed

public <E> FeedIterator<E> feed(EventSource eventSource,
                                FeedOptions feedOptions,
                                java.lang.Class<E> elementClass)

Send a request to the Feed endpoint and return a FeedIterator.

Type Parameters:

E - The type for data in an event.

Parameters:

eventSource - The Fauna Event Source.

feedOptions - The feed options.

elementClass - The expected class <E> of the feed events.

Returns:

FeedIterator An iterator that returns pages of Feed events.