JSDO class and object reference : progress.data.JSDO class
  

progress.data.JSDO class

The progress.data.JSDO is a JavaScript class that provides access to resources (Data Objects) of a Progress Data Object Service. A single progress.data.JSDO object (JSDO instance) provides access to a single resource supported by a given Data Object Service. This resource implements a given Data Object depending on the type of Data Object Service that provides it. For an OpenEdge Data Object Service, the resource is implemented using an ABL Business Entity, which is a singleton class or persistent procedure running on an OpenEdge application server (Progress Application Server for OpenEdge or OpenEdge AppServer). For a Rollbase Data Object Service, the resource is implemented by a Rollbase object provided by a Rollbase server running in a public or private cloud.
Once created for a given Data Object resource, a JSDO provides application-oriented, JavaScript methods that invoke Data Object operations supported by its resource implementation. These can include standard operations for reading and writing data, and can also include custom operations for invoking business logic and more complex data operations, depending on the implementation. An OpenEdge resource maps specified ABL routines to any of several supported operation types, each of which corresponds to a particular method in the JSDO. A Rollbase resource maps a corresponding set of server-implemented APIs to these same JSDO methods.
For an OpenEdge Data Object Service, you (or another OpenEdge user) identify how a JSDO maps JavaScript methods to operations of a given resource by adding annotations to the singleton procedure or class source code. These annotations map the ABL routines that implement a given resource operation to the corresponding JavaScript method in the JSDO that invokes the operation. You specify these annotations using features of Progress Developer Studio for OpenEdge (Developer Studio) in two ways:
1. When initially creating an ABL Business Entity to implement a Data Object that supports the business operations you want on a specified data model
2. When modifying any existing ABL singleton class or procedure that you want to function as a Business Entity that implements a Data Object resource
You can also use Developer Studio to add a given resource to an existing OpenEdge Data Object Service, as part of generating the Service along with the client-side artifacts required to create a corresponding JSDO for the resource on the client. These client-side artifacts include the Data Service Catalog that defines the schema and operations for each resource you can access in the Service using a corresponding JSDO.
For a Rollbase Data Object Service, the available resources and their supported operations are automatically created from the existing definitions of Rollbase objects that you (or another Rollbase user) select to create its Rollbase Data Service Catalog. The resulting Catalog defines the mappings between JSDO methods and the Rollbase APIs used to implement the operations on each resource (Rollbase object) supported by the Data Object Service.
At run time, the JSDO maintains an internal data store (JSDO memory) for managing table records that are exchanged between a given Data Object resource and the JSDO, and it provides methods to read and write data in JSDO memory as individual JavaScript record objects (see the progress.data.JSRecord class description). To support this data exchange between a JSDO and its Data Object resource, a given resource can support standard operation types that include Create, Read, Update, Delete (CRUD) operations, and Submit operations. The Read operation of a resource returns a specified result set from the resource to the client; the CUD operations create, update, or delete (respectively) one record at a time in the resource; and a Submit operation creates, updates, and deletes multiple records at a time in the resource. In addition to these standard operations, a resource can also support custom Invoke operations to access ABL business logic in a given OpenEdge resource or to read data from Rollbase objects that are related to a given Rollbase object resource.
The standard CRUD operations can operate on any OpenEdge or Rollbase single-table resource, or on an OpenEdge multi-table resource (ProDataSet) containing one or more temp-tables. Standard Submit operations are currently available only on an OpenEdge ProDataSet resource that supports before-imaging (with potentially complex server transaction support).
Each standard Data Object operation type (CRUD or Submit) maps to a corresponding standard method of the JSDO on the client. The records of each resource table are managed in the JSDO as an array of record objects, which the standard JSDO methods use to exchange data with the server as supported by the type of Data Object Service. The standard JSDO methods mapped to standard operation types support client access to the common business operations that can be generated for either an OpenEdge Business Entity or a Rollbase object. Other standard methods of the JSDO provide internal access to individual record objects in JSDO memory. Depending on the results of its standard methods, the JSDO also maintains a working record for each table in its memory that you can access directly using table and field references (see the notes in this class description). Thus, using the standard methods of a JSDO and its table references, you can interact with a corresponding Data Object resource in a consistent manner from one JSDO-resource mapping to another.
The JSDO methods to invoke the standard resource operations include fill( ) to Read resource data and saveChanges( ) to either Create, Update, or Delete individual records in the resource, or Submit to create, update, and delete multiple records in the resource. Both of these JSDO methods execute asynchronously. Any results, including errors, that are returned from both the resource operations and the JSDO method invocations themselves can be managed using two mechanisms:
1. Named events — To which you can subscribe event handlers (callback functions) to process the results when a given event is fired. The available events fire both before and after each resource operation executes, and both before and after execution of the JSDO method that invokes the operation, or operations. The callback for each event has a particular signature that is appropriate for the results returned for the event. See the descriptions of both the JSDO fill( ) and saveChanges( ) methods and the associated event descriptions for more information.
2. jQuery Promises — Deferred Promise objects, an instance of which can be returned as the method value when results are available. A Promise object provides methods that you can use to register callback functions that, in turn, execute for different conditions associated with the JSDO method results. In order to use jQuery Promises, your development environment must support them (or the exact equivalent). For more information on this mechanism, and how it works with the fill( ) and saveChanges( ) methods, see the notes for this class description.
If your environment supports jQuery Promises, you can use either or both of these mechanisms to return results for the standard resource operations.
Like the standard CRUD and Submit operations, a resource can define custom Invoke operations, depending on the type of resource (OpenEdge or Rollbase). For OpenEdge resources, an Invoke operation can call and return results for any ABL routine on the server that is defined by the resource. To call an Invoke operation for a specific ABL routine, an OpenEdge resource defines a corresponding invocation method that you can call on the JSDO to send the request the server. Rollbase resources can define similar invocation methods that you call on the JSDO to invoke server APIs that return records from related Rollbase objects.
Note that data exchanged between server and client using Invoke operations is not automatically stored in JSDO memory. It is initially accessible only from the return values and other results of the invocation methods provided by the JSDO. You can subsequently use other standard JSDO methods to exchange data between the invocation methods and JSDO memory. For example, you can use the JSDO addRecords( ) method to merge appropriate data returned by an invocation method directly into JSDO memory. The result in JSDO memory can then continue to be maintained and synchronized with the server using the JSDO fill( ) and saveChanges( ) methods to invoke the standard CRUD and Submit operations.
Unlike the standard fill( ) and saveChanges( ) methods, you can execute custom JSDO invocation methods either synchronously or asynchronously, depending on parameter settings that you use to call them. If you execute an invocation method asynchronously, the JSDO also supports events that fire before and after the method (and its Invoke operation) execute in the resource, returning the results in any event handler callbacks that you subscribe to these events. In addition, you can use the standard JSDO invoke( ) method as an API to asynchronously call custom invocation methods that return their results in jQuery Promise callbacks, similar to the fill( ) and saveChanges( ) methods, as long as your environment supports jQuery Promises.
Note that all JSDO methods that invoke either standard or custom resource operations return a request object to any subscribed event callbacks. This request object supports a number of properties containing the results of the resource operation, some of which appear in the request object only for specific events. Similarly, any Promise object returned by a JSDO method also returns an appropriate request object to each callback that you register for that object. For custom invocation methods that you execute synchronously, this request object is returned as the value of the invocation method. For more information on this request object, see the request object description.
When you instantiate a JSDO, it relies on a prior JSDO login session that you can establish using an instance of either the progress.data.JSDOSession class or the progress.data.Session class. This login session enables optionally secure communications between the client JSDO and the web server, its supported Data Object Services, and ultimately the application server that implements the resource accessed by the JSDO.
A JSDOSession insatnce manages its JSDO login session asynchronously using only jQuery Promises to return all session-related results, where as a Session instance can manage its JSDO login session either synchronously or asynchronously using several Session object events. Note that, similar to managing resource operations using jQuery Promises returned from JSDO methods, you can use the JSDOSession class to manage JSDO login sessions only if your environment supports jQuery Promises. Otherwise, you must use the Session class to manage the login session for a JSDO. For more information, see the progress.data.JSDOSession class and progress.data.Session class descriptions.

Constructors

Two constructors are available for the JSDO. The first constructor takes the name of the corresponding Data Object resource as a parameter; the second constructor takes an initialization object as a parameter.
The resource name specified for the constructor must match the name of a resource provided by a Data Object Service for which a login session has already been established. After the JSDO is created, it uses the information stored in the Data Service Catalog to communicate with the specified resource.
Syntax
progress.data.JSDO ( resource-name )
progress.data.JSDO ( init-object )
resource-name
A string expression set to the name of a resource that the JSDO will access. This resource must be provided by a Data Object Service for which a login session has already been established.
init-object
An object that can contain any writable JSDO properties. It must contain the required JSDO name property, which specifies the Data Object resource that the JSDO will access. This resource must be provided by a Data Object Service for which a login session has already been established.
This init-object can also contain either or both of the following optional initialization properties:
*autoFill — A boolean that specifies whether the the JSDO invokes its fill( ) method upon instantiation to initialize JSDO memory with data from its resource. The default value is false.
*events — An object that specifies one or more JSDO event subscriptions, each with its properties represented as an array, with the following syntax:
Syntax
events : {
     'event' : [ {
          [ scope : object-ref , ]
          fn : function-ref
     } ] [ ,
     'event' : [ {
          [ scope : object-ref , ]
          fn : function-ref
} ] ] ...
}
event
The name of an event to which the JSDO instance subscribes callbacks. See Events for a list of available JSDO events.
object-ref
An optional object reference that defines the execution scope of the callback function invoked when the event fires. If the scope property is omitted, the execution scope is the global object (usually the browser or device window).
function-ref
A reference to the callback function that is invoked when the event fires.
Each event passes a fixed set of parameters to its event callback, as described for the event. A reference to the description of each JSDO event is provided later in this class description.

Example

The following example illustrates the use of an initialization object to instantiate a JSDO:
dsItems = new progress.data.JSDO({
  name : 'Item',
  autoFill : false,
  events : {
    'afterFill' : [ {
                       scope : this,
                       fn : function (jsdo, success, request) {
                         // afterFill event handler statements ...
                       }
                    } ]
  }
});

Properties

Table 12. progress.data.JSDO properties
Member
Brief description (See also the reference entry)
A boolean on a JSDO that indicates if the JSDO automatically accepts or rejects changes to JSDO memory when you call the saveChanges( ) method.
A boolean on a JSDO and its table references that indicates if record objects are sorted automatically on the affected table references in JSDO memory at the completion of a supported JSDO operation.
A boolean on a JSDO and its table references that indicates if string field comparisons performed by supported JSDO operations are case sensitive or case-insensitive for the affected table references in JSDO memory.
Returns the name of the Data Object resource for which the current JSDO was created.
A property on a JSDO table reference that references a JSRecord object with the data for the working record of a table referenced in JSDO memory.
An object reference property on a JSDO that has the name of a corresponding table in the Data Object resource for which the current JSDO was created.
A boolean that specifies whether JSDO methods that operate on table references in JSDO memory recognize and honor data-relations defined in the schema (that is, work only on records of a child table that are related to the working record of a parent table).

Methods

Certain methods of the progress.data.JSDO class are called on the JSDO object itself, without regard to a table reference, whether that reference is explicit (specified in the method signature) or implicit (in the case of a JSDO containing only one table that is not explicitly specified). Other methods can be called on a specific table reference that is mapped to one of possibly multiple tables managed by the resource for which the current JSDO is created.
Table 13. progress.data.JSDO class-instance methods
Member
Brief description (See also the reference entry)
Accepts changes to the data in JSDO memory for the specified table reference or for all table references of the specified JSDO.
Accepts changes to the data in JSDO memory for a specified record object.
Reads the record objects stored in the specified local storage area and updates JSDO memory based on these record objects, including any pending changes and before-image data, if they exist.
Updates JSDO memory with one or more record objects read from an array, single-table, or multi-table resource that are passed in an object parameter, including any pending changes and before-image data, if they exist.
Clears out all data and changes stored in a specified local storage area, and removes the cleared storage area.
Alias: read( )
Initializes JSDO memory with record objects from the data records in a single-table resource, or in one or more tables of a multi-table resource, as returned by the Read operation of the Data Object resource for which the JSDO is created.
Returns an object containing the names and values of the user-defined properties defined in the current JSDO instance.
Note: Applies to Progress Data Objects Version 4.3 or later.
Returns the value of the specified JSDO user-defined property.
Note: Applies to Progress Data Objects Version 4.3 or later.
Returns true if record objects can be found in any of the tables referenced in JSDO memory (with or without pending changes), or in only the single table referenced on the JSDO, depending on how the method is called; and returns false if no record objects are found in either case.
Returns true if JSDO memory contains any pending changes (with or without before-image data), and returns false if JSDO memory has no pending changes.
A custom method on the JSDO that executes an Invoke operation defined for a Data Object resource.
Asynchronously calls a custom invocation method on the JSDO to execute an Invoke operation defined by a Data Object resource.
Clears out the data in JSDO memory and replaces it with all the data stored in a specified local storage area, including any pending changes and before-image data, if they exist.
Rejects changes to the data in JSDO memory for the specified table reference or for all table references of the specified JSDO.
Rejects changes to the data in JSDO memory for a specified record object.
Synchronizes to the server all record changes (creates, updates, and deletes) pending in JSDO memory for the current Data Object resource since the last call to the fill( ) or saveChanges( ) method, or since any prior changes have been otherwise accepted or rejected.
Saves JSDO memory to a specified local storage area, including pending changes and any before-image data, according to a specified data mode.
Replaces all user-defined properties in the current JSDO instance with the user-defined properties defined in the specified object.
Note: Applies to Progress Data Objects Version 4.3 or later.
Sets the value of the specified JSDO user-defined property.
Note: Applies to Progress Data Objects Version 4.3 or later.
Subscribes a given event callback function to a named event of the current JSDO or table reference.
Unsubscribes a given event callback function from a named event of the current JSDO or table reference.
Unsubscribes all event callback functions from a single named event of the current JSDO, JSDOSession or Session object, or unsubscribes all event callback functions from all events of the current JSDO, JSDOSession, or Session object.
Table 14. progress.data.JSDO table-reference methods
Member
Brief description (See also the reference entry)
Accepts changes to the data in JSDO memory for the specified table reference or for all table references of the specified JSDO.
Accepts changes to the data in JSDO memory for a specified record object.
Alias: create( )
Creates a new record object for a table referenced in JSDO memory and returns a reference to the new record.
Updates JSDO memory with one or more record objects read from an array, single-table, or multi-table resource that are passed in an object parameter, including any pending changes and before-image data, if they exist.
Alias: update( )
Updates field values for the specified JSRecord object in JSDO memory.
Searches for a record in a table referenced in JSDO memory and returns a reference to that record if found. If no record is found, it returns null.
Locates and returns the record in JSDO memory with the internal ID you specify.
Loops through the records of a table referenced in JSDO memory and invokes a user-defined callback function as a parameter on each iteration.
Returns an array of record objects for a table referenced in JSDO memory.
Returns an array of errors from the most recent invocation of Create, Read, Update, Delete, or Submit operations (CRUD or Submit) that you have invoked by calling the JSDO fill( ) or saveChanges( ) method on a Data Object resource.
Note: Updated for Progress Data Objects Version 4.3 or later.
Returns any before-image error string in the data of a record object referenced in JSDO memory that was set as the result of a resource Create, Update, Delete, or Submit operation.
Returns the unique internal ID for the record object referenced in JSDO memory.
Returns an array of objects, one for each field that defines the schema of a table referenced in JSDO memory.
Returns true if record objects can be found in any of the tables referenced in JSDO memory (with or without pending changes), or in only the single table referenced on the JSDO, depending on how the method is called; and returns false if no record objects are found in either case.
Rejects changes to the data in JSDO memory for the specified table reference or for all table references of the specified JSDO.
Rejects changes to the data in JSDO memory for a specified record object.
Deletes the specified table record referenced in JSDO memory.
Specifies or clears the record fields on which to automatically sort the record objects for a table reference after you have set its autoSort property to true (the default).
Specifies or clears a user-defined sort function with which to automatically sort the record objects for a table reference after you have set its autoSort property to true (the default).
Sorts the existing record objects for a table reference in JSDO memory using either specified sort fields or a specified user-defined sort function.
Subscribes a given event callback function to a named event of the current JSDO or table reference.
Unsubscribes a given event callback function from a named event of the current JSDO or table reference.

Events

