Quick Start

Top  Previous  Next

The goal of this chapter is to enable a developer to quickly become familiar with Backendless custom business logic feature. At the end of the instructions provided below you will have a Backendless application with a custom API event handler which modifies an object before it is saved with the Backendless API.

 

Using Code Generator

1.Login to Backendless console and create a new application called OrderManagement. You can use an existing application, however this guide assumes that certain data tables are created, which may conflict in an existing app. Use caution if you decide to use an existing app.
2.Click the Data icon to navigate to the Data/Schema browser section of the console:
backendless-data-section.zoom70
 
3.Click the "plus" icon in the lower left corner of the screen to add a new table. The reason a table should be created first is because one of the next steps will be registering an event handler for this table. Name the table "Order".
create-table.zoom50
 
4.Click Save to create the table. Select Yes in the popup to modify the table schema. Click Add Column and enter "customername" in the Name field as shown below:
customername-popup.zoom80
 
5.Click Save to add the column.
6.Click the Business Logic icon to navigate to the custom business logic section:
navigate-to-biz-logic.zoom80
 
7.Select Data Tables in the Service Events Handlers section. This is needed because you will be creating an event handler for a Data Service API call:
data-tables-handler
8.Every category of service event handlers contains three tabs: Code Generation, Debug and Production. Each tab represents a state of the code and displays a "model" of the code available in the corresponding state. A model is a collection of event handlers and timers.
Code Generation - a state containing a model created by the developer and lists the event handlers and timers for which the code should be generated.
Debug - displays a model recognized by CodeRunner™, a special utility used for local debugging of custom business logic.
Production - contains a model deployed into the backend for production purposes. This is the currently active model in the application.
event-handler-tabs
 
9.Select JAVA from the Language listbox on the Code Generation tab. This selection sets the programming language for the generated source code when event handlers and timers are added. Language selection can be changed at any time, which will result in the regenerated source code for the selected language.
10.Click the Add Event Handler button.
11.In the New Data Event Handler popup, select the Order table in the Context drop down:
new-data-event-handler
 
12.Click Save to create the handler. The system adds a new handler to the code generation model and automatically creates the necessary framework code which you will use to add your custom business logic. Additionally, the code generator automatically creates a class definition for the table referenced in the event handler. For instance, for the Order table, the generated code includes Order.java:
java-generated-code
 
13.Click the Download Code button located under the source code tree. Backendless generates a zip file with the same name as the name of the application. The zip file contains all the generated source code as well as project files:
download-java-code

 

Customizing and Running Code

1.At this point the generated file contains a complete project with all the necessary dependencies and source code which can be easily modified. Expand the zip file and open the project in IDEA or Eclipse.
 
2.The .zip file downloaded in step 13 described above already includes the CodeRunner™ SDK. The directory where you unzip the project file will be further referenced as [backendless-coderunner-home]in this guide. The CodeRunner™ SDK distribution (which is included into the zip) has the following structure:
coderunner-contents
where:
/bin - contains utilities for debugging and deploying custom code.
/classes - directory which СodeRunner™ uses by default when it looks for custom business logic code to debug or deploy.
/libs - may contain additional Java dependencies (.jar files) which will be added to the deployment.
 
3.The downloaded project uses[backendless-coderunner-home]/classes as the directory for the compiled output. This is important as the /classes directory is automatically recognized by CodeRunner™ when it looks for custom code.
 
4.Open OrderTableEventHandler.java and modify as shown below (adding the code into the beforeCreate method):
package com.backendless.ordermanagement.events.persistence_service;

import com.backendless.ordermanagement.models.Order;
import com.backendless.servercode.RunnerContext;
import com.backendless.servercode.annotation.Asset;
import com.backendless.servercode.annotation.Async;
import com.backendless.servercode.extension.PersistenceExtender;

/**
* OrderTableEventHandler handles events for all entities. This is accomplished
* with the @Asset( "Order" ) annotation. 
* The methods in the class correspond to the events selected in Backendless
* Console.
*/
@Asset( "Order" )
public class OrderTableEventHandler extends PersistenceExtender<Order>
{
  @Override
  public void beforeCreate( RunnerContext context, Order order ) throws Exception
  {
    System.out.println( "About to insert modified Order object into the data store" );
    String customerName = order.getCustomername();
    System.out.println( "?ustomer name received from client - " + customerName );
    order.setCustomername( customerName.toUpperCase() );
    System.out.println( "?ustomer name after the change - " + order.getCustomername() );
  }
}

 

5.IMPORTANT: Make sure you are using Java 8 when compiling the code.
 
Compile the code and make sure [backendless-coderunner-home]/classes contains the following directory structure:
coderunner-with-compiled-code

 

6.Open a command prompt window and change the current directory to [backendless-coderunner-home]/bin
 
7.Run the CodeRunner™ script as shown below. For instance, on a Linux system, the command to run CodeRunner™ is:
./coderunner.sh

 

8.Once CodeRunner™ starts, it produces the following output:

your-comp-name:bin username$ ./CodeRunner.sh
Listening for transport dt_socket at address: 5005
[INFO] CodeRunner(tm) Backendless Debugging Utility
[INFO] Copyright(C) 2016 Backendless Corp. All rights reserved.
[INFO] Version: 3.0.10 Build date: 20160309-0738
[INFO] CodeRunner session is running for 2 hour and will be terminated on 16:11:08.061[UTC]
 
