lorj 1.0.1 → 1.0.2

data/example/students_3/process/students.rb

@@ -14,169 +14,35 @@
 #    See the License for the specific language governing permissions and
 #    limitations under the License.
 
-# Students process - Define specific handlers
+# Students process
 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]))
+    #  byebug if ENV['BYEBUG'] # rubocop: disable Debugger
+    object = controller_create(sObjectType)
+    PrcLib.runtime_fail "Student '%s' not created.",
+                        hParams[:student_name] if object.nil?
+    PrcLib.info("'%s': '%s' created with id %s",
+                sObjectType, hParams[: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
+# Declaring your data model and handlers.
+class Lorj::BaseDefinition # rubocop: disable Style/ClassAndModuleChildren
+  # We need to define the student object and the handler to use while we need to
+  # create it.
+  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 get
+             :get_e => :controller_get,
+             # We use predefined call to the controller delete
+             :delete_e => :controller_delete
+             )
+
+  obj_needs :data, :student_name, :for => [:create_e], :mapping => :name
 end

data/example/students_3/student_v3.md

@@ -0,0 +1,283 @@
+# Writing student version 3
+
+The power of lorj is to keep the GENERIC process as is, and be able to create a
+controller replacing simply mock by another one.
+In this example, we will use a yaml_students API in the new controller.
+
+This API is written in `examples/yaml_students/yaml_students.rb`.
+
+A controller is like a wrapper to an API which offer what we would like to use
+to save our yaml file. And that's globally, what we are going to do.
+
+First of all, we would like to inform lorj that we are going to use a different
+controller, to be written in controller/yaml_students.rb
+
+Let's change the student_core object creation.
+
+## File `students.rb`
+``` ruby
+processes = [File.join(app_path, 'process', 'students.rb')]
+# now we changed from mock to our own controller, located in
+controller = File.join(app_path, 'controller', 'yaml_students.rb')
+
+# controller/yaml_students.rb
+#  student_core = Lorj::Core.new(nil, processes, :mock)
+student_core = Lorj::Core.new(nil, processes, controller)
+```
+
+Now, let's write the controller file.
+
+The controller contains 2 elements:
+* controller definition
+* controller code
+
+lorj will load automatically 'controller/yaml_students.rb' and expect to find
+the controller definition and code.
+
+* The Controller definition have to be written in a class named: YamlStudents
+  lorj automatically creates a class derived from Lorj::BaseDefinition, and
+  expect the file to define this class.
+
+  So, you will need to write something like:
+
+    class YamlStudents
+    ...
+    end
+
+  Parent class (< BaseDefinition) is not required, as made by lorj itself.
+
+  All declaration function we can use are defined in BaseDefinition.
+
+  We will use the following:
+  * define_obj         : Declare a meta object, and attach handlers
+  * obj_needs          : Assign some data as parameters to handlers.
+  * def_attr_mapping   : Define meta object attributes mapping.
+  * undefine_attribute : Remove some predefined meta object attribute
+
+  We use define_obj to define another meta object, to create the connection
+  And we need to update the existing meta object 'student', to say that in the
+  context of this controller we need a connection.
+  This controller definition is executed on top of the process data model.
+
+  Then, we need to map meta object attributes with the controller data attributes
+
+  When the controller object has been created, lorj will need to get back data
+  that was defined by the model. The Process uses this data to complete his task.
+  So, the controller will need to help lorj to extract data from the controller
+  object.
+
+  This the role of a get_attr function.
+
+  The usage of hdata (def_hdata) is a framework facility to build a Hash with
+  all data attributes and values required by the controller object to work.
+
+  Ok, let's write this controller, now:
+
+  To simplify, we split this controller in 3 files.
+  controller/yaml_students.rb declare, files and API to use
+  controller/yaml_students_def.rb contains the controller definition
+  controller/yaml_students_code.rb contains the controller code.
+
+## controller/yaml_students.rb
+``` ruby
+# 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.
+#
+controller_file = File.join(cur_path, 'yaml_students_code.rb')
+require controller_file # Load controller mapping
+
+# - Definition class
+#   This class declare any kind of mapping or additional attributes to consider.
+require File.join(cur_path, 'yaml_students_def.rb')
+```
+
+## controller/yaml_students_def.rb
+``` 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,
+             # 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 meta object 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
+
+  # instead of 'student_name', the yaml API uses 'name' as key
+  def_attr_mapping :student_name, :name
+end
+```
+
+##### controller/yaml_students_code.rb
+This file is code of the controller which will deal with the API to wrap and
+adapt the Generic process object data model to become compatible with
+the controller data model.
+
+For example:
+YamlStudent requires a first and last name at student creation time.
+As the GENERIC process only know the student name, the controller will
+need to determine how to get the first & last name from the student name.
+
+The generic Get a student from a unique ID doesn't exist. So, we need to adapt this
+to use a query :id => id instead.
+
+Of course, simple case, like when lorj ask directly the controller to query, it will
+simply call the query API function.
+
+Ok, let's see the code, now:
+
+``` ruby
+# This file describe the controller code.
+# The class name is determined by lorj.
+# See controller/yaml_students.rb for details
+class YamlStudentsController
+  # controller wrapper
+  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)
+
+      # Here, we adapt the lorj student data model  with the YamlStudent data model
+      fields = hParams[:student_name].split(' ')
+      fields.insert(0, 'first_name unknown') if fields.length == 1
+
+      options = {:first_name => fields[0..-2].join(' '),
+                 :last_name => fields[-1]}
+      hParams[:connection].create_student(hParams[:student_name], options)
+    else
+      controller_error "'%s' is not a valid object for 'create'", sObjectType
+    end
+  end
+
+  # This function return one element identified by an ID.
+  # But get is not a YamlStudent API functions. But query help to use :id
+  #
+  # so we will do a query
+  def get(sObjectType, id, hParams)
+    case sObjectType
+    when :student
+      result = query(sObjectType, {:id => id}, hParams)
+      return nil if result.length == 0
+      result[0]
+    else
+      controller_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
+      controller_error "'%s' is not a valid object for 'create'", sObjectType
+    end
+  end
+
+  # 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 ] ]
+  def get_attr(oControlerObject, key)
+    attributes = oControlerObject
+
+    controller_error("get_attr: attribute '%s' is unknown in '%s'. "\
+                     "Valid one are : '%s'",
+                     key[0], oControlerObject.class,
+                     valid_attributes) unless valid_attributes.include?(key[0])
+    attributes.rh_get(key)
+  rescue => e
+    controller_error "get_attr: Unable to map '%s'. %s\n See %s",
+                     key, e.message, e.backtrace[0]
+  end
+
+  private
+
+  # These are the valid controller fields.
+  def valid_attributes
+    [:name, :first_name, :last_name, :id, :status, :training]
+  end
+end
+```
+
+If you execute the code, right now, runtime/connection_string will be missing...
+One of possible way should be use save this an Account file, driven by the Account
+Object.
+
+In this example, we will simply set this data manually from the main.
+
+## students.rb
+We simply add a setting
+``` ruby
+[...]
+# now we changed from mock to our own controller, located in
+# controller/yaml_students.rb
+#  student_core = Lorj::Core.new(nil, processes, :mock)
+config = Lorj::Config.new
+config[:connection_string] = '/tmp/students.yaml'
+student_core = Lorj::Core.new(config, processes, controller)
+[...]
+```
+
+# Playing around
+
+If you want to move back to the mock controller, do it! You will still see that its keeps working.
+
+You can enhance your main by selecting between mock or yaml_students
+
+# next?
+
+In next version, we will enhance the process to remove duplicates, and ensure
+a student is created if it does not exist.
+
+[Details is explained here](example/students_4/student_v4_md.html)

data/example/students_3/students.rb

@@ -17,106 +17,49 @@
 
 app_path = File.dirname(__FILE__)
 
-if ENV['LORJ_DEV']
+if ENV['BYEBUG']
   require 'byebug'
   lib_path = File.expand_path(File.join(app_path, '..', '..', 'lib'))
   $LOAD_PATH << lib_path
 end
-require 'lorj'
-require 'ansi'
-
-# Load global Config
-
-# This object is used to provide configuration data to lorj
-
-# The config search is:
-# 1- Application defaults (defaults.yaml) - Not defined by default. update the
-# following line and create defaults.yaml
-# PrcLib.app_defaults = $APP_PATH
-# 2- Local defaults (~/.<Application Name>/config.yaml) - <Application Name> is
-# 'Lorj' by default. Can be updated with following line.
-# PrcLib.app_name = 'myapp'
-# 3 - runtime. Those variables are set, with config[key] = value
-
-config = Lorj::Config.new # Use Simple Config Object
 
-# You can use an account object, which add an extra account level
-# between runtime and config.yaml/app default
-# config = Lorj::Account.new('MyAccount') #
+require 'lorj'
 
-# If you want to see what is happening in the framework, uncomment
-# debug settings.
+# 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 = 5 # framework debug levels.
+PrcLib.core_level = 3 # framework debug levels.
 
 # Initialize the framework
 processes = [File.join(app_path, 'process', 'students.rb')]
+controller = File.join(app_path, 'controller', 'yaml_students.rb')
 
-# ~ student_core = Lorj::Core.new( config, processes, :mock)
-student_core = Lorj::Core.new(config,
-                              processes,
-                              File.join(app_path,
-                                        'controller',
-                                        'yaml_students.rb'))
-
-student_core.create(:connection, :connection_string => '/tmp/students.yaml')
-
-puts ANSI.bold('Create 1st student:')
-
-# Set the student name to use
-# There is different way to set them...
-# Those lines do the same using config object. Choose what you want.
-config.set(:first_name, 'Robert')
-config[:last_name]    = 'Redford'
-config[:student_name] = 'Robert Redford'
-config[:course]       = 'Art Comedy'
+# now we changed from mock to our own controller, located in
+# controller/yaml_students.rb
+#  student_core = Lorj::Core.new(nil, processes, :mock)
+config = Lorj::Config.new
+config[:connection_string] = '/tmp/students.yaml'
+student_core = Lorj::Core.new(config, processes, controller)
 
 # Ask the framework to create the object student 'Robert Redford'
-student_core.create(:student)
+student_core.create(:student, :student_name => 'Robert Redford')
 
-puts ANSI.bold('Create 2nd student:')
-# We can set runtime configuration instantly from the Create call
-# The following line :
-student_core.create(:student,
-                    :student_name => 'Anthony Hopkins',
-                    :first_name => 'Anthony',
-                    :last_name => 'Hopkins',
-                    :course => 'Art Drama'
-)
-# config[:student_name] = "Anthony Hopkins"
-# config[:course] = "Art Drama"
-# student_core.Create(:student)
+# Want to create a duplicated student 'Robert Redford'?
+student_core.create(:student, :student_name => 'Robert Redford')
+# no problem. The key is the key in the Mock controller array.
 
-puts ANSI.bold('Create 3rd student:')
-student_core.create(:student,
-                    :student_name => 'Marilyn Monroe',
-                    :first_name => 'Marilyn',
-                    :last_name => 'Monroe',
-                    :course => 'Art Drama'
-)
-# replaced the following :
-# config[:student_name] = "Anthony Hopkins"
-# student_core.Create(:student)
+student_core.create(:student, :student_name => 'Anthony Hopkins')
 
-puts ANSI.bold('Create mistake')
-student = student_core.create(:student,
-                              :student_name => 'Anthony Mistake',
-                              :first_name => 'Anthony',
-                              :last_name => 'Mistake',
-                              :course => 'what ever you want!!!'
-)
+# Let's create a third different student.
+students = student_core.query(:student,  :name => 'Robert Redford')
 
-puts format("Student created '%s'", student[:attrs])
+puts format('%s students found', students.length)
 
-# Because the last student was the mistake one, we can directly delete it.
-# Usually, we use get instead.
-puts ANSI.bold('Remove mistake')
-student_core.delete(:student)
-puts format('Wrong student to remove: %s = %s',
-            student[:id], student[:student_name])
+students.each do |a_student|
+  puts format('%s: %s', a_student[:id], a_student[:name])
+end
 
-puts ANSI.bold("List of students for 'Art Drama':")
-puts student_core.query(:student,  :course => 'Art Drama').to_a
+# let's check the get function, who is the ID 2?
+student = student_core.get(:student, 2)
 
-puts ANSI.bold('Deleted students:')
-puts student_core.query(:student, :status => :removed).to_a
+puts format('The student ID 2 is %s', student[:name])

data/example/students_4/controller/yaml_students.rb

@@ -0,0 +1,51 @@
+# 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.
+#
+controller_file = File.join(cur_path, 'yaml_students_code.rb')
+require controller_file # Load controller mapping
+
+# - Definition class
+#   This class declare any kind of mapping or additional attributes to consider.
+require File.join(cur_path, 'yaml_students_def.rb')