lorj 1.0.1 → 1.0.2

data/example/students_4/controller/yaml_students_code.rb

@@ -0,0 +1,109 @@
+# 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.
+
+# This class describes how to process some actions, and will do everything prior
+# this task to make it to work.
+
+# 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)
+      # We added test requiring :first_name and :last_name
+      required?(hParams, :first_name)
+      required?(hParams, :last_name)
+
+      hParams[:connection].create_student(hParams[:student_name],
+                                          hParams[:hdata])
+    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
+
+  # Example 4: Delete added to the controller.
+  def delete(sObjectType, hParams)
+    case sObjectType
+    when :student
+      required?(hParams, :connection)
+
+      hParams[:connection].delete_student(hParams[sObjectType][:id])
+    else
+      Error format("'%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

data/example/students_4/controller/yaml_students_def.rb

@@ -0,0 +1,72 @@
+# 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.
+
+# Declare
+# - additional objects and their specific process (:connection using basic
+# predefined :controller_create process)
+# - data_mapping :
+#   :connection_string => :file_name
+#   :course            => :training
+#
+# If some meta objects attributes has been added by the controller,
+# the main program and the GENERIC process will ignore them.
+#
+# If your controller will requires to have some data in this specific controller
+# attributes, you will have 2 options:
+# - Write a controller process which can take care of those new attributes
+#   This controller process will need to execute the original GENERIC process
+#   and then complete the task, with specific controller process to set
+#   these specific controller attributes.
+# - Set it up, using lorj setup function, if the data is declared setup-able by
+#   the controller.
+#   The controller can define how the setup have to ask values, and even can get
+#   data from the GENERIC process.
+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
+end

data/example/students_4/process/students/code/students.rb

@@ -0,0 +1,103 @@
+# 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.
+
+# In this version 4, The process will ensure a student is created only if
+# missing and remove duplicates.
+
+# 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.
+  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)
+    when 1
+      found_one_student(list[0], hParams[:student_name])
+    else
+      found_multiple_students(list, hParams[:student_name])
+    end
+  end
+
+  private
+
+  # Create a single new student
+  def create_new_student(hParams)
+    user = hParams[:student_name].split(' ')
+
+    controller_data = {}
+    unless hParams.exist?(:first_name)
+      if user.length == 1
+        controller_data[:first_name] = 'unknown first name'
+      else
+        controller_data[:first_name] = user[0..-2].join(' ')
+      end
+    end
+    controller_data[:last_name] = user[-1] unless hParams.exist?(:last_name)
+
+    student = controller_create(:student, controller_data)
+
+    process_fail format("Student '%s' not created.",
+                        hParams[:student_name]) if student.nil?
+
+    PrcLib.info(format("'student': '%s' created with id %s",
+                       hParams[:student_name],
+                       student[:id]))
+    student
+  end
+
+  # Identified 1 student
+  def found_one_student(student, student_name)
+    PrcLib.info(format("'student': '%s' loaded with id %s",
+                       student_name, student[:id]))
+
+    student
+  end
+
+  # Identified multiple identical students
+  # It will remove duplicated.
+  def found_multiple_students(list, student_name)
+    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)
+    PrcLib.info("'student': First loaded with id %s", list[0, :id])
+    list[0]
+  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("'student': %s duplicated '%s' removed. ", count, student_name)
+  end
+
+  def remove_student_object(object)
+    register(object)
+    controller_delete(:student)
+  end
+end

data/example/students_4/process/students/definition/students.rb

@@ -0,0 +1,60 @@
+# 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.
+
+# In this version 4, The process will ensure a student is created only if
+# missing and remove duplicates.
+
+# 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 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
+end

data/example/students_4/process/students.rb

@@ -0,0 +1,29 @@
+# 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.
+
+# In this version 4, The process will ensure a student is created only if
+# missing and remove duplicates.
+
+process_path = File.dirname(__FILE__)
+
+# Define model
+
+lorj_objects = %w(students)
+
+lorj_objects.each do |name|
+  require File.join(process_path, 'students', 'code', name + '.rb')
+  require File.join(process_path, 'students', 'definition', name + '.rb')
+end

data/example/students_4/student_v4.md

