Webman-framework

Lightweight, Component-based, and Database-oriented Web Application Framework

About | Overview | Documentation

 

Documentation > Modules and APIs > webman_JSON

webman_JSON

 

Description:

Component-type module that provides data interoperability service over http-text/plain communication. The data passed is actually a list of attributes and values of a selected data entity fabricated using JSON (JavaScript Object Notation) string format/structure. The data entities are normally an operation-based references to database tables of the application.

 

Dependencies:

CPAN's Modules:

  • JSON (Composition)

Webman-framework's Component-type Modules:
  • CGI_Component::webman_CGI_component (Inheritance)

 

1. JSON-format Data

Below is a general form of JSON string structure used to fabricate data entity attributes and values:

[ { "error":"...", "list":[...] } ]

In the context of JSON specification it's a list of a single hash with error and list as the hash keys. The error key is mapped to a string to store any errors occurs when clients try to access the service. Possible errors that might be captured are including invalid access to restricted entities and database query error on tables referred by the entities. If there are no errors captured the error key is mapped to null. The next key (list) is mapped to a list of hashes with their keys and values are the attributes and values of the current retrieved entity.

 
2. Default Implementations

The framework implements webman_JSON based component-type modules runtime inside single CGI script called index_JSON.cgi. This CGI script is allocated inside framework's CGI-bin directory together with main-controller's runtime CGI script (index.cgi). The index_JSON.cgi script still actually use the framework's main-controller to execute webman_JSON based/type modules but limited to which referred by nodes under Root --> json_entities_ link path structure. Underneath this link path structure the framework provides two default reference nodes of webman_JSON based/type modules as follows:

Root
|
|--json_entities_
   |
   |--authentication
   |
   |--users

The reference nodes authentication, users, and any other new nodes added will become the name of entities available for data interoperability service provided. These entity names are passed to index_JSON.cgi script using special CGI parameter named entity via HTTP POST/GET method. For each entities there might be attributes and their values passed together to filter or scope the returned data.

The authentication node is a reference to webman_JSON_authentication module that is a child of webman_JSON component-type modules. It has two attributes to be processed that are the login and the password. As a publicly accessed component, it provides service to authenticate users who are registered with the application. For any success authentication, it will return valid session ID which later can be used as a privilege-key for successive access to other restricted application resources. The authentication entity might also be used on other users who are registered out from the scope of JSON data interoperability service (users who are registered to only use the main web application host by the framework). The plain text data returned from authentication entity is in the form of JSON-formatted text as belows:

[
    {
       "error":null,
       "list":
       [
          {
             "session_id":"1661865234375",
             "web_service_url":null,
             "groups":[
                "ADMIN",
                "COM_JSON"
             ],
             "login_name":"foo",
             "full_name":"FOO FULL NAME",
             "description":"JASON Based Service Users"
          }
       ]
    }
]

The users node is simply a black-box implementation of webman_JSON component-type module that provide current list of users registered inside current application where the JSON data service is derived from.

Implementing JSON data service as a framework's component-type modules inside standard application's link structure will give the benefit of using the built-in security control provide by the framework at both link and component levels. This is very important and convenient in term of access control management since the service might be used and manipulated by other various external client's resources.


 
3. Instantiation and Basic Parameter Setting

There is only one basic parameter setting regarding to the main function of the module that is the SQL string command (line 6) used to query database table items reffered by JSON service entities.

  1 my $component = new webman_JSON;         
  2                                          
  3 $component->set_CGI($cgi);               
  4 $component->set_DBI_Conn($db_conn);      
  5                                          
  6 $component->set_SQL("select * from ...");
  7                                          


 
4. Component-type Generic Function Calls

The proposed component-type generic function calls is slightly different since the module not primarily purposes to support the view presentation of the applications but to retrieved the queried items from database tables referred by service entities and convert them into JSON-formatted text data (line 12). The JSON-formatted text later might be used internally by the caller's runtime (lines 18-26) or passed to the client who make a call to the service via http-text/plain connection (lines 31-32).

  8 my $json_text = undef;                                            
  9                                                                   
 10 if ($component->auth_Link_Path && $component->authenticate) {     
 11     $component->run_Task;                                         
 12     $json_text = $component->get_Content_JSON;                    
 13 }                                                                 
 14                                                                   
 15 ### Manipulate the returned JSON-formatted text using CPAN's JSON 
 16 ### module in the case of the module is run for internal data     
 17 ### implementations inside the caller's runtime.                  
 18 #my $json = new JSON;                                             
 19                                                                   
 20 #$json->indent([1]);                                              
 21 #my $data = $json->decode($json_text);                            
 22                                                                   
 23 #foreach my $item (@{$data}) {                                    
 24     #...                                                          
 25     #...                                                          
 26 #}                                                                
 27                                                                   
 28 ### The implementations if the module is run inside the CGI main  
 29 ### script and the returned JSON-format text is used for data     
 30 ### interoperability service over http-text/plain connection.     
 31 #print "Content-type: text/plain\n\n";                            
 32 #print $json_text;                                                


 
5. Child Module for Customization

Most common customizations are to manipulate the constructed JSON-formatted text before it's passed to the client (lines 50-?58), and programmatically modify the SQL string command to support more complex database query logic (line 71).

  1 package child_module_name;                             
  2                                                                          
  3 use webman_JSON;                                                         
  4                                                                          
  5 @ISA=("webman_JSON");                                                    
  6                                                                          
  7 sub new {                                                                
  8     my $class = shift;                                                   
  9                                                                          
 10     my $this = $class->SUPER::new();                                     
 11                                                                          
 12     #$this->set_Debug_Mode(1, 1);                                        
 13                                                                          
 14     bless $this, $class;                                                 
 15                                                                          
 16     return $this;                                                        
 17 }                                                                        
 18                                                                          
 19 sub get_Name {                                                           
 20     my $this = shift @_;                                                 
 21                                                                          
 22     return __PACKAGE__;                                                  
 23 }                                                                        
 24                                                                          
 25 sub get_Name_Full {                                                      
 26     my $this = shift @_;                                                 
 27                                                                          
 28     return $this->SUPER::get_Name_Full . "::" . __PACKAGE__;             
 29 }                                                                        
 30                                                                          
 31 sub run_Task {                                                           
 32     my $this = shift @_;                                                 
 33                                                                          
 34     my $cgi = $this->get_CGI;                                            
 35     my $dbu = $this->get_DBU;                                            
 36     my $db_conn = $this->get_DB_Conn;                                    
 37                                                                          
 38     my $login_name = $this->get_User_Login;                              
 39     my @groups = $this->get_User_Groups;                                 
 40                                                                          
 41     my $match_group = $this->match_Group($group_name_, @groups);         
 42                                                                          
 43     #$this->set_Error("???");                                            
 44                                                                          
 45     $this->SUPER::run_Task;                                              
 46                                                                          
 47     my $json_hash_ref = $this->decode_JSON_Text($this->get_Content_JSON);
 48                                                                          
 49     ### Next is to customize $json_hash_ref                              
 50     #$json_hash_ref->{error} = ...;                                      
 51                                                                          
 52     foreach my $item (@{$json_hash_ref->[0]->{list}}) {                  
 53         #$item->{attribute_1} = ...;                                     
 54         #...;                                                            
 55         #$item->{attribute_n} = ...;                                     
 56     }                                                                    
 57                                                                          
 58     $this->{content_json} = $this->encode_JSON_Text($json_hash_ref);     
 59 }                                                                        
 60                                                                          
 61 sub customize_SQL {                                                      
 62     my $this = shift @_;                                                 
 63                                                                          
 64     my $cgi = $this->get_CGI;                                            
 65     my $dbu = $this->get_DBU;                                            
 66     my $db_conn = $this->get_DB_Conn;                                    
 67                                                                          
 68     my $sql = $this->{sql};                                              
 69                                                                          
 70     ### Next to customize the $sql string.                               
 71     #$sql = ...;                                                         
 72                                                                          
 73     return $sql;                                                         
 74 }                                                                        
 75                                                                          
 76 1;