firebomb-java

Firebase object mapper

Firebomb makes it easier to persist relational data in a NoSQL document database such as Firebase.

Related Projects

• Firebomb (firebase-android)

Getting Started (with Firebase server)

Add Firebomb to your project

Gradle

repositories {
    jcenter()
}

dependencies {
    compile 'firebomb:core:0.2.0'
    compile 'firebomb:firebase-server:0.2.0'
}

Maven

<dependency>
  <groupId>firebomb</groupId>
  <artifactId>core</artifactId>
  <version>0.2.0</version>
  <type>pom</type>
</dependency>

<dependency>
  <groupId>firebomb</groupId>
  <artifactId>firebase-server</artifactId>
  <version>0.2.0</version>
  <type>pom</type>
</dependency>

Initialize Firebomb

Initialize Firebase and then initialize Firebomb with a new FirebaseManager.

Firebomb.initialize(new FirebaseServerConnection(FirebaseDatabase.getInstance()));
Firebomb.getInstance().setRootPath("v1"); // Optional root path

Defining Entities

Annotations

Entities are defined using annotations inspired by (but not derived from) JPA/Hibernate specifications.

Example

@Entity // (Required)
public class User {
    @Id // (Required)
    public String id;
    
    @Property("username") // (Optional) Specify name for the property
    @NonNull // (Optional) Specify field as non-null
    public String name;
    
    @Ignore // Ignore this member
    public String ignoreMe;
    
    @OneToMany(foreignFieldName = "host")
    public List<Meal> hostedMeals = new ArrayList<>();
    
    @ManyToMany(foreignIndexName = "guests")
    public List<Meal> rsvps = new ArrayList<>();
    
    public User() {} // Required empty constructor
}

@Entity // Default reference is inferred as plural form of lowercase classname
@Reference("mealList") // (Optional) Specify specific reference name
public class Meal {
    @Id // Id is non-null if not marked as @GeneratedValue
    @GeneratedValue // (Optional) Id will be autogenerated by the database
    public String id;
    
    @ManyToOne(foreignIndexName = "hostedMeals")
    public User host;
    
    @ManyToMany(foreignIndexName = "rsvps")
    public List<User> guests = new ArrayList<>();
    
    public Meal() {} // Require empty constructor
}

This results in the following schema:

- users
    <userId>
        - id
        - username
        - hostedMeals
            <mealId>
                - id
        - rsvps
            <mealId>
                - id
- mealList
    <mealId>
        - id
        - host
            - <userId>
                - id
        - guests
            <userId>
                - id

Persistence

Firebomb persists objects by constructing a map of the changes required to the document database. In particular, relationship updates are fanned out to their corresponding entities in the write map.

Operations

Firebomb currently supports three basic persistence operations:

Firebomb.find()

<T> CompletableFuture<T> find(Class<T> entityType, String id)

Inputs:

• Class entityType : The entity class type
• String id : Entity Id

Returns: CompletableFuture<T>

A promise for the persisted entity type with the given Id. Completes with null if no such entity exists. Related foreign entities are lazy-loaded with only their Id fields.

Firebomb.persist()

<T> CompletableFuture<T> persist(T entity)

Inputs:

• T entity : The entity object

Returns: CompletableFuture<T>

A promise that returns the persisted entity (with its auto-generated Id if applicable) upon completion.

Firebomb.remove()

CompletableFuture<Void> remove(Class entityType, String id)

Inputs:

• Class entityType : The entity class type
• String id : Entity Id

Returns: CompletableFuture<Void>

A promise that completes upon deletion of the given entity type with the given Id.

License

Firebomb-java is distributed under the Apache License 2.0.