com.github.b3er.rxfirebase:firebase-database

RxFirebase2

RxJava 2 binding APIs for Firebase Android SDK based on RxFirebase.

RxJava Version

It supports RxJava 2.x.

Modules

firebase-auth

RxJava binding APIs for Firebase Authentication.

compile ('com.github.b3er.rxfirebase:firebase-auth:11.2.0') {
    transitive = false
}

firebase-auth-kotlin

Kotlin support module for firebase-auth.

compile ('com.github.b3er.rxfirebase:firebase-auth-kotlin:11.2.0') {
    transitive = false
}

firebase-database

RxJava binding APIs for Firebase Realtime Database Android SDK.

compile ('com.github.b3er.rxfirebase:firebase-database:11.2.0') {
    transitive = false
}

firebase-database-kotlin

Kotlin support module for firebase-database

compile ('com.github.b3er.rxfirebase:firebase-database-kotlin:11.2.0') {
    transitive = false
}

firebase-storage

RxJava binding APIs for Firebase Storage Android SDK.

compile ('com.github.b3er.rxfirebase:firebase-storage:11.2.0') {
    transitive = false
}

firebase-storage-kotlin

Kotlin support module for firebase-storage

compile ('com.github.b3er.rxfirebase:firebase-storage-kotlin:11.2.0') {
    transitive = false
}

Each kotlin support module maps all methods in Java module into an extension function on following classes:

• firebase-auth-kotlin
  • FirebaseAuth
  • FirebaseUser
• firebase-database-kotlin
  • DatabaseReference
• firebase-storage-kotlin
  • StorageReference

Basically, extension function has same name of methods in RxXXX classes in Java module.

If extension function conflicts with a method in a class that is being extended, it will be renamed with rx prefix.

For more details, please refer to following 'Usage' section.

Usage

Here are some usages of RxFirebase2. Since it provides just a wrapper for Firebase Android SDK, see official documentation for the details.

Firebase Authentication

Get the currently signed-in user (Listener)

Get currently signed-in user by Firebasebase.AuthStateChangeListener.

As a listener, it will emit FirebaseAuth object on each auth state changes until unsubscribed.

Note that RxFirebaseAuth.authStateChanges() will emit initial value on subscribe.

Java:

RxFirebaseAuth.authStateChanges(FirebaseAuth.getInstance()).subscribe(
                new Consumer<FirebaseAuth>() {
                    @Override
                    public void accept(FirebaseAuth firebaseAuth) throws Exception {
                        // Do something when auth state changes.
                    }
                }, new Consumer<Throwable>() {
                    @Override
                    public void accept(Throwable throwable) throws Exception {
                        // Handle error
                    }
                });

Kotlin:

FirebaseAuth.getInstance().authStateChanges()
        .subscribe({
            // Do something when auth state changes.
        }, {
            // Handle error
        })

Get the currently signed-in user (getCurrentUser())

Since FirebaseAuth.getCurrentUser() might return null when auth object has not finished initializing, it returns Optional wrapper of FirebaseUser object to prevent null pointer exception.

Java:

 RxFirebaseAuth.getCurrentUser(FirebaseAuth.getInstance())
                .subscribe(new Consumer<Optional<FirebaseUser>>() {
                    @Override
                    public void accept(Optional<FirebaseUser> user)
                            throws Exception {
                        if (user.isPresent()) {
                            // Do something with user
                        } else {
                            // There is not signed in user or
                            // Firebase instance was not fully initialized.
                        }
                    }
                }, new Consumer<Throwable>() {
                    @Override
                    public void accept(Throwable throwable) throws Exception {
                        // Handle error
                    }
                });

Kotlin:

FirebaseAuth.getInstance().rxGetCurrentUser()
        .subscribe({
            if (user.isPresent) {
                // Do something with user
            } else {
                // There is not signed in user or
                // Firebase instance was not fully initialized.
            }
        }, {
            // Handle error
        })

Sign in anonymously

