Home

Introduction to Firefall

Firefall works slightly differently to Objectify. Where as Objectify has Keys and Refs which are essentially the same thing but refs can load the entity directly from the datastore. Firefall only has the Ref type. Because the underlying Firestore SDK doesn't really handle things such as keys as they are called DocumentReference(s). Docs on this can be found here. Id recommend you learn the basic of Firestore before using this library.

Also please note that Firefall is still in active development. So any features and API are subject to change.

Also if you find any bugs or need something that isn't currently available please submit a PR as a feature request the best describe it.

There may be some information here which is directly taken from the Objectify Wiki/Docs for simplicity. So I would like to thank all who worked on Objectify for an amazing library and inspiring me to build Firefall.

Throughout code examples I will be using Lombok to automatically generate getters and setters for my code. Feel free to have a look at these also. If you are not using Lombok make sure to create your getters and setters manually etc.

Overview

This is a quick tour of what using Firefall looks like, intended to give you a taste of the framework. Full explanations can be found later in the documentation.

Defining Entities

If you are familiar with Firestore entities are called documents, and to get an entity you use a document reference. So the Id of each entity is not stored on the entity/document itself. So when we load from the Firestore we need to append the Id to the entity from the document reference. Thats where the HasId comes in, to define an entity that we can get the Id from in Firefull. As this defines a String as an id. Have a look into HasId if you are still a little confused.

Ids are always strings, and are always generated for you if not set. If you define a new entity wit ha custom Id that will also work too.

import lombok.Data;
import nz.co.delacour.firefull.core.HasId;

@Data
public class User extends HasId<User> {

    private String email;
    private String name;
    
    public User() {
        super(User.class);
    }

}

Basic Operations

User user = new User("example@example.com", "example");
fir().save().type(User.class).entity(user).now();    // async without the now()

assert user.id != null;    // id was autogenerated

// Get it back
LoadResult<User> result = fir().load().type(User.class).ref(Ref.create(User.class, user.getId()));  // Result is async
User fetched1 = result.now();    // Materialize the async value

// More likely this is what you will type
User fetched2 = fir().load().type(User.class).id(user.id).now();

// Or you can issue a query
User fetched3 = fir().load().type(User.class).filter("email", "example@example.com").first().now();

// Change some data and write it
user.email = "example2@example2.com";
fir().save().type(User.class).entity(user).now();    // async without the now()

// Delete it
fir().delete().type(User.class).entity(user).now();    // async without the now()