Data Handling with Rhom and ORM

The RhoMobile Suite provides several APIs for handling device data. Released with RhoMobile Suite 5.3 is the ORM common API, which supports JavaScript and Ruby. Pay attention to ORM Common API has not been officially released. It should not be used in a production environment.

RMS 5.2 and earlier versions support the original Rhom API for Ruby apps and the ORM API, which adds JavaScript support to Rhom via the OPAL library.

RMS 5.3 and higher:

• ORM Common API (JavaScript and Ruby)
• ORM Model Common API (JavaScript and Ruby)

RMS 5.2 and lower:

• ORM API and ORM Model API (JavaScript)
• Rhom API (Ruby)

Documentation:

• ORM Common API Guide (JavaScript)
• ORM Common API Guide (Ruby)
• JavaScript ‘Rhom’ Guide
• Ruby Rhom Guide

• What is ORM?
• What’s a model?
• Property Bag Model
• Fixed Schema Model
• How to Include the ORM API
• Database Encryption

What is ORM?

In general computing, ORM refers to the object-relational mapping technique that permits records of a relational database to be stored and retrieved programatically as objects. For RhoMobile, the ORM API provides a powerful high-level interface to an on-device SQLite database that can work alone or with the RhoConnectClient to enable two-way synchronization between your application and a RhoConnect server.

One of the main benefits of using an ORM is the simplicity it brings to database operations. Instead of having to write complex SQL statements by hand, an app can perform database actions by getting and setting properties on model objects. For example:

Update a record with a SQL command:

update product set price=119,brand='Symbol' where object='12345'

Update the same record with ORM:

product.updateAttibutes({price: 119, brand: "Symbol"});

Delete a record with SQL:

delete from product where object='12345'

Delete an object with ORM:

product.destroy();

What’s a model?

In general, RhoMobile applications follow the Model-View-Controller (MVC) pattern. In RhoMobile, a model can store information from two sources:

• Data created or collected on the device
• Data retrieved from a RhoConnect synchronization server

Each model contains attributes (aka ‘fields’) that store information relating to that model. For example, a Product model might have the attributes of name, brand and price. Applications will normally have a model for each entity that they handle (i.e. Customer, Product, Invoice, InvoiceLine, Order, LineItem, etc).

RhoMobile apps can use two kinds of models:

• Property Bag
• Fixed Schema

Each model type has advantages and disadvantages depending on the application.

Property Bag Model

In the property bag model, data is stored as key-value pairs in a single table using the object-attribute-value or entity-attribute-value model. This model is sometimes referred to as ‘open schema’ because the fields (or keys) do not have to be defined in advance; the API stores and syncs all key-value pairs that are entered.

Advantages

• Simple, doesn’t require advance attribute design
• Attributes can be added or removed without modifying the database schema
• Requires no data migration following a schema change

Disadvantages

• Since all attributes are indexed, the database can be much larger than with fixed schema
• Sync process can be slower because database insertions are performed at the attribute level

Fixed Schema Model

In a fixed schema model, each model has a separate database table and attributes forms the columns of that table. In this sense, the fixed schema model is similar to a traditional relational database.

Advantages

• Smaller database size; indexes can be assigned to specific attributes
• Sync process may be faster because whole objects are inserted at once

Disadvantages

• Schema changes require data migration
• Database performance may be slow without careful index specificity

How to Include the ORM API

By default, RhoMobile apps will be built to use the older Rhom implementation (for Ruby) and ORM implementation (for JavaScript). To activate the newer ORM Common API (which supports both JavaScript and Ruby), add the following line to application’s rhoconfig.txt file:

use_new_orm = 1  

Possible Values:

• 0 = use ‘old’ Rhom/ORM API (default)
• 1 = use newer ORM Common API

Database Encryption

If your application requires local (on-device) database encryption, enable it by setting a flag in build.yml:

encrypt_database: 1

If you are using RMS with version lesser than 6.0.58 and want to update your application with a version, built on newer RMS version, and you don’t want to database be automatically clean - you should enable a flag in build.yml:

use_deprecated_encryption: 1

Platform Notes

• iOS uses an AES 256 encryption algorithm from the iOS SDK.
• Android uses an AES 256 ecryption algorithm from the Android SDK.
• Windows Mobile uses an RC4 algorithm from Windows Mobile SDK.