Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

ORM

This JavaScript API class allows you to interact with the local RHOM database and programatically add models or get references to models.

Enabling the API

This API is part of the coreapi extension that is included automatically.

extensions: ["coreapi"]

JavaScript Usage

Be sure to review the JavaScript API Usage guide for important information about using this API in JavaScript.

If you are going to be using the JS ORM API, you’ll also need to include these lines in any files that will be using it:

<script type="text/javascript" charset="utf-8" src="/public/api/rhoapi-modules-ORM.js"></script>
<script type="text/javascript" charset="utf-8" src="/public/api/rhoapi-modules-ORMHelper.js"></script>
<script type="text/javascript" charset="utf-8" src="/public/api/rhoapi-modules-Ruby-RunTime.js"></script>

Ruby Usage

For Ruby access to the RHOM database please see the Rhom Ruby API guide.

Methods

addModel( Anoynomous Function methods)

Creates an ORM model reference.

Parameters

  • Anoynomous Function methods :

    • modelName("value") : STRING

      The name of your model.

    • enable("value") : STRING Optional

      Enables Model Properties.

      Possible Values :

      sync

      If set then model is set for RhoConnect Sync.

      propertyBag

      (Default) Model will be of type propertyBag.

      fixedSchema

      Model will be of type fixedSchema.

    • property("name","type") : STRING,STRING Optional

      Used to create properties on your model.

      • name : STRING

        The name of the property.

      • type : STRING

        The type of property value: String, Float, integer, Varchar, Blob – String is default.

    • addIndex("name",[colArray]) : STRING, ARRAY Optional

      Add an index to your fixedSchema model.

      • name : STRING

        The name of the index.

      • colArray : ARRAY

        Array of model column names to use in index, Ex: [‘name’,‘qty’]

    • addUniqueIndex("name",[colArray]) : STRING, ARRAY Optional

      Add an index to your fixedSchema model.

      • name : STRING

        The name of the index.

      • colArray : ARRAY

        Array of model column names to use in index, Ex: [‘name’,‘qty’]

    • belongs_to("name") : STRING Optional

      Add belongs_to association to another defined model, for sync models. Comma-separated String for more than one model.

    • set(property,value) : STRING,VALUE Optional

      Set Behavior of this model. Possible property options and corresponding values.

      • partition : STRING

        The partition to use for this model. Partitions can be used to segment the data and keep non-synched data separate from synched models. Possible values.

        Possible Values :

        local

        This partition is used automatically if the model is not a sync model.

        user

        This partition is used automatically if the model is a sync model.

      • sync_type : STRING

        Sets the type of sync it will be.

        Possible Values :

        none

        If data model is not a sync model.

        incremental

        Used when the data model is a sync model. Just syncs changes.

      • sync_priority : INTEGER

        Determines how frequently to check for changes. In seconds. Default is 1000.

Synchronous Return:

  • Model

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.ORM.addModel( Anoynomous Function methods)

databaseFullReset(BOOLEAN resetClientInfo, BOOLEAN resetLocalModels)

Deletes all records from the property bag and model tables.

Parameters

  • resetClientInfo : BOOLEAN Optional

    True to clean the client_info table, false otherwise.

    False on default.

  • resetLocalModels : BOOLEAN Optional

    True to clean local (non-synced) models, false otherwise.

    Reset all models.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.ORM.databaseFullReset(BOOLEAN resetClientInfo, BOOLEAN resetLocalModels)

databaseFullResetAndLogout()

Deletes all records from the property bag and model tables. Logout the user from RhoConnectClient. For examples, see Resetting the Database in Using the Local Database with ORM.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.ORM.databaseFullResetAndLogout()

databaseFullResetEx(HASH propertyMap)

Deletes all records from the property bag and model tables for the model names passed in parameters.

Parameters

  • propertyMap : HASH

    Properties map.

    • models : ARRAY

      Array of models names to reset.

    • reset_client_info : BOOLEAN Optional

      If set to true, client_info table will be cleaned.

      False on default.

    • reset_local_models : BOOLEAN Optional Default: false

      If set to true, local(non-synced models) will be cleaned.

      Reset all models.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.ORM.databaseFullResetEx(HASH propertyMap)

databaseFullclientResetAndLogout()

Deletes all records from the property bag and model tables. Logout the user from RhoConnectClient and erase all RhoConnectClient device information. Equivalent to ORM::ORM.databaseFullReset(true) followed by RhoConnectClient.logout.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.ORM.databaseFullclientResetAndLogout()

databaseLocalReset()

Reset only local (non-sync-enabled) models.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.ORM.databaseLocalReset()

export()

Deprecated

Export db.

Synchronous Return:

  • STRING

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.ORM.export()

getClientId()

Returns the current sync client id.

Synchronous Return:

  • STRING

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.ORM.getClientId()

getModel(String modelName)

Returns a model.

Parameters

  • modelName : String

    Name of the model you want returned.

Synchronous Return:

  • Model

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.ORM.getModel(String modelName)

haveLocalChanges()

Returns true if any of the Rhodes model objects have local database changes that need to be synchronized, false otherwise.

Synchronous Return:

  • BOOLEAN

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.ORM.haveLocalChanges()

import(STRING zipName)

Deprecated

Import db.

Parameters

  • zipName : STRING

    The name of the zip file.

Synchronous Return:

  • BOOLEAN

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.ORM.import(STRING zipName)

Examples

Add ORM model, create ORM object

This example describes creating model and adding model object.

var productModel = Rho.ORM.addModel(function(model){
  model.modelName("Product");
  model.enable("sync");
  model.property("name","string");
  model.property("brand","string");
  model.property("price","float");
  model.set("partition","user");
});

// create model object and save it to database
var product = productModel.create({
  brand: 'Apple',
  name: 'iPhone5',
  price: 199.99});

// read product from database
var product = productModel.find('first');
product.get('brand'); // Apple
product.get('name'); // iPhone5

                        
Get Model by name

Get a model.

// The model 'Product' must have been defined in JavaScript execution earlier 
// in order for 'getModel' to work properly. 

// The models generated in RhoStudio, are not accessible in JavaScript unless 
// the classes are defined via the  Rho.ORM.addModel api


// Get a model by its name after it has been added
var productModel = Rho.ORM.getModel("Product");

           
                    
ORM databaseFullResetEx Method Examples

Delete all Rhodes model objects for a source, filtering by conditions.

Rho.ORM.databaseFullResetEx({'models' : ['Product', 'Customer'], 'reset_client_info' : true, 'reset_local_models' : true} 
                            

Remarks

Performance Findings Using Property Bag Vs Fixed Schema

In our testing, we have found that, overall, the Fixed Schema database model has much better performance that the same tests run using Property Bag, concerning complex data sets. We strongly recommend that enterprise-grade apps use the Fixed Schema model for their app databases as we have seen test results upwards of 10 times faster using the Fixed Schema model. The only current drawback to Fixed Schema is that it is more complex to initially setup. If your dataset is fairly simple in construction, Property Bag should prove sufficient.