Hemi Framework: Data IO

Overview

The Data IO Service provides an IO layer for sending and receiving data requests through registered providers. Generic requests are made for a specified bus and include descriptive information, actions, and payloads. Data IO providers responds for specific bus types, and directs the request to a target for the action. When the action is completed (synchronously or asynchronously), the provider writes the results to the response.

Additional Reading

• API: Data IO
• Account Manager

Object Model

Portions of the Data IO object model, including Group and Data, were adapted from the Account Manager API.

• IORequest - The Request object represents all information about a request for data, including any payload, subjects, or instructions.
• IOInstruction - Pagination, group, and order instructions accompanying the request.
• IOResponse - The Response object contains information written by registered providers, including groups, data, messages and status.
• IOSubject - The Subject represents the entity on whose behalf the request is made. Typically the subject represents a user name or a unique id.
• Group - A group represent an aggregation of data or other groups.
• Data - Data represents meta information and details for a segment of data. Data may represent the contents of a file, a list item, etc.
• Policy - Policies may be attached to groups and data, and are used to define authorization instructions for specified subjects.

Request Model

The Data IO Service uses a modified REST model based on the Core Web (using Account Manager) HTTP Handler processing model. This model uses a coarse-to-fine declaration to identify the nearest approximate API for handling the request.

In the Data IO Service, registered providers are invoked for all requests on the specified bus.

Request Syntax

The following example represents the syntax of a new Data IO request.

var oInstruction = Hemi.data.io.service.newIOInstruction();
var oRequest = Hemi.data.io.service.newIORequest(
   iBus,
   sApplication,
   sContext,
   sCatalog,
   sAction,
   sId,
   sName,
   bDetailsOnly,
   bAsync,
   bCache,
   oInstruction
);

• Bus : ONLINE, OFFLINE, LOCAL, STATIC, or ANY. The Bus parameter determines whether a provider receives requests.
• Application: The type of application intended to process the request.
• For example, the Hemi JavaScript Framework may us DWAC to indicate that the target application is the Distributed Web Application Component handler from the Core Web application.
• Context: The context of the request used as a descriminator when processing the data.
• Example: The hemi.framework.io.offline.provider uses a combination of the Context, Catalog, and Action values to differentiate between lists of groups from lists of data.
• Example: The DWAC application uses the Context to identify a parent group, the Catalog to identify a group, and the Request Name or Id to identify a specific data item.
• Catalog: The general scope of the request relative to the application.
• For example, the framework provider treats Fragment and Template Groups as catalogs. However, this is subjective to the client and data source.
• Action: The action to perform.
• Example: List, Delete, Edit, Add, Read
• Id: A unique identifier intended to uniquely identify a resource.
• Name: The name of a particular resource in the scope of the Context or Catalog.
• Details Only: A bit indicating whether the request is only for meta information.
• Async : A bit indicating that the provider may make an asynchronous request as needed. Otherwise, the provider should make a synchronous request.
• Cache : A bit indicating that the provider may cache results as needed.
• Instruction : A set of pagination and filtering instructions for use when requesting lists of data.

Response Model

Responses may be handled in one of three ways:

1. Synchronous requests may use the response as returned by the openRequest method.
2. Subscribing to the oncloseiorequest publication, which includes the response id.
3. Including a handler when invoking openRequest, which is invoked with the Service, Subject, Request, and Response objects as parameters.

The validity of the IOResponse object is subject to the interpretation of the implementation. The recommended use is to use the status property to store boolean success or failure conditions, the responseGroups array for retrieving a result of Group values, and the responseData array for retrieving a result of Data values.

Example Request

Hemi.include("hemi.data.io");
// Demo IO Provider demonstrated below
Hemi.include("demo.io.provider");
var oInstruction = Hemi.data.io.service.newIOInstruction(
   bPaginate,
   iStartRecord,
   iRecordCount,
   sOrder,
   sGroup
);
var oRequest = Hemi.data.io.service.newIORequest(
   BUS_TYPE,
   sApplicationName,
   sContext,
   sCatalog,
   sAction, 
   sId,
   sName,
   bDetailsOnly,
   bAsync,
   bCache,
   oInstruction
);
Hemi.data.io.service.openRequest(
   Hemi.data.io.service.getSubject(),
   oRequest,
   HandleGridLoad
);
function HandleIOLoad(oService, oSubject, oRequest, oResponse){
  /// ...
}

Example Provider

The following is an example of a new Data IO Provider:

(function () {
   HemiEngine.include("hemi.event");
   HemiEngine.include("hemi.data.io");
   HemiEngine.namespace("demo.io.provider", HemiEngine, {
      service: null,
      serviceImpl: function () {
         this.ready_state = 4;
         Hemi.prepareObject("demo_io_provider", "1.0", 1, true, 1);
         Hemi.util.logger.addLogger(this, "IO Provider", "Demo IO Provider", "001");
         // callback upon service registration
         //
         this.handle_io_register = function (oService) {
            // Identify service as supporting the named Request and Action combinations
            //
            this.getProperties().useRegisteredApi = 1;
            this.implement("Catalog", "List");
            this.implement("Action", "Read");
         };
         this.handle_io_request = function(oService, oSubject, oRequest, oResponse ){
            /// If the general method is not handled, the handling moves to the specific
            /// implementation
            ///
            return 0;
         };
         /// Synchronous handling example
         ///
         this.requestCatalogList = function(oService, oSubject, oRequest, oResponse){
            if(oRequest.requestApplication != "My App"){
               /// Skip requests this provider doesn't want to handle
               return 1;
            }
            var sCtx = oRequest.requestContext;
            if(
               oRequest.requestContext == "PublicDirectory"
               &&
               oRequest.requestCatalog == "CalendarWidgets"
            ){
               /// Create a policy indicating a read operation is permitted
               ///
               var oPolicy = Hemi.data.io.service.NewPolicy();
               oPolicy.read = 1;
               /// Get the list of 'CalendarWidgets' from wherever
               ///
               var aWidgets = ...;
               /// Copy the source data into the DataIO format
               for(var i = 0; i < aWidgets.length; i++){
                  var oData = Hemi.data.io.service.NewData();
                  oData.id = ...;
                  oData.name = ...;
                  oData.value = ...;
                  oData.mimeType = ...;
                  oData.size = ...;
                  oData.path = ...;
                  oData.policies.push(oPolicy);
                  oResponse.writeData(oData, this, 0, Hemi.data.io.service.getBusType().ANY);
               }
            }
            return 1;
         };
         // Registry the object for a STATIC bus
         //
         Hemi.data.io.service.register(
            this,
            Hemi.data.io.service.getBusType().STATIC
         );
      }
   }, 1);
}());