@@ -0,0 +1,191 @@
+# Writing student version 4
+
+In this example, we will enhance the process to remove duplicates, and ensure
+a student is created if it does not exist.
+
+We will also manage a little more data, like first name, last name and course.
+
+And we will simplify the way to transmit those data to the controller using the
+notion of hdata
+
+First of all, let's add 4 additional fields to the process:
+- student_name : Already configured.
+- first_name   : The controller should be able to use a different first_name than
+                 the one splitted from student_name. This is a new data.
+- last_name    : list first_name, last_name can be set directly, instead of built
+                 from student_name
+- course       : This is a new field. We will consider that YamlStudent API know it
+                 it as 'training' instead.
+
+---
+Before any update, compare to example 3, we have splitted `process/students.rb`
+in several files, to make the distintion of 'definition' and 'code'
+
+`process/students.rb` now contains:
+```ruby
+process_path = File.dirname(__FILE__)
+
+# Define model
+
+lorj_objects = %w(students)
+
+lorj_objects.each do | name |
+  require File.join(process_path, 'students', 'code', name + '.rb')
+  require File.join(process_path, 'students', 'definition', name + '.rb')
+end
+```
+
+The definition part is stored in:
+`process/students/definition/students.rb` : Definition of student meta object.
+                                            It contains the BaseDefinition code.
+`process/students/code/students.rb`       : Student meta object code.
+                                            It contains the StudentsProcess code.
+
+---
+Ok, To add new field to the process, update the process definition file:
+
+```ruby
+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 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
+
+```
+
+The YamlStudent controller needs to be updated as well, because we considered
+that training is the known field to use for course. We need to map it.
+
+We will also instroduce the hdata.
+hdata will ask lorj to create a Hash with the data set and already mapped.
+So, instead of setting yourself an Hash that the API may requires to work,
+you declare it and lorj will build it for you.
+
+Then on the controller code, you will just need to refer to the :hdata.
+We will see that in the next file.
+
+Here in the controller definition, we just declared the hdata to map.
+
+So, we need to update the controller definition file:
+
+```ruby
+class YamlStudents
+  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
+
+  define_obj(:student)
+  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
+```
+
+ok, cool.
+
+Now we need to update the controller code because we did not implemented the
+delete task in the controller. The process needs it to remove duplicates.
+
+But we need also to accept first and last name data from the process.
+We will move the split to the process as well.
+
+Additionnally, we talked about 'hdata'. 'hdata' will simplify the code as well.
+
+Let's see.
+We need to change the create, as we are going to use hdata:
+
+```ruby
+  # 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)
+      # We added test requiring :first_name and :last_name
+      required?(hParams, :first_name)
+      required?(hParams, :last_name)
+
+      #We replaced the previous code with simply hParams[:hdata].
+      hParams[:connection].create_student(hParams[:student_name],
+                                          hParams[:hdata])
+    else
+      controller_error "'%s' is not a valid object for 'create'", sObjectType
+    end
+  end
+```
+
+And then add the delete function used by the process to remove duplicates.
+
+```ruby
+  # Example 4: Delete added to the controller.
+  def delete(sObjectType, hParams)
+    case sObjectType
+    when :student
+      required?(hParams, :connection)
+
+      hParams[:connection].delete_student(hParams[sObjectType][:id])
+    else
+      Error format("'%s' is not a valid object for 'create'", sObjectType)
+    end
+  end
+```
+That's it.
+
+As you saw, the main program has not changed. Just process and controllers.
+
+In the next version is the full implementation of what `yaml_students/students.rb`
+main basic tool running the YamlStudent API.

data/example/students_4/students.rb

@@ -0,0 +1,65 @@
+#!/usr/bin/env ruby
+# 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.
+
+app_path = File.dirname(__FILE__)
+
+if ENV['BYEBUG']
+  require 'byebug'
+  lib_path = File.expand_path(File.join(app_path, '..', '..', 'lib'))
+  $LOAD_PATH << lib_path
+end
+
+require 'lorj'
+
+# 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.
+
+# Initialize the framework
+processes = [File.join(app_path, 'process', 'students.rb')]
+controller = File.join(app_path, 'controller', 'yaml_students.rb')
+
+# 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_name => 'Robert Redford')
+
+# 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.
+
+student_core.create(:student, :student_name => 'Anthony Hopkins')
+
+# Let's create a third different student.
+students = student_core.query(:student,  :name => 'Robert Redford')
+
+puts format('%s students found', students.length)
+
+students.each do |a_student|
+  puts format('%s: %s', a_student[:id], a_student[:name])
+end
+
+# let's check the get function, who is the ID 2?
+student = student_core.get(:student, 2)
+
+puts format('The student ID 2 is %s', student[:name])