Methods

  • Entity Methods are used for carrying out various operations on the Entity tables
  • Users have the ability to specify how the method will interact with the database
  • Entity Methods are associated with Entity Tables which are generally request or response data

In this article

Methods

An Entity can have one or more Entity Methods.

Field's Description

  • Has Error? This is internal field. If there is any inconsistency/improper in the setting of the entity/entity table/entity field, or if the steps that need to be followed in creating the entity is not followed, then “Has Error” will be highlighted in red color. Clicking it will provide the details of what that error was, with suggestions to fixing the error.

  • Method Name Need to provide the name of the Entity method. Entity method name should be unique for that database

  • Entity Name A dropdown with the list of existing Entities will be shown. Need to pick the Entity under which the new Entity Method need to be created.

  • Operation

    Need to select the database operation for which the Entity method is created. Possible options are: Create, CreateUpdateDelete, Delete, Execute, Read, Update, Validate.

    Operation Action
    C Create
    CUD CreateUpdateDelete
    D Delete
    E Execute
    R Read
    U Update
    V Validate

     

    When the method is going to be used to perform Insert, then select the Operation as C. (Method type 1, 2, 3, 6).

    When the method is going to be used to perform Create, Update and Delete, then select the Operation as CUD. (Method type 1).

    When the method is going to be used to perform Delete, then select the Operation as D. (Method type 1, 2, 3, 6).

    When the method is going to be used to execute a SQL Stored procedure or a DLL method, then select the Operation as E. (Method type 3, 6).

    When the method is going to be used to perform just Read only, then select the Operation as R. (Method type 1, 2, 3, 6).

    When the method is going to be used to perform just Update only, then select the Operation as U. (Method type 1, 2, 3, 6).

  • Method Type This specifies type for the db_method_name_core. The following types are possible

    0: System

    1: Table

    2: Sql

    3: SP (Non-Entity Compliant)

    4: SP (Entity Compliant)

    5: WCF URL

    6 : DLL

    Method Type:

     

    Table Type Description Notes
    0 System Reserved, do not use
    1 Table Method where database table is directly used.
    2 SQL Method is specified as SQL Statements. SQL may or may not have parameters
    3 SP (non-Entity Compliant) All SQL Server stored procedure (SP) methods. SP may or may not have parameters
    4 SP (Entity Compliant) It is only used few areas now. Do not use this method
    5 WCF URL Not implemented, do not use
    6 DLL For all DLL methods

     

     

  • Target Method Source

    Read Methods

    Cumulative Read Method: Read methods specified at method level for all response tables

    Non-Cumulative Read Method:  Read methods specified at each table level

     

     

    Request Tables for Read Methods:

     

    Request table is specified when there are parameters in SP or query or DLL methods (Method Type 2,3, 4, 6).

     

    In the query method below, @order_no is a parameter

    select * from order_detail where order_no = @order_no

     

    There are no parameters in the query method below. No request table is specified.

    select * from order_detail

    Request table can also be specified for Table Method (Method Type 1).  Its use is illustrated below.

     

    Target_method_source =  order_detail

    Request Table = OrderRequest, that has one field OrderNo whose db_column_name = order_no

     

    When the entity engine sees a request table specified, it is converted to a query like below

    select * from order_detail where order_no = @order_no

     

    This is useful when selecting just the records for particular order, instead reading the whole table.

     

    Deferred read

     

    Deferred read is applicable only to non-cumulative methods. It means the records are read, by execute the method, on navigating to the parent record for the first time.  Taking an example of a non-cumulative method, with two tables (parent-child). The child table records are read only when needed. On navigating to a specific parent record, child table records are fetched using parent table’s key.

     

    On non-cumulative methods, Deferred Read is set on child tables, as stated in table below.

    Method Type Request Tables specified Deferred Read Comments
    Query/SP Yes Yes If there is a request table, it means child table’s read method has parameters that uses parent table’s row value(s).
    Query/SP No No If there is no request table, the child table’s read method fetches data only once.
     
     
    Query is executed only once and all records are read
    Table Not Applicable Yes For any child table’s, whose read method is a non-cumulative method and has method_type = 1, it always set as deferred method.

     

    When to use Deferred Methods?

     

    Deferred Read fetches the child records as needed, and is required to execute the method on parent record navigation.  The fetch is performed only when navigating the parent for the first time, reused when the parent record is re-navigated.

     

    Non-deferred Read fetches all child records along with parent table. All child table records are read into memory (temp tables). On parent record navigation appropriate child records are filtered using parent key.

    Deferred read should be used when child tables are large (1000’s of records).  Non-Deferred will be useful when all of the child table records are a small (less few hundred records).   When child table records are small the non-deferred read method performance will be higher than deferred read method.

  • Description A short explanation of what that Entity Method is created for, what it will do.

  • Skip Entity Validation? Do not execute this method in entity validations. This field is relevant only on Entity database side, and will not be used on the use/application side.When set to true, this Entity Method will not be used in Entity Validation. By default this option is false.

  • Enable ? It’s Used to set whether that Entity object is enabled or disabled. When disabled, details of that entity object will not be get used.

  • Not Used? If the Entity Method is not used in any of the places, then can use this option can be set to True. By default this option is false.

  • Read Only? If "read_only", CUD operations will not be permitted on this table, and will be used only as read only table. "Choose" will be allowed, to choose the records, for Execute or other non-read operations. ##### On the request side, if read only and required, then default value must be provided

  • Disconnected Mode ? The response tables of this method will not be cached as dataset tables, and cannot be accessed again. The method response tables is disconnected, cannot be referred (cannot be used for connect CUD operations), uncached, one-time read only, static data. This flag is used to prevent the connected entity operations, and perform only as disconnected operation.

  • Has Internal Parameters? Some methods have internal computed parameters and use them for producing output data. For example, based on login user, the response varies.  These methods should not be cached, and must not be used as shared data for all users.

     

    This flag should also be set when a method’s output cannot be used as shared/cached data for any reason.

  • Is Group Method? If this is set to true, it represents a a grouped methods, which consits of itself and many group member methods. The group member methods are listed in method_group_list table

  • Cascade Delete ? This option can be used to automatically perform delete in Child tables of this methods target SQL table. By default “Add Cascade Delete” is false.

  • ValidationMethod Not yet Implemented.

  • Is Crud Operation Default Method? Sets this method as default method for CRUD (Create/Read/Update/Delete). By default it is false.

  • Is Dynamic Tables? Table does not have to define fields. Whatever response come from the method/sp execution will be output. In a normal case, for a Read method, Entity Response table need to be get added with the fields list. If the method need to display the output without any settings or operations, then this “Is Dynamic Tables” option can be set to true and no need to set any Entity table as Response table. Whatever response come from the method/sp execution will be the output. By default it is false.

  • Updates Dataset? This setting is Relevant only "is_connect_method" = true. See purpose and use in is_connected_method description.

  • Supports Batch Mode? This setting is Relevant only "is_connect_method" = true. See purpose and use in is_connected_method description.

  • Supports Non Batch Mode? This setting is relevant only when "is_connect_method" is set as true. See purpose and use in is_connected_method description.

  • Requires Refresh? Execute method may update the data in the underlying dataset tables. It may update 0-n tables, conditionally based on data and logic. It will be complex to define all the response tables, write code in execute method, send the updated data back, and the client to update it’s data in one or more tables for one or more rows. Instead, when execute method updates dataset tables, the behaviour is indicated by setting this flag, requires_refresh = 1. A simple refresh event (on the connected dataset tables), is good enough to get the updated data.By default this option is false.

  • Variable Response Tables? The response tables will vary based on the request data.By default this option is false.

  • Derived Method Field Name The fields - derived_method_field_name and derived_method_field_mapping are used for polymorphism implementation. See further description in the field - dervice_method_field_mapping

  • Derived Method Field Mapping

    Entity Method Polymorphism implementation

    NF will follow the C# polymorphic method, as in URL: https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/polymorphism.

    Base classes may define and implement virtual methods, and derived classes can override them, which means they provide their own definition and implementation. At run-time, when client code calls the method, the CLR looks up the run-time type of the object, and invokes that override of the virtual method. Thus, in your source code you can call a method on a base class, and cause a derived class’s version of the method to be executed.

    In OO languages, look up of the run-time type of the object, is the basis of polymorphism. In Nebula Framework, the lookup will be based on the value of data in one or more specified field(s) on each row of the request table.  Here we use only one field for implementing polymorphism. Values from multiple fields and/or any calculation using multiple fields are not available and implemented now.

    Example methods

    Generic Property - Base Method - abstract/virtual  

    Account Property, Instrument Property … - Derived Method - Actual Method(s)     

    mclsys.entity_methods table - will have these 2 new fields: derived_method_field_name   derived_method_field_mapping  - a json of

    [

      {

        value(of derived_method_field_name): 1,

        method_name: "AccountPropertyRead"

      },

      {

        value(of derived_method_field_name): 2,

        method_name: "InstrumentPropertyRead"

      }

    ]

    If derived_method_field_mapping is null OR if no method is specified for a value, then the base method (method specified in column method_name) acts as the default method (as if the base method is the virtual method, and no overridden method exist)

  • Target Method References This field is used to specify the hardcoded db objects. This will be a JSON array field. This column will be used when "output_sp_or_query" is used or for any hardcoded db objects in the code.

  • Rest Verb(s)

  • Rest Method Name

    * FUTURE PLANNED IMPLEMENTATION *

    User must mention the name of the method used in the web API’s URL.

  • Comments A little longer explanation of what that Entity object will do.

  • Created Date Date in which Entity object was created.

  • Created User User who created that Entity object.

  • Updated Date Date in which Entity object was last modified.

  • Updated User User who updated that Entity object lastly.

  • Row Identifier Internal field.

Method Tables

Concept

  • A Nebula Framework (NF) method generally has zero (parameter-less method) or one request table (scalar parameters). However, when the method requires additional supporting tables, all required data tables are specified as request table(s).  The supporting tables are marked as data transfer tables.

     

  • More than one request table is specified for the purpose of providing data as parent-child related tables to NF a method, with some child table(s) having many rows.  There is no need to specify two tables with single row in each table (all scalar values may be combined in one request table).

     

  • When a NF method has only one request table, that table should be marked data_transfer_table=false

     

  • If a NF method has more than one request table, the following are the rules.
  1. One and only table must be marked with data_transfer_table=false  
  2. Rest of the tables - [tables 2 … n] - must have value data_transfer_table=true.
  3. One additional field is added in table a) for each table in the list b).  In this field, set the data_transfer_table_name = the name of Entity table in b).  By doing so, the name of the #table is passed during execution.

 

Usage in NF Read method(s)

A data transfer table may be used as data filters. For example, to get address of list of selected Customer(s), a list of select customers is sent as data transfer table=true.  The list is used as where condition to the read method to restrict data to only selected customers.

 

Usage in NF CUDE method(s)

Cumulative CUD method(s)

Generally, CUD methods perform operation on a single NF table. However, CUDE operations can be performed on multiple NF tables in a single method by passing many request tables to CUD operation.  The first request table (marked with data transfer table = false) is used parameter(s) to the CUD method, and the rest of the tables (data transfer table = true) are sed as supporting tables.  CUDE methods generally takes scalar values as parameters.

