lorj 0.2.0 → 1.0.0

data/lib/core/core_model.rb

@@ -0,0 +1,328 @@
+# 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.
+
+# rubocop: disable Metrics/AbcSize
+
+# TODO: Move most declaration functions to Model class for simplification.
+
+# 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
+  # Model Object
+  class Model
+    attr_accessor :meta_obj, :meta_data, :meta_predefined_values
+    attr_accessor :query_auto_map
+
+    # Model initialisation
+    def initialize
+      ###################################################
+      # Class management Section
+      ###################################################
+
+      # Meta Object declaration structure
+      # <Object>
+      #   :query_mapping        List of keypath mapped.
+      #     <keypath> = <keypath mapped>
+      #   :lambdas:
+      #     :create_e:          function to call at 'Create' task
+      #     :delete_e:          function to call at 'Delete' task
+      #     :update_e:          function to call at 'Update' task
+      #     :get_e:             function to call at 'Get'    task
+      #     :query_e:           function to call at 'Query'  task
+      #   :value_mapping:       Define list of Object's key values mapping.
+      #     <keypath>           key value mapping lists
+      #       <value> = <map>   Define the value mapping.
+      #   :returns
+      #     <keypath>           key value to extract from controller object.
+      #   :params:              Defines CloudData (:data) or object (:CloudObj)
+      #                         needs by the <Object>
+      #     :keys:              Contains keys in a tree of hash.
+      #       <keypath>:        String. One element (string with : and /) of
+      #                         :list defining the key
+      #         :type:          :data or :CloudObj
+      #         :for:           Array of events which requires the data or
+      #                         CloudObj to work.
+      #         :mapping:       To automatically create a provider hash data
+      #                         mapped (hdata).
+      #         :required:      True if this parameter is required.
+      #         :extract_from:  Array. Build the keypath value from another
+      #                         params value.
+      #                         Ex: This example will extract :id from
+      #                             :security_groups object
+      #                             :extract_from => [:security_groups, :id]
+      #
+      @meta_obj =  {}
+
+      # meta data are defined in defaults.yaml and loaded in Lorj::Default class
+      # definition.
+      # Cloud provider can redefine ForjData defaults and add some extra
+      # parameters.
+      # To get Application defaults, read defaults.yaml, under :sections:
+      # Those values can be updated by the controller with define_data
+      # <Section>:
+      #   <Data>:               Required. Symbol/String. default: nil
+      #                         => Data name. This symbol must be unique, across
+      #                            sections.
+      #     :desc:              Required. String. default: nil
+      #                         => Description
+      #     :explanation:  |-   Print a multiline explanation before ask the key
+      #                         value.
+      #                         ERB template enable. To get config data,
+      #                         type <%= config[...] %>
+      #     :readonly:          Optional. true/false. Default: false
+      #                         => oForjConfig.set() will fail if readonly is
+      #                            true. It can be set, only thanks to:
+      #                            - oForjConfig.setup()
+      #                              or using private
+      #                            - oForjConfig._set()
+      #     :account_exclusive: Optional. true/false. Default: false
+      #                         => Only oConfig.account_get/set() can handle the
+      #                            value
+      #                            oConfig.set/get cannot.
+      #     :account:           Optional. default: False
+      #                         => setup will configure the account with this
+      #                           <Data>
+      #     :ask_sort:          Number which represents the ask order in the
+      #                         step group. (See /:setup/:ask_step for details)
+      #     :after:  <Data>     Name of the previous <Data> to ask before the
+      #                         current one.
+      #     :depends_on:
+      #                         => Identify :data type required to be set before
+      #                            the current one.
+      #     :default_value:     Default value at setup time. This is not
+      #                         necessarily the Application default value
+      #                         (See /:default)
+      #     :validate:          Regular expression to validate end user input
+      #                         during setup.
+      #     :value_mapping:     list of values to map as defined by the
+      #                         controller
+      #       :controller:      mapping for get controller value from process
+      #                         values
+      #         <value> : <map> value map equivalence. See data_value_mapping
+      #                         function
+      #       :process:         mapping for get process value from controller
+      #                         values
+      #         <value> : <map> value map equivalence. See data_value_mapping
+      #                         function
+      #     :default:           Default value. Replace /:default/<data>
+      #     :list_values:       Defines a list of valid values for the current
+      #                         data.
+      #       :query_type       :controller_call to execute a function defined
+      #                         in the controller object.
+      #                         :process_call to execute a function defined in
+      #                         the process object.
+      #                         :values to get list of values from :values.
+      #       :object           Object to load before calling the function.
+      #                           Only :query_type = :*_call
+      #       :query_call       Symbol. function name to call.
+      #                           Only :query_type = :*_call
+      #                         function must return an Array.
+      #       :query_params     Hash. Controler function parameters.
+      #                           Only :query_type = :*_call
+      #       :validate         :list_strict. valid only if value is one of
+      #                          thoselisted.
+      #       :values:          to retrieve from.
+      #                         otherwise define simply a list of possible
+      #                         values.
+      #       :ask_step:        Step number. By default, setup will determine
+      #                         the step, thanks to meta lorj object
+      #                         dependencies tree.
+      #                         This number start at 0. Each step can be defined
+      #                         by /:setup/:ask_step/<steps> list.
+      #     :pre_step_function: Process called before asking the data.
+      #                         if it returns true, user interaction is
+      #                         cancelled.
+      #     :post_step_function:Process called after asking the data.
+      #                         if it returns false, the user is requested to
+      #                         re-enter a new value.
+      #
+      # :setup:                  This section describes group of fields to ask,
+      #                          step by step.
+      #     :ask_step:           Define an Array of setup steps to ask to the
+      #                          end user. The step order is respected, and
+      #                          start at 0
+      #     -  :desc:            Define the step description. ERB template
+      #                          enable. To get config data, type config[...]
+      #        :explanation:  |- Define a multiline explanation. This is printed
+      #                          out in brown color.
+      #                          ERB template enable. To get config data, type
+      #                          <%= config[...] %>
+      #        :add:             Define a list of additionnal fields to ask.
+      #        - <Data>          Data to ask.
+      #
+      # :default:                List of <Data> application default values.
+      #     <Data> :             Value to use at the config application level.
+      @meta_data = {}
+
+      # The Generic Process can pre-define some data and value
+      # (function predefine_data)
+      # The Generic Process (and external framework call) only knows about
+      # Generic data.
+      # information used:
+      #
+      @meta_predefined_values = {}
+
+      # <Data>:                  Data name
+      #   :values:               List of possible values
+      #      <Value>:            Value Name attached to the data
+      #        options:          Options
+      #          :desc:          Description of that predefine value.
+
+      @context = {
+        :oCurrentObj => nil,    # Defines the Current Object to manipulate
+        :needs_optional => nil, # set optional to true for any next needs
+        # declaration
+        :ClassProcess => nil,   # Current Process Class declaration
+        :oCurrentData => nil,   # Current data model declaration
+        :oCurrentObj => nil,    # Current object declaration
+        :oCurrentKey => nil     # Current attribute declaration
+      }
+
+      # Available functions for:
+      # - BaseDefinition class declaration
+      # - Controler (derived from BaseDefinition) class declaration
+
+      @query_auto_map = false
+
+      # Model options
+      @options = {}
+    end
+
+    # Model options (get/set)
+    # Uses Hash merge to set model options.
+    def options(options = nil)
+      @options.merge!(options) unless options.nil?
+      @options
+    end
+
+    def [](option)
+      return nil if option.nil?
+      @options[option] if @options.key?(option)
+    end
+
+    def []=(option, value)
+      return nil if option.nil?
+      @options[option] = value
+    end
+
+    # Current Attribute identifier
+    #
+    # parameters: (Hash)
+    # - +option+     : optional. KeyPath or a string.
+    #   - if option is a KeyPath, save the keypath.
+    #   - if option is a Symbol, consider it as function_name for error report.
+    #
+    # return:
+    # - string : KeyPath attribute
+    def attribute_context(options = nil)
+      function_name = nil
+      function_name = options.to_s if options.is_a?(Symbol)
+      @context[:oCurrentKey] = options if options.is_a?(KeyPath)
+
+      msg = ''
+      msg += '-' + function_name unless function_name.nil?
+      msg += ': No model object attribute context defined. '\
+             'Missing attr_mapping or obj_needs?'
+
+      PrcLib.dcl_fail('%s%s', self.class, msg) if @context[:oCurrentKey].nil?
+
+      @context[:oCurrentKey]
+    end
+
+    # Internal Current Data identifier
+    #
+    # parameters: (Hash)
+    # - +:data+     : optional. Data name to keep in context.
+    #
+    # return:
+    # - string : Data name
+    def data_context(data = nil)
+      @context[:oCurrentData] = data unless data.nil?
+
+      data = @context[:oCurrentData]
+
+      PrcLib.dcl_fail('Config data context not set. at least, you '\
+                      'need to call define_data before.') if data.nil?
+
+      data
+    end
+
+    # Internal Current Process identifier
+    # parameters: (Hash)
+    # - +:process+        : optional. Process name to keep in context.
+    # return:
+    # - string : Process name
+    def process_context(process = nil)
+      @context[:ClassProcess] = process unless process.nil?
+      process = @context[:ClassProcess]
+
+      _lorj_dcl_error('Config process context not set. at least, you '\
+                      'need to call define_data before.') if process.nil?
+
+      process
+    end
+
+    def needs_optional(value = nil)
+      @context[:needs_optional] = value unless value.nil? || !value.boolean?
+      @context[:needs_optional]
+    end
+
+    def needs_setup(value = nil)
+      @context[:needs_setup] = value unless value.nil? || !value.boolean?
+      @context[:needs_setup]
+    end
+
+    # Object Context identifier (get/set)
+    # parameters: (Hash)
+    # - +:object+        : optional. Object to keep in context.
+    # - +:function_name+ : optional. Symbol. Call function name for error report
+    # return:
+    # - string : Object name
+    def object_context(options = nil)
+      if options.is_a?(Hash) && options.key?(:object)
+        @context[:oCurrentObj] = options[:object]
+        needs_optional false
+        needs_setup false
+      end
+
+      msg = ''
+      if options.rh_exist?(:function_name) &&
+         options[:function_name].is_a?(Symbol)
+        msg += '-' + options[:function_name].to_s
+      end
+      msg += ': No model object context defined. Missing define_obj?'
+
+      PrcLib.dcl_fail('%s%s', self.class, msg) if @context[:oCurrentObj].nil?
+      @context[:oCurrentObj]
+    end
+
+    def heap(value = nil)
+      @context[:heap] = caller[1..-1] if value.is_a?(TrueClass)
+      @context[:heap]
+    end
+
+    def clear_heap
+      @context[:heap] = nil
+    end
+  end
+end

