Tutorial: Migration guide

Android Migration guide

This guide will point out the main differences between Webcom's Android SDK et Firebase's SDK.

Configuration

Webcom's Android SDK is an Android Library and not a simple Jar file like Firebase's.

The libray defines the Android permissions & the Context so you don't have to do it yourself.

However, you can still set the Context yourself. To do so, just add the following lines to your Android Application's or Activity's onCreate method.

@Override
public void onCreate() {
    super.onCreate();
    Config.setContext(this);
    // other setup code
}

MultiThread

One of the main differences is that the new library is not working on the UI thread. Therefore all callbacks are not executed on the UI thread so you might need to call runOnUiThread to execute your actions:

runOnUiThread(new Runnable() {
    @Override
    public void run() {
        // UI interaction
    }
});

Data navigation

Creating a reference to your Webcom database doesn't change:

Webcom myRef = new Webcom("<your-app>");

Firebase's methods getParent() & getRoot() are renamed to parent() & root(). The child() method is unchanged.

Read Data

Webcom's Android SDK API is similar to the JavaScript API.

Firebase's method addValueEventListener(), addChildEventListener() are merged into a single method on() with a additionnal event type parameter.

Both ValueEventListener and ChildEventListener are replaced with the Listener class OnQuery.

myRef.on(Query.Event.VALUE, new OnQuery(){
    @Override
    public void onComplete(DataSnapshot snapData, @Nullable String prevName) {
        // code to handle current data
        Object value = snapData.value();
    }
    @Override
    public void onCancel(WebcomError error) {
        // event subscription was canceled because of permission reason
    }
    @Override
    public void onError(WebcomError error) {
        // an error occured
    }
});

// instead of

myRef.addValueEventListener(new ValueEventListener() {
    @Override
    public void onDataChange(DataSnapshot snapshot) {
        // code to handle current data
        Object value = snapshot.getValue(); 
    }
    @Override public void onCancelled(FirebaseError error) { }
});

The Webcom's Android API allows for a finer control of event subscription.


myRef.on(Query.Event.CHILD_ADDED, new OnQuery(){
    @Override
    public void onComplete(DataSnapshot snapData, @Nullable String prevName) {
        // code to handle current data
        Object value = snapData.value();
    }
    @Override
    public void onCancel(WebcomError error) {
        // event subscription was canceled because of permission reason
    }
    @Override
    public void onError(WebcomError error) {
        // an error occured
    }
});
myRef.on(Query.Event.CHILD_CHANGED, new OnQuery(){
    @Override
    public void onComplete(DataSnapshot snapData, @Nullable String prevName) {
        // code to handle current data
        Object value = snapData.value();
    }
    @Override
    public void onCancel(WebcomError error) {
        // event subscription was canceled because of permission reason
    }
    @Override
    public void onError(WebcomError error) {
        // an error occured
    }
});

// instead of

myRef.addChildEventListener(new ChildEventListener() {
    @Override
    public void onChildAdded(DataSnapshot snapshot, String previousChildKey) {
        Object value = snapshot.getValue();
    }
    @Override
    public void onChildChanged(DataSnapshot snapshot, String previousChildKey) {
        Object value = snapshot.getValue();
    }
    @Override
    public void onChildRemoved(DataSnapshot snapshot) {
        Object value = snapshot.getValue();
    }
    @Override
    public void onChildMoved(DataSnapshot snapshot) {
        Object value = snapshot.getValue();
    }
    @Override public void onCancelled(FirebaseError error) { }
});

A listener can also be triggered just once. With Webcom's Android SDK, you are not limited to the "value" event.


myRef.once(Query.Event.VALUE, new OnQuery(){
    ...
});
myRef.once(Query.Event.CHILD_ADDED, new OnQuery(){
    ...
});

// instead of

myRef.addListenerForSingleValueEvent(new ValueEventListener() {
 ...
});

Write Data

Firebase's method setValue(), updateChildren() & removeValue() are renamed as set(), update() & remove().

All write methods can accept a OnComplete Completion Listener as a parameter. OnComplete replaces Firebase's Firebase.CompletionListener.


myRef.set("I'm writing data", new OnComplete(){
    @Override
    public void onComplete() {
        // Data saved successfully.
    }
    @Override
    public void onError(WebcomError error) {
        // Data could not be saved
        String errorMessage = error.getMessage();
    }
});

// instead of

myRef.setValue("I'm writing data", new Firebase.CompletionListener() {
    @Override
    public void onComplete(FirebaseError firebaseError, Firebase firebase) {
        if (firebaseError != null) {
            // Data could not be saved
            String errorMessage = firebaseError.getMessage();
        } else {
            // Data saved successfully.
        }
    }
});

For more information, see the Write data tutorial or the POJO tutorial if you prefer to use your own Java Objects.

Authentication

Webcom's SDK does not use a global listener for authentication state. The OnAuth listener must be passed as an argument to the authentication methods:

myRef.authWithPassword("caramel@webcom.com", "coneexplosion", new OnAuth(){
  @Override
  public void onComplete(@Nullable AuthResponse response) {
    // User account authenticated
    String token = response.getToken();
  }
  @Override
  public void onError(WebcomError error) {
    // User account not authenticated
  }
});

For more information, see the Authentication tutorial.