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

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!