lorj 0.1.0

data/example/students_4/controller/yaml_students.rb

@@ -0,0 +1,82 @@
+# 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 Mock controller keep the data in memory in hash/Array data.
+
+# 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'))
+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'))
+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
+
+   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 has been expanded. The object name will be built from first and last name
+   define_obj(:student)
+   obj_needs   :CloudObject,              :connection
+
+   set_hdata   :first_name
+   set_hdata   :last_name
+   set_hdata   :course,      :mapping => :training
+
+   get_attr_mapping :course, :training
+
+   # 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_4/controller/yaml_students_controller.rb

@@ -0,0 +1,141 @@
+# 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 Mock controller keep the data in memory in hash/Array data.
+
+# 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)
+
+            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
+   # Used by network process.
+   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(sObjectType, sUniqId, hParams)
+      case sObjectType
+         when :student
+            required?(hParams, :connection)
+
+            list = hParams[:connection].query_student({:id => sUniqId})
+            if list.length == 0
+               nil
+            else
+               list[0]
+            end
+         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::rhGet(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::rhSet(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

data/example/students_4/process/students.rb

@@ -0,0 +1,112 @@
+# Students process
+class StudentsProcess
+   def create_student(sObjectType, hParams)
+      PrcLib::state ("Running creation process for object '%s' = '%s'" % [sObjectType, hParams[:student_name] ])
+
+      aStudentName = hParams[:student_name].split(" ")
+      # config object is a reference to runtime/config data.
+      config[:first_name] = aStudentName[0]
+      config[:last_name] = aStudentName[1]
+
+      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
+
+   def query_student(sObjectType, sQuery, hParams)
+      PrcLib::state ("Running query process for object '%s' with query '%s'" % [sObjectType, sQuery])
+
+      oObjects = controller_query(sObjectType, sQuery)
+      raise "Query error." if oObjects.nil?
+
+      PrcLib::info ("'%s': Queried. %s records found." % [sObjectType, oObjects.length])
+      oObjects
+   end
+
+   def get_student(sObjectType, sId, hParams)
+      PrcLib::state ("Running get process for object '%s' with ID %s" % [sObjectType, sId ])
+
+      oObject = controller_get(sObjectType, sId)
+      PrcLib::debug("No ID %s found." % sId) if oObject.nil?
+
+      oObject
+   end
+
+   def delete_student(sObjectType, hParams)
+      Error "Unable to delete students, if at least one student is not loaded, or query not defined." if not hParams.exist?(:student) and not hParams.exist?(:query)
+
+      # This student deletion process supports 2 modes:
+      # - Delete from a query field (:query hParams)
+      # - Delete the latest loaded student.
+
+      if hParams.exist?(:query)
+         result = Query(sObjectType, hParams[:query])
+         if result.length > 0
+            result.each { | student |
+               puts "Student to remove: %s = %s" % [student[:id], student[:name]]
+               register(student)
+               controller_delete(:student)
+               PrcLib::info ("'%s:%s' student removed" % [student[:id], student[:name]])
+            }
+         end
+      else
+         controller_delete(:student)
+      end
+   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,
+   {
+      :create_e => :create_student, # The function to call in the class Students
+      :query_e  => :query_student,
+      :delete_e => :delete_student,
+      :get_e    => :get_student
+   })
+
+   # All obj_needs will be collected and passed to the process handler as hParams.
+   # Data required to create a student
+   obj_needs   :data,   :student_name,         { :for => [:create_e] }
+
+   # Data optional for any kind of event
+   obj_needs_optional
+   obj_needs   :data,   :query,                { :for => [:delete_e] }
+   obj_needs   :data,   :first_name
+   obj_needs   :data,   :last_name
+   obj_needs   :data,   :course
+
+   # Define Data a student object needs to take care.
+   # The controller should map it if needed (if the value exists)
+   # But it can also add some extra attributes not predefined by the process.
+   # Usually, the process should ignore it.
+   # But if it detect it, the process should be careful with this data
+   # which are really specific to only one controller and may break the controller agnostic capability.
+   def_attribute :course
+   def_attribute :first_name
+   def_attribute :last_name
+   def_attribute :name
+   def_attribute :status
+end
+
+class Lorj::BaseDefinition
+end

data/example/students_4/students.rb

@@ -0,0 +1,103 @@
+#!/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. (0 to 5)
+
+# 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 oConfig[key] = value
+
+oConfig = 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
+# oConfig = Lorj::Account.new('MyAccount')
+
+
+# Initialize the framework
+# Use students process
+hProcesses = [ File.join($APP_PATH, 'process', 'students.rb')]
+# Use yaml_students controller
+sController = File.join($APP_PATH, 'controller', 'yaml_students.rb')
+oStudentCore = Lorj::Core.new( oConfig, hProcesses, sController )
+
+# This kind of connection_string should be part of an Account Data.
+# So, we won't need to set this config.
+# But you can imagine to set at runtime this config as well.
+oConfig[:connection_string] = "/tmp/students.yaml"
+
+# Note that we have commented the next line.
+# oStudentCore.Create(:connection, :connection_string => "/tmp/students.yaml")
+# This call is not required, as the framework has all the information to create
+# the connection, at the first time this connection is required.
+# ie, while starting to create a student.
+
+
+# Set the student name to use
+oConfig[:student_name] = "Robert Redford"
+
+# Ask the framework to create the object student 'Robert Redford'
+puts ANSI.bold("Create 1st student:")
+oStudentCore.Create(:student)
+# The connection is made because creating a student requires
+# the object :connection. (See example/students_4/controller/yaml_students.rb, around line 70)
+
+puts ANSI.bold("Create 2nd student:")
+# Want to create a duplicated student 'Robert Redford'?
+oStudentCore.Create(:student)
+# Because the process ensure that there is no duplicate, this won't create duplicates
+
+# We can set runtime configuration instantly from the Create call
+# The following line :
+puts ANSI.bold("Create 3rd student:")
+oStudentCore.Create(:student, {:student_name => "Anthony Hopkins"})
+# replaced the following :
+# oConfig[:student_name] = "Anthony Hopkins"
+# oStudentCore.Create(:student)
+
+# Let's query students named "Robert Redford"
+puts ANSI.bold("Querying students as 'Robert Redford':")
+oStudents = oStudentCore.Query(:student, { :name => "Robert Redford" } )
+
+puts "%s students found for '%s':" % [oStudents.length, "Robert Redford"]
+
+oStudents.each { | oStudent |
+   puts "%s: %s" % [oStudent[:id], oStudent[:name]]
+}
+
+# let's check the get function, who is the ID 2?
+puts ANSI.bold("Who is student ID 2?")
+oStudent = oStudentCore.Get(:student, 2)
+
+puts "\nThe student ID 2 is %s" % oStudent[:name] unless oStudent.nil?
+puts "\nThe student ID 2 doesn't exist." if oStudent.nil?
+
+puts ANSI.bold("Create mistake")
+oStudentCore.Create(:student, {
+   :student_name => "Anthony Mistake",
+   :course => 'what ever you want!!!'
+})
+
+# The query logic has been implemented directly in the process,
+# so now, any kind of  controller Delete will have the same behavior...
+puts ANSI.bold("Remove mistake")
+hQuery = { :name => "Anthony Mistake"}
+oStudentCore.Delete(:student, :query => hQuery)
+
+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

data/example/yaml_students/students.rb

@@ -0,0 +1,78 @@
+#!/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.
+
+require 'rubygems'
+require 'ansi'
+
+$APP_PATH = File.dirname(__FILE__)
+
+require File.join($APP_PATH, 'yaml_students.rb')
+
+school = YamlSchool.new('/tmp/students.yaml')
+
+puts ANSI.bold("Create 1st student:")
+if school.query_student({:name => "Robert Redford"}).length == 0
+   school.create_student("Robert Redford", {
+      first_name: 'Robert',
+      last_name:  'Redford',
+      training:   'Art Comedy'
+   })
+end
+
+puts ANSI.bold("Create 2nd student:")
+if school.query_student({:name => "Anthony Hopkins"}).length == 0
+   school.create_student("Anthony Hopkins", {
+      first_name: 'Anthony',
+      last_name:  'Hopkins',
+      training:   'Art Drama'
+   })
+end
+
+puts ANSI.bold("Create 3rd student:")
+if school.query_student({:name => "Marilyn Monroe"}).length == 0
+   school.create_student("Marilyn Monroe", {
+      first_name: 'Marilyn',
+      last_name:  'Mistake',
+      training:   'Art Drama'
+   })
+end
+
+puts ANSI.bold("Create mistake")
+oStudent = school.create_student("Anthony Mistake", {
+   first_name: 'Anthony',
+   last_name:  'Mistake',
+   training:   'what ever you want!!!'
+})
+
+puts "Student created: '%s'" % oStudent
+
+puts ANSI.bold("Remove mistake")
+result = school.query_student({:name => "Anthony Mistake"})
+if result.length > 0
+   result.each { | student |
+      puts "Wrong student to remove: %s = %s" % [student[:id], student[:name]]
+      school.delete_student(student[:id])
+   }
+end
+
+
+puts ANSI.bold("List of students for 'Art Drama':")
+puts school.query_student({ :training => "Art Drama"})
+
+puts ANSI.bold("Deleted students:")
+puts school.query_student({ :status => :removed})

data/example/yaml_students/yaml_students.rb

@@ -0,0 +1,115 @@
+# 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.
+
+require 'yaml'
+
+class YamlSchool
+   attr_accessor :sFile
+   attr_accessor :hData
+
+   def initialize(sFile)
+      @hData = { :students => []}
+      @sFile = sFile
+      load_data()
+   end
+
+   def load_data()
+      if File.exists?(@sFile)
+         @hData = YAML.load_file(@sFile)
+         @hData = { :students => []} if not @hData
+         @hData[:students] = [] unless @hData.key?(:students)
+      end
+   end
+
+   def save_data()
+         begin
+            File.open(@sFile, 'w') do |out|
+               YAML.dump(@hData, out)
+            end
+         rescue => e
+            Lorj.error("%s\n%s" % [e.message, e.backtrace.join("\n")])
+            return false
+         end
+      true
+   end
+
+   def create_student(name, fields)
+
+      if fields[ :first_name].nil? or fields[ :last_name].nil?
+         puts "YAML API: Unable to create a student. :first_name and :last_name required."
+         return nil
+      end
+
+      result = fields.clone
+      result[:name] = name
+      result[:name] = "%s %s" % [result[:first_name], result[:first_name]] if name.nil?
+      result[:status] = :active
+
+      @hData[:students] << result
+
+      result[:id] = @hData[:students].length()-1
+
+      save_data()
+      result
+   end
+
+   def delete_student(sId)
+      return false unless File.exists?(sFile)
+
+      @hData[:students].each { | value |
+         hElem = value
+         if value[:id] == sId
+            @hData[:students][sId][:status] = :removed
+            save_data()
+            return 1
+         end
+      }
+      0
+   end
+
+   def query_student(sQuery)
+
+      result = []
+
+      @hData[:students].each { | value |
+         hElem = value
+         sQuery.each { | query_key, query_value |
+            hElem = nil if (
+               value.key?(:status) and
+               value[:status] != :active and
+               not sQuery.key?(:status)) or
+               not value.key?(query_key) or
+               value[query_key] != query_value
+         }
+         result << hElem if hElem
+      }
+      result
+
+   end
+
+   def update_student(sId, fields)
+      aList = query_student({ :id => Id})
+      if aList.length == 1
+         aList[0].merge(fields)
+      end
+      save_data()
+   end
+
+end