lorj 0.1.0

data/lib/core/lorj-data.rb

@@ -0,0 +1,567 @@
+# (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.
+
+# Module Lorj which contains several classes.
+#
+# Those classes describes :
+# - processes (BaseProcess)   : How to create/delete/edit/query object.
+# - controler (BaseControler) : If a provider is defined, define how will do object creation/etc...
+# - definition(BaseDefinition): Functions to declare objects, query/data mapping and setup
+# this task to make it to work.
+module Lorj
+   # This class is the Data object used by lorj object!
+   # This is a key component of lorj
+   #
+   # You find this object in different places.
+   #
+   # type:
+   # - object/data : The Data object contains any kind of data.
+   #   This data contains 2 elements:
+   #   - controler object : This is a ruby object managed by the controller.
+   #     Only the controller has the knowledge to manage this kind of data.
+   #   - attributes       : This is the internal data mapping from the controller object.
+   #     The controller helped to build this data thanks to the BaseController.get_attr / BaseController.set_attr
+   #     Attributes are declared by the Data model in BaseDefinition. At least usually, each object has 2 attributes: :id and :name
+   #
+   # - list        : The Data object contains a list of Lorj::Data
+   #
+   # If the object is of type :list, following functions are usable:
+   #
+   # - length                : return numbers of Lorj::Data
+   # - each / each_index     : loop on the list, key/value or key_index. yield can return 'remove' to remove the element from the list during loop.
+   #
+   # If the Data object is of type :data or :object or even :list, following functions are usable.
+   #
+   # - set/[]=/get/[]/exist? : Basic get/set/exist? feature.
+   # - type?/object_type?    : Determine the type of this object. ie :data (stands for :object as well) or :list
+   # - to_a                  : Array of Data attributes
+   # - empty? nil?           : Identify if the object is empty. Avoid to use nil?.
+   # - register/unregister   : Used by Lorj::BaseDefinition internal @ObjectData.
+   #   registered?           : Determine if this object is stored in the global object cache.
+
+   class Lorj::Data
+
+      # Initialize Lorj::Data object
+      #
+      # * *Args* :
+      #   - +oType+ : default is :object
+      #     Support :data/:object for single object data
+      #             :list for a list of object data
+      #
+      # * *Returns* :
+      #   hash - internal data object.
+      #
+      # * *Raises* :
+      #   No exceptions
+      #
+      def initialize(oType = :object)
+         oType = :data if not [:list, :object, :data].include?(oType)
+         @oType = oType
+         case oType
+            when :data, :object
+               @data = new_object
+            when :list
+               @data = new_object_list
+         end
+      end
+
+      # Return Lorj::Data object type
+      #
+      # * *Args* :
+      #   Nothing
+      #
+      # * *Returns* :
+      #   - +type+ : Symbol or nil
+      #      nil if no object.
+      #      :object for single object data
+      #      :list for a list of object data
+      #
+      # * *Raises* :
+      #   No exceptions
+      #
+      def type?()
+         @oType
+      end
+
+      # Return :object type of the Lorj::Data object.
+      #
+      # * *Args* :
+      #   Nothing
+      #
+      # * *Returns* :
+      #   - +type+ : Symbol or nil
+      #      nil if no object.
+      #      :object type
+      #
+      # * *Raises* :
+      #   No exceptions
+      #
+      def object_type?()
+         @data[:object_type]
+      end
+
+      # Set a Lorj::Data object and return itself.
+      #
+      # There 3 usages:
+      # - Set from a Lorj::Data.
+      #   ex: if data is already a Lorj::Data,
+      #      copy = Lorj::Data.new()
+      #      copy.set(data)
+      # - Set from an object, not Lorj::Data and not a list.
+      #   ex:
+      #      data = { :test => 'toto'}
+      #      copy = Lorj::Data.new()
+      #      copy.set(data, :object) { |oObject |
+      #         oObject
+      #      }
+      # - Set from a list of objects, not Lorj::Data and not a :object.
+      #   ex:
+      #      data = [{ :name => 'toto'}, {:name => 'test'}]
+      #      copy = Lorj::Data.new()
+      #      copy.set(data, :list, { :name => /^t/ }) { |oObject |
+      #         oObject
+      #      }
+      #
+      # * *Args* :
+      #   - +data+  : Lorj::Data or any other data.
+      #   - +ObjType: required only if data is not a Lorj::Data
+      #     Use :object to store and extract attributes
+      #     Use :list to extract elements, store them and extract attributes for each of them. data must support each(oObject) loop function
+      #   - +Query+ : Optional. To store the query object used to get the list objects. It assumes ObjectType = :list
+      #   - +yield+ : code to extract +data+ attributes from the object (:object or :list). Should return an hash containing attributes data.
+      #
+      # * *Returns* :
+      #   - +self+ : Lorj::Data
+      #
+      # * *Raises* :
+      #   No exceptions
+      #
+      def set(oObj, sObjType = nil, hQuery = {})
+         if oObj.is_a?(Lorj::Data)
+            oType = oObj.type?
+            case oType
+               when :data, :object
+                  @data[:object_type] = ((sObjType.nil?)? (oObj.object_type?) : sObjType)
+                  @data[:object] = oObj.get(:object)
+                  @data[:attrs] = oObj.get(:attrs)
+               when :list
+                  @data[:object_type] = ((sObjType.nil?)? (oObj.object_type?) : sObjType)
+                  @data[:object] = oObj.get(:object)
+                  @data[:list] = oObj.get(:list)
+                  @data[:query] = oObj.get(:query)
+            end
+            return self
+         end
+
+         # while saving the object, a mapping work is done?
+         case @oType
+            when :data, :object
+               @data[:object_type] = sObjType
+               @data[:object] = oObj
+               @data[:attrs] = yield(sObjType, oObj)
+            when :list
+               @data[:object] = oObj
+               @data[:object_type] = sObjType
+               @data[:query] = hQuery
+               unless oObj.nil?
+                  begin
+                     oObj.each { | oObject |
+                        next if oObject.nil?
+                        begin
+                           oDataObject = Lorj::Data.new(:object)
+
+                           oDataObject.set(oObject, sObjType) { |sObjectType, oObject|
+                              yield(sObjectType, oObject)
+                           }
+                           @data[:list] << oDataObject
+                        rescue => e
+                           raise Lorj::PrcError.new(), "'%s' Mapping attributes issue.\n%s" % [sObjType, e.message]
+                        end
+                     }
+                  rescue => e
+                     raise Lorj::PrcError.new(), "each function is not supported by '%s'.\n%s" % [oObj.class, e.message]
+                  end
+               end
+         end
+         self
+      end
+
+      # Set the :object type
+      #
+      # * *Args* :
+      #   - +ObjType: required only if data is not a Lorj::Data
+      #
+      # * *Returns* :
+      #   - +self+ : Lorj::Data
+      #
+      # * *Raises* :
+      #   No exceptions
+      #
+      def type=(sObjType)
+         return self if self.empty?
+         @data[:object_type] = sObjType
+         self
+      end
+
+      # Get value from Lorj::data
+      #
+      # * *Args* :
+      #   - +keys+: See get function.
+      #
+      # * *Returns* :
+      #   - +self+ : Lorj::Data
+      #
+      # * *Raises* :
+      #   No exceptions
+      #
+      def [](*key)
+         get(*key)
+      end
+
+      # Set Lorj::data attribute value for an :object
+      #
+      # * *Args* :
+      #   - +keys+ : attribute keys
+      #   - +value+: Value to set
+      #
+      # * *Returns* :
+      #   true
+      #
+      # * *Raises* :
+      #   No exceptions
+      #
+      def []=(*key, value)
+         return false if @oType == :list
+         Lorj::rhSet(@data, value, :attrs, key)
+         true
+      end
+
+      # Get value from Lorj::data
+      # Depending on Lorj::Data type, you can get:
+      # - :object
+      #   - get internal object data (:object)
+      #     ex: object = data[:object]
+      #   - get attribute data
+      #     ex:
+      #      data = { :name => 'toto'}
+      #      copy = Lorj::Data.new()
+      #      copy.set(data, :object) { |oObject |
+      #         {:real_name => oObject[:name]}
+      #      }
+      #
+      #      puts copy[:name]      # => nil
+      #      puts copy[:real_name] # => 'toto'
+      #      puts copy[:object]    # => { :name => 'toto'}
+      #      puts copy[:attrs]     # => { :real_name => 'toto'}
+      # - :list
+      #   - get internal object data (:object)
+      #     ex: object = data[:object]
+      #   - get stored query object data (:query)
+      #     ex: object = data[:query]
+      #   - get one element attribute or object data
+      #     ex:
+      #      data = [{ :name => 'toto'}, {:name => 'test'}]
+      #      copy = Lorj::Data.new()
+      #      copy.set(data, :list, { :name => /^t/ }) { |oObject |
+      #         {:real_name => oObject[:name]}
+      #      }
+      #
+      #      puts copy[0]             # => { :real_name => 'toto'}
+      #      puts copy[0][:object]    # => { :name => 'toto'}
+      #      puts copy[0][:attrs]     # => { :real_name => 'toto'}
+      #      puts copy[1]             # => { :real_name => 'test'}
+      #      puts copy[1, :real_name] # => 'test'
+      #      puts copy[1, :test]      # => nil
+      #
+      # * *Args* :
+      #   - +keys+: See get function.
+      #
+      # * *Returns* :
+      #   - +self+ : Lorj::Data
+      #
+      # * *Raises* :
+      #   No exceptions
+      #
+      def get(*key)
+         return @data if key.length == 0
+         case @oType
+            when :data, :object # Return only attrs or the real object.
+               return @data[key[0]] if key[0] == :object
+               return Lorj::rhGet(@data, key) if key[0] == :attrs
+               Lorj::rhGet(@data, :attrs, key)
+            when :list
+               return @data[key[0]] if [:object, :query].include?(key[0])
+               return @data[:list][key[0]] if key.length == 1
+               @data[:list][key[0]][key[1..-1]] # can Return only attrs or the real object.
+         end
+      end
+
+      # Get the list of elements in an array from Lorj::Data :list type.
+      #
+      # * *Args* :
+      #   No parameters
+      #
+      # * *Returns* :
+      #   - +Elements+ : Array of elements
+      #
+      # * *Raises* :
+      #   No exceptions
+      #
+      def to_a()
+         result = []
+         self.each { |elem|
+            result<< elem[:attrs]
+         }
+         result
+      end
+
+      # return true if a data object exist or if an extracted attribute exist.
+      #
+      # * *Args* :
+      #   - +keys+ : Keys to verify.
+      #
+      # * *Returns* :
+      #   - +exist?+ : true or false.
+      #
+      # * *Raises* :
+      #   No exceptions
+      #
+      # Examples:
+      #      data = Lorj::Data.new()
+      #
+      #      puts data.exist?(:object)          # => false
+      #
+      #      data.set({ :name => 'toto'}, :object) { |oObject |
+      #         {:real_name => oObject[:name]}
+      #      }
+      #      list = Lorj::Data.new()
+      #
+      #      puts data.exist?(:object)          # => false
+      #
+      #      list.set([{ :name => 'toto'}, {:name => 'test'}], :list) { |oObject |
+      #         {:real_name => oObject[:name]}
+      #      }
+      #
+      #       puts data.exist?(:object)         # => true
+      #       puts data.exist?(:name)           # => true
+      #       puts data.exist?(:test)           # => false
+      #       puts data.exist?(:attrs, :name)   # => true
+      #       puts list.exist?(0)               # => true
+      #       puts list.exist?(0, :object)      # => true
+      #       puts list.exist?(2)               # => false
+      #       puts list.exist?(2, :object)      # => false
+      #       puts list.exist?(0, :name)        # => true
+      #       puts list.exist?(0, :test)        # => false
+      def exist?(*key)
+         case @oType
+            when :data, :object
+               return true if key[0] == :object and @data.key?(key[0])
+               return true  if key[0] == :attrs and Lorj::rhExist?(@data, key)
+               (Lorj::rhExist?(@data, :attrs, key) == key.length+1)
+            when :list
+               return true if key[0] == :object and @data.key?(key[0])
+               (Lorj::rhExist?(@data[:list][key[0]], :attrs, key[1..-1]) == key.length)
+         end
+      end
+
+      # return true if the Lorj::Data object is nil.
+      #
+      # * *Args* :
+      #   No parameters
+      #
+      # * *Returns* :
+      #   - true/false
+      #
+      # * *Raises* :
+      #   No exceptions
+      #
+      def empty?()
+         @data[:object].nil?
+      end
+
+      # Redefine nil? Warning! Can be confused. Cannot see if your object is simply nil or if current object is simply empty.
+      # Use empty? instead.
+      # A warning will be raised soon to ask developer to update it.
+      #
+      # * *Args* :
+      #   No parameters
+      #
+      # * *Returns* :
+      #   - true/false
+      #
+      # * *Raises* :
+      #   No exceptions
+      #
+      def nil?()
+         # Obsolete Use empty? instead.
+         @data[:object].nil?
+      end
+
+      # return 0, 1 or N if the Lorj::Data object is nil.
+      # 0 if no objects stored
+      # 1 if an object exist even if type :object or :list
+      # >1 if a list is stored. It will give the number of elements in the list.
+      #
+      # * *Args* :
+      #   No parameters
+      #
+      # * *Returns* :
+      #   - >=0 : Number of elements
+      #
+      # * *Raises* :
+      #   No exceptions
+      #
+      def length()
+         case @oType
+            when :data
+               return 0 if self.empty?
+               1
+            when :list
+               @data[:list].length
+         end
+      end
+
+      # yield loop on a list
+      #
+      # * *Args* :
+      #   - +yield+ : sAction = yield (elem), where action can :removed to remove the element from the list.
+      #
+      # * *Returns* :
+      #   no values
+      #
+      # * *Raises* :
+      #   No exceptions
+      #
+      def each(sData = :list)
+         to_remove = []
+         return nil if @oType != :list or not [:object, :list].include?(sData)
+
+         @data[:list].each { |elem|
+            sAction = yield (elem)
+            case sAction
+               when :remove
+                  to_remove << elem
+            end
+         }
+         if to_remove.length > 0
+            to_remove.each { | elem |
+               @data[:list].delete(elem)
+            }
+         end
+      end
+
+      # yield loop on a list
+      #
+      # * *Args* :
+      #   - +yield+ : sAction = yield (index), where action can :removed to remove the element from the list.
+      #
+      # * *Returns* :
+      #   no values
+      #
+      # * *Raises* :
+      #   No exceptions
+      #
+      def each_index(sData = :list)
+         to_remove = []
+         return nil if @oType != :list or not [:object, :list].include?(sData)
+
+         @data[:list].each_index { |iIndex|
+            sAction = yield (iIndex)
+            case sAction
+               when :remove
+                  to_remove << @data[:list][iIndex]
+            end
+         }
+         if to_remove.length > 0
+            to_remove.each { | elem |
+               @data[:list].delete(elem)
+            }
+         end
+      end
+
+      # A Lorj::Data can be cached by Lorj::ObjectData.
+      # When adding Lorj::Data to Lorj::ObjectData, Lorj::Data object will be registered.
+      # This function will determine if this object is registered or not.
+      #
+      # * *Args* :
+      #     none
+      #
+      # * *Returns* :
+      #   - registered : true or false if registered or not
+      #
+      # * *Raises* :
+      #   No exceptions
+      #
+      def registered?()
+         @bRegister
+      end
+
+      # A Lorj::Data can be cached by Lorj::ObjectData.
+      # When adding Lorj::Data to Lorj::ObjectData, Lorj::Data object will be registered.
+      # Lorj::ObjectData will call this function to marked it as registered.
+      #
+      # * *Args* :
+      #     none
+      #
+      # * *Returns* :
+      #   - self
+      #
+      # * *Raises* :
+      #   No exceptions
+      #
+      def register()
+         @bRegister = true
+         self
+      end
+
+      # A Lorj::Data can be cached by Lorj::ObjectData.
+      # When adding Lorj::Data to Lorj::ObjectData, Lorj::Data object will be registered.
+      # Lorj::ObjectData will call this function to marked it as unregistered.
+      #
+      # * *Args* :
+      #     none
+      #
+      # * *Returns* :
+      #   - self
+      #
+      # * *Raises* :
+      #   No exceptions
+      #
+      def unregister()
+         @bRegister = false
+         self
+      end
+      private
+
+      # Define minimal @data structure for a :list object type.
+      def new_object_list
+         {
+            :object        => nil,
+            :object_type   => nil,
+            :list          => [],
+            :query         => nil
+         }
+      end
+
+      # Define minimal @data structure for a :object object type.
+      def new_object
+         oCoreObject = {
+            :object_type => nil,
+            :attrs => {},
+            :object => nil,
+         }
+      end
+
+   end
+end

data/lib/core/lorj-keypath.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.
+
+# Module Lorj which contains several classes.
+#
+# Those classes describes :
+# - processes (BaseProcess)   : How to create/delete/edit/query object.
+# - controler (BaseControler) : If a provider is defined, define how will do object creation/etc...
+# - definition(BaseDefinition): Functions to declare objects, query/data mapping and setup
+# this task to make it to work.
+
+module Lorj
+
+   # Class to handle key or keypath on needs
+   # The application configuration can configure a key tree, instead of a key.
+   # KeyPath is used to commonly handle key or key tree.
+   # Thus, a Keypath can be converted in different format:
+   #
+   # Ex:
+   # oKey = KeyPath(:test)
+   # puts oKey.to_s      # => 'test'
+   # puts oKey.sKey      # => :test
+   # puts oKey.sKey[0]   # => :test
+   # puts oKey.sKey[1]   # => nil
+   # puts oKey.sFullPath # => ':test'
+   #  puts oKey.aTree    # => [:test]
+   #
+   # oKey = KeyPath([:test,:test2,:test3])
+   # puts oKey.to_s      # => 'test/test2/test3'
+   # puts oKey.sKey      # => :test3
+   # puts oKey.sKey[0]   # => :test
+   # puts oKey.sKey[1]   # => :test2
+   # puts oKey.sFullPath # => ':test/:test2/:ẗest3'
+   # puts oKey.aTree     # => [:test,:test2,:test3]
+   #
+   class KeyPath
+
+      def initialize(sKeyPath = nil)
+
+         @keypath = []
+         self.set sKeyPath
+      end
+
+      def key=(sKeyPath)
+         self.set(sKeyPath)
+      end
+
+      def set(sKeyPath)
+
+         if sKeyPath.is_a?(Symbol)
+            @keypath = [ sKeyPath]
+         elsif sKeyPath.is_a?(Array)
+            @keypath = sKeyPath
+         elsif sKeyPath.is_a?(String)
+            if /[^\\\/]?\/[^\/]/ =~ sKeyPath or /:[^:\/]/ =~ sKeyPath
+               # keypath to interpret
+               aResult = sKeyPath.split('/')
+               aResult.each_index { | iIndex |
+                  next if not aResult[iIndex].is_a?(String)
+                  aResult[iIndex] = aResult[iIndex][1..-1].to_sym if aResult[iIndex][0] == ":"
+               }
+               @keypath = aResult
+            else
+               @keypath = [sKeyPath]
+            end
+         end
+      end
+
+      def aTree()
+         @keypath
+      end
+
+      def sFullPath()
+         return nil if @keypath.length == 0
+         aKeyAccess = @keypath.clone
+         aKeyAccess.each_index { |iIndex|
+            next if not aKeyAccess[iIndex].is_a?(Symbol)
+            aKeyAccess[iIndex] = ":" + aKeyAccess[iIndex].to_s
+         }
+         aKeyAccess.join('/')
+      end
+
+      def to_s
+         return nil if @keypath.length == 0
+         aKeyAccess = @keypath.clone
+         aKeyAccess.each_index { |iIndex|
+            next if not aKeyAccess[iIndex].is_a?(Symbol)
+            aKeyAccess[iIndex] = aKeyAccess[iIndex].to_s
+         }
+         aKeyAccess.join('/')
+      end
+
+      def sKey(iIndex = -1)
+         return nil if @keypath.length == 0
+         @keypath[iIndex] if self.length >= 1
+      end
+
+      def length()
+         @keypath.length
+      end
+   end
+end