lorj 1.0.1 → 1.0.2

data/example/students_5/controller/yaml_students.rb

@@ -0,0 +1,106 @@
+# encoding: UTF-8
+
+# (c) Copyright 2014 Hewlett-Packard Development Company, L.P.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+
+# when you declare this controller with a file name, lorj expect this file
+# to contains the controller code and the controller definition.
+# The code have to be declared in a class which is named as follow from the file
+# name:
+#   1st letter is capitalized
+#   A '_' followed by a letterif replaced by the capicatl letter.
+#   Ex: my_code.rb => assume to declare MyCode class
+#
+# The controller code class is built from the source file name as explained
+# below + 'Controller'
+#  Ex: my_code.rb => assume to use MyCodeController for controller handlers and
+#                    functions.
+#
+# The controller definition class is build from the file name only.
+#  Ex: my_code.rb => assume to use MyCode for controller definition.
+
+# This class describes how to process some actions, and will do everything prior
+# this task to make it to work.
+
+# declare yaml student API to the controller
+cur_path = File.expand_path(File.dirname(__FILE__))
+api_file = File.join(cur_path, '..', '..', 'yaml_students', 'yaml_students.rb')
+
+require api_file
+
+# The controller is a combination of 2 elements:
+# - Controller class
+#   Code which will interfere with the external API.
+#
+# - Definition class
+#   This class declare any kind of mapping or additional attributes to consider.
+controller_file = File.join(cur_path, 'yaml_students_controller.rb')
+require controller_file # Load controller mapping
+
+# Declare
+# - additional objects and their specific process (:connection using basic
+# predefined :controller_create process)
+# - data_mapping :
+#   :connection_string => :file_name
+#   :course            => :training
+#
+# If some data has been added by the controller, the main and process,
+# won't take care and the framework will fails.
+# To eliminate this errors, there is 2 cases:
+# - detect this change in the process or the main.
+# - set it up, using lorj setup function, if the data is declared askable by
+#   the controller.
+#   The controller can define how the setup have to ask values, and even can get
+#   data from itself.
+class YamlStudents
+  # This is a new object which is known by the controller only.
+  # Used to open the yaml file. Generically, I named it :connection.
+  # But this can be any name you want. Only the controller will deal with it.
+  define_obj(:connection,
+             # Nothing complex to do. So, simply call the controller create.
+             :create_e => :controller_create
+  )
+
+  obj_needs :data,   :connection_string,  :mapping => :file_name
+  undefine_attribute :id    # Do not return any predefined ID
+  undefine_attribute :name  # Do not return any predefined NAME
+
+  # The student model have to be expanded.
+  define_obj(:student)
+  # It requires to create a connection to the data, ie opening the yaml file.
+  # So, before working with the :student object, the controller requires a
+  # connection
+  # This connection will be loaded in the memory and provided to the controller
+  # when needed.
+  # obj_needs :CloudObject update the :student object to requires a connection
+  # before.
+  obj_needs :CloudObject,              :connection
+
+  # To simplify controller wrapper, we use hdata built by lorj, and passed to
+  # the API
+  # This hdata is a hash containing mapped data, thanks to def_hdata.
+  def_hdata :first_name
+  def_hdata :last_name
+  # Instead of 'course', the yaml API uses 'training'
+  def_hdata :course, :mapping => :training
+
+  def_attr_mapping :course, :training
+  # instead of 'student_name', the yaml API uses 'name'
+  def_attr_mapping :student_name, :name
+
+  # This controller will know how to manage a student file with those data.
+  # But note that the file can have a lot of more data than what the process
+  # usually manage. It is up to you to increase your process to manage more data
+  # Then each controller may need to define mapping fields.
+end

data/example/{students_3 → students_5}/controller/yaml_students_controller.rb

@@ -21,9 +21,9 @@
 
 # declare yaml student API to the controller
 yaml_students_file = File.expand_path(
-                      File.join(
-                        File.dirname(__FILE__),
-                        '..', '..', 'yaml_students', 'yaml_students.rb'))
+  File.join(
+    File.dirname(__FILE__),
+    '..', '..', 'yaml_students', 'yaml_students.rb'))
 require yaml_students_file
 
 # The controller is a combination of 2 elements:
