lorj 1.0.1 → 1.0.2

data/Rakefile

@@ -17,9 +17,16 @@
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 require 'rubocop/rake_task'
+require 'rdoc/task'
 
 task :default => [:lint, :spec]
 
+desc 'Generate lorj documentation'
+RDoc::Task.new do |rdoc|
+  rdoc.main = 'README.md'
+  rdoc.rdoc_files.include('README.md', 'lib', 'example', 'bin')
+end
+
 desc 'Run the specs.'
 RSpec::Core::RakeTask.new do |t|
   t.pattern = 'spec/*_spec.rb'

data/example/students_1/student_v1.md

@@ -0,0 +1,115 @@
+# Writing student version 1
+
+**NOTE**: following example is available in `examples/students_1/`
+
+First of all, write your first main. Create a file `example.rb` with following content:
+
+## File `students.rb`
+
+``` ruby
+    #!/usr/bin/env ruby
+
+    app_path = File.dirname(__FILE__)
+    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')]
+    student_core = Lorj::Core.new( nil, processes)
+
+    # Ask the framework to create the object student 'Robert Redford'
+    student_core.create(:student, :student_name => "Robert Redford")
+```
+
+## File `process/students.rb`
+
+Now, let's write our first process. We are going to create a file Students.rb
+under a sub-directory 'process'.
+
+``` ruby
+  # Students process
+  class StudentsProcess
+    def create_student(object_type, params)
+        puts format("Running creation process for object '%s' = '%s'",
+                    object_type, params[:student_name] )
+
+        # If you prefer to print out to the log system instead:
+        # PrcLib::debug("Running creation process for object '%s' = '%s'",
+        #               object_type, params[:student_name])
+    end
+  end
+
+  # Declaring your data model and handlers.
+  class Lorj::BaseDefinition
+
+     # 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
+     )
+
+     obj_needs :data, :student_name, :for => [:create_e]
+
+  end
+```
+
+What did we wrote?
+
+* We defined a *StudentsProcess* class
+
+    This is the core of your GENERIC process. It describes how to handle the
+    object requested. The data to use is available in `params`.
+
+    **IMPORTANT !!** There is no reference to any files or Database connection.
+
+    **NOTE**: Lorj framework requires you to define a class name composed by the
+    name of the process and 'Process'.
+    Here, it is 'Students' + **'Process'**
+
+
+* We declared the data model and the process handlers with declaration in
+  *Lorj::BaseDefinition* class.
+
+    In short, we declared `:student` object, which needs `:student_name` at
+    creation step.
+    Currently the data model used here is very simple. There is one meta object
+    with some limited attributes, handlers and parameters.
+    The process itself is defined by several functions in StudentsProcess class
+    with one handlers function declared by the data model.
+
+    **NOTE** Implicitely, the framework consider that the object contains at
+    least 2 attributes, :id (should be unique) and :name (string)
+
+  We used the following feature provided by *Lorj::BaseDefinition*:
+  * define_obj         : Declare a meta object, and attach handlers
+  * obj_needs          : Assign some data as parameters.
+
+
+Currently, this model do nothing except printing out.
+
+##typical output
+
+    $ example/students_1/students.rb
+    WARNING: PrcLib.app_defaults is not set. Application defaults won't be loaded.
+    Running creation process for object 'student' = 'Robert Redford'
+    WARNING: 'create_student' has returned no data for object Lorj::Data 'student'!
+
+There is 2 warnings.
+
+* **PrcLib.app_defaults** represents the application name. It is used to keep
+  your application configuration data in ~/.{PrcLib.app_defaults}/ directory.
+  Defining this data in your main, will eliminate this warning.
+* **create_student** function in your process has returned nothing. while lorj
+  is called to create an object, it assumes to get the object data created. Lorj
+  keep those data in a cache. In this example, **create_student** returned nil,
+  and lorj raise a warning about that.
+
+# what next? version 2
+
+Complete the process to have create/query/get and delete capability, with mock controller.
+The mock controller is basically a controller keeping data in memory.
+
+[Details is explained here](../students_2/student_v2_md.html)

data/example/students_1/students.rb

@@ -15,14 +15,20 @@
 #    See the License for the specific language governing permissions and
 #    limitations under the License.
 
+if ENV['BYEBUG']
+  require 'byebug'
+  lib_path = File.expand_path(File.join(app_path, '..', '..', 'lib'))
+  $LOAD_PATH << lib_path
+end
+
 app_path = File.dirname(__FILE__)
 
 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.
+#  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')]

data/example/students_2/process/students.rb

@@ -19,12 +19,12 @@ class StudentsProcess
   def create_student(sObjectType, hParams)
     PrcLib.state(format("Running creation process for object '%s' = '%s'",
                         sObjectType, hParams[:student_name]))
-
+    #  byebug if ENV['BYEBUG'] # rubocop: disable Debugger
     object = controller_create(sObjectType)
-    fail format("Student '%s' not created.",
-                hParams[:student_name]) if object.nil?
-    PrcLib.info(format("'%s': '%s' created with id %s",
-                       sObjectType, hParams[:student_name],  object[:id]))
+    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
 end

data/example/students_2/student_v2.md

@@ -0,0 +1,90 @@
+# Writing student version 2
+
+**NOTE**: following example is available in `examples/students_2/`
+
+lorj comes with a `:mock` controller. This one is really basic. It keeps data in an Hash in MockController class.<br>
+In this example, we add create/get/query/delete capability in the process and use the `:mock` controller to store the data.
+
+## File `process/Students.rb`
+
+Add 3 handlers query_e, get_e and delete_e like this. Add the :mapping case as well.
+
+``` 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
+      :get_e    => :controller_get,   # We use predefined call to the controller get
+      :delete_e => :controller_delete # We use predefined call to the controller delete
+   })
+
+# Note about mapping. This is usually done by the controller. We will see this later.
+obj_needs    :data, :student_name, :for => [:create_e], :mapping => :name
+
+end
+```
+
+Update the handler `create_student`:
+
+``` ruby
+def create_student(sObjectType, hParams)
+    PrcLib.state("Running creation process for object '%s' = '%s'",
+                  sObjectType, hParams[:student_name])
+
+    object = controler.create(sObjectType)
+    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
+```
+
+
+
+## File `students.rb`
+The update your main and add those lines. In the following, we create 3 students, while 2 are duplicated.
+
+``` ruby
+
+  # 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 "%s students found" % students.length
+
+  students.each { | a_student |
+     puts "%s: %s" % [a_student[:id], a_student[:name]]
+  }
+
+  # let's check the get function, who is the ID 2?
+  student = student_core.get(:student, 2)
+
+  puts "The student ID 2 is %s" % student[:name]
+
+```
+
+##typical output:
+
+    $ example/students_2/students.rb
+    WARNING: PrcLib.app_defaults is not set. Application defaults won't be loaded.
+    2 students found
+    0: Robert Redford
+    1: Robert Redford
+    The student ID 2 is Anthony Hopkins
+
+
+Cool! But everything is in memory! We would like to write this in a file.
+Writing our controller, means that the process should not be updated anymore!
+
+Let's move to the most interesting version. Integrate an API example in lorj!
+
+# Next?
+
+[Details is explained here](../students_3/student_v3_md.html)

data/example/students_2/students.rb

@@ -17,7 +17,7 @@
 
 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
@@ -27,19 +27,19 @@ 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.
+#  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')]
 
+#  byebug if ENV['BYEBUG'] # rubocop: disable Debugger
 student_core = Lorj::Core.new(nil, processes, :mock)
-
 # 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_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')
@@ -49,7 +49,7 @@ students = student_core.query(:student,  :name => 'Robert Redford')
 
 puts format('%s students found', students.length)
 
-students.each do | a_student |
+students.each do |a_student|
   puts format('%s: %s', a_student[:id], a_student[:name])
 end
 

data/example/students_3/controller/yaml_students.rb

@@ -14,88 +14,38 @@
 #    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.dirname(__FILE__)
-api_file = File.expand_path(File.join(cur_path, '..', '..',
-                                      'yaml_students', 'yaml_students.rb'))
+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.
 #
-#   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
-
-controller_file = File.expand_path(File.join(cur_path,
-                                             'yaml_students_controller.rb'))
+controller_file = File.join(cur_path, 'yaml_students_code.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
+# - Definition class
+#   This class declare any kind of mapping or additional attributes to consider.
+require File.join(cur_path, 'yaml_students_def.rb')

data/example/students_3/controller/yaml_students_code.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.
+
+# 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)
+
+      # Yaml Student API requires to provide :
+      # student_name, first and last name.
+      # We are splitting student_name to get first and last name.
+      # But we need to ensure to find at least one space.
+      # if not, we will forcelly set to 'first_name unknown'
+      # Currently the Generic Student Process do not take care of
+      # this kind of data structure. In Version 4, we will move this feature
+      # to the process.
+      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

data/example/students_3/controller/yaml_students_def.rb

@@ -0,0 +1,69 @@
+# 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
+
+  # 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.
+  # The example 4 shows those mapping definition.
+end