[INFO] Registering runner on: https://api.backendless.com with secretKey: 3EAC25F1-5C3F-27CF-FFE8-57347B89A100
[INFO] Runner successfully registered
[INFO] Parsing event model...
[INFO] Build successfully: 1 handler, 0 timers
[INFO] Deploying model to server, and starting debug...
[INFO] Model successfully deployed.
[INFO] Waiting for events...

 

10.At this point CodeRunner™ is connected to Backendless and the code is ready for local debugging. Return to Backendless Console, click the Business Logic icon, select Data Tables from the Service Events Handlers section and click the Debug tab. It shows the events which are available in the debug model:
event-handler-in-debug

 

11.To test the code you must issue an API request to store an object in the Order table. You could write a client application using any programming language of your choice:
Java                - Create object using Backendless SDK for Java
Objective-C        - Create object using Backendless SDK for iOS
JavaScript        - Create object using Backendless SDK for JavaScript
ActionScript        - Create object using Backendless SDK for Flex/AIR
C#/VB                - Create object using Backendless SDK for .NET
 
or with REST        - Create object using REST API

 

12.This guide uses the REST API to create an API request to store an object. The REST request with the curl utility is:
8.
curl -H application-id:APP-ID -H secret-key:REST-SECRET-KEY -H Content-Type:application/json -X POST -d "{\"customername\":\"foobar corp\"}" -v https://api.backendless.com/v1/data/Order

The APP-ID and REST-SECRET-KEY values must be obtained from the Manage > App Settings screen in Backendless Console:
app-id-secret-key.zoom70

 

13.Run the curl command in a separate command prompt window. Once the API call completes, notice the following output in the window where CodeRunner™ runs. The output comes from the custom code you developed:

About to insert modified Order object into the data store
Сustomer name received from client - foobar corp
Сustomer name after the change - FOOBAR CORP

 

14.To make sure the custom code has executed properly, return to Backendless Console and switch back to Data section. Select the Order table and check the object stored in the table:
custom-code-result-data
 
 

Local Debugging

1.Now that you confirmed that the custom code is plugged into the API invocation chain, it is important to establish a connection between the coderunner process and the IDE debugger. CodeRunner is automatically configured to accept remote debugging connections on port 5005. To connect to the process, use the remote debugging facility in the IDE. For example, in IntelliJ IDEA, select "Run" from the main menu and then select "Edit Configurations". Click the "plus" icon to add a new configuration. Select "Remote" from the list and enter "ordermanagement" into the name field as shown below:
idea-remote-debug.zoom70

 

2.Click OK and launch the debugger. Once the debugger is attached to the coderunner process, you can establish breakpoints in the code and re-run the client application. Usually debugging takes more time than the duration of the timeout on the client-side. You should expect that the client application (or even the curl request) will receive a timeout, but you should still be able to continue the debugging of your custom code.
idea-debug-backendless.zoom70s

 

Deploying Code to Production

Deploying code to production can be done using the deploy.sh utility available in the [backendless-coderunner-home]/bin directory. To run the deployment script, it is necessary to use CodeRunner secret key - the same key used for the debugging purposes:

1.Navigate to the Manage > App Settings screen in Backendless Console and copy the CodeRunner Secret Key.
 
2.In a command prompt window change the current directory to [backendless-coderunner-home]/bin.
 
3.Run the following command:
./deploy.sh 

 The deploy script uses application id and CodeRunner secret key from bin\runner.config.

 

4.Once the deployment script runs, it should produce the following output:

your-comp-name:bin username$ ./deploy.sh
[INFO] CodeRunner(tm) Backendless Debugging Utility
[INFO] Copyright(C) 2016 Backendless Corp. All rights reserved.
[INFO] Version: 3.0.10 Build date: 20160309-0738
[INFO] CodeRunner session is running for 2 hour and will be terminated on 16:26:25.795[UTC]
 
[INFO] Registering runner on: https://api.backendless.com with secretKey: 3EAC25F1-5C3F-27CF-FFE8-57347B89A100
[INFO] Runner successfully registered
[INFO] Parsing event model...
[INFO] Build successfully: 1 handler, 0 timers
[INFO] Deploying model to server, and starting debug...
[INFO] Model successfully deployed.
[INFO] Waiting for events...
[INFO] Publishing 1 event handler and 0 timers and 0 services to the server…
[INFO] Successfully published all event handlers and timers.
[INFO] If you connected to coderunner for debug - please stop debugging
[INFO] CodeRunner will shutdown now
[INFO] Debugging Utility disconnected successfully
[INFO] Thank you for using Backendless

 

5.Once the code is deployed to production, it is immediately plugged into your application. You can verify the production deployment in Backendless Console. Open the Business Logic section, click Data Tables under the Service Events Handlers section and click the Production tab:
service-handler-production
 
6.An event handler running in production can be disabled by clicking the checkbox in the Enable column.

 

This concludess the Quick Start. You can try repeating the process for other event handler or timers. If you run into any problems or have any questions, do not hesitate contacting us at http://support.backendless.com.


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.: