occi-core 4.3.6 → 5.0.0.alpha.1

data/lib/occi/core/model.rb

@@ -0,0 +1,341 @@
+module Occi
+  module Core
+    # Implements a generic envelope for all OCCI-related categories. This
+    # class can be used directly for various reasons or, in a specific way,
+    # as an ancestor for custom classes providing `Model`-like functionality.
+    # Its primary purpose is to provide a tool for working with multiple
+    # sets of different categories, aid with their transport and validation.
+    #
+    # @attr categories [Set] set of categories associated with this model instance
+    #
+    # @author Boris Parak <parak@cesnet.cz>
+    class Model
+      include Yell::Loggable
+      include Helpers::ArgumentValidator
+      include Helpers::Renderable
+
+      attr_accessor :categories
+
+      # Constructs an instance with the given information. All arguments are
+      # optional and will default to empty `Set` instances if not provided.
+      #
+      # @example
+      #   my_model = Occi::Core::Model.new
+      #   my_model << mixin << kind << action
+      #
+      # @param args [Hash] arguments with model instance information
+      # @option args [Set] :categories set of categories associated with this model instance
+      def initialize(args = {})
+        pre_initialize(args)
+        default_args! args
+
+        @categories = args.fetch(:categories)
+
+        post_initialize(args)
+      end
+
+      # Collects everything present in this model and merges it into
+      # a single set. This will include kinds, mixins, and actions.
+      # The resulting set can be used, for example, in conjunction with the `<<`
+      # operator to create an independent copy of the model.
+      #
+      # @return [Set] content of this model as a new `Set` instance
+      def all
+        Set.new categories
+      end
+
+      # Collects all `Occi::Core::Kind` instances in this model.
+      #
+      # @return [Set] all `Occi::Core::Kind` instances from this model
+      def kinds
+        typed_set(categories, Occi::Core::Kind)
+      end
+
+      # Collects all `Occi::Core::Kind` instances specified
+      # as `parent` in one or more other kinds in this model.
+      # These instances may not appear in the model itself if
+      # it has not been successfully validated yet.
+      #
+      # @return [Set] parenting `Occi::Core::Kind` instances from this model
+      def parent_kinds
+        parents = kinds
+        parents.collect!(&:parent)
+        parents.reject!(&:nil?)
+        parents
+      end
+
+      # Collects all `Occi::Core::Mixin` instances in this model.
+      #
+      # @return [Set] all `Occi::Core::Mixin` instances from this model
+      def mixins
+        typed_set(categories, Occi::Core::Mixin)
+      end
+
+      # Collects all `Occi::Core::Mixin` instances specified
+      # in `depends` in one or more other mixins in this model.
+      # These instances may not appear in the model itself if
+      # it has not been successfully validated yet.
+      #
+      # @return [Set] depended on `Occi::Core::Mixin` instances from this model
+      def depended_on_mixins
+        depended_on = mixins
+        depended_on.collect!(&:depends)
+        depended_on.flatten!
+        depended_on.reject!(&:nil?)
+        depended_on
+      end
+
+      # Collects all `Occi::Core::Action` instances in this model.
+      #
+      # @return [Set] all `Occi::Core::Action` instances from this model
+      def actions
+        typed_set(categories, Occi::Core::Action)
+      end
+
+      # Collects all `Occi::Core::Action` instances specified
+      # in `actions` in one or more other mixins/kinds in this model.
+      # These instances may not appear in the model itself if
+      # it has not been successfully validated yet.
+      #
+      # @return [Set] associated `Occi::Core::Action` instances from this model
+      def associated_actions
+        associated = kinds + mixins
+        associated.collect!(&:actions)
+        associated.flatten!
+        associated.reject!(&:nil?)
+        associated
+      end
+
+      # Collects all `Occi::Core::Kind` instances related to the given instance.
+      #
+      # @param kind [Occi::Core::Kind] top-level kind
+      # @param options [Hash] look-up modifiers, currently only `directly: true`
+      # @return [Set] all instances related to the given instance
+      def find_related(kind, options = { directly: false })
+        raise ArgumentError, 'Kind is a mandatory argument' unless kind
+        method = options[:directly] ? :directly_related? : :related?
+        Set.new(kinds.select { |knd| knd.send(method, kind) })
+      end
+
+      # Collects all `Occi::Core::Mixin` instances dependent on the given instance.
+      #
+      # @param mixin [Occi::Core::Mixin] top-level mixin
+      # @return [Set] all instances dependent on the given instance
+      def find_dependent(mixin)
+        raise ArgumentError, 'Mixin is a mandatory argument' unless mixin
+        Set.new(mixins.select { |mxn| mxn.depends?(mixin) })
+      end
+
+      # Collects everything with the given location.
+      # This method looks for an explicit/full match on the location.
+      #
+      # @param location [URI] expected location
+      # @return [Set] set of results possibly containing a mix of types
+      def find_by_location(location)
+        filtered_set(
+          all.select { |elm| elm.respond_to?(:location) },
+          key: 'location', value: location
+        )
+      end
+
+      # Collects all `Occi::Core::Category` successors with the given identifier.
+      #
+      # @param identifier [String] expected identifier
+      # @return [Set] set of found categories
+      def find_by_identifier(identifier)
+        filtered_set(categories, key: 'identifier', value: identifier)
+      end
+
+      # See `find_by_identifier`. Returns first found object or raises an error.
+      #
+      # @param identifier [String] expected identifier
+      # @return [Object] found category
+      def find_by_identifier!(identifier)
+        found = categories.detect { |elm| elm.identifier == identifier }
+        raise Occi::Core::Errors::ModelLookupError, "Category #{identifier.inspect} not found in the model" unless found
+        found
+      end
+
+      # Collects all `Occi::Core::Category` successors with the given term.
+      #
+      # @param term [String] expected term
+      # @return [Set] set of found categories
+      def find_by_term(term)
+        filtered_set(categories, key: 'term', value: term)
+      end
+
+      # Collects all `Occi::Core::Category` successors with the given schema.
+      #
+      # @param schema [String] expected schema
+      # @return [Set] set of found categories
+      def find_by_schema(schema)
+        filtered_set(categories, key: 'schema', value: schema)
+      end
+
+      # Auto-assigns the given object to the appropriate internal set.
+      # Unknown objects will result in an `ArgumentError` error.
+      #
+      # @param object [Object] object to be assigned
+      # @return [Occi::Core::Model] self, for chaining purposes
+      def <<(object)
+        case object
+        when Occi::Core::Category
+          categories << object
+        else
+          raise ArgumentError, "Cannot automatically assign #{object.inspect}"
+        end
+
+        self
+      end
+      alias add <<
+
+      # Auto-removes the given object from the appropriate internal set.
+      # Unknown objects will result in an `ArgumentError` error.
+      #
+      # @param object [Object] object to be removed
+      # @return [Occi::Core::Model] self, for chaining purposes
+      def remove(object)
+        case object
+        when Occi::Core::Category
+          categories.delete object
+        else
+          raise ArgumentError, "Cannot automatically delete #{object.inspect}"
+        end
+
+        self
+      end
+
+      # Validates kinds, mixins, and actions stored in this model.
+      # Validity of each category is considered with regard to other categories.
+      # If you are looking for a more aggressive version raising validation errors,
+      # see `#valid!`.
+      #
+      # @return [TrueClass] on successful validation
+      # @return [FalseClass] on failed validation
+      def valid?
+        valid_helper? :valid!
+      end
+
+      # Validates kinds, mixins, and actions stored in this model.
+      # Validity of each category is considered with regard to other categories.
+      # This method will raise an error on the first invalid instance.
+      def valid!
+        valid_categories! # checking all identifiers
+        valid_parents!    # parentage on kinds
+        valid_actions!    # associated actions
+        valid_depends!    # dependencies on mixins
+        valid_applies!    # applicability on mixins
+      end
+
+      # Reports emptiness of the model.
+      #
+      # @return [TrueClass] if there are no categories
+      # @return [FalseClass] if there are some categories
+      def empty?
+        categories.empty?
+      end
+      alias nothing? empty?
+
+      # Loads OGF's OCCI Core Standard from `Occi::Core::Warehouse`.
+      #
+      # @example
+      #    model = Occi::Core::Model.new
+      #    model.load_core!
+      def load_core!
+        Occi::Core::Warehouse.bootstrap! self
+      end
+
+      # Returns an instance of `Occi::Core::InstanceBuilder` associated with this model.
+      #
+      # @return [Occi::Core::InstanceBuilder] instance of IB
+      def instance_builder
+        Occi::Core::InstanceBuilder.new(model: self)
+      end
+
+      protected
+
+      # :nodoc:
+      def sufficient_args!(args)
+        return if args[:categories]
+        raise Occi::Core::Errors::MandatoryArgumentError, '`categories` is a mandatory ' \
+              "argument for #{self.class}"
+      end
+
+      # :nodoc:
+      def defaults
+        { categories: Set.new }
+      end
+
+      # :nodoc:
+      def pre_initialize(args); end
+
+      # :nodoc:
+      def post_initialize(args); end
+
+      # :nodoc:
+      def typed_set(source, type)
+        Set.new(source.select { |elm| elm.is_a?(type) })
+      end
+
+      # :nodoc:
+      def filtered_set(source, filter)
+        raise ArgumentError, 'Filtering key is a mandatory argument' if filter[:key].blank?
+        Set.new(source.select { |elm| elm.send(filter[:key]) == filter[:value] })
+      end
+
+      # :nodoc:
+      def valid_helper?(method)
+        begin
+          send method
+        rescue Occi::Core::Errors::InstanceValidationError => ex
+          logger.warn "Instance invalid: #{ex.message}"
+          return false
+        rescue URI::InvalidURIError, Occi::Core::Errors::CategoryValidationError => ex
+          logger.warn "Category invalid: #{ex.message}"
+          return false
+        end
+
+        true
+      end
+
+      # :nodoc:
+      def valid_categories!
+        categories.each(&:valid!)
+      end
+
+      # :nodoc:
+      def valid_parents!
+        report_diff!('kinds') { parent_kinds - kinds }
+      end
+
+      # :nodoc:
+      def valid_depends!
+        report_diff!('mixins') { depended_on_mixins - mixins }
+      end
+
+      # :nodoc:
+      def valid_applies!
+        not_applicable = mixins.select { |mxn| mxn.applies.blank? }
+        return if not_applicable.empty?
+        logger.warn 'The following mixins are not applicable to any entity sub-type: ' \
+                    "#{not_applicable.collect(&:identifier).inspect}"
+      end
+
+      # :nodoc:
+      def valid_actions!
+        report_diff!('actions') { associated_actions - actions }
+      end
+
+      # :nodoc:
+      def report_diff!(type)
+        raise 'You have to provide a diff block!' unless block_given?
+        diff = yield
+        return if diff.empty?
+
+        raise Occi::Core::Errors::CategoryValidationError,
+              "The following #{type} have been referenced but not defined: " \
+              "#{diff.to_a.collect(&:identifier).inspect}"
+      end
+    end
+  end
+end