data/lib/core/core_object_data.rb

@@ -0,0 +1,330 @@
+# 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.
+
+# rubocop: disable Metrics/AbcSize
+
+# 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
+  # Represents a list of key/value pairs
+  # if the value is a Lorj::Data(data or list), the key will be the Lorj::Data
+  # type.
+  #
+  # This class is used in 3 different contexts:
+  # - Process context:
+  #   create/query/update/delete/get handler uses it to build the handler
+  #   parameters and is passed to each process handler as 2nd parameter.
+  #   ex: If a connection object is created as follow:
+  #     define_obj(:connection,
+  #                :create_e => :connection_create)
+  #     obj_needs(:data, :uri)
+  #
+  #       then at runtime:
+  #     lorj_object.create(:connection, :uri => 'http://example.org')
+  #       will call 'connection_create' (params)
+  #     def connection_creat(object_type, params)
+  #       where object_type is ':connection' and
+  #       params is a 'Lorj::ObjectData' containing :uri value.
+  #
+  #   The object behavior is adapted to the process usage.
+  #   By default for Lorj::Data(:object), params[aKey] will get or set object
+  #   attributes.
+  #   ex: params[:uri]  # => 'http://example.org'
+  #       params[:test] # => nil
+  #
+  # - Controller context:
+  #   create/query/update/delete/get handler uses it to build controller
+  #   parameters like hdata.
+  #   The object behavior is adapted to the controller usage
+  #   By default for Lorj::Data(:object), hParams[aKey] will get or set
+  #   controller object
+  #
+  # - Internally by BaseDefinition.  to get a Lorj::Data cache.
+  #
+  class ObjectData
+    # Initialize the object. By default, usage is for controller context.
+    #
+    # * *Args* :
+    #   - +internal+    : Context
+    #     - true if process context
+    #     - false if controller context. This is the default value.
+    #
+    # * *Returns* :
+    #   - nothing
+    #
+    # * *Raises* :
+    #   No exceptions
+    def initialize(internal = false)
+      @params = {}
+      @params[:hdata] = {} unless internal
+      @internal = internal
+    end
+
+    # Get function
+    #
+    # key can be an array, a string (converted to a symbol) or a symbol.
+    #
+    # * *Args*    :
+    #   - +key+   : key tree (list of keys)
+    #     If key[1] == :attrs, get will forcelly use the Lorj::Data object
+    #     attributes
+    #     If key[1] == :ObjectData, get will forcelly return the controller
+    #     object
+    #     otherwise, get will depends on the context:
+    #     - controller context: will return the controller object
+    #     - Process context: will return the Lorj::Data object attributes
+    # * *Returns* :
+    #   value found or nil.
+    # * *Raises* :
+    #   nothing
+    def [](*key)
+      key = key.flatten
+
+      return @params if key.length == 0
+
+      object = @params.rh_get(key[0])
+
+      # Return ObjectData, attributes if asked. or depends on context.
+      value = object_data_get(object, key)
+      # otherwise, simply return what is found in keys hierarchy.
+      value = @params.rh_get(key) if value.nil?
+
+      value
+    end
+
+    # Functions used to set simple data/Object for controller/process function
+    # call.
+    # TODO: to revisit this function, as we may consider simple data, as
+    # Lorj::Data object
+    def []=(*key, value)
+      return nil if [:object, :query].include?(key[0])
+      @params.rh_set(value, key)
+    end
+
+    # Add function. Add a Lorj::Data (data or list) to the ObjectData list.
+    #
+    # key can be an array, a string (converted to a symbol) or a symbol.
+    #
+    # * *Args*    :
+    #   - +oDataObject+ : Lorj::Data object
+    # * *Returns* :
+    #   Nothing
+    # * *Raises* :
+    #   nothing
+    def add(oDataObject)
+      # Requires to be a valid framework object.
+      fail Lorj::PrcError.new,
+           format("Invalid Framework object type '%s'.",
+                  oDataObject.class) unless oDataObject.is_a?(Lorj::Data)
+
+      object_data_add(oDataObject)
+      oDataObject.register
+    end
+
+    # delete function. delete a Lorj::Data (data or list) from the ObjectData
+    # cache.
+    #
+    # * *Args*    :
+    #   - +object+ : Lorj::Data or Symbol representing a Lorj::Data cached.
+    # * *Returns* :
+    #   Nothing
+    # * *Raises* :
+    #   nothing
+    def delete(obj)
+      if obj.is_a?(Symbol)
+        object_type = obj
+        obj = @params[object_type]
+        @params[object_type] = nil
+      else
+        object_data_delete(obj)
+      end
+      obj.unregister unless obj.nil?
+    end
+
+    # Merge 2 ObjectData.
+    #
+    # * *Args*    :
+    #   - +hHash+ : Hash of Lorj::Data. But it is possible to have different
+    #               object type (not Lorj::Data)
+    # * *Returns* :
+    #   hash merged
+    # * *Raises* :
+    #   nothing
+    def <<(hHash)
+      @params.merge!(hHash) unless hHash.nil?
+    end
+
+    # check Lorj::Data attributes or object exists. Or check key/value pair
+    # existence.
+    #
+    # * *Args*    :
+    #   - +hHash+ : Hash of Lorj::Data. But it is possible to have different
+    #               object type (not Lorj::Data)
+    # * *Returns* :
+    #   true/false
+    # * *Raises* :
+    #   PrcError
+    def exist?(*key) # rubocop: disable Metrics/MethodLength
+      fail Lorj::PrcError.new, 'ObjectData: key is not list of values '\
+      '(string/symbol or array)' unless [Array, String,
+                                         Symbol].include?(key.class)
+
+      key = [key] if key.is_a?(Symbol) || key.is_a?(String)
+
+      key = key.flatten
+
+      object = @params.rh_get(key[0])
+      return false if object.nil?
+
+      if object.is_a?(Lorj::Data)
+        object_data_exist?(object, key)
+      else
+        # By default true if found key hierarchy
+        @params.rh_exist?(key)
+      end
+    end
+
+    # Determine the type of object identified by a key. Lorj::Data attributes or
+    # object exists. Or check key/value pair existence.
+    #
+    # * *Args*    :
+    #   - +key+ : Key to check in ObjectData list.
+    # * *Returns* :
+    #   - nil if not found
+    #   - :data if the key value is simply a data
+    #   - :DataObject if the key value is a Lorj::Data
+    # * *Raises* :
+    #   PrcError
+
+    def type?(key)
+      return nil unless @params.rh_exist?(key)
+      :data
+      :DataObject if @params[key].type == :object
+    end
+
+    # cObj was an old way to get the internal data :object.
+    # Replaced by get(:object)
+    # def cobj(*key)
+    #   @params.rh_get(key, :object) if @params.rh_exist?(key, :object)
+    # end
+
+    private
+
+    # Get function
+    #
+    # key can be an array of symbol or string (converted to a symbol).
+    #
+    # * *Args*    :
+    #   - +object+: Lorj::Data object to get data. Must exist.
+    #   - +key+   : key tree (list of keys)
+    #     If key[1] == :attrs, get will forcelly use the Lorj::Data object
+    #     attributes
+    #     If key[1] == :ObjectData, get will forcelly return the controller
+    #     object
+    #     otherwise, get will depends on the context:
+    #     - controller context: will return the controller object
+    #     - Process context: will return the Lorj::Data object attributes
+    # * *Returns* :
+    #   value found or nil.
+    # * *Raises* :
+    #   nothing
+    def object_data_get(object, *key)
+      key = key.flatten
+
+      return nil unless object.is_a?(Lorj::Data)
+
+      # Return ObjectData Element if asked. Ignore additional keys.
+      return @params[key[0]] if key[1] == :ObjectData
+
+      # Return attributes if asked
+      return object[:attrs,  key[2..-1]] if key[1] == :attrs
+
+      # params are retrieved in process context
+      # By default, if key is detected as a framework object, return its
+      # data.
+      return object[:attrs,  key[1..-1]] if @internal
+
+      # params are retrieved in controller context
+      # By default, if key is detected as a controller object, return its
+      # data.
+      return object[:object,  key[1..-1]] unless @internal
+    end
+
+    # Add function. Add a Lorj::Data (data or list) to the ObjectData list.
+    #
+    # key can be an array, a string (converted to a symbol) or a symbol.
+    #
+    # * *Args*    :
+    #   - +oDataObject+ : Lorj::Data object
+    # * *Returns* :
+    #   Nothing
+    # * *Raises* :
+    #   nothing
+    def object_data_add(oDataObject)
+      object_type = oDataObject.object_type?
+
+      if oDataObject.type == :list
+        old_data_object = @params.rh_get(:query, object_type)
+        old_data_object.unregister if old_data_object
+        @params.rh_set(oDataObject, :query, object_type)
+      else
+        old_data_object = @params.rh_get(object_type)
+        old_data_object.unregister if old_data_object
+        @params[object_type] = oDataObject
+      end
+    end
+
+    # delete function. delete a Lorj::Data (data or list) from the ObjectData
+    # list.
+    #
+    # * *Args*    :
+    #   - +oDataObject+ : Lorj::Data object
+    # * *Returns* :
+    #   Nothing
+    # * *Raises* :
+    #   nothing
+    def object_data_delete(obj)
+      fail Lorj::PrcError.new,
+           format('ObjectData: delete error. obj is not a'\
+                  " framework data Object. Is a '%s'",
+                  obj.class) unless obj.is_a?(Lorj::Data)
+      if obj.type == :list
+        @params.rh_set(nil, :query, obj.object_type?)
+      else
+        object_type = obj.object_type?
+        @params[object_type] = nil
+      end
+    end
+
+    def object_data_exist?(object, key)
+      # Return true if ObjectData Element is found when asked.
+      return true if key[1] == :ObjectData && object.type?(key[0]) == :object
+
+      # Return true if attritutes or controller object attributes found when
+      # asked.
+      return object.exist?(key[2..-1]) if key[1] == :attrs
+      return object.exist?(key[1..-1]) if key.length > 1
+      true
+    end
+  end
+end