About Event Handlers

Top  Previous  Next

An event handler is a custom code which responds to an API event. For every API call Backendless generates two kinds of events - "before" and "after". The before event is generated before the default logic of the API implementation is executed and the "after" event is fired right after the default API implementation logic. An event handler can respond to either one of these events. A synchronous event handler participates in the API invocation chain and can modify the objects in the chain's flow. For example, the "before" event handlers can modify the arguments of the API calls so the default logic gets the modified objects. Similarly, an "after" handler can modify the return value (or exception) so the client application which made the API request receives the modified value. The diagram below illustrates the flow:

backendless-incocation-chain

Each Backendless service is responsible for emitting the "before" and "after" events for each API call. Custom business logic code can subscribe to these events by extending special "framework" classes and overriding methods corresponding to an API call. For example, the following code demonstrates custom code wrapper for the "before" event of the Publish API call from the Backendless Messaging service:

package com.backendless.ordermanagement.events.messaging_service;

import com.backendless.messaging.DeliveryOptions;
import com.backendless.messaging.Message;
import com.backendless.messaging.PublishOptions;
import com.backendless.servercode.RunnerContext;
import com.backendless.servercode.annotation.Asset;
import com.backendless.servercode.annotation.Async;
import com.backendless.servercode.extension.MessagingExtender;

@Asset( "default" )
public class DefaultChannelEventHandler extends MessagingExtender
{
  @Override
  public void beforePublish( RunnerContext context, Object message, PublishOptions publishOptions, DeliveryOptions deliveryOptions ) throws Exception 
  {
    // custom logic goes here
  }
}

There are several important design elements in the code snippet:

The @Asset annotation specifies the "asset" or in this case a messaging channel for which the code will be called.
The class extends backendless\core\extension\BaseMessagingEventHandler. This is required in order for the custom code to inject itself into the API invocation handling chain. Every service has its own extender class. In this case - BaseMessagingEventHandler indicates it is the extender for the Messaging service.
The beforePublish method is the actual event handler. The name of the method indicates it will be invoked before the default implementation logic of the Publish method.
The method has the same signature as the official Publish method from the Messaging service with the exception of the RunnerContext argument.

 

CodeRunner Context

The RunnerContext class is defined as:

hmtoggle_plus1RunnerContext.java

package com.backendless.servercode;

import com.backendless.commons.DeviceType;

public class RunnerContext
{
  private String appId;
  private String userId;
  private String userToken;
  private DeviceType deviceType;

  public String getAppId()
  {
    return this.appId;
  }

  public String getUserId()
  {
    return this.userId;
  }

  public String getUserToken()
  {
    return this.userToken;
  }

  public DeviceType getDeviceType()
  {
    return this.deviceType;
  }
}

 

The table below provides a summary for all available services. The "Asset" column indicates the type of resource that is the target of the API call which triggered the event. It also helps to think of the "asset" as the context of an event and a container of the object which is created/modified/deleted by the API call. For example, for the Data Service, asset is a table and for Messaging Service it the channel.

Service

Server Code Class to Extend

Asset

Available Events (each item has "before" and "after" events)

User Service

com.backendless.servercode.extension.UserExtender

 

N/A

Login

Register

Update

Remove

Describe

RestorePassword

Logout

Data Service

com.backendless.servercode.extension.PersistenceExtender

Table

Create

FindById

LoadRelations

Remove

Update

Describe

Find

FindFirst

FindLast

Messaging Service

com.backendless.servercode.extension.MessagingExtender

Messaging Channel

Publish

Subscribe

Cancel

Poll

DeviceRegistration

Media Service

com.backendless.servercode.extension.MediaExtender

N/A

acceptConnection

publishStarted

publishFinished

streamCreated

streamFinished

File Service

com.backendless.servercode.extension.FilesExtender

Directory or file in the root of the file storage

MoveToRepositoryDeleteFileOrDirectory

Geo Service

com.backendless.servercode.extension.GeoExtender

Geo category

AddPoint

UpdatePoint

RemovePoint

GetCategories

GetPoints

AddCategory

DeleteCategory

RelativeFind

 


Please let us know how we can improve the documentation by leaving a comment. All technical questions should be posted to the Backendless Support forum. We do not respond to the technical questions on the documentation pages.: