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.

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.

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.

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.

The standard CRUD operations can operate on any OpenEdge 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 an OpenEdge Business Entity. 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.

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. 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.

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 description.

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

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.

Events

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).

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:

// 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.
• 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

  Note: 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, record property, table reference property (JSDO class)