Get started in Java

These instructions assume that you use Bazel and Gazelle , and you may also use Maven . You can adapt them for any build system you like.

Setup

JAR Files

First, download the JAR files and put them in a jars/ directory in your project. Then, add jars/BUILD.bazel . Finally, use TwiceDBClientJar for the client library and TwiceDBProcessorJar to auto-generate code for your database models.

Maven

First, add the Maven dependencies com.twicedb:twicedb-client:0.31.0 and com.twicedb:twicedb-processor:0.31.0 , and add the repository https://maven.twicedb.com . Then, add jars/BUILD.bazel . Finally, use @com_twicedb_twicedb_client for the client library and to auto-generate code for your database models.

Annotations

With setup completed, let’s imagine that we have an existing project with the following classes, and we want to integrate them with TwiceDB:

package com.myproject.models;

public class Company {
  public String name;

  public Company(String name) {
    this.name = name;
  }
}

package com.myproject.models;

public class Person {
  public String firstname;
  public String lastname;
  public Integer salary;
  public Person manager;
  public Company company;

  public Person(
    String firstname,
    String lastname,
    Integer salary,
    Person manager,
    Company company) {
    this.firstname = firstname;
    this.lastname = lastname;
    this.salary = salary;
    this.manager = manager;
    this.company = company;
  }
}

Here are the modified classes:

package com.myproject.models;

import com.twicedb.client.api.Indexable;
import com.twicedb.client.api.TwiceDBIndex;
import com.twicedb.client.api.TwiceDBObject;

@TwiceDBObject
public class Company extends Indexable<Company> {
  @TwiceDBIndex public String name;
}

package com.myproject.models;

import com.twicedb.client.api.Indexable;
import com.twicedb.client.api.TwiceDBIndex;
import com.twicedb.client.api.TwiceDBObject;
import com.twicedb.client.api.TwiceDBProject;
import com.twicedb.client.api.TwiceDBRef;

@TwiceDBObject
public class Person extends Indexable<Person>
  implements PersonRefSupport {
  @TwiceDBIndex public String firstname;
  @TwiceDBIndex public String lastname;
  @TwiceDBIndex @TwiceDBProject public Integer salary;
  @TwiceDBRef private final Person manager = null;
  @TwiceDBRef private final Company company = null;
}

You can see that the code is quite a bit shorter, and you can probably guess from the model definitions what behaviors are provided. Let’s review the changes one-by-one:

We annotated Company with @TwiceDBObject and made it extend Indexable<Company>. This allows TwiceDB to generate the code required to interact with the database.
We annotated Company.name with @TwiceDBIndex. This allows us to do fast Company lookups by name.
We annotated Person with @TwiceDBObject and made it extend Indexable<Person>. This allows TwiceDB to generate the code required to interact with the database.
We made Person implement PersonRefSupport. This allows us to use methods generated by TwiceDB to read the fields annotated with @TwiceDBRef.
We annotated Person.firstname and Person.lastname with @TwiceDBIndex. This allows us to do fast Person lookups by firstname, by lastname, or by both.
We annotated Person.salary with @TwiceDBIndex and with @TwiceDBProject. This allows us to do fast Person lookups by salary and to calculate aggregate statistics, such as mean salary.
We annotated Person.manager and Person.company with @TwiceDBRef, made them private final, and set them equal to null since these relations are managed entirely by TwiceDB.
We removed the Company and the Person constructors. Constructors are generated automatically by TwiceDB.

Stuck?

If you get stuck, consult twicedb-get-started-in-java , which contains all of the code that you see here. Don’t forget to choose the correct branch for your setup: main for downloaded JAR files, or use-twicedb-client-with-maven for Maven. For a complete reference, check out the full documentation .

Next steps

Now that you know how to set up your code for TwiceDB and Java, take a look at the examples to see how a complete application fits together.