Table 15. progress.data.JSDO events
Member
Brief description (See also the reference entry)
Fires after the JSDO, by means of a saveChanges( ) call following an add( ) call, sends a request to create a record in the Data Object resource and receives a response to this request from the server.
Fires after the JSDO, by means of a saveChanges( ) call following a remove( ) call, sends a request to delete a record in the Data Object resource and receives a response to this request from the server.
Alias: afterRead
Fires on the JSDO after a call to the fill( ) method executes and returns the results from the server to JSDO memory for a Read operation request on its Data Object resource.
Fires after a custom invocation method is called asynchronously on a JSDO and a response to the Invoke operation request is received from the server.
Fires once for each call to the saveChanges( ) method on a JSDO, after responses to all create, update, and delete record requests sent to a Data Object resource have been received from the server.
Fires after the JSDO, by means of a saveChanges( ) call following an assign( ) call, sends a request to update a record in the Data Object resource and receives a response to this request from the server.
Fires before the JSDO, by means of a saveChanges( ) call following an add( ) call, sends a request to create a record in the Data Object resource on the server.
Fires before the JSDO, by means of a saveChanges( ) call following a remove( ) call, sends a request to delete a record in the Data Object resource on the server.
Alias: beforeRead
Fires on the JSDO before a call to the fill( ) method executes and sends a Read operation request to its Data Object resource.
Fires when a custom invocation method is called asynchronously on a JSDO before the request for the Invoke operation is sent to the server.
Fires once on the JSDO before a call to the saveChanges( ) method sends the first request to create, update, or delete a record in its Data Object resource on the server.
Fires before the JSDO, by means of a saveChanges( ) call following an assign( ) call, sends a request to update a record in the Data Object resource on the server.
The JSDO can subscribe to the events listed in the previous table in either of two ways:
*Using the JSDO constructor — In the init-object parameter of the constructor, list each subscribed event with an optional scope object and an event handler method to be executed when the event fires. See the constructors description for this class.
*Using the subscribe( ) method — See the subscribe( ) method (JSDO class).
Note: JSDO events do not fire for custom invocation methods if the method call is synchronous.

Example

The following code fragment shows a simple JavaScript coding sequence for creating and using a JSDO referenced by the variable dsCustomer to read resource data, starting with the attempted JSDO login using a progress.data.JSDOSession instance:
Table 16. Example — Using a JSDO
// create a JSDOSession for a specified web application
// that requires Form authentication
var pdsession = new progress.data.JSDOSession( {
serviceURI : 'https://testmach:8943/SportsMobile',
authenticationModel : progress.data.Session.AUTH_TYPE_FORM
});

// log in by authenticating to the specified web application
pdsession.login(username, password).done(
function( session, result, info ) {
// login().done handler statements
  // load Catalog for a service that is hosted by the web application
  session.addCatalog('https://testmach:8943/SportsMobile/static/SportsMobileSvc.json'
).done(
function( session, result, details ) {
// addCatalog().done() handler statements
  // create JSDO for dsCustomer resource
var dsCustomer = new progress.data.JSDO('dsCustomer');
// load JSDO memory with resource data
dsCustomer.fill().done(
function (jsdo, success, request) {
       // fill().done() handler statements ...
}).fail(
function (jsdo, success, request) {
       // fill().fail() handler statements ...
});
}).fail(
function( session, result, details ) {
// addCatalog().fail() handler statements ...
});
}).fail(
function( session, result, info ) {
// login().fail() handler statements ...
});

Notes

