occi-core 4.3.6 → 5.0.0.alpha.1

data/lib/occi/core/helpers/parser_dereferencer.rb

@@ -0,0 +1,96 @@
+module Occi
+  module Core
+    module Helpers
+      # Introduces dereferencing capabilities to various parsers. This allowes
+      # parsers to convert `Occi::Core::Category` sub-types from identifier into proper objects.
+      #
+      # @author Boris Parak <parak@cesnet.cz>
+      module ParserDereferencer
+        # Dereferences cross-category references. Takes existing string
+        # identifiers for actions, mixins, and kinds and replaces them
+        # with actual instances.
+        #
+        # @param derefd [Array] list of instances needing dereferencing
+        # @param parsed [Array] list of raw parsed categories (as hashes)
+        # @return [Array] dereferenced list of instances
+        def dereference_identifiers!(derefd, parsed)
+          derefd.each do |cat|
+            next if cat.is_a?(Occi::Core::Action) # nothing to do here
+            lookup_references!(cat, derefd, parsed)
+          end
+          derefd
+        end
+
+        # Looks up inter-category references and replaces them with existing objects.
+        #
+        # @param cat [Occi::Core::Mixin, Occi::Core::Kind] category to dereference
+        # @param derefd [Array] list of known categories
+        # @param parsed [Array] list of original parsed category structures
+        def lookup_references!(cat, derefd, parsed)
+          parsed_cat = parsed.detect { |pcat| "#{pcat[:scheme]}#{pcat[:term]}" == cat.identifier }
+          raise Occi::Core::Errors::ParsingError, "#{self} -> #{cat.identifier} not in the model" unless parsed_cat
+          lookup_action_references!(cat, derefd, parsed_cat[:actions])
+
+          if cat.is_a?(Occi::Core::Mixin)
+            lookup_depends_references!(cat, derefd, parsed_cat[self::DEPENDS_KEY])
+            lookup_applies_references!(cat, derefd, parsed_cat[self::APPLIES_KEY])
+          else
+            # only Occi::Core::Kind is left here
+            lookup_parent_references!(cat, derefd, parsed_cat[self::PARENT_KEY])
+          end
+        end
+
+        # @param cat [Occi::Core::Mixin, Occi::Core::Kind] category instance needing action dereferencing
+        # @param derefd [Array] list of all available category instances
+        # @param parsed_actions [Array] textual representation of needed actions
+        def lookup_action_references!(cat, derefd, parsed_actions)
+          return if parsed_actions.blank?
+          parsed_actions.each { |action| cat.actions << first_or_die(derefd, action) }
+        end
+
+        # @param kind [Occi::Core::Kind] kind instance needing parent dereferencing
+        # @param derefd [Array] list of all available category instances
+        # @param parsed_rel [Array] textual representation of needed parent(s)
+        def lookup_parent_references!(kind, derefd, parsed_rel)
+          return if parsed_rel.blank? || kind.parent.is_a?(Occi::Core::Kind)
+          if parsed_rel.is_a?(Enumerable)
+            if parsed_rel.count > 1
+              raise Occi::Core::Errors::ParsingError,
+                    "#{self} -> Kind #{kind} with multiple parents #{parsed_rel.inspect}"
+            end
+            parsed_rel = parsed_rel.first
+          end
+
+          kind.parent = first_or_die(derefd, parsed_rel)
+          kind.send(:load_parent_attributes!) # this is safe because there was no previous parent!
+        end
+
+        # @param mixin [Occi::Core::Mixin] mixin instance needing applicability dereferencing
+        # @param derefd [Array] list of all available category instances
+        # @param parsed_rel [Array] textual representations of needed applicability targets
+        def lookup_applies_references!(_mixin, _derefd, _parsed_rel)
+          raise Occi::Core::Errors::ParserError, 'Must be implemented in the parser class'
+        end
+
+        # @param mixin [Occi::Core::Mixin] mixin instance needing dependency dereferencing
+        # @param derefd [Array] list of all available category instances
+        # @param parsed_rel [Array] textual representations of needed dependencies
+        def lookup_depends_references!(_mixin, _derefd, _parsed_rel)
+          raise Occi::Core::Errors::ParserError, 'Must be implemented in the parser class'
+        end
+
+        # @param where [Enumerable] list of items to look through, items must respond to `.identifier`
+        # @param what [String] identifier of the desired item
+        # @return [Object] desired item from `where`
+        def first_or_die(where, what)
+          found = where.detect { |elm| elm.identifier == what }
+          unless found
+            raise Occi::Core::Errors::ParsingError,
+                  "#{self} -> Category #{what.to_s.inspect} referenced but not provided"
+          end
+          found
+        end
+      end
+    end
+  end
+end

