Android SDK

The Android SDK for Backbeam depends on Android Asynchronous Http Client. The source code of the SDK is hosted on Github. You can checkout the repository or download the latest version.

To start using it in your project:

  • If you are using Eclipse import the SDK to your Eclipse workspace and then in the section decicated to Android click on "Add library project"
  • If you are using Android Studio add the SDK to the "libraries" folder of your project. You need to change both the settings.gradleand the build.gradle file in order to include a reference to the SDK

Configure your application

First of all you need to configure the Backbeam singleton in your main activity.

// The subdomain you see in the control panel of your project
Backbeam.setProject("your_project_subdomain");
Backbeam.setEnvironment("dev"); // it must be 'dev' or 'pro'
Backbeam.setContext(getApplicationContext());

// API keys are only needed if you use client-side server logic
// Create the API keys in the control panel of your project
Backbeam.setSharedKey("your_shared_key");
Backbeam.setSecretKey("your_secret_key");

// Configuration needed if you are using server-side logic
Backbeam.setWebVersion("v1");
Backbeam.setHttpAuth("xxxxxxxxxxx");

Be sure to indicate that your application needs Internet access in your manifest AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />

Now you can start coding. All the classes you need are placed in the io.backbeam package. So you can import them individually or import the whole package:

import io.backbeam.*;

Objects

Most of the time you will read and manipulate the data stored in the database using BackbeamObject. This is a very basic class that encapsulates the information of a record in your database. You can access its fields and some other metainformation. These are the most important methods in the BackbeamObject class

  • getString(field) Returns the value of the given field if it is a String. If it is not present or it is not a String this method returns null
  • getId() Returns the unique identifier of this object or null if this object hasn't been stored in the database yet
  • getCreatedAt() Returns the date in which this object was created or null if this object hasn't been stored in the database yet
  • getUpdatedAt() Returns the date in which this object was created or null if this object hasn't been stored in the database yet
  • getDate(field) Returns the value of a date field
  • getNumber(field) Returns the value of a numeric field
  • getJson(field) Returns the value of a JSON field
  • getBoolean(field) Returns the value of a boolean field
  • getDay(field) Returns the value of a "day" field
  • getObject(field) Returns the value of a relationship "to-one"
  • getLocation(field) Returns the value of a "location" field
  • getEntity() Returns the identifier of the entity this object is member of
  • isNew() Returns true if this object hasn't been stored yet
  • isEmpty() Returns true if this object does not have any field value defined yet
  • isDirty() Returns true if there are pending changes in this object to be saved

You have equivalent methods to set the values of each field depending on its value type, but you only need them when using client-side business logic. You will learn more about that in the section about manipulating data

Join results

Many times you will perform joins in your BQL queries and other operations. If the join is made in a relationship "to one" you can just use obj.getObject(fieldname) to get the value of the relationship. Let's see an example where the BQL query is made in the client side:

Backbeam.select("event").setQuery("join place").fetch(100, 0, new FetchCallback() {
  @Override
  public void success(List<BackbeamObject> objects, int totalCount, boolean fromCache) {
    BackbeamObject event = objects.get(0); // pick a place (in real code check the objects.size() first)
    BackbeamObject place = event.getObject("place");
  }
});

You can also make joins in the "to many" side of a relationship. In that case you can fetch a number of objects in the relationship and you can always get the total number of objects in the relationship.

Backbeam.select("place").setQuery("join last 10 events").fetch(100, 0, new FetchCallback() {
  @Override
  public void success(List<BackbeamObject> objects, int totalCount, boolean fromCache) {
    BackbeamObject place = objects.get(0); // pick a place (in real code check the objects.size() first)
    JoinResult join = place.getJoinResult("events");

    List<BackbeamObject> events = join.getResults();
    int count = join.getCount();
  }
});

If you are only interested in the number of objects in a relationship you can just query using for example join events. Check the BQL documentation for further information.

Users authentication

One of the functionalities of the SDK is to remember the authenticated user between sessions of the application. You can always access the current authenticated user using Backbeam.currentUser() and you can logout the user by calling Backbeam.logout(). This applies to all authentication mechanisms.

Where to put the business logic

With Backbeam you can write the business logic in your mobile app or in the server-side. The main pros and cons are the following:

  • Client-side logic is easier for mobile developers
  • The server-side logic can be updated at any moment without releasing new versions, and affects all versions
  • The client-side logic requires API keys. The server-side logic don't, so it is more secure (no secrets to keep in code)
  • Server-side logic can be written once and be used in any platform (iOS, Android, web)

If your choice is to use client-side logic then you should learn: how to mamipulate data, users authentication, and push notifications.

If you think that server-side logic is better for your needs then you should learn how to invoke the server-side logic from your Android code.