Uses Anonymous Authentication for sign in. Note that it emits FirebaseUser object of currently signed-in user.

Java:

RxFirebaseAuth.signInAnonymous(FirebaseAuth.getInstance())
                .subscribe(new Consumer<FirebaseUser>() {
                    @Override
                    public void accept(FirebaseUser firebaseUser) throws Exception {
                        // Do something with anonymous user
                    }
                }, new Consumer<Throwable>() {
                    @Override
                    public void accept(Throwable throwable) throws Exception {
                        // Handle error
                    }
                });

Kotlin:

FirebaseAuth.getInstance().rxSignInAnonymous()
        .subscribe({
            // Do something with anonymous user
        }, {
            // Handle error
        })

Update a user's profile

For a method which returns Task<Void> as a result, Completable is used.

Java:

FirebaseUser user = ...;

UserProfileChangeRequest request = new UserProfileChangeRequest.Builder()
        .setDisplayName("John Doe")
        .setPhotoUri(Uri.parse("http://my.photo/johndoe"))
        .build();

 RxFirebaseUser.updateProfile(user, request)
                .subscribe(new Action() {
                    @Override
                    public void run() throws Exception {
                        // Update successful
                    }
                }, new Consumer<Throwable>() {
                    @Override
                    public void accept(Throwable throwable) throws Exception {
                        // Update was not successful
                    }
                });

Kotlin:

val user: FirebaseUser = ...

val request = UserProfileChangeRequest.Builder()
        .setDisplayName("John Doe")
        .setPhotoUri(Uri.parse("http://my.photo/johndoe"))
        .build()

user.rxUpdateProfile(request)
        .subscribe({
            // Update successful
        }, { 
            // Handle error
        })

Firebase Realtime Database

Write to your database

Retrieve an instance of your database using FirebaseDatabase.getInstance() and pass the reference of the location to RxFirebase.setValue() with a value.

Java:

DatabaseReference ref = ...;

RxFirebaseDatabase.setValue(ref, "Lorem ipsum")
                .subscribe(new Action() {
                    @Override
                    public void run() throws Exception {
                        // Update successful
                    }
                }, new Consumer<Throwable>() {
                    @Override
                    public void accept(Throwable throwable) throws Exception {
                        // Something went wrong
                    }
                });

Kotlin:

val ref: DatabaseReference = ...;
ref.rxSetValue("Lorem ipsum")
        .subscribe({
                    // Update successful
                }, { 
                    // Handle error
                })

Update specific fields

To simultaneously write to specific children of a note without overwriting other child nodes, use the RxFirebase.updateChildren() method.

Java:

DatabaseReference ref = ...;

Map<String, Object> update = new HashMap<>();
update.put("/posts/foo", /* Post values */);
update.put("/user-posts/bar", /* Post values */);

 RxFirebaseDatabase.updateChildren(ref, update)
                .subscribe(new Action() {
                    @Override
                    public void run() throws Exception {
                        // Update successful
                    }
                }, new Consumer<Throwable>() {
                    @Override
                    public void accept(Throwable throwable) throws Exception {
                        // Something went wrong
                    }
                });

Kotlin:

val ref: DatabaseReference = FirebaseDatabase.getInstance().getReference()

val update = mapOf(
              "/posts/foo" to /* Post values */,
              "user-posts/bar" to /* Post values */)

ref.rxUpdateChildren(update)
        .subscribe({
                    // Update successful
                }, { 
                    // Handle error
                })

Read from your database

Listen for value events

You can use the RxFirebase.dataChanges() method to get a snapshot(DataSnapshot) of the contents at a given path, as they existed at the time of the event.

This method will emit an event once when subscribed, and again every time the data, including children, changes.

Java:

DatabaseReference ref = ...;

RxFirebaseDatabase.dataChanges(ref)
                .subscribe(new Consumer<DataSnapshot>() {
                    @Override
                    public void accept(DataSnapshot dataSnapshot) throws Exception {
                        if (dataSnapshot.exists()) {
                            // Do something with data
                        } else {
                            // Data does not exists
                        }
                    }
                }, new Consumer<Throwable>() {
                    @Override
                    public void accept(Throwable throwable) throws Exception {
                        // Handle error
                    }
                });

