TubDataStore

TubDataStore

Entity communication class. Use it to:

  • execute any entity method using TubDataStore#run
  • execute any SQL statement using TubDataStore#runSQL or TubDataStore.execSQL (we strongly recommend usage of ORM instead SQL)
  • store several named data collection using TubDataStore#currentDataName (data stored inside server memory, not in JS, this is very good for GC)
  • iterate other collection rows using TubDataStore#next, eof, e.t.c and retrieve row data using TubDataStore.get

  • serialize data to XML or JSON

    To retrieve data from database using build-in ORM (to execute entity select method) preffered way is to use UB.Repository fabric function.

Constructor

new TubDataStore(entity)

Arguments:
  1. entity (String|TubEntity)

Members

bof: Boolean

Indicate current position in data collection is on the begining of collection

eof: Boolean

Indicate current position in data collection is on the end of collection.

entity: TubEntity readonly

Entity repository created with

connection: TubConnection

Database connection

initialized: Boolean

Is store initialized

asJSONObject: String

Return string representation of Instance in format [{attr1: value1, attr2: value2},... ]

asJSONArray: String

Return string representation of Instance in Array of array format

asXMLPersistent: String

Return XML representation of Instance in MS DataSet format

currentDataName: String

Active dataset name we work with. There is some predefined dataNames - see mixin documentation for details

Predefined values:

  • selectBeforeUpdate
  • selectAfterUpdate
  • selectAfterInsert
  • selectBeforeDelete

rowCount: Number

Record count. If DataStore is not initialized or empty will return 0.

totalRowCount: Number

Total record count if store are filled with withTotal() option. If DataStore is not initialized or empty or inited without withTotal() will return -1.

rowPos: Number

Row position inside currentDataName dataset. Read/write

Methods

run(methodName, params) → Boolean

Run any entity method.
Arguments:
  1. methodName (String)
  2. params (Object|TubList)
Example
var store = new TubDataStore('doc_attachment');
store.run('update', {execParams: {
         ID: 1,
         approved: 0
     }
});

store.run('anyEntityMethod', {param1: 'valueOfParam1', ...});

runSQL(sql, params)

Execute SQL with parameters and place result into dataStore. This method expect SQL statement have result.

To execute SQL statement without result (insert for example) - use TubDataStore.execSQL instead.

Arguments:
  1. sql (String)  SQL statement to run
  2. params (Object|TubList)  SQL parameters list

execSQL(sql, params)

Execute SQL with parameters. Not wait result data
Arguments:
  1. sql (String)  SQL statement to run
  2. params (Object|TubList)  SQL parameters list

initFromJSON(source)

init dataStore content from JSON string If you need to init dataStore w/o rows:

 var ds = new TubDataStore('myEntityCode');
 ds.initFromJSON({"fieldCount":1,"values":["ID"],"rowCount":0});
 console.log(ds.initialized); // TRUE

WARNING!!! during initFromJSON UnityBase determinate field types from vield values, so if some data column contain only numeric values it becode Number (even if in source it String).

Arguments:
  1. source

fieldIndexByName(fieldName)

Return zero based index of fieldName from current data store (-1 if not found)
Arguments:
  1. fieldName (String)
Example
var r = UB.Repository('cdn_organization').attrs(['ID', 'mi_owner.name']).where('[ID]', '=', 3000000002801).select();
            console.log(r.fieldIndexByName('mi_owner.name')); // 1
            console.log(r.fieldIndexByName('unexistedAttr')); // -1

get(attrib) → Number|String

Return value of attribute.

In case store initialized using TubDataStore.run style we can return Number or String type, but in case it initialized using runSQL columns data types is unknown and you must cast value do required type directly.

Arguments:
  1. attrib (Number|String)  attribute index or name. Index is faster but less readable.

getAsBuffer(attrib) → ArrayBuffer

Return value of attribute as ArrayBuffer.

You can apply this method to blob fields only

Arguments:
  1. attrib (Number|String)  attribute index or name. Index is faster but less readable.

next()

Move next

prev()

Move prev

first()

Move first

last()

Move last

generateID() → Number

Generate a new identifier (int64)

freeNative()

Release all internal resources. Store became unusable after call to freeNative()

initialize(source, keyMapopt) → TubDataStore static

Initialize DataStore from one of supported source formats:

  • Flatten(fastest): 
    {fieldCount: K, rowCount: Z, values: [field1Name, ..., fieldKName, row1field1Value,  ..., row1fieldKValue, row2field1Value,..]}
  • Array-of-array : 
    [[row1field1Value,  ..., row1fieldKValue], ..., [rowZfield1Value, ... rowZfieldKValue]

  • Array-of-object : 

    [{field1Name: row1field1Value, ..., fieldKName: row1fieldKValue}, ....]

    Can (optionally) convert source field names to new names using keyMap array.

Arguments:
  1. source (Object|Array)
  2. [keyMap] (Array:.<(String:|Object:)>)  Optional mapping of source field names to new field names
Example
var ds = new TubDataStore('my_entity');

     // init empty (rowCount=0) dataStore with provided fields.
     // In case keyMap is omitted we consider it contain one attribute 'ID'
     ds.initialize([]); // the same as ds.initialize([], ['ID']);
     ds.initialize([], ['ID', 'name', {from: 'AGE', to: 'age'}]);

     // Initialize dataStore from array-of-object representation
     // Resulting datstore will contain 3 field: ID, nam, age (in order, they listen in keyMap array).
     // During initialization we convert fiend name 'AGE' -> age;
     ds.initialize([{ID: 10, name: 'Jon', AGE: 10}, {ID: 20, name: 'Smith', AGE: 63}],
        ['ID', 'name', {from: 'AGE', to: 'age'}]);

     //the same, but do not convert AGE->age. Result dataset field order is unknown
     ds.initialize([{ID: 10, name: 'Jon', AGE: 10}, {ID: 20, name: 'Smith', AGE: 63}]);

     //result dataset will contain only two field 'ID' & 'age'
     ds.initialize([{ID: 10, name: 'Jon', AGE: 10}, {ID: 20, name: 'Smith', AGE: 63}],
        ['ID', {from: 'AGE', to: 'age'}]);

     // Initialize dataStore from Array-of-array data
     // in this case keyMap is mandatory.
     // In case of mapping from is zero-based index of source element in row array
     ds.initialize([[10, 'Jon', 10], [20, 'Smith', 63]], ['ID', 'name', 'age']);
     // or use mapping
     ds.initialize([[10, 'Jon', 10], [20, 'Smith', 63]],
        ['ID', {from: 2, to: 'age'}, {from: 1, to: 'name'}]);