data/lib/occi/core/parsers/base_parser.rb

@@ -0,0 +1,168 @@
+module Occi
+  module Core
+    module Parsers
+      # Implementes base components necessary to parse all renderings.
+      #
+      # @attr model [Occi::Core::Model, Occi::Infrastructure::Model] model to use as a primary reference point
+      # @attr media_type [String] type of content to parse
+      #
+      # @abstract Not for direct use.
+      # @author Boris Parak <parak@cesnet.cz>
+      class BaseParser
+        include Yell::Loggable
+        include Helpers::ArgumentValidator
+        include Helpers::ErrorHandler
+
+        # Media type constants
+        MEDIA_TYPES = [].freeze
+
+        attr_accessor :model, :media_type
+
+        # Constructs an instance of the parser that will use a particular model as the reference for every
+        # parsed instance. Only instances allowed by the model will be successfuly parsed. In case of
+        # `Occi::Core::Category` instances, only identifiers are parsed and existing instances from the model
+        # are returned.
+        #
+        # @param args [Hash] constructor arguments in a Hash
+        # @option args [Occi::Core::Model] :model model to use as a primary reference point
+        # @option args [String] :media_type type of content to parse
+        def initialize(args = {})
+          pre_initialize(args)
+          default_args! args
+
+          @model = args.fetch(:model)
+          @media_type = args.fetch(:media_type)
+
+          post_initialize(args)
+        end
+
+        # Parses entities from the given body/headers. Only kinds, mixins, and actions already declared
+        # in the model are allowed.
+        #
+        # @param body [String] raw `String`-like body as provided by the transport protocol
+        # @param headers [Hash] raw headers as provided by the transport protocol
+        # @param expectation [Class] expected class of the returned instance(s)
+        # @return [Set] set of instances
+        def entities(_body, _headers, _expectation = nil)
+          raise Occi::Core::Errors::ParserError, 'This method needs to be implemented in subclasses'
+        end
+
+        # See `#entities`.
+        def resources(body, headers)
+          entities body, headers, Occi::Core::Resource
+        end
+
+        # See `#entities`.
+        def links(body, headers)
+          entities body, headers, Occi::Core::Link
+        end
+
+        # Parses action instances from the given body/headers. Only actions already declared in the model are
+        # allowed.
+        #
+        # @param body [String] raw `String`-like body as provided by the transport protocol
+        # @param headers [Hash] raw headers as provided by the transport protocol
+        # @return [Set] set of parsed instances
+        def action_instances(_body, _headers)
+          raise Occi::Core::Errors::ParserError, 'This method needs to be implemented in subclasses'
+        end
+
+        # Parses categories from the given body/headers and returns corresponding instances
+        # from the known model.
+        #
+        # @param body [String] raw `String`-like body as provided by the transport protocol
+        # @param headers [Hash] raw headers as provided by the transport protocol
+        # @param expectation [Class] expected class of the returned instance(s)
+        # @return [Set] set of instances
+        def categories(_body, _headers, _expectation = nil)
+          raise Occi::Core::Errors::ParserError, 'This method needs to be implemented in subclasses'
+        end
+
+        # See `#categories`.
+        def kinds(body, headers)
+          categories body, headers, Occi::Core::Kind
+        end
+
+        # See `#categories`.
+        def mixins(body, headers)
+          categories body, headers, Occi::Core::Mixin
+        end
+
+        # See `#categories`.
+        def actions(body, headers)
+          categories body, headers, Occi::Core::Action
+        end
+
+        # Checks whether the given media type is supported by this
+        # parser instance.
+        #
+        # @param media_type [String] media type string as provided by the transport protocol
+        # @return [TrueClass] if supported
+        # @return [FalseClass] if not supported
+        def parses?(media_type)
+          self.media_type == media_type
+        end
+
+        # Looks up the given category identifier in the model. Unsuccessfull lookup will raise an error, as will an
+        # unexpected class of the found instance.
+        #
+        # @param identifier [String] category identifier to look up in the model
+        # @param klass [Class] expected class (raises error otherwise)
+        # @return [Object] found instance
+        def lookup(identifier, klass)
+          found = handle(Occi::Core::Errors::ParsingError) { model.find_by_identifier!(identifier) }
+          unless found.is_a?(klass)
+            raise Occi::Core::Errors::ParsingError, "#{self.class} -> #{identifier.inspect} isn't #{klass}"
+          end
+          found
+        end
+
+        class << self
+          # Returns a list of supported media types for this parser.
+          #
+          # @return [Array] list of supported media types
+          def media_types
+            self::MEDIA_TYPES
+          end
+
+          # Checks whether the given media type is supported by this
+          # parser.
+          #
+          # @param media_type [String] media type string as provided by the transport protocol
+          # @return [TrueClass] if supported
+          # @return [FalseClass] if not supported
+          def parses?(media_type)
+            media_types.include? media_type
+          end
+        end
+
+        protected
+
+        # :nodoc:
+        def sufficient_args!(args)
+          %i[model media_type].each do |attr|
+            unless args[attr]
+              raise Occi::Core::Errors::MandatoryArgumentError, "#{attr} is a mandatory " \
+                    "argument for #{self.class}"
+            end
+          end
+        end
+
+        # :nodoc:
+        def defaults
+          { model: nil, media_type: nil }
+        end
+
+        # :nodoc:
+        def pre_initialize(args); end
+
+        # :nodoc:
+        def post_initialize(args)
+          return if media_type.include?(args[:media_type])
+          raise Occi::Core::Errors::ParserError, "Media type #{args[:media_type].inspect} is not supported " \
+                "by instances of this parser, only #{media_type.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/occi/core/parsers/json/action_instance.rb