Kotlin:

val ref: DatabaseReference = ...

ref.dataChanges()
        .subscribe({
            if (it.exists()) {
                // Do something with data
            } else {
                // Data does not exists
            }
        }) {
            // Handle error
        }

If you want to get a data as a native object, you can use RxFirebaseDatabase.dataChangesOf(Class<T>) or RxFirebaseDatabase.dataChangesOf(GenericTypeIndicator<T>).

You must unsubscribe a subscription once you're done with listening value events to prevent memory leak.

Listen for child events

Child events are trigger in response to specific operations that happen to the children of a node from an operation such as a new child added through the push() method or a child being update through the updateChildren() method.

You can listen for child events by RxFirebaseDatabase.childEvents() method, which emits an event as following:

• ChildAddEvent - Emitted on ChildEventListener.onChildAdded() call
• ChildChangeEvent - Emitted on ChildEventListener.onChildChanged() call
• ChildMoveEvent - Emitted on ChildEventListener.onChildMoved() call
• ChildRemoveEvent - Emitted on ChildEventListener.onChildRemoved() call

RxFirebaseDatabase.childEvents() will emit all types of event by default. If you need to listen for specific event, you can filter by using ofType() operator in RxJava as following:

Java:

DatabaseReference ref = ...;

RxFirebaseDatabase.childEvents(ref)
                .ofType(ChildAddEvent.class)
                .subscribe(new Consumer<ChildAddEvent>() {
                    @Override
                    public void accept(ChildAddEvent childAddEvent) throws Exception {
                        // Handle for Child add event
                    }
                }, new Consumer<Throwable>() {
                    @Override
                    public void accept(Throwable throwable) throws Exception {
                        // Handle error
                    }
                });

Kotlin:

val ref: DatabaseReference = ...

ref.childEvents()
        .ofType(ChildAddEvent::class.java)
        .subscribe({
            // Handle for child add event
        }) {
            // Handle error
        }

You must unsubscribe a subscription once you're done with listening child events to prevent memory leak.

Read data once

This is useful for data that only needs to be loaded once and isn't expected to change frequently or require active listening.

Similar to listening for the data changes, you can use RxFirebaseDatabase.data() method to get an Optional wrapper of static snapshot of the contents.

Java:

DatabaseReference ref = ...;

RxFirebaseDatabase.data(ref)
        .subscribe(new Action1<DataSnapshot>() {
            @Override
            public void call(DataSnapshot dataSnapshot) {
                if (dataSnapshot.exists()) {
                    // Do something with data
                } else {
                    // Data does not exists
                }
            }
        }, new Action1<Throwable>() {
            @Override
            public void call(Throwable throwable) {
                // Handle error
            }
        });

Kotlin:

val ref: DatabaseReference = FirebaseDatabase.getInstance().getReference()

ref.data()
        .subscribe({
            if (it.exists()) {
                // Do something with data
            } else {
                // Data does not exists
            }
        }) {
            // Handle error
        }

Versioning

RxFirebase2 uses a versioning rule that is related to corresponding Firebase's version by following rule:

RxFirebaseVersion : {major}.{minor}.{patch} =
    {Firebase major}.{Firebase minor * 10 + Firebase patch}.{RxFirebase patch}

For example, a library version that depends on 9.6.0 version of Firebase SDK, whose patch version is 1 will be 9.60.1.

Development Snapshot

Snapshots of the development version are available in [Sonatype's snapshots repository](Sonatype's snapshots repository).

You can register snapshots repo as your project's remote repo as following:

repositories {
    ... other remote repositories ...

    // Add following line
    maven { url "https://oss.sonatype.org/content/repositories/snapshots/" }
}

Currently, there is no snapshot available.

License

Copyright 2017 Ilya Usanov <[e-mail]>

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.