Java

This section is intended to help Java developers get started using the Fauna Java driver for application development.

Current version and repository location

Current stable version

4.3.0

Repository

fauna/faunadb-jvm

Dependencies

  • Java 11

  • Jackson for JSON parsing.

Installation

Download from the Maven central repository:

faunadb-java/pom.xml:
<dependencies>
  ...
  <dependency>
    <groupId>com.faunadb</groupId>
    <artifactId>faunadb-java</artifactId>
    <version>4.3.0</version>
    <scope>compile</scope>
  </dependency>
  ...
</dependencies>

Example application

The following example code runs a bare-bones Java application which creates a new document in a collection called People.

Prerequisites

  • A Fauna account. If you don’t have one, see the dashboard quick start for help getting set up.

  • A supported version of Java and the Fauna Java driver.

  • Maven 3.6.x, or higher.

Procedure

  1. Navigate to the Fauna Dashboard

    Log in to your Fauna account at Fauna Dashboard if you’re not already logged in.

  2. Create a new database

    Click NEW DATABASE. Select the Classic region group.

  3. Create a new collection

    Click NEW COLLECTION. Name your new collection People and save it.

  4. Create an access key

    Click SECURITY in the left-side navigation menu. Create a new key for your database. Be sure to save the key’s secret in a safe place, as it is only displayed once.

  5. Create a local environment variable with your access key’s secret

    On MacOS and Linux systems, enter the following in a terminal window:

    export FAUNADB_SECRET=<your-secret>

    For Windows systems, enter the following in a terminal window:

    set FAUNADB_SECRET=<your secret>

    For either example, replace <your secret> with the secret for the access key that you created.

  6. Create a project folder using the standard directory layout

    In a terminal window, in an empty folder, run the following command:

    mvn archetype:generate \
  -DgroupId=example \
  -DartifactId=example \
  -DarchetypeArtifactId=maven-archetype-quickstart \
  -DarchetypeVersion=1.4 \
  -DinteractiveMode=false

    Then enter the folder:

    cd example

  7. Edit the pom.xml file

    With your preferred editor, replace the contents of the pom.xml file with the following:

    <?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>example</groupId>
  <artifactId>example</artifactId>
  <version>1.0</version>
  <packaging>jar</packaging>
  <name>example</name>

  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
  </properties>

  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>4.13.2</version>
    </dependency>

    <dependency>
      <groupId>com.faunadb</groupId>
      <artifactId>faunadb-java</artifactId>
      <version>4.3.0</version>
    </dependency>

    <dependency>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-nop</artifactId>
      <version>1.7.36</version>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <artifactId>maven-assembly-plugin</artifactId>
        <version>3.2.0</version>
        <executions>
          <execution>
            <id>make-assembly</id>
            <phase>package</phase>
            <goals>
              <goal>single</goal>
            </goals>
            <configuration>
              <finalName>example</finalName>
              <appendAssemblyId>false</appendAssemblyId>
              <archive>
                <manifest>
                  <mainClass>example.App</mainClass>
                </manifest>
              </archive>
              <descriptorRefs>
                <descriptorRef>jar-with-dependencies</descriptorRef>
              </descriptorRefs>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

  8. Create a local application file

    With your preferred editor, replace the contents of the src/main/java/example/App.java file with the following code:

    package example;

import static com.faunadb.client.query.Language.*;
import static com.faunadb.client.query.Language.TimeUnit.*;
import static com.faunadb.client.types.Codec.*;
import static com.faunadb.client.types.Value.NullV.NULL;

import com.faunadb.client.FaunaClient;
import com.faunadb.client.types.*;
import com.faunadb.client.types.Value.*;

/**
* The class for our example app code.
*/
public class App {
    /**
    * The example.
    */
    public static void main(String[] args) throws Exception {
        String secret   = System.getenv("FAUNADB_SECRET");
        String endpoint = System.getenv("FAUNADB_ENDPOINT");

        if (secret == null || secret == "") {
            System.out.println(
                "The FAUNADB_SECRET environment variable is not set, exiting."
            );
            System.exit(1);
        }
        if (endpoint == null || endpoint == "") {
            endpoint = "https://db.fauna.com/";
        }
        FaunaClient client = FaunaClient.builder()
            .withSecret(secret)
            .withEndpoint(endpoint)
            .build();

        System.out.println(
            client.query(
                Create(
                    Collection("People"),
                    Obj(
                        "data", Obj(
                            "first", Value("Linus"),
                            "last", Value("Torvalds"),
                            "age", Value(52)
                        )
                    )
                )
            ).get());
    }
}

  9. Compile the application

    mvn clean package

    Note that the first compilation might take a while as dependencies are downloaded. Subsequent compilations should be notably faster.

  10. Run the application

    java -jar target/example.jar

    You should see results similar to this:

    {ref: ref(id = "324883734738240000", collection = ref(id = "People", collection = ref(id = "collections"))), ts: 1646092123640000, data: {first: "Linus", last: "Torvalds", age: 52}}

    If you get an error, check to make sure that the secret for your access key is correct.

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!