Row Objects

Row Objects
lac31
Row objects are key objects in API and logic processing. When you create an API and connect API Creator to your database, 
CA Live API Creator
 builds a JavaScript object model and creates a row object type for each base table. You can think of these as Object-Relational Mapping (ORM) objects: they provide access to attributes, related objects, and persistence. Objects refer to the JavaScript objects created as part of the JavaScript object model. For example, the Demo API includes the 
customer
 and 
purchaseorder
 objects. API Creator updates this model automatically (for example, if you change the schema) when you reload your schema.
The row object type provides familiar persistence and accessor functions. 
In this article:
 
 
2
 
 
In most applications, you shape your API by defining custom resources. Custom resources provide multi-object retrieval and update.
For more information about how to shape your API by defining custom resources, see Customize your API.
The following diagram shows an API PUT/POST request containing a JSON document (the leftmost object) that consists of an Order and possibly several Items:
  resource row logic.png  
Persistence
The row object type provides persistence. Like ORM objects, these row-object types are persistence-enabled. You can access attributes and related data using these row objects. You can handle the update events that these row-object types expose in JavaScript.
As ORM objects, API Creator can read and write rows to disk. The read/write occurs in the following ways:
Submitted Rows Saved
Read, insert, update, and delete verbs and save changed rows, with logic enforcement.
Chained Updates Saved
Your logic can cause API Creator to retrieve and update related rows. For example, the previous diagram shows that API Creator submitted Order and Item. It also shows that logic caused an adjustment of a Customer, which API Creator saves.
API Creator brackets requests into a transaction.
LogicContext Read/Write Services
 
CA Live API Creator
 does the following:
  1. Submits rows to your logic, for example, in JavaScript logic events.
  2. Passes these events the 
    logicContext
     object, which provides APIs for reading any data in API Creator and altering it.
  3. Saves submitted/changed updates to rows to disk at the end of the transaction.
For more information:
Resource/Row Mapping
The row object type provides resource/row mapping. You make update requests by way of custom resources. API Creator shares the row logic over all custom resources by mapping (transforming) custom resources to rows.
Request Event Processing
API Creator processes request events using the following workflow:
  1. API Creator invokes your request event handler, providing you an opportunity to reformat the JSON. For example, you can reformat the JSON or, for complex transaction-handling, you can inject 
    @metadata
     tags.
  2. API Creator creates table rows from each JSON row.
  3. One of the following occurs:
    • (PUT operations) API Creator retrieves the values that are not included in the JSON row (so the ensuing logic always sees a "full" row) and performs optimistic locking checks.
    • (POST operations, or rows that are designated with the insert 
      @metadata
       action tag) API Creator generates the primary key (for example, 
      OrderId
      ) by inserting the row into the database.The value is cascaded into the foreign keys of contained rows (for example, 
      OrderId
       is placed into each Item).
For more information:
Logic Execution
The row object type provides logic execution. Rows are rich, not anemic, domain objects. They provide access to attributes and persistence and enforce your business logic. When the client makes PUT/POST/DELETE requests, they invoke the relevant reactive logic and events you have defined.
For more information:
Logic Phase Processing
For each row, API Creator invokes your reactive logic automatically based on what changed in a row. Reactive logic can chain to update other related rows, for example, the Order can adjust the customer's balance. Logic invocation and ordering are system-defined, which reduces errors and simplifies maintenance.
For more information about reactive logic, see Logic.
Commit Phase Processing
After all the rows are processed, and all the derivations have been done, API Creator executes commit validations and events. In this way you can specify logic such as "an order must have one or more items", for example:
Derive Order.itemCount as count(items)
Commit Validation - Order.itemCount > 0
Logic Coding
Typically you specify your logic in server-side JavaScript. Your logic is passed key information required for its operation:
  • row
    oldRow
    . The rows that were submitted or chained.
  • The 
    logicContext
     object. This object provides services to read/write other rows.
Your logic can read/write the row attributes and access related data.
For more information about server-side JavaScript events, including logic event rule types, see Logic Event Rule Types and the Quick Reference.
Attribute/Related Object Access
The row object type provides attribute/related object access. Rows are passed to your logic and events and provide access to attributes (
row.OrderDate
) and related objects (
row.Customer.name
).
Row objects have the following behaviors:
  • Attributes.
     Rows have attributes for every column. For example, you can refer to an order's 
    amount_total
     using 
    row.amount_total
    .
  • Parent role accessors. 
    Rows provide accessors to parent data, for example:
    var department =
    row.headDepartment
    ; // head department for current department row
    var deptName = row.headDepartment.name; // or, data in the row
  • Child role accessors.
     Rows provide role accessors. You can refer to an orders' 
    row.customer.balance
     or obtain a collection of 
    row.lineitems
     (a collection of line item rows).
    var worksForEmps =
    row.reportingEmployees;
    // child role name
    for (var eachEmpNo in worksForEmps) {
    var eachEmp = worksForEmps[eachEmpNo];
    logicContext.logDebug(eachEmp);
    }
    You can get code completion access to row attributes and role accessors using the JavaScript code editor in API Creator.
There can be many child rows (more than a few thousands). Be careful about iterating over them using this method. This method can use up a significant amount of memory and CPU.
For more information:
Show Attribute Values for Logging and Debugging
You can show attribute values for logging and debugging using the 
toString()
 method.
For more information about logging and debugging, see Debug.
Metadata Access
API Creator passes the 
logicContext
 object to your rules and events. The 
logicContext
 object provides methods to return the description of the row, useful for extension services seeking to deal with rows generically.
For more information about the 
logicContext
 object, see The logicContext Object.