data/lib/occi/core/helpers/raw_json_parser.rb

@@ -0,0 +1,18 @@
+module Occi
+  module Core
+    module Helpers
+      # Introduces JSON parsing to various parser classes. This allowes
+      # parsers to convert JSON-formatted text into hashes.
+      #
+      # @author Boris Parak <parak@cesnet.cz>
+      module RawJsonParser
+        # :nodoc:
+        def raw_hash(body)
+          JSON.parse body, symbolize_names: true
+        rescue => ex
+          raise Occi::Core::Errors::ParsingError, "#{self} -> JSON parsing failed: #{ex.message}"
+        end
+      end
+    end
+  end
+end

data/lib/occi/core/helpers/renderable.rb

@@ -0,0 +1,93 @@
+module Occi
+  module Core
+    module Helpers
+      # Introduces rendering capabilities to every receiver
+      # class. Short-hand `to_<format>` methods are automatically
+      # generated for every available rendering `format`. The
+      # renderability is evaluated in runtime, when calling `render`
+      # or one of the `to_<format>` methods.
+      #
+      # @author Boris Parak <parak@cesnet.cz>
+      module Renderable
+        # Default renderer factory class
+        RENDERER_FACTORY_CLASS = Occi::Core::RendererFactory
+
+        # Renders the receiver into the specified over-the-wire `format`.
+        # `format` is automatically injected into `options` and these
+        # are then passed (unmodified) to the underlying renderer. See
+        # documentation of a specific renderer for details.
+        #
+        # @example
+        #   render 'text' # => String
+        #   render 'json' # => String
+        #   render 'headers' # => Hash
+        #
+        # @param format [String] over-the-wire format, mandatory
+        # @param options [Hash] options passed to the underlying renderer
+        # @return [Object] output of the chosen renderer
+        def render(format, options = {})
+          options[:format] = format
+          logger.debug "#{self.class} is being rendered to #{format} with #{options.inspect}" if respond_to?(:logger)
+          renderer_for(format).render(self, options)
+        end
+
+        # Instance delegate for `RendererFactory#renderer_for`, see `RendererFactory`.
+        def renderer_for(format)
+          renderer_factory.renderer_for(format)
+        end
+
+        # Instance proxy to `renderer_factory` instance, see `Renderable::renderer_factory`.
+        def renderer_factory
+          Renderable.renderer_factory
+        end
+
+        # Adds available rendering formats as `to_<format>` methods on
+        # the receiver.
+        #
+        # @example
+        #   class Test
+        #     include Occi::Core::Helpers::Renderable
+        #   end
+        #
+        #   t = Test.new
+        #   t.to_text   # => String
+        #
+        # @param base [Class] class receiving this module
+        def self.included(base)
+          renderer_factory.formats.each do |format|
+            base.logger.debug "Renderable: Adding support for #{format} to #{base}" if base.respond_to?(:logger)
+            base.send(:define_method, "to_#{format}", proc { render(format) })
+          end
+        end
+
+        # Allows calling `.extend(Renderable)` on instances. Does not allow
+        # class-based extension, will raise a `RuntimeError` error.
+        #
+        # @example
+        #   o = Object.new
+        #   o.extend Renderable
+        #   o.to_text  # => String
+        #
+        # @param base [Class, Object] class or object being extended
+        def self.extended(base)
+          base.is_a?(Class) ? raise("#{self} cannot extend #{base}") : included(base.class)
+        end
+
+        # Returns pre-constructed instance of the active renderer
+        # factory providing access to registered renderers.
+        #
+        # @return [Object] instance of the renderer factory
+        def self.renderer_factory
+          renderer_factory_class.instance
+        end
+
+        # Provides access to the default renderer factory class.
+        #
+        # @return [Class] renderer factory class
+        def self.renderer_factory_class
+          RENDERER_FACTORY_CLASS
+        end
+      end
+    end
+  end
+end