@@ -47,6 +47,8 @@ class YamlStudentsController
   def create(sObjectType, hParams)
     case sObjectType
     when :connection
+      byebug if ENV['BYEBUG'] # rubocop: disable Debugger
+
       required?(hParams, :hdata, :file_name)
       YamlSchool.new(hParams[:hdata, :file_name])
     when :student

data/example/students_5/process/students.rb

@@ -0,0 +1,182 @@
+# encoding: UTF-8
+
+# (c) Copyright 2014 Hewlett-Packard Development Company, L.P.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+
+# Students process - Define specific handlers
+class StudentsProcess
+  # create_student process handler to get a student.
+  #
+  # * If not found, create it.
+  # * If multiple found, remove duplicates
+  # * otherwise return the one found.
+  # rubocop:disable Metrics/MethodLength
+  def create_student(sObjectType, hParams)
+    PrcLib.state(format("Running creation process for object '%s' = '%s'",
+                        sObjectType, hParams[:student_name]))
+
+    list = process_query(sObjectType, :student_name => hParams[:student_name])
+    case list.length
+    when 0
+      create_new_student(hParams[:student_name])
+    when 1
+      found_one_student(list[0], hParams[:student_name])
+    else
+      found_multiple_students(list, hParams[:student_name])
+    end
+  end
+  # rubocop:enable Metrics/MethodLength
+
+  private
+
+  # Create a single new student
+  def create_new_student(student_name)
+    object = controller_create(:student)
+    fail format("Student '%s' not created.", student_name) if object.nil?
+
+    PrcLib.info(format("'student': '%s' created with id %s",
+                       student_name,
+                       object[:id]))
+    object
+  end
+
+  # Identified 1 student
+  def found_one_student(object, student_name)
+    PrcLib.info(format("'student': '%s' loaded with id %s",
+                       student_name, object[:id]))
+    object
+  end
+
+  # Identified multiple identical students
+  # It will remove duplicated.
+  def found_multiple_students(list, student_name)
+    object = list[0]
+    PrcLib.warning(format("More than one student named '%s' is found: %s "\
+                          'records. Selecting the first one and removing '\
+                          'duplicates.',
+                          student_name, list.length))
+    remove_multiple_students(list[1..-1], student_name)
+    object
+  end
+
+  # Remove list of identical students
+  def remove_multiple_students(list, student_name)
+    return false unless list.is_a?(Array)
+    return false if list.length == 0
+
+    count = 0
+    list.each { |elem| count += remove_student_object(elem) }
+    PrcLib.info(format("'student': %s duplicated '%s' removed. "\
+                       'First loaded with id %s',
+                       count, student_name, object[:id]))
+  end
+
+  def remove_student_object(object)
+    register(object)
+    controller_delete(:student)
+  end
+
+  # The following handler is inactive.
+  # It provides a simple print-out code.
+  # If you want to activate it:
+  # * uncomment query_student function
+  # * update the :student data model
+  #   on query_e, replace controller_query by query_student
+
+  # def query_student(sObjectType, sQuery, hParams)
+  #    PrcLib::state (format("Running query process for object '%s' "\
+  #                          "with query '%s'",
+  #                           sObjectType,
+  #                           sQuery))
+  #
+  #   objects = controller_query(sObjectType, sQuery)
+  #   raise "Query error." if objects.nil?
+  #
+  #   PrcLib::info (format("'%s': Queried. %s records found.",
+  #                        sObjectType,
+  #                        objects.length))
+  #   objects
+  # end
+
+  # This handler is inactive.
+  # It provides a simple print-out code.
+  # If you want to activate it:
+  # * uncomment get_student function
+  # * update the :student data model
+  #   on get_e, replace controller_get by get_student
+
+  # def delete_student(sObjectType, hParams)
+  #    controller_delete(:student)
+  #    PrcLib::info (format("'%s:%s' student removed",
+  #                         hParams[:student, :id],
+  #                         hParams[:student, :name]))
+  # end
+end
+
+module Lorj
+  # Declaring your data model and handlers.
+  # Process Handlers functions have to be declared before, as lorj check their
+  # existence during data model definition.
+  class BaseDefinition
+    # We need to define the student object data model and process handlers to
+    # use.
+    # Process handlers must manipulate data defined here.
+    #
+    # The controller can redefine object for it needs, but should NEVER impact
+    # the main process.
+    # The controller can add specific process to deal with internal controller
+    # objects.
+    # But this should never influence the original process model.
+
+    # Use define_obj, to declare the new object managed by lorj with process
+    # handlers.
+
+    define_obj(:student,
+               # The function to call in the class Students
+               :create_e => :create_student,
+               # We use predefined call to the controller query
+               :query_e => :controller_query,
+               # We use predefined call to the controller delete
+               :delete_e => :controller_delete
+               )
+
+    # obj_needs is used to declare parameters to pass to handlers.
+    # :for indicates those parameters to be passed to create_e handler only.
+    # Those data (or objects) will be collected and passed to the process
+    # handler as hParams.
+
+    obj_needs :data,   :student_name,           :for => [:create_e]
+
+    # By default, all data are required.
+    # You can set it as optional. Your process will need to deal with this
+    # optional data.
+    obj_needs_optional
+    obj_needs :data,   :first_name,             :for => [:create_e]
+    obj_needs :data,   :last_name,              :for => [:create_e]
+    obj_needs :data,   :course
+    # Note that in this model, the training is renamed as course.
+
+    # the controller will need to map it to 'training'.
+
+    # def_attribute defines the data model.
+    # The process will be able to access those data
+    def_attribute :course
+    def_attribute :student_name
+    def_attribute :first_name
+    def_attribute :last_name
+    def_attribute :status
+
+    undefine_attribute :name
+  end
+end

data/example/students_5/student_v5.md

@@ -0,0 +1,382 @@
+# Writing student version 5
+
+**NOTE**: following example is available in `examples/students_5/`
+
+In this last example, we are fully implementing the yaml_student example which
+is demonstrated in `examples/yaml_students/students.rb`.
+this script is the main program calling the api and create a basic yaml file example in `/tmp/students.yaml`
+
+So, we are going to update this main to use lorj instead and reproduce the same
+functionnality.
+
+You can review the script 'students.rb' to see the simple code.
+
+In short, this code do:
+
+* create 3 students, only if they do not exists
+* remove a wrong one
+* Identify list of students on a specific training
+* Identify students removed.
+
+We will do the same thing with lorj.
+
+Using lorj means you are going to split your code in different pieces. You will need to integrate a layer between your main and the API. This layer is composed by :
+
+* 1 generic data model
+* 1 generic process handlers
+* 1 controller definition - expanding the data model for our Student yaml API
+* 1 controller code - wrapper to the student yaml API.
+
+So, we are going to update following files:
+
+* students.rb - Adapt the main to do the same as original students script using the student yaml API.
+* process/students.rb - Student data model - Update the process data model.
+* process/students.rb - Student process handler - Update student process handlers.
+* controller/yaml_students.rb - controller definition - Extend the student data model with controller definition.
+* controller/yaml_students_controller.rb - controller code - Write the student yaml API wrapper.
+
+First of all, let me re-visit the :student data model, then the student process handlers.
+
+We need to define more parameters for handlers, and define the data model.
+
+##### File `process/students.rb`
+Update the class Lorj::BaseDefinition, and the data model and handlers parameters.
+
+*The generic data model:*
+
+``` ruby
+    class Lorj::BaseDefinition
+       define_obj(:student,
+       {
+          :create_e => :create_student,   # The function to call in the class Students
+          :query_e  => :controller_query, # We use predefined call to the controller query
+          :delete_e => :controller_delete # We use predefined call to the controller delete
+       })
+
+       # obj_needs is used to declare parameters to pass to handlers.
+       # :for indicates those parameters to be passed to create_e handler only.
+       # Those data (or objects) will be collected and passed to the process handler as hParams.
+
+       obj_needs   :data,   :student_name,          { :for => [:create_e] }
+
+       # By default, all data are required.
+       # You can set it as optional. Your process will need to deal with this optional data.
+       obj_needs_optional
+       obj_needs   :data,   :first_name,            { :for => [:create_e] }
+       obj_needs   :data,   :last_name,             { :for => [:create_e] }
+       obj_needs   :data,   :course  # Note that in this model, the training is renamed as course.
+                                     # the controller will need to map it to 'training'.
+
+       # def_attribute defines the data model.
+       # The process will be able to access those data
+       # if the controller has mapped them.
+       # For the exercice, I have changed the name of the training field to become :course instead.
+       def_attribute :course
+       # Same thing for the student name. instead of 'name', we defined :student_name
+       def_attribute :student_name
+       def_attribute :first_name
+       def_attribute :last_name
+       def_attribute :status
+
+       undefine_attribute :name
+   end
+```
+
+Then, update the process to manage student duplicates. Update function `create_student`
+
+*The generic process handlers:*
+
+``` ruby
+    class StudentsProcess
+       def create_student(sObjectType, hParams)
+          PrcLib::state ("Running creation process for object '%s' = '%s'" % [sObjectType, hParams[:student_name] ])
+
+          # config object is a reference to runtime/config data.
+          oList = Query(sObjectType, {:name => hParams[:student_name]})
+          case oList.length
+             when 0
+                oObject = controller_create(sObjectType)
+                raise "Student '%s' not created." % hParams[:student_name] if oObject.nil?
+                PrcLib::info ("'%s': '%s' created with id %s" % [sObjectType, hParams[:student_name],  oObject[:id]])
+             when 1
+                oObject = oList[0]
+                PrcLib::info ("'%s': '%s' loaded with id %s" % [sObjectType, hParams[:student_name],  oObject[:id]])
+             else
+                oObject = oList[0]
+                PrcLib::warning("More than one student named '%s' is found: %s records. Selecting the first one and removing duplicates." % [hParams[:student_name], oList.length])
+                iCount = 0
+                oList[1..-1].each { | elem |
+                   register(elem)
+                   iCount += controller_delete(sObjectType)
+                }
+                PrcLib::info ("'%s': %s duplicated '%s' removed. First loaded with id %s" % [sObjectType, iCount, hParams[:student_name],  oObject[:id]])
+          end
+          oObject
+       end
+    end
+```
+
+Here you see that we query, check list, create if missing, or delete if duplicates found.
+You can run it now, as we still uses mock controller. It should work.
+
+##### File `students.rb`
+
+Now, let's update the main to be close to what we have on `examples/yaml_students/students.rb`
+
+This is a simple basic translation of `examples/yaml_students/students.rb`
+
+``` ruby
+    #!/usr/bin/env ruby
+
+    $APP_PATH = File.dirname(__FILE__)
+    require 'lorj'
+    require 'ansi'
+
+    # If you want to see what is happening in the framework, uncomment debug settings.
+    # PrcLib.level = Logger::DEBUG # Printed out to your console.
+    # PrcLib.core_level = 3 # framework debug levels. Values between 0 to 5.
+
+    # Initialize the framework
+    hProcesses = [ File.join($APP_PATH, 'process', 'students.rb')]
+
+    # You can try with mock instead. uncomment the next line and comment 2 next lines.
+    #~ oStudentCore = Lorj::Core.new( nil, hProcesses, :mock)
+    oStudentCore = Lorj::Core.new( nil, hProcesses, File.join($APP_PATH, 'controller', 'yaml_students.rb'))
+    oStudentCore.Create(:connection, :connection_string => "/tmp/students.yaml")
+
+    puts ANSI.bold("Create 1st student:")
+
+    oStudentCore.Create(:student, {
+       student_name:  'Robert Redford',
+       first_name:    'Robert',
+       last_name:     'Redford',
+       course:        'Art Comedy'
+    })
+
+    puts ANSI.bold("Create 2nd student:")
+    oStudentCore.Create(:student, {
+       student_name:  'Anthony Hopkins',
+       first_name:    'Anthony',
+       last_name:     'Hopkins',
+       course:        'Art Drama'
+    })
+
+    puts ANSI.bold("Create 3rd student:")
+    oStudentCore.Create(:student, {
+       student_name: "Marilyn Monroe",
+       first_name:   'Marilyn',
+       last_name:    'Monroe',
+       course:       'Art Drama'
+    })
+
+    puts ANSI.bold("Create mistake")
+    oStudentCore.Create(:student, {
+       :student_name  => "Anthony Mistake",
+       :first_name    => 'Anthony',
+       :last_name     => 'Mistake',
+       :course        => 'what ever you want!!!'
+    })
+
+    # Because the last student was the mistake one, we can directly delete it.
+    # Usually, we use get instead.
+    puts ANSI.bold("Remove mistake")
+    oStudentCore.Delete(:student)
+
+    puts ANSI.bold("List of students for 'Art Drama':")
+    puts oStudentCore.Query(:student, { :course => "Art Drama"}).to_a
+
+    puts ANSI.bold("Deleted students:")
+    puts oStudentCore.Query(:student,{ :status => :removed}).to_a
+```
+
+We have reproduced the code. Note that there is no if while creating. It is embedded in the create_student process.
+
+##### File `controller/yaml_students_controller.rb`
+
+We need to write the controller part, now. As I said, it is like a wrapper. Let's have a look:
+
+*The controller code:*
+
+``` ruby
+    # declare yaml student API to the controller
+    cur_file = File.expand_path(File.join(File.dirname(File.dirname(__FILE__)), "..", "yaml_students", 'yaml_students.rb'))
+    require cur_file
+
+    # The controller is a combination of 2 elements:
+    # - Controller class
+    #   Code which will interfere with the external API.
+    #
+    #   The file name must respect the name of the class. 1st letter already capitalized and letter after _ is capitalized.
+    #   file: my_code.rb => needs to create MyCodeController class
+    #
+    # - Definition class
+    #   This class declare any kind of mapping or additional fields to consider.
+    #   Additionnal fields are unknow by the process. So, those fields will needs to be setup before.
+    #
+    #   file name convention is identical than controller class.
+    #   file: my_code.rb => needs to create MyCode class
+
+    class YamlStudentsController
+       def initialize()
+          @@valid_attributes = [:name, :first_name, :last_name, :id, :status, :training]
+       end
+
+       def create(sObjectType, hParams)
+          case sObjectType
+             when :connection
+                required?(hParams, :hdata, :file_name)
+                YamlSchool.new(hParams[:hdata, :file_name])
+             when :student
+                required?(hParams, :connection)
+                required?(hParams, :student_name)
+
+                # We use the hdata built by the lorj. See set_hdata in the next file.
+                hParams[:connection].create_student(hParams[:student_name], hParams[:hdata])
+             else
+                Error "'%s' is not a valid object for 'create'" % sObjectType
+          end
+       end
+
+       # This function return a collection which have to provide:
+       # functions: [], length, each
+       def query(sObjectType, sQuery, hParams)
+          case sObjectType
+             when :student
+                required?(hParams, :connection)
+
+                hParams[:connection].query_student(sQuery)
+             else
+                Error "'%s' is not a valid object for 'create'" % sObjectType
+          end
+
+       end
+
+       def delete(sObjectType, hParams)
+          case sObjectType
+             when :student
+                required?(hParams, :connection)
+
+                hParams[:connection].delete_student(hParams[sObjectType][:id])
+             else
+                Error "'%s' is not a valid object for 'create'" % sObjectType
+          end
+       end
+
+       def get_attr(oControlerObject, key)
+          # This controller function read the data and
+          # extract the information requested by the framework.
+          # Those data will be mapped to the process data model.
+          # The key is an array, to get data from a level tree.
+          # [data_l1, data_l2, data_l3] => should retrieve data from structure
+          #                                like data[ data_l2 [ data_l3 ] ]
+          begin
+             attributes = oControlerObject
+             raise "get_attr: attribute '%s' is unknown in '%s'. Valid one are : '%s'",
+                   key[0], oControlerObject.class,
+                   @@valid_attributes unless @@valid_attributes.include?(key[0])
+             Lorj::rh_get(attributes, key)
+          rescue => e
+             Error "get_attr: Unable to map '%s'. %s" % [key, e.message]
+          end
+       end
+
+       def set_attr(oControlerObject, key, value)
+          begin
+             attributes = oControlerObject
+             raise "set_attr: attribute '%s' is unknown in '%s'. Valid one are : '%s'",
+                   key[0], oControlerObject.class,
+                   @@valid_attributes  unless @@valid_attributes.include?(key[0])
+             Lorj::rh_set(attributes, value, key)
+          rescue => e
+             Error "set_attr: Unable to map '%s' on '%s'" % [key, sObjectType]
+          end
+       end
+
+       def update(sObjectType, oObject, hParams)
+          case sObjectType
+             when :student
+                required?(hParams, :connection)
+
+                hParams[:connection].update_student(oObject)
+             else
+                Error "'%s' is not a valid object for 'create'" % sObjectType
+          end
+       end
+
+    end
+
+```
+In short, we wrap:
+
+- create with YamlSchool.create_student
+- delete with YamlSchool.delete_student
+- query with YamlSchool.query_student
+- update with YamlSchool.update_student
+
+And we have defined 2 additional functions
+
+- get_attr: to extract data from a YamlSchool Object
+- set_attr: to set data to a YamlSchool Object
+
+##### File `controller/yaml_students.rb`
+
+And we need to write some mapping stuff to the controller. We have to add this
+
+*The controller definition:*
+
+``` ruby
+    class YamlStudents
+       # This is a new object which is known by the controller only.
+       # Used to open the yaml file. Generically, I named it :connection.
+       # But this can be any name you want. Only the controller will deal with it.
+       define_obj(:connection,{
+        :create_e => :controller_create # Nothing complex to do. So, simply call the controller create.
+       })
+
+       obj_needs   :data,   :connection_string,  :mapping => :file_name
+       undefine_attribute :id    # Do not return any predefined ID
+       undefine_attribute :name  # Do not return any predefined NAME
+
+       # The student model have to be expanded.
+       define_obj(:student)
+       # It requires to create a connection to the data, ie opening the yaml file.
+       # So, before working with the :student object, the controller requires a connection
+       # This connection will be loaded in the memory and provided to the controller
+       # when needed.
+       obj_needs   :CloudObject,              :connection
+
+       # To simplify controller wrapper, we use hdata built by lorj, and passed to the API
+       # This hdata is a hash containing mapped data, thanks to set_hdata.
+       set_hdata :first_name
+       set_hdata :last_name
+       # Instead of 'course', the yaml API uses 'training'
+       set_hdata :course, :mapping => :training
+
+       get_attr_mapping :course, :training
+       # instead of 'student_name', the yaml API uses 'name'
+       get_attr_mapping :student_name, :name
+
+       # This controller will know how to manage a student file with those data.
+       # But note that the file can have a lot of more data than what the process
+       # usually manage. It is up to you to increase your process to manage more data.
+       # Then each controller may need to define mapping fields.
+    end
+```
+
+That's it!
+
+#####typical output:
+    $ example/students_3/students.rb
+    WARNING: PrcLib.app_defaults is not set. Application defaults won't be loaded.
+    Create 1st student:
+    Create 2nd student:
+    Create 3rd student:
+    Create mistake
+    Student created '{:id=>3, :course=>"what ever you want!!!", :student_name=>"Anthony Mistake", :first_name=>"Anthony", :last_name=>"Mistake", :status=>:active}'
+    Remove mistake
+    Wrong student to remove: 3 = Anthony Mistake
+    List of students for 'Art Drama':
+    {:id=>1, :course=>"Art Drama", :student_name=>"Anthony Hopkins", :first_name=>"Anthony", :last_name=>"Hopkins", :status=>:active}
+    {:id=>2, :course=>"Art Drama", :student_name=>"Marilyn Monroe", :first_name=>"Marilyn", :last_name=>"Monroe", :status=>:active}
+    Deleted students:
+    {:id=>3, :course=>"what ever you want!!!", :student_name=>"Anthony Mistake", :first_name=>"Anthony", :last_name=>"Mistake", :status=>:removed}