*Three web-communicating methods of this class, fill( ), saveChanges( ), and invoke( ), always execute asynchronously and return a reference to a jQuery Promise object as the return value when jQuery Promises are supported in the development environment. A Promise is a deferred object that defines methods which, in turn, register callbacks that execute when results are available from the method that returns the Promise. You provide your own code in each callback to handle the results returned for a given Promise method, much like the code you provide in an event callback.
The primary Promise methods for use with a JSDO object include done( ), fail( ), and always( ), which allow you to separately handle the successful, unsuccessful, and all results (respectively) of a JSDO method execution. Note that for any given JSDO method, the parameter lists for all Promise method callbacks have the same signature. Note also that the callback for the always( ) method executes with the same values in its parameter list as the callback for the done( ) or fail( ) method, whichever one executes with results.
For more information on the jQuery implementation of Promises and the additional Promise methods that are available to register callbacks, see the following jQuery topics at the specified web locations:
*Category: Deferred Object — http://api.jquery.com/category/deferred-object/
*Promise Object — http://api.jquery.com/Types/#Promise
*.promise — http://api.jquery.com/promise/
*For more information on defining a Data Object resource, including the standard CRUD, Submit, and any custom Invoke operations, for:
*OpenEdge Data Object Services — See the topics on creating Business Entities to implement Data Object resources and updating Business Entities for access by mobile and web apps built using Kendo UI in OpenEdge Development: Web Services.
*Rollbase Data Object Services — See Creating Progress Data Catalogs for use with AppBuilder in the Rollbase documentation. Note that Rollbase automatically defines CRUD and Invoke operations only that are supported by each single-table resource according to the definition of the Rollbase object from which the resource is created.
*The JSDO supports a working record for each table referenced in JSDO memory. Certain JSDO methods set a specific record as the working record. After other methods execute, there is either no working record set or existing working records remain unchanged. When there is a working record, you can access the fields of the record using one of the following mechanisms:
Syntax
jsdo-ref.table-ref.field-ref
jsdo-ref.field-ref
jsdo-ref.record.data.field-ref // Read-only;
                               // For a jsdo-ref with only one table-ref
jsdo-ref.table-ref.record.data.field-ref // Read-only
jsrecord-ref.data.field-ref // Read-only
jsdo-ref
The reference to a JSDO, and if the JSDO contains only a single table, an implied reference to any working record that is set for that table.
table-ref
A table reference property with the name of a table in jsdo-ref memory and a reference to the table working record. There is one table reference in a JSDO for each table referenced by the JSDO. For more information on table reference properties, see the table reference property (JSDO class) description.
field-ref
A field reference property on a table-ref or on the data property object, with the name and value of a field in the working record of the referenced table. There is one such field reference and data object property for each field defined in the table schema. If field-ref is an array field, which is supported in OpenEdge resource tables for example, you can also access individual array elements using either standard JavaScript subscripts or JSDO array-element references in the form, field-ref_integer, where integer is a one (1)-based integer that qualifies the name of the field reference property that corresponds to the array field element. For more information on field reference properties, see the table reference property (JSDO class) description.
record
A property of type JSRecord on a table reference, which references the working record of a referenced table specified by:
*jsdo-ref.table-ref
*jsdo-ref if the JSDO references only one table
If the JSDO references more than one table, the record property is null at the JSDO level and is available only on a table-ref.
data
A property on a JSRecord object with the field values for the working record specified by:
*jsdo-ref.table-ref
*jsdo-ref if the JSDO references only one table
*A jsrecord-ref returned for an associated JSDO table reference
If a field-ref has the same name as a built-in property or method of the JSDO, you must use the data property to reference its value in the working record.
Caution: Never write directly to a field-ref using this data property; in this case, use field-ref only to read the data. Writing field values using the data property does not mark the record for update when calling the saveChanges( ) method, nor does it re-sort the record in JSDO memory according to any order you have established using the autoSort property. To mark a record for update and automatically re-sort the record according to the autoSort property, you must assign a field value either by setting a jsdo-ref.table-ref.field-ref for a working record or by calling the assign( ) method on a valid table-ref or JSRecord object reference.
jsrecord-ref
A reference to a JSRecord object for a table referenced in JSDO memory. You can return a jsrecord-ref for a working record as the value of the record property or as a value returned by supported JSDO built-in methods that return a working record, such as add( ) and find( ).
For more information on properties available to reference working record fields using this syntax, see the properties listed in this class description and in the description of the progress.data.JSRecord class. For more information on the methods for setting the working record for referenced tables, see the methods listed in this class description and in the description of the progress.data.JSRecord class.
*Many standard JSDO methods are actually invoked on a JSDO table reference, and can only be invoked on the JSDO itself when its JSDO memory is initialized with a single table.
*For a multi-table resource, such as an OpenEdge ProDataSet, the JSDO accesses the data for all unrelated tables in JSDO memory as top-level tables of the JSDO. Access to data for all related child tables depends on the working record of the parent table in the JSDO and the setting of the useRelationships property.

See also

progress.data.JSRecord class, progress.data.Session class, record property, table reference property (JSDO class), table reference property (UIHelper class)