data/lib/occi/core/helpers/yaml_summoner.rb

@@ -0,0 +1,44 @@
+module Occi
+  module Core
+    module Helpers
+      # Introduces YAML parsing capabilities to every receiver
+      # class.
+      #
+      # @author Boris Parak <parak@cesnet.cz>
+      module YamlSummoner
+        # Reads the provided YAML file and passes its content as `args` to the
+        # constructor of the class. YAML file is expected to provide all the
+        # necessary information (depending on the class in question) in the
+        # required form (appropriate types and structures). Dereferencing will
+        # will be automatically attempted on suitable classes, this requires
+        # `model` and `attribute_definitions` to be provided.
+        #
+        # @example
+        #    Occi::Core::AttributeDefinition.from_yaml 'my_def.yml'
+        #      # => #<Occi::Core::AttributeDefinition>
+        #
+        # @param path [String] path to a YAML File
+        # @param model [Occi::Core::Model] model instance for dereferencing (category look-up)
+        # @param attribute_definitions [Hash] hash with known attribute definitions for dereferencing
+        # @return [Object] instance of receiver class
+        def from_yaml(path, model = nil, attribute_definitions = nil)
+          raise 'This method cannot be invoked on instances' unless is_a? Class
+          allowed_classes = respond_to?(:allowed_yaml_classes, true) ? allowed_yaml_classes : []
+
+          object_args = YAML.safe_load(File.read(path), allowed_classes)
+          object_args.symbolize_keys!
+          object_args.dereference_with!(self, model, attribute_definitions) if needs_dereferencing?
+          new object_args
+        end
+
+        # Identifies classes suitable for dereferencing.
+        #
+        # @return [TrueClass] if needs dereferencing
+        # @return [FalseClass] if does not need dereferencing
+        def needs_dereferencing?
+          ancestors.include? Occi::Core::Category
+        end
+      end
+    end
+  end
+end

data/lib/occi/core/helpers.rb

@@ -0,0 +1,13 @@
+module Occi
+  module Core
+    # Contains various helper modules and classes shared with
+    # the rest of the code. For details, see documentation
+    # for the particular helper.
+    #
+    # @author Boris Parak <parak@cesnet.cz>
+    module Helpers; end
+  end
+end
+
+require File.join(File.dirname(__FILE__), 'helpers', 'argument_validator')
+Dir[File.join(File.dirname(__FILE__), 'helpers', '*.rb')].each { |file| require file.gsub('.rb', '') }

data/lib/occi/core/instance_builder.rb

