Mobile server side query components

Contents 1 Introduction 2 SecuredJSONProcess 3 Mobile Service implementation 4 ProcessHQLQuery class 4.1 Server side example 4.2 Client side call example 5 JSONProcessSimple class 5.1 Server side example 5.2 Client side call example

Introduction

Openbravo Mobile Core provides some classes to interact retrieving data or to execute processes in the server side. These classes can be invoked from the client side.

This is the hierarchy of abstract classes that are used for this purpose:

SecuredJSONProcess

This class is not intended to be directly extended. It provides the security layer for the ProcessHQLQuery and JSONProcessSimple classes.

Refer to Security Model documentation to understand the security model proposed for mobile applications.

Classes extending SecuredJSONProcess can be securitized overriding the following methods:

• getFormId: Returns a String with the ID of the form representing the mobile application. Only if the current role has access to this form, the process will be executed
• bypassSecurity: If this method returns true, the process can be executed by any valid session regardless of if it has access to the mobile application. This should only be bypassed in very rare cases in which the process does not execute any action that modifies data and the information returned does not compromise security at all
• getProperty: Returns a String with the property that grants access to the current process
• bypassPreferenceCheck: Boolean that allows to bypass preference based security (getProperty is not evaluated if true is returned by this method). When preference check is bypassed, the process can be executed by any session that has access to the application form
• hasPermission: If this method is overridden, the previous methods are not used. If it returns true, the process is accessible and if it returns false it is not. In general, this method should not be overridden. The only exception to this rule, is when the security model proposed by default does not fit your business requirements and you need to implement your own model.

Mobile Service implementation

Since RR16Q2 it is possible to have multiple classes implementing the same Mobile Service. To identify the service that it is implementing it is needed to add an Annotation using the MobileServiceQualifier qualifier and declare the service name:

@MobileServiceQualifier(serviceName = "org.openbravo.retail.posterminal.master.BusinessPartner")

It is also possible to determine the order in which the different classes are executed overriding the getPriority() method. Openbravo provided implementations have a default priority of 100.

  /**
   * Returns the execution priority within the classes implementing a Mobile Service.
   * 
   * @return an int with the priority value. The lower int the higher priority.
   */
  protected int getPriority() {
    return 100;
  }

Finally it is possible to determine if the next class has to be executed when the current implementation finish successfully or when it throws an exception. By default Openbravo won't call any other class with lower priority. There are 2 methods available that can be override to configure this behavior:

  /**
   * Mobile Service processes should override this method to determine if the next priority mobile
   * service class should be executed or not.
   * 
   * @return true to execute the next service class.
   */
  protected boolean executeNextServiceClass() {
    return false;
  }
  
  /**
   * Mobile Service processes should override this method to determine if the next priority mobile
   * service class should be executed or not when this service has thrown an exception.
   * 
   * @return true to execute the next service class.
   */
  protected boolean executeNextServiceClassOnFailure() {
    return false;
  }

ProcessHQLQuery class

The aim of this class is to return a JSON object based on a (set of) HQL query. Classes extending this class, return a HQL that will be used to generate the object.

To learn more about HQL queries, see The Hibernate Query Language.

This class implements two methods:

• isAdminMode: Optional boolean method. To know more about what "Administrator mode" concept means, you can refer to this document: DAL - Administrator Mode

• getQuery: Receives a JSON object and returns a JSON object with the list of HQL queries to execute. Parameters are also sent to the server in a JSON object. There are some tags that can be used within the HQL query that provide shortcuts to environmental attributes. See the Client-Entity wiki page for more information about the tags' concepts:
  • $clientCriteria: Get readable clients
  • $orgCriteria: Get readable organizations
  • $naturalOrgCriteria: Get the natural organization tree
  • $parentOrgCriteria: Get the parent organization tree
  • $childOrgCriteria: Get the child organization tree
  • $activeCriteria: Ensure the record is active
  • $readableCriteria: Only readable records (belongs to a readable client, belongs to a readable organization and is active)
  • $readableClientCriteria: Only readable records (belongs to a readable client and is active)
  • $roleId: Current role ID
  • $userId: Current user ID
  • $languageId: Current language ID

Server side example

package org.openbravo.retail.posterminal.example;
 
import java.util.Arrays;
import java.util.List;
 
import org.codehaus.jettison.json.JSONException;
import org.codehaus.jettison.json.JSONObject;
import org.openbravo.mobile.core.process.ProcessHQLQuery;
 
@MobileServiceQualifier(serviceName = "org.openbravo.retail.posterminal.example.MyExample")
public class MyExample extends ProcessHQLQuery {
 
  @Override
  protected boolean isAdminMode() {
    return true;
  }
 
  @Override
  protected List<String> getQuery(JSONObject jsonsent) throws JSONException {
    return Arrays
        .asList(new String[] {"from Currency where id =:currency and $readableCriteria"});
  }
}

Client side call example

The query is called from the client-side using the OB.DS.Request object. It has two parameters: the JSON object sent and the callback handler:

new OB.DS.Request('org.openbravo.retail.posterminal.example.MyExample').exec(
  {
    currency: this.get('terminal').currency
  }, function(data) {
    if (data[0]) {
      console.log('This is the returned object');
      console.log(data[0]);
    }
  }
);
 

JSONProcessSimple class

The purpose of the classes extending it should be executing a process in the backend, returning as result a JSON object.

It implements one method

• exec: Receives a JSON object and returns a JSON object. Unlike ProcessHQLQuery, it doesn't just execute a query: any custom logic can be implemented inside.

Server side example

package org.openbravo.retail.posterminal.example;
 
import javax.servlet.ServletException;
 
import org.codehaus.jettison.json.JSONException;
import org.codehaus.jettison.json.JSONObject;
import org.openbravo.mobile.core.process.JSONProcessSimple;
 
@MobileServiceQualifier(serviceName = "org.openbravo.retail.posterminal.example.MyExample")
public class MyExample extends JSONProcessSimple {
 
  public JSONObject exec(JSONObject jsonsent) throws JSONException, ServletException {
 
    JSONObject result = new JSONObject();
 
    // Here do whatever you need and finally return a JSONObject object
 
    // It is needed to put an object called 'data' if you want to return some variables inside the result JSONObject
    // It is needed to put a variable 'message' if you want to return a string inside the result JSONObject
    // You can return a 'status' variable with '0' in case everything went OK or '1' if there was an exception inside the result JSONObject
 
    return result;
  }
}

Client side call example

new OB.DS.Process('org.openbravo.retail.posterminal.example.MyExample').exec({
  currency: this.get('terminal').currency
}, function(data) {
  if (data && data.exception) {
    // Error handler
  } else {
    console.log('This is the returned object');
    console.log(data);
  }
});

Category: Mobile Developers Guide