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.

Next steps

Now that your development environment is set up, you’re ready to start developing more complex applications. The following resources can help.

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!