@@ -0,0 +1,162 @@
+module Occi
+  module Core
+    # Provides mechanisms for easy instantiation of various
+    # Entity sub-types such as Resource or Link (and their sub-types).
+    # Unknown sub-types will result in generic `Occi::Core::Resource`
+    # and `Occi::Core::Link` instances.
+    # Known (pre-defined) sub-types will be provided as instances of
+    # unique classes inheriting from the abovementioned.
+    #
+    # @attr model [Occi::Core::Model] model filled with known category definitions
+    #
+    # @author Boris Parak <parak@cesnet.cz>
+    class InstanceBuilder
+      include Yell::Loggable
+      include Helpers::ArgumentValidator
+
+      attr_accessor :model
+
+      # Constructs and instance of the InstanceBuilder. It can be used to quickly and easily get
+      # get instances of various `Occi::Core::Entity` sub-types based on their kind identifier.
+      #
+      # @param args [Hash] constructor arguments
+      # @option args [Occi::Core::Model] :model model filled with known category definitions
+      def initialize(args = {})
+        pre_initialize(args)
+        default_args! args
+
+        @model = args.fetch(:model)
+
+        post_initialize(args)
+      end
+
+      # Constructs an instance based on the given category identifier. This method
+      # can construct instances of Entity sub-types.
+      #
+      # @example
+      #    build 'http://schemas.ogf.org/occi/core#resource'
+      #      # => Occi::Core::Resource
+      #
+      # @param identifier [String] identifier of the category
+      # @param args [Hash] hash for the instance constructor
+      # @return [Object] constructed instance
+      # @return [NilClass] if such an instance could not be constructed
+      def build(identifier, args = {})
+        k_args = args_with_kind(identifier, args)
+        klass(identifier, parent_klass(k_args[:kind])).new k_args
+      end
+      alias get build
+
+      # Constructs an instance based on the given category identifier. This method
+      # can construct instances of Resource sub-types.
+      #
+      # @example
+      #    build_resource 'http://schemas.ogf.org/occi/core#resource' # => Occi::Core::Resource
+      #
+      # @param identifier [String] identifier of the category
+      # @param args [Hash] hash for the instance constructor
+      # @return [Object] constructed instance
+      # @return [NilClass] if such an instance could not be constructed
+      def build_resource(identifier, args = {})
+        klass(identifier, Occi::Core::Resource).new args_with_kind(identifier, args)
+      end
+
+      # Constructs an instance based on the given category identifier. This method
+      # can construct instances of Link sub-types.
+      #
+      # @example
+      #    build_link 'http://schemas.ogf.org/occi/core#link' # => Occi::Core::Link
+      #
+      # @param identifier [String] identifier of the category
+      # @param args [Hash] hash for the instance constructor
+      # @return [Object] constructed instance
+      # @return [NilClass] if such an instance could not be constructed
+      def build_link(identifier, args = {})
+        klass(identifier, Occi::Core::Link).new args_with_kind(identifier, args)
+      end
+
+      # Looks up the appropriate candidate class for the given identifier. If no class
+      # is found in static tables, the last known ancestor is returned. For Core, this
+      # method ALWAYS returns the last known ancestor given as `last_ancestor`, for
+      # compatibility reasons.
+      #
+      # @param identifier [String] identifier of the category
+      # @param last_ancestor [Class] expected ancestor
+      # @return [Class] pre-defined class or given last ancestor
+      def klass(identifier, last_ancestor)
+        found_last_ancestor = self.class.klass_map[identifier]
+        if found_last_ancestor && !found_last_ancestor.ancestors.include?(last_ancestor)
+          raise Occi::Core::Errors::InstanceValidationError,
+                "#{found_last_ancestor.inspect} is not a sub-type of #{last_ancestor.inspect}"
+        end
+        found_last_ancestor || last_ancestor
+      end
+
+      # Looks up the given identifier in the model. Returns `Occi::Core::Kind` instance if
+      # found and raises an error otherwise. Look-up results not related to `Occi::Core::Kind`
+      # will also raise an error.
+      #
+      # @param identifier [String] identifier of the category
+      # @return [Occi::Core::Kind] full category definition from the model
+      def kind(identifier)
+        kind = model.find_by_identifier!(identifier)
+        unless kind.is_a? Occi::Core::Kind
+          raise Occi::Core::Errors::CategoryValidationError, "#{identifier.inspect} " \
+                'is not a kind'
+        end
+        kind
+      end
+
+      # Locates the closes known parent class for instances of the given kind.
+      # This usually means `Occi::Core::Resource`, `Occi::Core::Link`, or error.
+      #
+      # @param kind [Occi::Core::Kind] kind instance to evaluate
+      # @return [Class] located known parent class
+      def parent_klass(kind)
+        if kind.related? kind(Occi::Core::Constants::RESOURCE_KIND)
+          Occi::Core::Resource
+        elsif kind.related? kind(Occi::Core::Constants::LINK_KIND)
+          Occi::Core::Link
+        else
+          raise Occi::Core::Errors::ModelLookupError,
+                "Could not identify #{kind.identifier.inspect} as a Link or Resource"
+        end
+      end
+
+      class << self
+        # :nodoc:
+        def klass_map
+          {}
+        end
+      end
+
+      protected
+
+      # :nodoc:
+      def sufficient_args!(args)
+        return if args[:model]
+        raise Occi::Core::Errors::MandatoryArgumentError, 'model is a mandatory ' \
+              "argument for #{self.class}"
+      end
+
+      # :nodoc:
+      def defaults
+        { model: nil }
+      end
+
+      # :nodoc:
+      def pre_initialize(args); end
+
+      # :nodoc:
+      def post_initialize(args); end
+
+      # :nodoc:
+      def args_with_kind(identifier, args)
+        k_args = args.clone
+        k_args[:kind] = kind(identifier)
+        k_args[:rel] = kind(k_args[:rel]) if k_args[:rel]
+        k_args
+      end
+    end
+  end
+end