Class 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
    • Method Detail

      • 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