@@ -0,0 +1,36 @@
+module Occi
+  module Core
+    module Parsers
+      module Json
+        # Static parsing class responsible for extracting action instances from JSON.
+        # Class supports 'application/json' via `json`. No other formats are supported.
+        #
+        # @author Boris Parak <parak@cesnet.cz>
+        class ActionInstance
+          include Yell::Loggable
+          include Helpers::ErrorHandler
+          extend Helpers::RawJsonParser
+
+          class << self
+            # Parses action instances. Internal references between objects are converted from strings
+            # to actual objects. Actions have to be declared in the provided model.
+            #
+            # @param body [String] JSON body for parsing
+            # @param model [Occi::Core::Model] model with existing categories
+            # @return [Occi::Core::ActionInstance] action instance
+            def json(body, model)
+              parsed = raw_hash(body)
+              ep = Entity.new(model: model)
+
+              action = handle(Occi::Core::Errors::ParsingError) { model.find_by_identifier!(parsed[:action]) }
+              ai = Occi::Core::ActionInstance.new(action: action)
+              ep.set_attributes!(ai.attributes, parsed[:attributes]) if parsed[:attributes]
+
+              ai
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/occi/core/parsers/json/category.rb

@@ -0,0 +1,113 @@
+module Occi
+  module Core
+    module Parsers
+      module Json
+        # Static parsing class responsible for extracting categories from JSON.
+        # Class supports 'application/json' via `json`. No other formats are supported.
+        #
+        # @author Boris Parak <parak@cesnet.cz>
+        class Category
+          include Yell::Loggable
+          include Helpers::ErrorHandler
+          extend Helpers::ParserDereferencer
+          extend Helpers::RawJsonParser
+
+          # Typecasting lambdas
+          TYPECASTER_HASH = {
+            'boolean' => Boolean,
+            'string'  => String,
+            'number'  => Numeric,
+            'array'   => Array,
+            'object'  => Hash
+          }.freeze
+
+          # Hash constants for ParserDereferencer
+          PARENT_KEY  = :parent
+          APPLIES_KEY = :applies
+          DEPENDS_KEY = :depends
+
+          class << self
+            # Parses categories into instances of subtypes of `Occi::Core::Category`. Internal references
+            # between objects are converted from strings to actual objects. Categories provided in the model
+            # will be reused but have to be declared in the parsed model as well.
+            #
+            # @param body [String] JSON body for parsing
+            # @param model [Occi::Core::Model] model with existing categories
+            # @param full [Boolean] dereference categories
+            # @return [Occi::Core::Model] model with all known category instances
+            def json(body, model, full = true)
+              parsed = raw_hash(body)
+
+              instantiate_hashes! parsed, model
+              return model unless full
+
+              raw_categories = [parsed[:kinds], parsed[:mixins]].flatten.compact
+              dereference_identifiers! model.categories, raw_categories
+
+              model
+            end
+
+            # :nodoc:
+            def instantiate_hashes!(raw, model)
+              raw[:kinds].each { |k| model << instatiate_hash(k, Occi::Core::Kind) } if raw[:kinds]
+              raw[:mixins].each { |k| model << instatiate_hash(k, Occi::Core::Mixin) } if raw[:mixins]
+              raw[:actions].each { |k| model << instatiate_hash(k, Occi::Core::Action) } if raw[:actions]
+            end
+
+            # :nodoc:
+            def instatiate_hash(raw, klass)
+              obj = klass.new(
+                term: raw[:term], schema: raw[:scheme], title: raw[:title],
+                attributes: attribute_definitions(raw[:attributes])
+              )
+
+              if obj.respond_to?(:location)
+                obj.location = handle(Occi::Core::Errors::ParsingError) { URI.parse(raw[:location]) }
+              end
+
+              obj
+            end
+
+            # :nodoc:
+            def attribute_definitions(raw)
+              return {} if raw.blank?
+
+              attr_defs = {}
+              raw.each_pair do |k, v|
+                def_hsh = typecast(v)
+                unless def_hsh[:type]
+                  raise Occi::Core::Errors::ParsingError, "#{self} -> Attribute #{k.to_s.inspect} has no type"
+                end
+                attr_defs[k.to_s] = Occi::Core::AttributeDefinition.new def_hsh
+              end
+
+              attr_defs
+            end
+
+            # :nodoc:
+            def typecast(hash)
+              hash = hash.clone
+              hash[:type] = TYPECASTER_HASH[hash[:type]]
+              hash[:pattern] = handle(Occi::Core::Errors::ParsingError) { Regexp.new(hash[:pattern]) } if hash[:pattern]
+              hash
+            end
+
+            # :nodoc:
+            def lookup_applies_references!(mixin, derefd, parsed_rel)
+              return if parsed_rel.blank?
+              parsed_rel.each { |kind| mixin.applies << first_or_die(derefd, kind) }
+            end
+
+            # :nodoc:
+            def lookup_depends_references!(mixin, derefd, parsed_rel)
+              return if parsed_rel.blank?
+              parsed_rel.each { |mxn| mixin.depends << first_or_die(derefd, mxn) }
+            end
+
+            private :lookup_applies_references!, :lookup_depends_references!
+          end
+        end
+      end
+    end
+  end
+end