Execute Method

Execute method is performed on NF table of data on some chosen rows or all rows of a table of data that is previously read.   By passing the read response table names to the execute method, as data transfer table, the available data is directly consumed by the execute method.

Usage in handling JSON fields

 

Data transfer table concept is effectively used in dealing with JSON fields in a NF table. Displaying JSON data as hierarchical tabular data, ability to edit JSON data elements is a challenge in working with JSON data.  The data transfer table, NF hierarchy grids, and other JSON handling methods are effectively used to provide easy read, edit capability for JSON fields, as in the flow below,

Field's Description

  • Has Error? This is internal field. If there is any inconsistency/improper in the setting of the entity/entity table/entity field, or if the steps that need to be followed in creating the entity is not followed, then “Has Error” will be highlighted in red color. Clicking it will provide the details of what that error was, with suggestions to fixing the error.

  • Method Name It’s used for storing the Entity Method under which this Method Table belongs to. Primary and foreign key field. Handled internally.

  • Table Name Existing Entity Tables will be listed here. One or more entity tables can be added to an entity method.

  • Table Type

    Need to pick the table type from the dropdown. There are 2 table types: Request and Response.
    A method table will consist of combination of Request and Response Tables.
    If the method just get input parameters and do not return back any data, then that method table will be have one request table and zero response table
    If the method do not get any input parameters and just return back one or more result sets of data from the database, then the method table will have zero request table and one or more response tables. The output of result sets needs to match with the number of response tables.
    If the method gets input parameters and returns back one or more result sets of data from the database, then the method table will have one request table and one or more response tables.

    Request Table:

    As the name suggests, request tables are used to request data from the database based on certain parameters mentioned in the target method source property of the Entity method. These are parameters represented by entity fields.
    There can be one request table for an entity method.
    If there are no parameters to the target method source property, then there is no need of a request table.

    If the method performs an insert or update or delete operation, then there will be one or more input parameters for the SP or SQL that is used for that method. For this case, entity table need to be created with the fields that are the parameters for the SP/SQL, and get that entity table added as Request table for that method.

    Response Table:

    This will be the output of the data returned from database, when the target method source of the method is executed.
    These are represented by Entity Fields.
    For an entity method there could zero or 1 or more response tables.

    If the SP/SQL used for that method do not return back any data from the database, then no need to set an entity table as response table.

    If the SP/SQL used for that method return back one or more result sets of data from the database, then need to create separate entity table for each of the result sets and set them as Response table.

  • Index Need to provide an integer value, preferably start with 0. This will be used when there are more than one method tables of same Table type (Ex Response table) was got added for that entity method. For the case of Response tables, since it could have more than 1 response tables for that method, need to specify the index of the method table, in which the result set data is get returned from the database. Index should match with the order in which the result sets is returned. Index should be unique for that method’s table type.

  • Temp Db Table Name Need to provide a name in temp table format. Entity service use this name when it creates the table structure for that entity table and to store and process the data that is fetched from database. For a good practice use the name of the entity table as temp db tale name. For example if the name of the entity table name is SubAccountRequest, and the table type is Request, then for this “Temp Db Table Name” use as: #sub_account_request. Likewise, for table type of Response, name can be used as #sub_account_read.

  • Is Static Temp Table? In the entity service side, temp_db_table_name will be different for every instance, with table created as: temp_db_table_name + _ + @instance_id. If this field, static_temp_db_table_name when set as true, the same name as specified in temp_db_table_name (without the addition of instance_id) will be used, without any changes. This is required generally when used with "data_transfer_table", where the data is expected in a specified table name (hardcoded in SPs, functions). By default this option is false.

  • Is Dynamic Columns? Normally for an Entity table, need to specify the table fields. In some cases, the SP used for the method could return dynamic result set, for which the fields will not be known. In this case, this option can be set to true and no need to add fields for this data table. Whatever response come from the method/SP execution will be returned as output. Note: Such read data cannot be updated, and it is read-only. By default this option is false.

  • Requery Every Page? In the #response temp tables, Primary keys only are stored. And at each page request, the data is queried from underlying tables for every page, by joining the primary keys from #response temp table. When this setting is added at the table level, it will be overridden with value set at the table_views level. When the setting is added at the view level, it overrides any value set at the method_tables level.
    By default this option is false.

  • Read Only? If "read_only", CUD operations will not be permitted on this table, and will be used only as read only table. "Choose" will be allowed, to choose the records, for Execute or other non-read operations. ##### On the request side, if read only and required, then default value must be provided

  • Data Transfer Table? If this is checked, it represents a table/#table that is used inside the SP for request or response purposes. Many SPs passes a table name as parameter which is then either used or populated (request or response) by the SP.By default this option is false.

  • Comments A little longer explanation of what that Entity object will do.

  • MinOccurs This option is used with is_abstract, and when value of is_abstract option is set as true. This min_occurs and max_occurs represent minimum number of rows and maximum number of rows that are possible for a request/response table. Generally, but not always, input (request) table will have single row for various parameters of an input to a method (Ex. a WCF method for sql server function). Sometimes, the response from method could also be restricted from one to many rows. e.g. A scalar SQL function can return only one row with one field value. There are also several TVF examples of uni-row (one row with multiple fields).

  • MaxOccurs Is used with is_abstract, and when value of is_abstract = true.

  • Row Chooser Table Name Need to provide the entity table name that need to be used as row chooser.

  • Field For Dynamic Field Values

    On CUD operations, dynamic column values are sent as JSON on this field. Entity service will map the response field to request table fields, field by field. In table with dynamic table fields, this is not possible. Hence all dynamic columns all aggregated as one json and sent by the client.

    Max Row Count: Can provide an integer value of maximum number of rows that the method should return back. This will be useful when the number of rows that the method will return is not known, and to restrict the number rows returned by the method.

    Show last Records Initial View: This option can be used when the data returned from database is bind in a data grid, and at page load, to show the last page view. Normally in the UI, when data grid is used, data returned from method is bind and initially the first page will be get shown (when there are more records than the page setting).
    When this option is set to true, at the initial page load, in the grid, last page view will get shown.
    By default this option is false.

  • Max Row Count Can provide an integer value of maximum number of rows that the method should return back. This will be useful when the number of rows that the method will return is not known, and to restrict the number rows returned by the method.

  • Inital Record Position

  • Created Date Date in which Entity object was created.

  • Created User User who created that Entity object.

  • Updated User User who updated that Entity object lastly.

  • Updated Date Date in which Entity object was last modified.

  • Row Identifier Internal field.

  • Datatransfer as Json?

  • Datatransfer Full Table Data?

  • Is Sorted List?

  • Aggregate Operations

  • Response Filters

  • Default Value Method Name