Skip to content

Handlers, Events and Listeners

Backendless Real-Time Database emits events when objects are created, updated, upserted or deleted. These events, along with the object which triggered the event, can be delivered in real-time to your application code via listener objects.

In order to subscribe to a real-time event, your application code must obtain an event handler for a data table in the Backendless database. A handler channels real-time events to the added listeners. These events include information about objects which were created, updated or deleted from the table the handler represents. To obtain a handler for a table, use the following API:

EventHandler<Map> rtHandler = Backendless.Data.of( "TABLE-NAME" ).rt();

EventHandler<E> rtHandler = Backendless.Data.of( E ).rt();

where:

Argument                Description
TABLE-NAME Name of the table to obtain a handler for.
E a Java class identifying the table to obtain a handler for.

Important

Multiple invocations of the methods to get a handler for the same data table return a new instance of the handler. As a result, each handler maintains its own collection of listeners. This can provide additional convenience if different parts of the client application need to have its own instance of the handler. Alternatively, if the same handler must be shared across the entire application, it is simple to configure it as a singleton object.

Real-Time Event Listeners

In order to receive real-time events from the Backendless database, a listener must be registered using an event handler described above.

A listener is an object which implements the AsyncCallback interface. You can see specific implementations of the interfaces in sections of the doc describing individual real-time events:

package com.backendless.async.callback;

import com.backendless.exceptions.BackendlessFault;

public interface AsyncCallback<T> {
  void handleResponse(T eventObject);
  void handleFault(BackendlessFault fault);
}

The diagram below illustrates the relationship between a data table in Backendless database, an API event handler and listeners handling real-time events:

handlers-listeners

The event handler object can be used for adding and removing listeners for the following events:

  • create - triggered when an object is saved in the database table represented by the event handler.
  • update - triggered when an object is updated in the database table represented by the event handler
  • upsert - triggered when an object is upserted in the database table represented by the event handler
  • delete - triggered when an object is deleted from the database table represented by the event handler
  • bulk update - triggered when multiple objects are updated in the database table represented by the event handler
  • bulk upsert - triggered when multiple objects are upserted in the database table represented by the event handler
  • bulk delete - triggered when multiple objects are deleted from the database table represented by the event handler